diff --git a/doc/AdminGuide.md b/doc/AdminGuide.md index 4a1083f..2eeecd4 100644 --- a/doc/AdminGuide.md +++ b/doc/AdminGuide.md @@ -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 @@ -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 diff --git a/doc/UserGuide.md b/doc/UserGuide.md index 78d3eb6..a692de8 100644 --- a/doc/UserGuide.md +++ b/doc/UserGuide.md @@ -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 @@ -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 @@ -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`. @@ -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: @@ -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` @@ -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 @@ -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`