DO274 - ch02s03

Bookmark this page

Configuring Event-Driven Ansible Controller to Run Ansible Rulebooks

Objectives

Set up new projects, the automation decision environment, and integration with automation controller so that Event-Driven Ansible controller can launch job templates based on events monitored by Ansible Rulebooks.

Event-Driven Ansible Controller Resources

Certain resources must be created and configured in Event-Driven Ansible controller before you can use it to run Ansible Rulebooks. The following list provides a brief explanation of each resource type.

Credentials: Credentials allow authentication to external resources. These external resources include container registries (such as private automation hub, quay.io, and so on), and source code management tools (such as GitLab and GitHub).
Projects: Projects contain Ansible Rulebooks and the rulebooks must be in either the rulebooks or extensions/eda/rulebooks directories in the project directory. If cloning the project repository requires authentication, then you must create a source code management credential. Currently, the only project source code management type available is Git, and the repository must be accessible via HTTP/HTTPS.
Automation decision environments: Automation decision environments are container images and they have a similar purpose to automation execution environments. Event-Driven Ansible controller uses automation decision environments to run rulebooks. Adding an automation decision environment might require a container registry credential.

Note

The Automation Hub Default Decision Environment automation decision environment is already created in the classroom environment.

Controller tokens: You need to create a controller token for every Event-Driven Ansible controller user. Controller tokens authenticate to automation controller for the purpose of running job and workflow templates from rulebooks. Automation controller must contain the job and workflow templates that the rulebooks are configured to launch.
Rulebook activations: Rulebook activations specify how to run a rulebook on Event-Driven Ansible controller. Each rulebook activation defines a project, a rulebook, and an automation decision environment. If desired, you can include variables that become available to your rulebook. Event-Driven Ansible controller runs any enabled rulebook activation.
Rule audits: Rule audits are generated automatically by Event-Driven Ansible controller when a rule in a running rulebook activation triggers an action. Clicking a rule name in the rule audit list enables you to inspect the event that triggered the rule and the action taken by the rule.

Creating Credentials

Use the following steps to create a credential resource in the Event-Driven Ansible controller.

Log in to the Event-Driven Ansible controller web UI.
Navigate to Access → Credentials and then click Create credential.
Figure 2.2: Creating a credential
Note
In the Token field, you can enter either a token or the password for the specified user.
Click Create credential to create the credential resource.

After you create the credential, the web UI displays the credentials details page. From there or from the credentials list view, you can edit or delete the credential.

Creating Projects

Creating a project depends upon the following resources:

A source code management (SCM) credential resource in the Event-Driven Ansible controller (if the SCM repository requires authentication)
An SCM repository containing rulebooks in either the rulebooks or extensions/eda/rulebooks directories in the project directory.

Use the following steps to create a project resource in the Event-Driven Ansible controller:

Log in to the Event-Driven Ansible controller web UI.
Navigate to Projects and then click Create project.
Complete the form and then click Create project to create the project resource.
Important
Git SCM is currently the only available option.
The SCM URL cannot be changed after the project is created.
After you create the project, the web UI displays the project details page. From there or from the projects list view, you can edit or delete the project.

Creating Controller Tokens

Creating a controller token requires that you have already created a user token in automation controller.

Use the following steps to create a user token in automation controller and then create the controller token resource in Event-Driven Ansible controller.

Log in to the automation controller web UI.
Click your username in the upper right of the page and then click User Details.
Figure 2.3: Automation controller user details
Click the Tokens tab and then click Add.
Figure 2.4: Creating a token
The following fields are available:
Field Description
Application The name of the application (optional)
Description A description of the token (optional)
Scope The level of access that the token has
Important
The Scope field must be set to Write.
Click Save to create the token. The web UI displays the generated token. Save or copy the value of the token.
Figure 2.5: Token display
Log in to the Event-Driven Ansible controller web UI.
Click your username in the upper right corner and then click User Details.
Click the Controller Tokens tab and then click Create controller token.
The following fields are available:
Field Description
Name The name of the controller token
Description A description of the controller token (optional)
Token The value of the token saved or copied from automation controller
Figure 2.6: Creating a controller token
Click Save to create the controller token. After you create the token, the web UI displays the Controller Tokens tab, where you can view the token details such as the expiration date, or delete the token.

