Create Ansible Inventories
Create static, dynamic, plugin, and remote Ansible inventories in Harness IaCM, configure dynamic sources from workspace resources, and filter hosts with attribute conditions.
An inventory defines the machines your playbooks target and the variables those machines carry. This guide shows you how to create a static inventory with manually defined hosts, a dynamic inventory that derives hosts from the resources in a Terraform or OpenTofu workspace, a plugin inventory that fetches hosts from a cloud provider through an Ansible inventory plugin, and a remote inventory that reads a static inventory file from a Git repository.
What you will learn from this topic
Inventory types: When to choose a static, dynamic, plugin, or remote inventory.
Static setup: Create an inventory and define hosts and groups manually.
Dynamic setup: Add a source that resolves hosts from workspace resources, select the host address attribute, and filter hosts with conditions.
Plugin setup: Point Harness at a Git-stored inventory plugin configuration and a cloud connector.
Remote setup: Point Harness at a Git-stored static inventory file and understand how inventory variables override it.
Variables: Attach inventory-level Ansible variables (passed as
--extra-vars) and environment variables (injected into the process environment), including secrets.
Before you begin
Harness account with IaCM enabled: You need Infrastructure as Code Management under Infrastructure in Harness. Go to Getting started with Harness Platform to access or create a Harness account.
Ansible concepts: Familiarity with hosts, groups, and inventories. Go to Configuration management with Ansible to review the concepts.
A provisioned workspace (dynamic inventories only): Dynamic sources resolve hosts from the resources of an IaCM workspace, so the workspace must exist and hold state. Go to Get started with IaCM to create and provision a workspace.
Git and cloud connectors (plugin inventories only): The plugin configuration file lives in a Git repository, and provider credentials come from a cloud connector. Go to Connect to a code repository and Cloud connectors to set these up.
Choose an inventory type
Harness IaCM supports four inventory types. Choose based on how your hosts come into existence:
Static: You define a list of hosts and groups manually. Best for fixed fleets, bastion hosts, and small stateful clusters where the topology is known and stable.
Dynamic: Hosts are derived dynamically from different sources, such as the resources of a Terraform or OpenTofu workspace. Best when provisioning creates or replaces hosts, because the inventory tracks state without manual updates.
Plugin: Hosts are fetched from a cloud provider by an Ansible inventory plugin, with the plugin configuration file stored in your Git repository. Best when your team already standardizes on plugins such as
aws_ec2orazure_rm.Remote: Hosts and groups are read from a static inventory file stored in a Git repository, instead of being entered manually in Harness. Best when you already maintain an INI-format inventory file in Git and want Harness to read it directly rather than re-entering hosts.
Create an inventory
Follow the interactive guide or the step-by-step instructions to create an inventory.
To create an inventory, do the following:
In the Harness UI, navigate to the IaCM module.
In the left sidebar under Configuration, select Inventories.
Select + New Inventory. The New Inventory dialog opens on the About Inventory step.
Enter a Name. An Id is generated automatically and cannot be changed after creation. Description and Tags are optional.
Under How do you want to set up the inventory?, select Static, Dynamic, Plugin, or Remote.
For Static and Dynamic, select Create. For Plugin or Remote, select Next and complete the extra steps described in the Plugin or Remote tab below.
After creation, Harness opens the inventory detail page with four tabs: Hosts, Variables, Activity History, and Configuration. The remaining setup differs by type.
A static inventory starts empty. You add groups and hosts manually on the Hosts tab.
Select + New Group to add a group, or + New Host to add a host directly.
For a group, enter a Group name and optionally select existing hosts that belong to it, then select Apply Changes.
For a host, enter the Host Address (for example,
web1.example.comor10.0.1.25), optionally assign it to groups, then select Apply Changes.
Go to Manage hosts and groups for the full host and group workflow, including host-level variables and connection settings.
A dynamic inventory resolves hosts from one or more sources. Each source points at an IaCM workspace and selects resources from its state.
To add a source, do the following:
On the inventory's Hosts tab, select + Source. The Source Configuration panel opens with three tabs: Configuration, Static Variables, and Dynamic Variables.
On the Configuration tab, enter a Name. The source identifier becomes the Ansible group name for the hosts it resolves.
Select the Workspace that provisions the hosts you want to configure.
Select the Resource Type to match (for example,
aws_instance). The list is populated from the resource types present in the workspace state.Select the Host Address Attribute. This is the resource attribute Ansible uses to connect to each host (for example,
public_dnsorpublic_ip).Optionally, under Filters (optional), select + Add Filter to narrow which resources become hosts. Go to Filter hosts with conditions.
Select Apply Changes.
At pipeline run time, Harness queries the workspace state, applies your filters, and renders each matching resource as a host in the source's group.
Add one source per logical tier. For example, a webservers source that selects aws_instance resources tagged Role=web, and a databases source that selects instances tagged Role=db. Playbooks can then target each group by the source identifier.
A plugin inventory uses an Ansible inventory plugin to fetch hosts from a cloud provider. The plugin configuration file (for example, aws_ec2.yml) lives in your Git repository, and a cloud connector supplies the provider credentials. Selecting Plugin extends the dialog into a three-step wizard.
On the About Inventory step, enter the name and select Plugin, then select Next.
On the Source step, define where the inventory configuration is stored:
Select Git Provider: Choose Harness Code Repository or Third-party Git provider.
Git Connector: Select the connector with read access to the repository (third-party providers only).
Repository: Select or enter the repository name.
Git Fetch Type: Choose Latest from Branch, Git Tag, or Commit SHA, and supply the branch, tag, or SHA.
Folder Path (optional): Enter the path to the folder containing your plugin configuration.
Select Next. On the Provider step, select a cloud provider for first-class integration (AWS, GCP, or Azure) or select Custom to use any other inventory plugin.
Select the Cloud Connector that holds the provider credentials.
Select Create.
At pipeline run time, the plugin queries the provider API through the connector credentials and renders the hosts your configuration file selects.
A plugin inventory's detail page differs from the other types: instead of a Hosts tab, it opens on an Inventory Definition tab that renders your plugin configuration file from Git. A typical aws_ec2.yaml looks like this:
A remote inventory reads a static, INI-format inventory file from a Git repository instead of hosts entered manually in Harness. Selecting Remote extends the dialog into a two-step wizard.
On the About Inventory step, enter the name and select Remote, then select Next.
On the Source step, define where the inventory file is stored:
Select Git Provider: Choose Harness Code Repository or Third-party Git provider.
Select Repository: Select or enter the repository name. The field shows a scope badge (Project, Organization, or Account) for the resolved repository.
Git Fetch Type: Choose Latest from Branch or Git Tag.
Git Branch: Select or enter the branch to fetch from (shown when Git Fetch Type is Latest from Branch). Commit SHA pinning is not supported for Remote inventories.
Inventory Path: Enter the path to the inventory file within the repository, for example
inventory/hosts.ini.
Select Create.
At pipeline run time, Harness fetches the inventory file from Git and parses its hosts and groups.
A remote inventory's detail page differs from the other types: instead of a Hosts tab, it opens on an Inventory Definition tab that renders the fetched inventory file from Git. A typical hosts.ini looks like this:
For every other inventory type, an inventory-level Variables row is the weakest source of precedence and is overridden by the same key defined in the Git-stored file. For a Remote inventory, this is reversed: inventory-level variables you define in the Harness UI are passed as --extra-vars, which is the strongest precedence in Ansible. A UI variable overrides the same key defined in group_vars or host_vars inside the repository, on every run, until you remove it from the Variables tab.
Filter hosts with conditions
Filters control which workspace resources a dynamic source turns into hosts. Each filter is a condition made of an attribute, an operator, and a value. Multiple filters combine with AND logic, so a resource must match every condition to be included.
To add a filter in the Source Configuration panel, do the following:
Select Add Filter.
Select the resource attribute to evaluate (for example,
tags.environment).Select an operator: equals, not equals, contains, does not contain, starts with, or ends with.
Enter the value to compare against (for example,
prod).
Some common filter patterns are:
Environment scoping:
tags.environmentequalsprodso only production resources are configured.Role scoping:
tags.Rolecontainswebso database instances never receive the web playbook.Naming conventions:
tags.Namestarts withedge-to select a named subset of a larger fleet.
Use dynamic variables from resource attributes
Dynamic sources can attach variables to every host they resolve, with values drawn from each resource's attributes or the workspace outputs. Use Harness expressions in the value field:
<+attributes.ATTRIBUTE_NAME>reads an attribute from the matched resource, for example<+attributes.private_ip>.<+outputs.OUTPUT_NAME>reads an output from the workspace, for example<+outputs.cluster_endpoint>.
For example, a dynamic variable with key region and value <+attributes.availability_zone> gives every resolved host a region host variable your playbook can reference as {{ region }}. Static values are also allowed and apply unchanged to every host in the source.
Add inventory variables
The inventory Variables tab has two independent editors: Ansible Variables and Environment Variables. Saving one collection does not affect the other.
Ansible variables
Ansible variables apply to every host in the inventory. Harness passes them to ansible-playbook as --extra-vars at run time. They are the right place for connection settings and shared configuration values that your playbook tasks reference directly.
To add Ansible variables, do the following:
Open the inventory and select its Variables tab.
Under Ansible Variables, select + Add Variable.
Set the Type (string or secret), enter the Key and Value, then select Save Changes.
A common baseline for SSH-based fleets stores the connection user as a string (ansible_user: ubuntu) and the private key as a secret-type variable (ansible_ssh_private_key_file) referencing a Harness secret. Secret values are masked in pipeline logs.
The precedence of inventory-level Ansible variables depends on inventory type:
Remote
Inventory variables are passed as --extra-vars and override variables defined in the Git-stored inventory file.
All other types
Inventory variables are the weakest precedence and are overridden by variables defined in the inventory file.
Environment variables
Environment variables are injected into the Ansible process environment before ansible-playbook runs. Use them for process-level settings such as ANSIBLE_HOST_KEY_CHECKING or custom tool paths. They are not passed as --extra-vars and are not available as Ansible variables in playbook tasks.
To add environment variables, do the following:
Open the inventory and select its Variables tab.
Under Environment Variables, select + Add Variable.
Set the Type (string or secret), enter the Key and Value, then select Save Changes.
Secret-typed environment variables are resolved at run time and masked in logs. Pipeline-defined environment values win collisions with inventory environment variables.
View activity history
The Activity History tab lists past executions that used this inventory, including the playbook, the pipeline execution, and the run status. Use it to correlate configuration runs with provisioning events and to audit who changed what, when.
Troubleshooting
Next steps
You created an inventory and connected it to real hosts, either manually, from workspace state, or from a Git-stored inventory file.
Go to Manage hosts and groups to add host-level variables, groups, and connection settings.
Go to Create Ansible playbooks to register the playbook that will run against this inventory.
Go to Example Ansible use cases to apply inventories to web fleets, patching, and compliance patterns.
Last updated
Was this helpful?