Skip to main content
Version: 25.x

Ansible Playbooks

Avantra can execute Ansible Playbooks as workflow steps. See Ansible Documentation - Ansible playbooks for general Ansible reference.

Prerequisites​

Install Ansible​

To use Ansible Playbooks with Avantra, you need to install an Ansible environment. Ansible must be installed on the OS running the Avantra master server. See Ansible Documentation - Installing Ansible for more information.

Configure the Ansible environment​

By default, Ansible Playbooks are run using the Avantra Server user, with no additional setup required. You can run playbooks as a different OS user by configuring the Ansible environment:

  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.
  6. 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 SSH credentials​

SSH is used to connect to managed nodes. Credentials must be set on each Avantra server that will act as an Ansible managed node:

  1. Navigate to your Avantra server that will be a managed node for Ansible.
  2. Double-click to open.
  3. Click Credentials.
  4. Enable the Ansible User (SSH) credentials.
  5. Click the edit button and add the SSH credentials.

Defining a playbook step​

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

  1. Click Automation > Step Library.
  2. Click New > New Ansible step.
  3. Enter a Name and assign a Namespace.
note

If playbooks are stored in a Git repository, the repository must be linked to the selected namespace.

  1. Click Create.
  2. Paste or write the Ansible Playbook YAML in the step editor. See Ansible Documentation - Creating a playbook.

Use the tabs to configure the step further:

  • Settings: Edit the name, namespace, and description.
  • Parameters: Add inputs for the playbook. Each parameter has a name, parameter type, type, optional default value, and optional documentation. Parameters can be instered as variables using YAML. 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.
  • Documentation: Add usage notes visible in the workflow builder.
  • Test: Test the step before adding it to a workflow.

Testing a playbook step​

In the Test tab, provide:

  • A path to the Ansible inventory (relative reposit path, absolute path on the control node, or a system / system selector). For information on Ansible inventories, see Ansible Documentation - Building Ansible inventories.
  • An Ansible Environment that is the user running the Ansible step. This must match an OS User.
  • A timeout time, in seconds.
  • Any additional arguments, which are forwarded to the ansible-playbook command. Any defined parameters appear here for value entry.

Click Run playbook to test the step. A return code of 2 indicates failure.

Adding to a workflow as a step​

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 (identifiable by AP).
  6. Click Edit to open the Input table to configure the step with:

Ansible step results are included in the workflow's JSON output files. For information on exporting the JSON output files, see Exporting JSON results.