<commit_before>
.. _actions-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:

.. code-block:: ini

   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>]
    parameters:
     <parameter name>: <parameter value>

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

          * Full:

            .. code-block:: ini

               keyword: 
                - value1
                - value2
                - value3

          * Abbreviated:

            .. code-block:: ini

               keyword: [ value1, value2, value3 ]

**Examples**

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.

Prerequisites

* 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. 

.. tip:: 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
         :command:`fuel plugins --sync`.

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

         You can also download all task definitions, including the core and
         plugins tasks, for the environment with the command
         :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:

.. code-block:: ini

   - id: fuel-plugin-example-iotop
     type: shell
     role: '*'
     requires: [post_deployment_start]
     required_for: [post_deployment_end]
     parameters:
     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Ж

.. code-block:: console

   # 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

.. note:: 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<commit_msg>[Fuel Plugin SDK] Actions for existing roles in fuel-docs<commit_after>
.. _actions-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:

.. code-block:: ini

   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>]
    parameters:
     <parameter name>: <parameter value>

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

          * Full:

            .. code-block:: ini

               keyword: 
                - value1
                - value2
                - value3

          * Abbreviated:

            .. code-block:: ini

               keyword: [ value1, value2, value3 ]

**Examples**

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.

Prerequisites

* 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. 

.. tip:: 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
         :command:`fuel plugins --sync`.

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

         You can also download all task definitions, including the core and
         plugins tasks, for the environment with the command
         :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:

.. code-block:: ini

   - id: fuel-plugin-example-iotop
     type: shell
     role: '*'
     requires: [post_deployment_start]
     required_for: [post_deployment_end]
     parameters:
     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:

.. code-block:: console

   # 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

.. note:: 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
{'fraction_non_alphanumeric': 0.0761754068716094, 'fraction_numerical': 0.005198915009041591, 'mean_word_length': 2.5884022708840226, 'pattern_counts': {'":': 0, '<': 23, '<?xml version=': 0, '>': 31, 'https://': 0, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5630678', 'n_tokens_mistral': 2345, 'n_tokens_neox': 2199, 'n_words': 1143}