diff --git a/docs/extra_vars.rst b/docs/extra_vars.rst deleted file mode 100644 index aed2361c..00000000 --- a/docs/extra_vars.rst +++ /dev/null @@ -1,75 +0,0 @@ -========================================= -Extra vars for playbooks or job templates -========================================= - -Extra vars needed by each playbook or job template should be explicitly -specified in the extra_vars section under actions in a rulebook. The values of -extra vars can be literals or references to rulebook variables. In addition to -the user specified extra vars, the rulebook engine automatically inserts -fact/event (single match) or facts/events (multiple matches) under the top -level key ansible_eda. - -Example of run_playbook and run_module actions: - -.. code-block:: yaml - - action: - run_playbook: - name: playbooks/hello.yml - extra_vars: - foo: "{{ FOO }}" - bar: BAR - -Example of run_job_template action: - -.. code-block:: yaml - - action: - run_job_template: - name: Demo - organization: Default - job_args: - extra_vars: - foo: "{{ FOO }}" - bar: BAR - -Example of a playbook that uses the extra_vars: - -.. code-block:: yaml - - - name: Print extra_vars - hosts: localhost - gather_facts: false - tasks: - - name: Print variable foo set by user - ansible.builtin.debug: - msg: '{{ foo }}' - - name: Print variable event set by rulebook engine - ansible.builtin.debug: - msg: '{{ ansible_eda.event }}' - -Rulebook variables can be loaded from a static file or selected from -environment variables through command line. - -Example to set rulebook variables through a static file: - -.. code-block:: php - - rulebook --vars myvars.yml --rulebook myrules.yml - -The content of myvars.yml: - -.. code-block:: php - - FOO: Foe - -Example to set rulebook variables through environment variables: - -.. code-block:: php - - export FOO=Foo - export BAR=Bar - rulebook --env-vars FOO,BAR --rulebook myrules.yml - -If there is a variable name conflict because of both --env-vars and --vars are -used, the ones from --env-vars take precedent. diff --git a/docs/index.rst b/docs/index.rst index 7c2f2d15..a7c5763e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -15,6 +15,7 @@ Welcome to Ansible Rulebook documentation rules conditions events_and_facts + variables host_limit multi_events actions diff --git a/docs/introduction.rst b/docs/introduction.rst index 187459d0..49621290 100644 --- a/docs/introduction.rst +++ b/docs/introduction.rst @@ -2,7 +2,7 @@ Introduction ==================== What is Event-Driven Ansible? ------------ +----------------------------- Event-Driven Ansible is a new way to enhance and expand automation. It improves IT speed and agility, while enabling consistency and diff --git a/docs/variables.rst b/docs/variables.rst new file mode 100644 index 00000000..99f9a330 --- /dev/null +++ b/docs/variables.rst @@ -0,0 +1,131 @@ +========= +Variables +========= + +Variables can be parsed into a rulebook using one or both of these command line arguments:: + + --vars VARS Variables file + --env-vars ENV_VARS Comma separated list of variables to import from the environment + +To import variables from a JSON or YAML formatted file, the `--vars` argument should be used. +To import environment variables the `--env-vars` argument should be used. It is possible to specify +multiple environment variables separated by a comma. + +.. important:: + Variables that are supplied using the `--vars` argument will have their data type preserved, but environment + variables parsed via `--env-vars` are always treated as strings. This is important to consider when parsing + variables into your rulebook. + +.. note:: + In cases where the same variable is supplied via `--env-vars` and `--vars`, the one from + `--env-vars` will always take precedence. + + +Accessing variables in your rulebook +------------------------------------ + +The are two important considerations to take into account when accessing variables in a rulebook: + + 1. In order to use variables in conditions, the variables supplied at runtime will be placed into a namespace + called **vars**. You must use the **vars.** prefix followed by the variable name to use variables in conditions. + + 2. Jinja substitution should be used when accessing variables in any other part of the rulebook, such as in + the source configuration or in actions. + +Let's take the following example rulebook: + + .. code-block:: yaml + + --- + - name: Testing vars + hosts: all + sources: + - ansible.eda.range: + limit: "{{ src_range_limit }}" + rules: + - name: Say Hello + condition: event.i == vars.match_this_int + action: + echo: + message: "Hi, I'm {{ MY_NAME }}." + +In this rulebook we use three different variables. One, **MY_NAME**, we will supply using an environment variable. +The other two will be supplied in a file called `vars.yml` which looks like this: + + .. code-block:: yaml + + --- + src_range_limit: 4 + match_this_int: 2 + +To run this rulebook we will need to use both `--vars` and `--env-vars` to parse the variables into the rulebook. Therefore, +we would execute the rulebook as follows: + + .. code-block:: console + + $ MY_NAME="Bob" ansible-rulebook -i inventory.yml --rulebook hello_there.yml --vars vars.yml --env-vars MY_NAME + +Which would return the following output: + + .. code-block:: console + + 2023-02-09 13:37:73.311337 : Hi, I'm Bob + +.. note:: + - To avoid potential issues with variable expansion, we recommend enclosing any value that contains Jinja substituted + variables in quotation marks, as shown in the above example. + - Note the use of the **vars.** prefix in the condition instead of Jinja substitution, which does not work when used in + conditions. Refer to the `Conditions `_ page for more information. + + +Providing extra vars to actions +------------------------------- + +The `run_playbook` and `run_job_template` actions include an optional parameter called **extra_vars** which can be used +for sending extra variables to the respective action. For example, you may have a playbook that runs remediation +tasks when an issue with a host is detected, but the playbook requires some variables to be provided at runtime +for it to execute properly. This is where the **extra_vars** parameter comes in. + +Extra vars needed by each playbook or job template should be explicitly specified in the **extra_vars** section +under the action in your rulebook. The values of extra vars may be literals, or references to other rulebook +variables. In addition to the user supplied runtime variables described above, the rulebook engine will automatically +insert event (single match) or events (multiple matches), ruleset and rule under the top level key **ansible_eda**. + +Example run_playbook action: + +.. code-block:: yaml + + action: + run_playbook: + name: playbooks/hello.yml + extra_vars: + foo: "{{ FOO }}" + bar: BAR + +Example run_job_template action: + +.. code-block:: yaml + + action: + run_job_template: + name: Demo + organization: Default + job_args: + extra_vars: + foo: "{{ FOO }}" + bar: BAR + +Example playbook that uses the extra_vars: + +.. code-block:: yaml + + - name: Print extra_vars + hosts: localhost + gather_facts: false + tasks: + - name: Print variable foo set by user + ansible.builtin.debug: + msg: '{{ foo }}' + - name: Print variable event set by rulebook engine + ansible.builtin.debug: + msg: '{{ ansible_eda.event }}'