Field	Description
`Application`	The name of the application (optional)
`Description`	A description of the token (optional)
`Scope`	The level of access that the token has

Field	Description
`Name`	The name of the controller token
`Description`	A description of the controller token (optional)
`Token`	The value of the token saved or copied from automation controller

Creating Ansible Rulebook Activations

Creating a rulebook activation requires that you have already created the following resources:

A controller token resource in the Event-Driven Ansible controller
A synced project that contains rulebooks in the Event-Driven Ansible controller
An automation decision environment resource in the Event-Driven Ansible controller

Use the following steps to create a rulebook activation resource in Event-Driven Ansible controller:

Navigate to Rulebook Activations and then click Create rulebook activation.

The following fields are available:

Field	Description
`Name`	The name of the rulebook activation
`Description`	A description of the rulebook activation (optional)
`Project`	The project that contains the rulebooks
`Rulebook`	The rulebook that the activation runs
`Decision environment`	The automation decision environment that runs the rulebook
`Restart policy`	A policy that decides when to restart the rulebook
`Variables`	Variable names and values to pass to the rulebook (optional)
`Rulebook activation enabled`	An option to enable the rulebook activation on creation

Figure 2.7: Creating a rulebook activation

Click Create rulebook activation to create the rulebook activation resource.

After you create the rulebook activation, the web UI displays the rulebook activation details page. From there or from the rulebook activation list view, you can edit or delete the rulebook activation.

Launching an Automation Controller Job Template or Workflow Template Using a Rulebook Activation

To run a job template or a workflow template using Event-Driven Ansible controller, a rulebook must use either the run_job_template or run_workflow_template actions.

The following is an example of using the run_job_template and run_workflow_template actions in a rulebook:

...output omitted...
      actions:
        - run_job_template:
            name: Sync production repository
            organization: Production

        - run_workflow_template:
            name: Build lastest version of production app
            organization: Production
...output omitted...

Both actions support the following arguments.

Field	Required	Description
`Name`	Yes	The name of the job or workflow template
`organization`	Yes	The name of the organization
`set_facts`	No	The artifacts from the job or workflow template execution that are inserted back into the ruleset as facts.
`post_events`	No	The artifacts from the job or workflow template execution that are inserted back into the ruleset as events.
`ruleset`	No	The name of the ruleset to post the event or assert the fact to. The default is the current ruleset.
`retry`	No	If the job or workflow template fails execution, retry it once. Takes a Boolean value of `true` or `false`
`retries`	No	If the job or workflow template fails execution, the number of times to retry it. Takes an integer value.
`delay`	No	The time interval between retries, specified in seconds. Takes an integer value.
`var_root`	No	If the event is a deeply nested dictionary, then the `var_root` field can specify the key name whose value should replace the matching event value. The `var_root` argument can take a dictionary to account for data when there are multiple matching events.
`job_args`	No	Additional arguments sent to the job or workflow template launch API. Any answers to the survey and other extra variables should be set in the `extra_vars` nested key. Events and facts are automatically included in `extra_vars` as well.

Note

To access event information from the ansible_eda namespace in the job or workflow template, either select the Prompt on launch checkbox in the Variables section of the template, or create a survey that includes the ansible_eda variable.

Figure 2.8: Variables prompt on launch

Viewing Rule Audits

Use the following steps to view audit details in Event-Driven Ansible controller.

Log in to the Event-Driven Ansible controller web UI.
Navigate to Rule Audit.
Figure 2.9: Rule audit list
The web UI displays a list of the rule audits.
Click the name of a rule audit to view details about the rulebook activation.
Figure 2.10: Audit details
The details page shows when the activation was triggered and if it was successful or not.
Click the Events tab to show the source event that was used.
Figure 2.11: List of audit events
Click the Actions tab to show the actions that were run.
Figure 2.12: List of audit actions
Note
If the rulebook activation ran the run_job_template or run_workflow_template actions, then the URL of the action name points to the corresponding job in automation controller.