Actions for existing roles

Actions for existing rolesΒΆ

The deployment_tasks.yaml file contains tasks that define actions. The tasks that define actions execute on the existing roles.

Basic syntax for a task definition:

- id: <task id>
  type: <type of task>
  groups: [<one or more of existing roles>]
  required_for: [<the list of tasks, which requires this one>]
  requires: [<the list of tasks, which a required for this one>]
   <parameter name>: <parameter value>


You can represent the lists in the full form or the abbreviated form:

  • Full:

     - value1
     - value2
     - value3
  • Abbreviated:

    keyword: [ value1, value2, value3 ]


We will provide examples of tasks that define actions. We will also provide examples of how to test the tasks.

We will list possible keyword values for reference.


  • A deployed Fuel environment with one controller node and one compute node.
  • A plugin enabled in the environment settings.

You can make live changes to the plugin’s deployment tasks, as this is much faster to test the changes this way rather than do the full environment reinstallation for every task change.


Here is how plugin live update works. When a plugin is installed, its files are in the directory /var/www/nailgun/plugins/<plugin name> on the Fuel Master node: plugin root directory or plugin root; the definitions of tasks are in the Nailgun database.

To quickly change and debug the plugin tasks, edit the files in the /var/www/nailgun/plugins/<plugin name> directory without rebuilding and reinstalling the plugin. Then synchronise the Nailgun database content with the filesystem with the command fuel plugins --sync.

You can also update the plugin from one version to a newer one with the command fuel plugins --update <rpm package for a new version of the plugin>. In this case you also need to run fuel plugins --sync after that.

You can also download all task definitions, including the core and plugins tasks, for the environment with the command fuel env --env <env-id> --deployment-tasks --download and verify that your plugin’s tasks are present by searching for the task IDs.

You can also change the tasks inside this file directly and then upload it. This way you can change and debug the already existing core tasks on the Fuel Master node in /etc/puppet/modules, not related to your plugin, but this is outside of the scope of this guide.

To make it simple, we will delete the automatically generated tasks.yaml and deployment_tasks.yaml files. We will create a new deployment_tasks.yaml from scratch.

Add a task to execute shell commands:

- id: fuel-plugin-example-iotop
  type: shell
  role: '*'
  requires: [post_deployment_start]
  required_for: [post_deployment_end]
  cmd: apt install iotop && echo `date` ' iotop installed' >>
  /tmp/post_deployment || echo `date` ' failed to install iotop'
  >> /tmp/post_deployment

Then sync the plugin tasks, execute the newly defined one, and verify the results:

# fuel plugins --sync
# fuel node  --nodes 1,2 --tasks fuel-plugin-example-iotop
# ssh node-1 "cat  /tmp/post_deployment;  iotop --version"
Fri May 20 12:48:08 UTC 2016  iotop installed
iotop 0.6


In the snippet above, the values for the node IDs and the node name are just examples and they may differ from the ones in your installation. To find the correct values, use the command fuel nodes.

The task in the example executes the shell commands listed in the parameter cmd: the task installs the package iotop on all the nodes in the environment; or, in our test, in the subset listed after the key ‘–nodes’. Pay attention to the parameters requires and required_for: they define when exactly during installation the task will run and are required for the task execution. The task will usually run in the post-deployment stage, but in our example we forced it to run alone. After the task execution, you can use the command iotop to monitor the I/O on the environment nodes.


If you receive the error message 400 Client Error: Bad Request (Problem with loading YAML file /var/www/nailgun/plugins/ fuel-plugin-example-1.0/deployment_tasks.yaml), verify the syntax of deployment_tasks.yaml.

The error 400 Client Error: Bad Request (Tasks fuel-plugin-example -iotop are not present in deployment graph) means that your tasks failed to synchronise with the Nailgun database or that your plugin is not enabled for the environment with the nodes that you specified.

If other issues, check the Astute log on the Fuel Master node at /var/log/docker-logs/astute/astute.log. Alternatively, check the Logs tab in the Fuel web UI.

In our example, we used the asterisk ‘*’ as the value for the keyword role. To run the tasks only on particular roles, but not the others, replace the value with the list of roles on which to run; for example:

role: [ primary-controller, controller, compute]


Use the list even if your task needs to run on only one role; for example role: [compute]. This will not work: role: compute.


The roles primary-controller and controller are not the same. The controller role does not include the primary-controller role, so they should be specified explicitly.


While you can run tasks on particular roles, you cannot run tasks on all roles except a particular role. For example, there is option to run tasks on all roles except for a compute role.

Our example task with the commands listed in the cmd parameter is not suitable for more than two shell commands; but we always can put the commands in a shell script and call the script instead:

 cmd: bash

Put the script in the subdirectory deployment_scripts in plugin root. If you run the plugin task, the result will be the same as in the previous case, when we defined all the commands in deployment_tasks.yaml.

The mechanism behind this is as follows. Before the plugin task runs, all the files inside the plugin root are synced by rsync protocol to the directory /etc/fuel/plugins/<plugin name> on target nodes. This directory is set as the default working directory for plugin tasks – although you can override it by specifying the explicit cwd parameter for the task, so the command bash will run the script from it.

Considering that deployment scripts are copied to target nodes before any of the tasks run, you can skip the step for syncing tasks if you only change the contents of the deployment scripts in the process of debugging and run the tasks directly after the changes.

You can use any script language or executable as long as they can be called from shell, but Puppet is the most common tool to write Fuel plugins and there is support for Puppet tasks.

Let us rewrite the same task using Puppet manifests.


- id: fuel-plugin-example-iotop
  type: puppet
  role: '*'
  requires: [post_deployment_start]
  required_for: [post_deployment_end]
   puppet_manifest: puppet/manifests/install_iotop.pp
   puppet_modules: puppet/modules:/etc/puppet/modules


notice('MODULAR: fuel-plugin-example/iotop')

package { 'iotop':
  ensure => 'installed',


All plugin tasks must be idempotent: each plugin task must be able to run multiple times without changing the results. Puppet manifests have an inherent advantage of idempotency and this is one of the reasons to use Puppet for plugin tasks.

We changed the type attribute of the deployment task to puppet and replaced the cmd parameter with the two Puppet specific ones: puppet_manifest and puppet_modules. If you are familiar with Puppet, these parameters are self-explanatory. The values of the parameters are path specifications relative to the deployment_scripts directory in plugin root. Follow the standard Puppet conventions and keep Puppet manifests in modules in separate subdirectories. In our example we are using no modules, but in any other not so trivial case it is good to keep the code modular. The parameter puppet_modules is required.


Pay attention to the first line of our Puppet manifest:

notice('MODULAR: fuel-plugin-example/iotop')

This is a convention to start any of your Puppet tasks in a plugin with the notice statement that starts with a substring MODULAR: followed by the name of the plugin and the name of the task itself. This output is in the Puppet logs. You can find the output in the Logs`of the Fuel web UI, at `/var/log/puppet.log`` on the Fuel target node, or at /var/log/remote/<target node IP>//puppet-apply.log. This convention is very helpful for debugging.

Related links

See also Deployment Tasks on Fuel Wiki.

Creative Commons Attribution 3.0 License

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.