openstack/tripleo-docs
Code Issues Proposed changes

Mistral API Documentation

Browse Source 
This initial Mistral API documentation covers the following topics:

- Register and introspect nodes
- Create and update plans
- Update and set Heat parameters
- Deploy the plan.

Change-Id: I36ddc04ae883f56ce0d816392630b330819120c5
This commit is contained in:
Dougal Matthews 2016-08-22 15:40:16 +01:00
parent 0f7b059cd9
commit d927b28a10
2 changed files with 320 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/source/index.rst
View File

@ -18,6 +18,7 @@ Contents:
advanced_deployment/backends
advanced_deployment/custom
troubleshooting/troubleshooting
mistral-api/mistral-api
developer/developer
contributions/contributions

319
doc/source/mistral-api/mistral-api.rst Normal file
View File

@ -0,0 +1,319 @@
Mistral API
===========
The public API for TripleO uses the OpenStack Workflow service, `Mistral`_ to
provide its interface. This allows external systems to consume and use the same
Workflows used by python-tripleoclient and tripleo-ui.
Working with Mistral
--------------------
TripleO functionality can be accessed via Mistral Workflows and Actions.
Workflows define a set number of steps and typically use a number of actions.
There is a set of actions which are intended to be used directly. When actions
are called directly, Mistral executes them synchronously which is quicker for
simple actions.
Mistral can be used with the CLI interface or Python bindings which are both
provided by `python-mistralclient`_ or via the `REST API`_ directly. This
guide will use the Mistral CLI interface for brevity.
When using the CLI, all of the TripleO workflows can be viewed with the
command ``openstack workflow list``. All of the workflows provided by TripleO
will have a name starting with ``tripleo.``
.. code-block:: plain
$ openstack workflow list
+--------------------------------------+-----------------------------------------+------------------------------+
| ID | Name | Input |
+--------------------------------------+-----------------------------------------+------------------------------+
| 1ae040b6-d330-4181-acb9-8638dc486b79 | tripleo.baremetal.v1.set_node_state | node_uuid, state_action, ... |
| 2ef20a58-b380-4b6b-a6cd-270352d0f3d2 | tripleo.deployment.v1.deploy_on_servers | server_name, config_name,... |
+--------------------------------------+-----------------------------------------+------------------------------+
To view the individual workflows in more detail and see the inputs they
accept use the ``openstack workflow show`` command. This command will also
show the default values for input parameters. If no default is given, then it
is required.
.. code-block:: plain
$ openstack workflow show tripleo.plan_management.v1.create_default_deployment_plan
+------------+-----------------------------------------------------------+
| Field | Value |
+------------+-----------------------------------------------------------+
| ID | fa8256ec-b585-476f-a83e-e800beb26684 |
| Name | tripleo.plan_management.v1.create_default_deployment_plan |
| Project ID | 65c5259b7a96436f898fd518815c42c1 |
| Tags | <none> |
| Input | container, queue_name=tripleo |
| Created at | 2016-08-19 10:07:10 |
| Updated at | None |
+------------+-----------------------------------------------------------+
This workflow can then be executed with the ``openstack workflow execution
create`` command.
.. code-block:: plain
$ openstack workflow execution create tripleo.plan_management.v1.create_default_deployment_plan \
'{"container": "my_cloud"}'
+-------------------+-----------------------------------------------------------+
| Field | Value |
+-------------------+-----------------------------------------------------------+
| ID | 824a8cf7-3306-4ef2-8efd-a2715dd0dbce |
| Workflow ID | fa8256ec-b585-476f-a83e-e800beb26684 |
| Workflow name | tripleo.plan_management.v1.create_default_deployment_plan |
| Description | |
| Task Execution ID | <none> |
| State | RUNNING |
| State info | None |
| Created at | 2016-08-22 12:33:35.493135 |
| Updated at | 2016-08-22 12:33:35.495764 |
+-------------------+-----------------------------------------------------------+
After a Workflow execution is created it will be scheduled up by Mistral and
executed asynchronously. Mistral can either be polled until it is finished or
you can subscribe to the `Zaqar`_ queue for messages from the running
Workflow. By default the TripleO workflows will send messages to a Zaqar queue
with the name ``tripleo``, the workflows all accept a ``queue_name`` parameter
which allows a user defined queue name to be used. It can be useful to use
different queue names if you plan to execute multiple workflows and want the
messages to be handled individually.
Actions can be used in a similar way to workflows, but the CLI commands are
``openstack action definition list``, ``openstack action definition show``
and ``openstack action execution run``.
`API reference documentation`_ is available for all TripleO Workflows.
Creating a Deployment Plan
--------------------------
Deployment plans consist of a Swift container and a Mistral Environment. The
TripleO Heat Templates are stored in Swift and then user defined parameters are
stored in the Mistral environment.
Using the default plan
^^^^^^^^^^^^^^^^^^^^^^
When the undercloud is installed, it will create a default plan with the name
``overcloud``. To create a new plan from the packaged version of
tripleo-heat-templates on the undercloud use the workflow
``tripleo.plan_management.v1.create_default_deployment_plan``. This workflow
accepts a name which will be used for the Swift container and Mistral
environment.
The following command creates a plan called ``my_cloud``.
.. code-block:: plain
$ openstack workflow execution create tripleo.plan_management.v1.create_default_deployment_plan \
'{"container": "my_cloud"}'
+-------------------+-----------------------------------------------------------+
| Field | Value |
+-------------------+-----------------------------------------------------------+
| ID | dc4800ef-8d0a-436e-9564-a7ee81ba93d5 |
| Workflow ID | fa8256ec-b585-476f-a83e-e800beb26684 |
| Workflow name | tripleo.plan_management.v1.create_default_deployment_plan |
| Description | |
| Task Execution ID | <none> |
| State | RUNNING |
| State info | None |
| Created at | 2016-08-23 10:06:45.372767 |
| Updated at | 2016-08-23 10:06:45.376122 |
+-------------------+-----------------------------------------------------------+
.. note::
When updating the packages on the undercloud with yum the TripleO Heat
Templates will be updated in `/usr/share/..` but any plans that were
previously created will not be updated automatically. At the moment this
is a manual process.
Using custom templates
^^^^^^^^^^^^^^^^^^^^^^
Manually creating a plan with custom templates is a three stage process. Each
step must use the same name for the container, we are using ``my_cloud``, but
it can be changed if they are all consistent. This will be the plan name.
1. Create the Swift container.
.. code-block:: bash
openstack action execution run tripleo.plan.create_container \
'{"container":"my_cloud"}'
.. note::
Creating a swift container directly isn't sufficient, as this Mistral
action also sets metadata on the container and may include further
steps in the future.
2. Upload the files to Swift.
.. code-block:: bash
swift upload my_cloud path/to/tripleo/templates
3. Trigger the plan create Workflow, which will create the Mistral environment
for the uploaded templates, do some initial template processing and generate
the passwords.
.. code-block:: bash
openstack workflow execution create tripleo.plan_management.v1.create_deployment_plan \
'{"container":"my_cloud"}'
Register and Introspect Baremetal Nodes
---------------------------------------
Baremetal nodes can be registered with Ironic via Mistral. This functionality
is provided by the ``tripleo.baremetal`` workflows.
Register Nodes
^^^^^^^^^^^^^^
The input for this workflow is a bit larger, so this time we will store it in
a file and pass it in, rather than working inline.
.. code-block:: bash
$ cat nodes.json
{
"remove": false,
"ramdisk_name": "bm-deploy-ramdisk",
"kernel_name": "bm-deploy-kernel",
"instance_boot_option": "local",
"nodes_json": [
{
"pm_password": "$RSA_PRIVATE_KEY",
"pm_type": "pxe_ssh",
"pm_addr": "192.168.122.1",
"mac": [
"00:8f:61:0d:6a:e1"
],
"memory": "8192",
"disk": "40",
"arch": "x86_64",
"cpu": "4",
"pm_user": "root"
}
]
}
* If ``remove`` is set to true, any nodes that are not passed to the workflow
will be removed.
* ``ramdisk_name`` and ``kernel_name`` are the Glance names for the kernel and
ramdisk to use for the nodes.
* ``instance_boot_option`` defines whether to set instances for booting from
the local hard drive (local) or network (netboot).
* The format of the nodes_json is documented in :ref:`instackenv`.
.. code-block:: bash
$ openstack workflow execution create tripleo.baremetal.v1.register_or_update \
nodes.json
The result of this workflow can be seen with the following command.
.. code-block:: bash
$ mistral execution-get-output $EXECUTION_ID
{
"status": "SUCCESS",
"new_nodes": [],
"message": "Nodes set to managed.",
"__task_execution": {
"id": "001892c5-4197-4c04-af74-aff95f6d584f",
"name": "send_message"
},
"registered_nodes": [
{
"uuid": "93feecfb-8a4d-418c-9f2c-5ef8db7aff2e",
...
},
]
}
The above information is accessible like this, or via the zaqar queue. The
registered_nodes property will contain each of the nodes registered with all
their properties from Ironic, including the UUID which is useful for
introspection.
Introspect Nodes
^^^^^^^^^^^^^^^^
To introspect the nodes, we need to either use the Ironic UUID's returned by
the register_or_update workflow or retrieve them directly from Ironic. Then
those UUID's can be passed to the introspection workflow. The workflow expects
nodes to be in the "manageable" state.
.. code-block:: bash
$ openstack workflow execution create tripleo.baremetal.v1.introspect \
'{"nodes_uuids": ["UUID1", "UUID2"]}'
Provide Nodes
^^^^^^^^^^^^^
After the nodes have been introspected they will still be in the manageable
state. To make them available for a deployment, use the provide workflow,
which has the same interface as introspection.
.. code-block:: bash
$ openstack workflow execution create tripleo.baremetal.v1.provide \
'{"nodes_uuids": ["UUID1", "UUID2"]}'
Parameters
----------
A number of parameters will need to be provided for a deployment to be
successful. These required parameters will depend on the Heat templates that
are being used. Parameters can be set with the Mistral Action
``tripleo.parameters.update``.
.. node::
This action will merge the passed parameters with those already set on the
plan. To set the parameters first use ``tripleo.parameters.reset`` to
remove any old parameters first.
In the following example we set the ``ComputeCount`` parameter to ``2`` on the
``my_cloud`` plan. This only sets one parameter, but any number can be provided.
.. code-block:: bash
$ openstack action execution run tripleo.parameters.update \
'{"container":"my_cloud", "parameters":{"ComputeCount":2}}'
Deployment
----------
After the plan has been configured it should be ready to be deployed.
.. code-block:: bash
$ openstack workflow execution create tripleo.deployment.v1.deploy_plan \
'{"container": "my_cloud"}'
Once the deployment is triggered, the templates will be processed and sent to
Heat. This workflow will complete when the Heat action has started, or if there
are any errors.
Deployment progress can be tracked via the Heat API. It is possible to either
follow the Heat events or simply wait for the Heat stack status to change.
.. _Mistral: http://docs.openstack.org/developer/mistral/
.. _python-mistralclient: http://docs.openstack.org/developer/mistral/guides/mistralclient_guide.html
.. _REST API: http://docs.openstack.org/developer/mistral/developer/webapi/index.html
.. _Zaqar: http://docs.openstack.org/developer/zaqar/
.. _API Reference Documentation: http://docs.openstack.org/developer/tripleo-common/reference/index.html