Skip to content

Commit

Permalink
Bring documentation up to date
Browse files Browse the repository at this point in the history 
Change-Id: I5aebc9f11bf7a2a5a1231586c7d4da1950e2917f
  • Loading branch information
@matejart
matejart committed Aug 23, 2016
1 parent 06b7494 commit 6a4e3e0
Show file tree
Hide file tree
Showing 2 changed files with 150 additions and 131 deletions.
63 changes: 38 additions & 25 deletions doc/AdminGuide.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -197,14 +197,25 @@ The UUIDs for images and flavours can be obtained using the `nova` client. See
[this document](Cloudify-3.3.1-OpenStack.md#preparing-inputs) to get
examples of the client usage.

To prepare the inputs, open a text file named `openstack-inputs.yaml` with
contents like in the following example:

```json
[
{"key": "agent_user", "value": "ubuntu", "description": "Agent user"},
{"key": "small_image_id", "value": "36dbc4e8-81dd-49f5-9e43-f44a179a64ea", "description": "Small image id"},
{"key": "small_flavor_id", "value": "070005dc-9bd5-4c0c-b2c6-88f81a7b7239", "description": "Small flavour id"},
{"key": "medium_image_id", "value": "36dbc4e8-81dd-49f5-9e43-f44a179a64ea", "description": "Medium image id"},
{"key": "medium_flavor_id", "value": "45170672-5608-473e-af9c-9097510472d6", "description": "Medium flavour id"},
{"key": "large_image_id", "value": "36dbc4e8-81dd-49f5-9e43-f44a179a64ea", "description": "Large image id"},
{"key": "large_flavor_id", "value": "1bd34fe1-57b3-4937-bf60-5edd35382b78", "description": "Large flavour id"}
]
```

Then submit the inputs to the deployment service:

```bash
dice-deploy-cli input-add agent_user "ubuntu" "Agent user"
dice-deploy-cli input-add small_image_id "36dbc4e8-81dd-49f5-9e43-f44a179a64ea" "Small image id"
dice-deploy-cli input-add small_flavor_id "070005dc-9bd5-4c0c-b2c6-88f81a7b7239" "Small flavour id"
dice-deploy-cli input-add medium_image_id "36dbc4e8-81dd-49f5-9e43-f44a179a64ea" "Medium image id"
dice-deploy-cli input-add medium_flavor_id "45170672-5608-473e-af9c-9097510472d6" "Medium flavour id"
dice-deploy-cli input-add large_image_id "36dbc4e8-81dd-49f5-9e43-f44a179a64ea" "Large image id"
dice-deploy-cli input-add large_flavor_id "1bd34fe1-57b3-4937-bf60-5edd35382b78" "Large flavour id"
$ dice-deploy-cli set-inputs openstack-inputs.yaml
```

### FCO inputs
Expand Down Expand Up @@ -262,24 +273,26 @@ inputs:
inputs. Before calling them, replace the values in the example with the
appropriate ones for your environment:

```bash
dice-deploy-cli input-add agent_user ubuntu "Agent user"
dice-deploy-cli input-add small_image_id 87978c6d-5ceb-39b2-8e8b-935503ad0307 "Small image id"
dice-deploy-cli input-add small_server_type "2 GB / 1 CPU" "Small server type"
dice-deploy-cli input-add small_disk "30Gb Storage" "Small disk"
dice-deploy-cli input-add medium_image_id 87978c6d-5ceb-39b2-8e8b-935503ad0307 v
dice-deploy-cli input-add medium_server_type "2 GB / 1 CPU" "Medium server type"
dice-deploy-cli input-add medium_disk "30Gb Storage" "Medium disk"
dice-deploy-cli input-add large_image_id 87978c6d-5ceb-39b2-8e8b-935503ad0307 Large image
dice-deploy-cli input-add large_server_type "2 GB / 1 CPU" "Large server type"
dice-deploy-cli input-add large_disk "30Gb Storage" "Large disk"
dice-deploy-cli input-add username 089e2a3a-5ae9-34e4-b03c-c694268acf1c "FCO username"
dice-deploy-cli input-add password 'p@ssword' "FCO password"
dice-deploy-cli input-add customer e50bfd1b-253a-3290-85ff-95e218398b7e "FCO customer"
dice-deploy-cli input-add service_url "https://cp.diceproject.flexiant.net" "Service URL"
dice-deploy-cli input-add agent_key 288f0541-9921-37a8-a07b-bb47eb27dc10 "Agent key"
dice-deploy-cli input-add vdc 9799fe42-02ef-3929-88d4-c993a02cbe1d "FCO VDC"
dice-deploy-cli input-add network 5264edab-8d29-329d-b4f9-5f8ca17cff78 "FCO network"
```json
[
{"key": "agent_user", "value": "ubuntu", "description": "Agent user"},
{"key": "small_image_id", "value": "87978c6d-5ceb-39b2-8e8b-935503ad0307", "description": "Small image id"},
{"key": "small_server_type", "value": "2 GB / 1 CPU", "description": "Small server type"},
{"key": "small_disk", "value": "30Gb Storage", "description": "Small disk"},
{"key": "medium_image_id", "value": "87978c6d-5ceb-39b2-8e8b-935503ad0307", "description": "Medium image id"},
{"key": "medium_server_type", "value": "2 GB / 1 CPU", "description": "Medium server type"},
{"key": "medium_disk", "value": "30Gb Storage", "description": "Medium disk"},
{"key": "large_image_id", "value": "87978c6d-5ceb-39b2-8e8b-935503ad0307", "description": "Large image id"},
{"key": "large_server_type", "value": "2 GB / 1 CPU", "description": "Large server type"},
{"key": "large_disk", "value": "30Gb Storage", "description": "Large disk"},
{"key": "username", "value": "089e2a3a-5ae9-34e4-b03c-c694268acf1c", "description": "FCO username"},
{"key": "password", "value": "p@ssword", "description": "FCO password"},
{"key": "customer", "value": "e50bfd1b-253a-3290-85ff-95e218398b7e", "description": "FCO customer"},
{"key": "service_url", "value": "https://cp.diceproject.flexiant.net", "description": "Service URL"},
{"key": "agent_key", "value": "288f0541-9921-37a8-a07b-bb47eb27dc10", "description": "Agent key"},
{"key": "vdc", "value": "9799fe42-02ef-3929-88d4-c993a02cbe1d", "description": "FCO VDC"},
{"key": "network", "value": "5264edab-8d29-329d-b4f9-5f8ca17cff78", "description": "FCO network"}
]
```

## Container management
Expand Down
218 changes: 112 additions & 106 deletions doc/UserGuide.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,19 +10,16 @@ Integration. Please refer to the
for instructions on how to obtain the tool

The tool first expects the DICE deployment service URL to be set. This is
possible either through setting the environment variable `DICE_DEPLOY`:

```bash
$ export DICE_DEPLOY=10.10.20.35:8000
```

or by using the action `use`:
possible by using the action `use`:

```bash
$ dice-deploy-cli use http://10.10.20.35:8000
[INFO] - Trying to set DICE Deployment Service URL
[INFO] - Checking DICE Deployment Service URL
[INFO] - URL set successfully
```

This creates a file `.dice-deploy-url` to contain the URL.
This creates a file `.dds.conf` to contain the URL.

Next, we need to authenticate the client with the service. The user name and
password portions are set by the administrator in the service deployment input
Expand All @@ -31,10 +28,13 @@ password `pwd434`. We supply these credentials to the command line tool:

```bash
$ dice-deploy-cli authenticate user pwd434
[INFO] - Checking DICE Deployment Service URL
[INFO] - Authenticating
[INFO] - Authorization succeeded
```

This call will obtain and store the authentication token in the
`.dice-deploy-auth` file in the current folder.
This call will obtain and update the `.dds.conf` file with the authentication
token received as a response.
All the subsequent calls will use this token to authenticate.

Now we can create a container. This will be a virtual unit in the deployment
Expand All @@ -48,8 +48,11 @@ for humans to understand a container's purpose. We use `create` action:

```bash
$ dice-deploy-cli create "Acceptance test environment"
Creating a new container ... DONE.
Container UUID: 02bba363-fb85-4a54-8a2f-f1a11a25ad9d
[INFO] - Checking DICE Deployment Service URL
[INFO] - Checking DICE Deployment Service authentication data
[INFO] - Creating new container
02bba363-fb85-4a54-8a2f-f1a11a25ad9d
[INFO] - Successfully created new container
```

We now have a container known with the UUID `02bba363-fb85-4a54-8a2f-f1a11a25ad9d`.
Expand All @@ -62,65 +65,45 @@ $ export CONTAINER_UUID="02bba363-fb85-4a54-8a2f-f1a11a25ad9d"
We can use it to push a blueprint.

```bash
$ dice-deploy-cli deploy $CONTAINER_UUID ../example.tar.gz
Creating a new deployment ... DONE.
Deployment UUID: b0e1b028-8a8c-408c-b619-206257c20481
$ dice-deploy-cli deploy $CONTAINER_UUID ../examples/test-setup.yaml
[INFO] - Checking DICE Deployment Service URL
[INFO] - Checking DICE Deployment Service authentication data
[INFO] - Starting blueprint deployment
[INFO] - Successfully started new deploy
```

The command both loads the blueprint in the container and starts the deployment
process. A subsequent call to the same command will have replaced the blueprint,
first uninstalling the existing blueprint and then creating and deploying the
new one.

Again, we will save the obtained deployment UUID in an environment variable:

```bash
$ export DEPLOYMENT_UUID="b0e1b028-8a8c-408c-b619-206257c20481"
```

Deployment process normally takes several minutes, possibly half an hour or
even more. Considering that the `deploy` action just sends the blueprint to the
service and exits without waiting for the process to finish, we need to be able
to check for the status of the blueprint's deployment in the container. We can
use `status` of the deployment to do that:

```bash
$ dice-deploy-cli status $DEPLOYMENT_UUID
Obtaining deployment status ...
uploaded
```

In scripts, it is also useful to be able to wait for the deployment process to
finish before being able to proceed with the deployed application. The CLI
tool provides action `wait-deploy`, which blocks the execution of a script,
process. It does not wait for the deployment to finish, but just submits the
request to be processed and exits. To track the progress of the request, use
the `wait-deploy` action, which blocks the execution of a script,
internally looping until the deployment either succeeds or finishes with an
error:

```bash
$ dice-deploy-cli wait-deploy $CONTAINER_UUID
Current status: pending
Current status: pending
Current status: preparing_deploy
Current status: preparing_deploy
Current status: preparing_deploy
# ...
Current status: working
Current status: working
Current status: working
Current status: working
[INFO] - Checking DICE Deployment Service URL
[INFO] - Checking DICE Deployment Service authentication data
[INFO] - Waiting for deployment to terminate
[INFO] - Container busy, blueprint is uploading_to_cloudify
[INFO] - Container busy, blueprint is uploading_to_cloudify
[INFO] - Container busy, blueprint is preparing_deployment
[INFO] - Container busy, blueprint is preparing_deployment
[INFO] - Container busy, blueprint is installing
[INFO] - Container busy, blueprint is installing
[INFO] - Container busy, blueprint is installing
[INFO] - Container busy, blueprint is installing
# ...
[INFO] - Container busy, blueprint is installing
[INFO] - Container busy, blueprint is installing
[INFO] - Container busy, blueprint is installing
[INFO] - Deployment is done
```

The following are important final states:
The time for the deployment process to finish depends on complexity of the
blueprint and overall speed of the platform, so it could take anything from
a few minutes on an idle platform to more than an hour on a busy one.

* `deployed` - the final state after the deployment action, indicating success.
* `undeployed` - the final state after the undeployment action, indicating
success.
* `error` - indicates an error condition, which occurred during the deploying or
undeploying process.

Once the blueprint deploys, the returned status will be `deployed`. At this
point we can obtain the deployment's outputs. The outputs
Once the blueprint deploys, we can obtain the deployment's outputs. The outputs
are the values, which depend on the configuration of the blueprint and the
dynamic values such as dynamically assigned addresses or ports. Please note
that the command expects the container's ID, not the inner deployment's:
Expand All @@ -129,40 +112,86 @@ that the command expects the container's ID, not the inner deployment's:
$ dice-deploy-cli outputs $CONTAINER_UUID | python -mjson.tool
{
"outputs": {
* "storm_nimbus_gui": "http://172.16.95.145:8080",
* "zookeeper_endpoint": "172.16.95.148:2181"
"test_node_1_outputs": {
"description": "Test node 1 properties",
"value": "test_property_default_value"
},
"test_node_2_outputs": {
"description": "Test node 2 properties",
"value": "test_property_value"
}
}
}
```

At any time during a container's lifetime, we can also obtain a full status
of the container using `container-info`:

```bash
$ dice-deploy-cli container-info $CONTAINER_UUID | python -mjson.tool
[INFO] - Checking DICE Deployment Service URL
[INFO] - Checking DICE Deployment Service authentication data
[INFO] - Getting information about container 02bba363-fb85-4a54-8a2f-f1a11a25ad9d
[INFO] - Information successfully obtained
{
"blueprint": {
"errors": [],
"id": "367eba48-9c84-403d-940b-6da18c6c3db2",
"in_error": false,
"modified_date": "2016-08-16T14:11:51",
"outputs": {
"test_node_1_outputs": {
"description": "Test node 1 properties",
"value": "test_property_default_value"
},
"test_node_2_outputs": {
"description": "Test node 2 properties",
"value": "test_property_value"
}
},
"state_name": "deployed"
},
"busy": false,
"description": "Acceptance test environment",
"id": "02bba363-fb85-4a54-8a2f-f1a11a25ad9d",
"modified_date": "2016-08-16T14:11:52"
}

```

At this point we can re-issue the `deploy` action with the same or a different
blueprint. The deployment service will tear down the previous deployment and
start a new one.

When we want to free the resources created by the deploy, we can call the tear
down action on the blueprint:

```bash
$ dice-deploy-cli teardown $DEPLOYMENT_UUID
Deleting deployment ... DONE.
[INFO] - Checking DICE Deployment Service URL
[INFO] - Checking DICE Deployment Service authentication data
[INFO] - Removing deployment from container 02bba363-fb85-4a54-8a2f-f1a11a25ad9d
[INFO] - Deployment removal started successfully
```

Finally, we can also delete the container.

```bash
$ dice-deploy-cli delete $CONTAINER_UUID
Deleting container ... DONE.
[INFO] - Checking DICE Deployment Service URL
[INFO] - Checking DICE Deployment Service authentication data
[INFO] - Deleting container 02bba363-fb85-4a54-8a2f-f1a11a25ad9d
[INFO] - Deletion succeeded
```

## Command line tool action reference

Complete reference documentation is displayed when the tool is invoked with no
arguments. To get more in-depth documentation with examples for specific
command, use `dice-deploy-cli help COMMAND`.
command, use `dice-deploy-cli COMMAND -h`.

### General actions

* `help`: display help
* parameters: [command]
* example: `dice-deploy-cli help`
* example: `dice-deploy-cli help deploy`

* `use`: use the URL as the DICE deployment service URL
* parameters: url
* example: `dice-deploy-cli use http://109.231.122.46:8000`
Expand All @@ -176,19 +205,21 @@ command, use `dice-deploy-cli help COMMAND`.
These actions (except for `create`) require the container's UUID as a parameter.

* `create`: creates a new container
* parameters: description (optional)
* parameters: description
* returns: container-uuid
* example: `dice-deploy-cli create`
* example: `dice-deploy-cli create "Smart Energy streaming application"`

* `deploy`: creates a new deployment in the container
* parameters: container-uuid package-file-name
* parameters: container-uuid blueprint-file-name
* returns: deployment-uuid
* example: `dice-deploy-cli deploy $CONTAINER_UUID pi-cluster.tar.gz`
* example: `dice-deploy-cli deploy $CONTAINER_UUID storm.yaml`

* `wait-deploy`: after calling deploy, this will block until deploy finishes
* parameters: container-uuid
* parameters: [--poll-interval POLL_INTERVAL_SECONDS] container-uuid
* example: `dice-deploy-cli wait-deploy $CONTAINER_UUID`
* example: `dice-deploy-cli wait-deploy --poll-interval 15 $CONTAINER_UUID`

* `container-info`: reports container state
* parameters: container-uuid
Expand All @@ -204,42 +235,17 @@ These actions (except for `create`) require the container's UUID as a parameter.
* returns: dict of deployment parameters
* example: `dice-deploy-cli outputs $CONTAINER_UUID`

* `node-ips`: get a list of node IP host addresses in the container
* `teardown`: uninstalls and deletes an existing deployment from the container
* parameters: container-uuid
* returns: list of dictionaries of node properties
* example: `dice-deploy-cli node-ips $CONTAINER_UUID`

* `nodes`: get a list of nodes and their properties in the container
* parameters: container-uuid [raw]
* returns: list of dictionaries of node properties
* example: `dice-deploy-cli nodes $CONTAINER_UUID`


### Blueprint/deployment actions

These actions require deployment's UUID as a parameter.

* `status`: get deployment status
* parameters: deployment-uuid
* returns: the deployment's current status
* example: `dice-deploy-cli status $DEPLOYMENT_UUID`

* `teardown`: uninstalls and deletes an existing deployment
* parameters: deployment-uuid
* example: `dice-deploy-cli teardown $DEPLOYMENT_UUID`

* example: `dice-deploy-cli teardown $CONTAINER_UUID`

### Input actions

Next two actions make it possible to add and delete inputs on deployment
service.
### Inputs actions

* `input-add`: add an input that is added to all yamls (not archives!)
* parameters: key value description
* returns: dict, representing new input
* example: `dice-deploy-cli input-add large_flavor_id 654fee342 "flavor"`
The following action enables managing the input parameters, which will accompany
each blueprint when it is deployed through the DICE deployment service:

* `input-delete`: delete an input
* parameters: key
* returns: None
* example: `dice-deploy-cli input-delete large_flavor_id`
* `set-inputs`: load a new set of inputs to be applicable for any subsequent
deployments, with the old inputs values being replaced or purged
* parameters: inputs-json-file
* example: `dice-deploy-cli set-inputs inputs-openstack.json`

0 comments on commit 6a4e3e0

Please sign in to comment.