# Ansible Playbooks

Workflow steps can be created using Ansible playbooks for completion of tasks. To use playbooks, there are several prerequisite steps that need to be completed first. Additional information about Ansible playbooks can be found at Ansible Documentation - Ansible playbooks.

## Install Ansible Environment

To use Ansible Playbooks with Avantra, you need to install an Ansible environment. For information on how to do this, see Ansible Documentation - Installing Ansible. The environment needs to be installed on the OS running the Avantra master server.

## Integrating with Avantra

By default, you can run Ansible Playbooks with the Avantra Server user. This means no additional setup is required. If you want to run the Playbooks using another OS user, you can configure the Ansible Environment. Doing so means that Ansible needs to be available for the configured OS User.

To configure the Ansible Environment to use another OS user, not the Avantra Server user:

1. Click Configurations > Integrations.

2. Click the Ansible Environments tab.

3. Click New.

4. Add the information required to configure the environment.

5. Click Save.

   Clicking Save and set as default will set this environment as the default environment when adding a playbook as a step in a workflow.

## Add Credentials

When using the native integration from Ansible to Avantra’s server inventory, SSH credentials must be maintained on the server managed system. These credentials will be used for Ansible to connect to the the managed nodes. To add credentials:

1. Navigate to your Avantra server that will be a managed node for Ansible, a target for the workflow execution.

2. Double-click to open the information pane.

3. Click Credentials.

4. Enable the Ansible User (SSH) credentials.

5. Click the edit button and add the SSH credentials.

## Adding to a Workflow

To add an Ansible Playbook to a workflow as a step, the Playbook needs to be defined.

### Defining an Ansible Playbook

To define a Playbook to be used as a workflow step:

1. Click Automation > Step Library.

2. Click New > New Ansible step.

3. Add a name for your Ansible step.

4. Assign the step to a Namespace.

   | If using a Git repository to store playbooks, you need to ensure that the repository is linked to the Namespace you select.

5. Click Create.

In the step pane there is a text field where you can add in Ansible Playbook YAML code. For information on how to create playbooks, see Ansible Documentation - Creating a playbook

The Settings tab is where you can modify the Name and Namespace for the step, and add a description.

The Parameters tab is where you can add inputs for the step to use. Parameters consist of: - A Name. This is a unique value. - A Parameter Type. - A Type. - A Default Value - Documentation, which is an optional field for adding information about the parameter.

Parameters can be inserted into the playbook code by treating it as a variable. For example, a parameter with a name string can replace a string of text with its value, meaning path: `~/textstring.txt` can be written as path: `~/{{textstring}}.txt`.

The Documentation tab is where you can provide detailed information about the step.

The Test tab is used to test whether the step executes successfully before you add it to a workflow. You need to provide:

- A location to the Ansible Inventory the Ansible step is running on. This can be a relative path into a repository, an absolute path on the control node, a system, or a system selector.

  For information on Ansible inventories, see Ansible Documentation - Building Ansible inventories.

- An Ansible Environment, which is the user running the Ansible step. This has to match an OS User.

- A timeout time, in seconds.

- Any additional arguments. These are forwarded to the ansible playbook command. Any parameters created will be listed here, where you can define values.

Click Run playbook to test the step. If the test fails, then a return code 2 will be displayed.

### Adding to a workflow as a step

With the Playbook defined, it can be added to a workflow. To add an Ansible step to a workflow:

1. Click Automation > Workflows.

2. Double click the workflow to add a step to.

3. Click the Steps tab.

4. Click New, then Step from the dropdown.

5. Locate and select the Ansible Playbook step. It will be identifiable by AP.

You can define additional arguments for the step if the field is set to constant value. Click Edit to open the Input table dialog. Inputs added here will be used in the step.

The Environment for the step can be defined. The environment needs to match the user running the Ansible step.

The Inventory field is a required field and defines the inventory the Ansible step is running on. A relative path into a repository or an absolute path can be defined.

Alternatively, systems and system selectors can be selected. For information on Ansible inventories, see Ansible Documentation - Building Ansible inventories.

When the workflow is run, the Ansible step is included in the JSON output files. For information on exporting the JSON output files, see Exporting JSON results.