Skip to main content

Create Ansible Playbooks

Last updated on

A playbook in Harness IaCM is a pointer to automation you maintain in Git: Harness stores the repository coordinates and fetches the playbook content at pipeline run time. This guide shows you how to register a playbook, attach playbook-level variables, and enable Ansible Galaxy so collection dependencies install automatically before the playbook runs.

What will you learn?​

  • Registration: Point Harness at the repository, branch or commit, and path where your playbook lives.
  • Variables: Attach playbook-scoped variables and environment variables, including secrets.
  • Ansible Galaxy: Enable automatic installation of collections from a requirements.yml file before execution.
  • Traceability: Review the playbook's activity history.

Before you begin​

  • Playbook in Git: Your playbook must be stored in a Git repository, either Harness Code Repository or a third-party provider. Go to Connect to a code repository to set up a connector with read access.
  • An inventory to target: Playbooks run against inventories at pipeline time. Go to Create Ansible inventories to create one.
  • A requirements file (Galaxy only): To install Galaxy dependencies automatically, the repository must contain a requirements file such as requirements.yml listing the collections your playbook needs.

Register a playbook​

Follow the interactive guide or the step-by-step instructions to register a playbook and enable Ansible Galaxy.

The playbook detail page opens with four tabs: Playbook Definition, Variables, Activity History, and Configuration.

Harness does not store or modify playbook content. Every pipeline run fetches from the configured Git coordinates, so pull requests, reviews, and tags on the playbook repository remain your source of truth.

tip

Pin production playbooks to a Git Tag or Commit SHA rather than a branch. Branch-based fetching always takes the latest commit, which means an unreviewed merge changes what production runs.

Add playbook variables​

Playbook variables travel with the playbook rather than the inventory, which makes them the right place for values that belong to the automation itself, independent of which hosts it targets.

To add variables, do the following:

  1. Open the playbook and select its Variables tab.
  2. Select + Variables and set the type (string or secret), key, and value.
  3. Select Save Changes.

Playbook variables and environment variables behave like their inventory counterparts: string values pass through as Ansible variables, secret values reference Harness secrets and are masked in logs, and environment variables are injected into the Ansible process environment. Go to Authenticate private Ansible Galaxy content for how secret-typed playbook variables reach the plugin at run time.

Install Ansible Galaxy dependencies​

Playbooks that use community or private collections need those collections installed in the execution container before the playbook runs. Instead of baking collections into a custom image, you can have Harness install them at run time from a requirements file in your playbook repository.

To enable Galaxy dependency installation on a playbook, do the following:

  1. Open the playbook and select its Configuration tab.
  2. Under the Ansible Galaxy section, turn on the Enable Ansible Galaxy toggle.
  3. In Requirements File, enter the path to your requirements file in the connected repository, for example requirements.yml. The requirements file path is required when the toggle is on.
  4. Select Apply Changes.

At pipeline run time, the Harness Ansible plugin runs ansible-galaxy collection install -r <requirements file> as a pre-flight step, after cloning the repository and before executing the playbook.

A typical requirements.yml looks like this:

collections:
  - name: community.general
  - name: ansible.posix
    version: ">=1.5.0"
  - name: my_namespace.my_collection
info

Collections hosted on a private Galaxy server, Red Hat Automation Hub, or a private Git repository need credentials at install time. Go to Authenticate private Ansible Galaxy content to configure ANSIBLE_GALAXY_SERVER_* settings, Git credential triples, or .netrc authentication.

tip

Runtime installation adds time to every pipeline run and depends on the Galaxy server being reachable. For production pipelines with stable dependencies, consider a pre-built image with collections baked in. Go to Manage playbook dependencies to compare both approaches.

View activity history​

The playbook's Activity History tab lists executions that used this playbook, with the inventory, pipeline execution, and status of each run. Use it together with the inventory activity history to answer what ran, where, and when.

Troubleshooting​

Ansible Galaxy requirements file must be set error when saving a playbook in Harness IaCM

When the Ansible Galaxy option is enabled, the requirements file path is required. Enter the path relative to the repository root, for example requirements.yml, or disable the option.

ansible-galaxy collection install fails during the pre-flight phase in a Harness IaCM pipeline

Check that the requirements file path is correct relative to the repository root and that the execution environment can reach the Galaxy server. For private servers, configure ANSIBLE_GALAXY_SERVER_* authentication settings.

Playbook not found error in Harness IaCM pipeline because repository, branch, or path is incorrect

Verify the Git connector, repository, branch or commit, and folder path on the playbook configuration, and confirm the connector has read access to that branch.

Next steps​

Your playbook is registered with its dependencies handled, ready to run against an inventory.