Integrate Terraform with Ansible Automation Platform

Authors: Simon Lynch and Prakash Manglanathan

This validated pattern integrates HCP Terraform (or Terraform Enterprise) with RedHat Ansible Automation Platform (AAP).

Customers who use Terraform, Ansible, or both, often ask if they could enhance their workflow by combining the two solutions, and how to decide when to use each tool for specific tasks. This can be confusing, as for some use cases the capabilities of each solution seem to overlap. Terraform and Ansible complement one another, and this pattern provides clear direction on when to use each across the infrastructure lifecycle.

We focus on the enterprise editions of Terraform and Ansible, as relying on Terraform Community Edition or Ansible OSS is not recommended for enterprise use cases due to limited governance, weaker security guardrails, and increasing maintenance complexity over time.

Target audience

This guide references the following roles:

• Platform team (responsible for infrastructure automation)
• Security team

Prerequisites

• Review the Terraform Operating Guide for Adoption
• Review the Terraform AAP provider documentation
• Privileged access to HCP & Ansible Automation Platform
• Privileged access to Vault & Packer (Optional)

This guide assumes the reader has a good understanding of HCP Terraform and Ansible Automation Platform concepts and has established those as a shared service.

Background and best practices

HCP Terraform and Ansible Automation Platform take complementary approaches to infrastructure automation. Terraform focuses on idempotent infrastructure provisioning, using graph-based dependency resolution and centralized state management to ensure consistent resource creation and modification. Ansible focuses on imperative automation with an agentless, push-based execution model that excels at configuration management and application deployment workflows.

As architects design their automation strategies, understanding these design differences ensures they select the right tool for the right job within an end to end automation workflow.

The following table provides an overview of the key design differences and strengths, helping you better understand where Terraform and Ansible excel and how they complement each other:

Choosing between Terraform and Ansible Automation Platform is not binary. Each tool brings unique strengths that are most powerful when used together. Effective enterprise automation strategies use both tools strategically throughout the infrastructure automation lifecycle. Terraform excels at infrastructure provisioning and state management, while Ansible excels at configuration management and post-provisioning orchestration.

When designing your automation architecture, consider the target personas and specific use cases. Prioritize efficiency and user experience to ensure successful adoption and operational effectiveness. Focus on defining responsibility boundaries for each tool and establishing seamless handover processes between them. This ensures reliable, end-to-end automation across your infrastructure environment.

Immutable versus mutable infrastructure

You can manage resources such as VMs and containers using either immutable or mutable patterns. Immutable infrastructure uses golden images defined in tools like Packer and Ansible that embed configurations directly into templates. Mutable infrastructure undergoes configuration after provisioning and deployment.

While immutable infrastructure is generally preferred, certain scenarios (for example, those involving legacy applications and processes) still require mutable approaches. In practice, enterprises often adopt a hybrid model that combines both.

In this hybrid model, Terraform provisions VMs from templated golden images, and triggers Ansible Automation Platform job templates and workflows for configuration management. This hybrid approach balances infrastructure consistency with operational flexibility, while reducing provisioning time and improving the overall user experience.

The following diagram outlines this workflow with an AWS EC2 example, though this workflow is applicable to any cloud or on premise virtual machine.

Terraform and Ansible use cases

The table below includes some common scenarios and describes how to use Terraform and Ansible Automation Platform to implement the solution. Bias towards supported ecosystem integrations rather than building custom coded solutions.

Approaches to integrate the use cases.

Validated architecture

The main components of this integration are:

• Your VCS repository that stores Terraform and Ansible code
• HCP Terraform or Terraform Enterprise
• Ansible Automation Platform
• Vault and Packer are optional and recommended

In the following diagram we demonstrate a high level architecture of the integration between HCP Terraform and Ansible Automation Platform.

1. Terraform agent connects to retrieve Terraform configuration and necessary variables from the workspace requesting the run.
2. Terraform agent connects to the cloud API (e.g. AWS API) to request resources such as the VM to provision.
3. Cloud API provisions the VM defined in the Terraform configuration.
4. Terraform agent connects to AAP and provides the VM host address, SSH credentials, and details of the playbook to execute.
5. AAP uses the host address and SSH to connect to the VM and perform configuration as defined in the playbook.

We recommend using Vault to manage the SSH credentials used in virtual machine fleets.

The following diagram shows a more detailed architecture with Vault, Terraform, and Ansible object hierarchy shown for clarity.

People and process

The Terraform Operating Guide for Adoption has extensive discussion on the people and process recommendations to onboard HCP Terraform or Terraform Enterprise. In this section we describe in brief the core teams and their roles & responsibilities as relating to managing this technology integration.

The two main teams are the platform team and the application team. This section describes how they work together to securely build and deploy applications at scale and deliver value for your customers.

Platform team

• Primarily owns and operates VCS, HCP Terraform and Ansible Automation Platform.
• Configures the HCP Terraform variables and variable sets for the Terraform AAP provider to connect to AAP.
• Provide clear guidance and Ansible templates to application teams on when to use the AAP provider and for what purposes.
• Establish consistent naming conventions and tagging strategy across both platforms that identify ownership, environment, cost center, and project affiliation.
  • This enables consistent resource tracking and management throughout the infrastructure lifecycle.
  • Consistent use of tagging simplifies ongoing management of any Ansible Automation Platform dynamic inventory that is metadata based.
• Ensure application teams (tenants) are appropriately configured in both HCP Terraform and AAP.
  • We refer to tenants as a logical grouping of users, resources, and permissions that share a common scope of control, such as a project or business unit. Each tenant must be consistently represented across both platforms, with synchronized identity, access controls, and resource ownership to enable seamless and secure automation workflows.
  • Map each application team to specific tenants in both platforms to ensure consistent organizational boundaries and prevent cross-contamination of resources, configurations, and sensitive data between different business units or projects.
  • Define clear handoff and data exchange mechanisms between Terraform and Ansible teams, including consistent conventions for variable passing, and error handling procedures to ensure smooth automation workflows.

The following diagram illustrates a high-level architecture for mapping a single team (team-A) across HCP Terraform and AAP using centralized authentication through a shared Identity Platform (SAML 2.0). This approach demonstrates how to map common identity groups across platforms, allowing the management of role-based access within both platforms for the same team, aligning to organization security boundaries.

• In HCP Terraform, team-A has access to a project, which is a self-service construct for workspace management and infrastructure provisioning.
• In AAP, team-A has a role assignment that permits access to relevant resources, such as inventories and machine credentials, aligning with the principle of least-privilege.

Application team

The application team is the main consumer of this integration. This guide ensures that developers in application teams are able to quickly provision cloud resources with Terraform and configure/orchestrate with Ansible while at the same complying with security needs of the organization.

• Developers write/edit terraform & ansible code and have access to the repo where the code is stored.
• Developers have read access to HCP Terraform to see the status of the terraform plan/apply.
• Developers optionally will also have access to Ansible Automation Platform (AAP) to review more details on the errors or warnings raised by AAP. We notice that in some organizations with a large number of developers, providing access for every developer to access AAP could be a challenge. In those scenarios one or two members of the development team will have AAP access to help the team.

The application team will have the following responsibilities:

• Ensure that developers have access to the enablement made available by the platform team on how to use the integration .
• Understand the importance of this integration and the value it provides to the organization.
• Understand who to contact if there are any questions about this integration.

Consumer onboarding automation

We recommend using the tfe provider to onboard consumers to HCP Terraform and Ansible Automation Platform. This approach automates the configuration of HCP Terraform in combination with the Ansible Automation Platform collections for configuration of a tenant or application team across both platforms.

Treat this integration as part of your broader cloud consumer onboarding strategy for both HCP Terraform and Ansible Automation Platform to ensure a consistent, cohesive user experience.

For each consumer tenant across platforms, create their projects, workspaces, variable sets, and team permissions in HCP Terraform, and the corresponding organizations, credentials, roles, job templates and workflows in Ansible Automation Platform. When you need to pass data between Terraform and Ansible Automation Platform, use the Terraform AAP provider to transfer data to AAP workflows or job templates. For sensitive data, use HashiCorp Vault key-value storage or use job template surveys to mask sensitive inputs.

AAP provider consumption

The Terraform AAP provider enables handoff between HCP Terraform and Ansible Automation Platform by automatically triggering Ansible Automation Platform job templates and workflows after infrastructure provisioning. This bridges infrastructure deployment and configuration management, reducing errors and deployment time while ensuring appropriate configuration of newly created resources through a unified solution.

The Terraform AAP provider supports hybrid inventory management, allowing organizations to combine declarative and dynamic approaches based on their infrastructure and operational needs. When deciding on an approach, consider the persona of the end user and how this aligns to self-service consumption for an application team.

Inventory management

Terraform managed inventory

The Terraform aap_inventory resource enables application teams to self-manage their inventory alongside infrastructure using the same declarative, idempotent approach. This provides an effective alternative for managing AAP inventory when dynamic inventory approaches become complex or impractical. This also supports the management of inventory in a self-service environment and aligns with a GitOps-first approach. Inventory is dynamically built from infrastructure code and reviewable in Git pull requests as you make infrastructure changes.

Dynamic inventory management can coexist with declarative inventory management. Use dynamic inventory management for centralized operational tasks such as patching large fleets of virtual machine resources. When using declarative inventory, give consideration to role based access control alignment with roles in AAP. Use custom roles for granular role based access control.

Naming conventions

When creating inventory with the AAP provider, it is important to have an inventory naming strategy that ensures unique names and clear traceability back to the owning workspace and application team. Use inheritance of variables from projects for business context. To identify the parent project and workspace, use concatenation of reserved workspace environment variables to create inventory names.

variable "TFC_PROJECT_NAME" {}  
variable "TFC_WORKSPACE_NAME" {}

Example inventory naming:

resource "aap_inventory" "vm_inventory" {  
  name        = "${var.TFC_PROJECT_NAME}${var.TFC_WORKSPACE_NAME}${var.app_id}"  
  description = var.inventory_description  
}

Dynamic inventory

Use existing dynamic inventory from Ansible Automation Platform in Terraform by looking up inventory using the AAP provider inventory data source (aap_inventory). Dynamic inventories allow for discovery based Ansible Automation Platform inventory. Dynamic inventory is dependent on the downstream endpoint, so give this consideration to ensure inventory alignment to consumer teams in a self-service environment. Dynamic inventory in AAP enables automatic discovery of hosts and systems from external sources, some common examples include:

• AWS, Azure, GCP
• VMware vSphere
• RedHat Satellite

It is important to ensure there is a strategy in place that enables self-service consumption when looking up and reusing existing inventory. Consider the tenancy model in environments that are not naturally multi-tenant. This requires careful planning around access patterns, security boundaries, and operational responsibilities. Organizations must design inventory management workflows that support team autonomy while maintaining appropriate guardrails, implementing automated discovery mechanisms that respect organizational hierarchies, and establishing clear policies for inventory sharing and reuse across different business contexts.

Ensure you have a well aligned strategy for metadata to manage a successful dynamic inventory. In this scenario Terraform can help with tag-based enforcement through the use of standardized private registry modules and IaC policy enforcement.

The following example uses default tags in the Terraform provider for AWS:

provider "aws" {  
  default_tags {  
    tags = {  
      Environment = var.environment_tag  
      Owner       = var.owner_tag  
      Project     = var.project_tag  
    }  
  }  
}

AAP job execution

When using the Terraform provider to set inventory or extra_vars, you must preconfigure the AAP job template with "prompt on launch" enabled for these values. Without this setting, the provider cannot override the defaults, causing job execution to fail.

The Terraform AAP provider executes jobs only once by default. You can use the resource's trigger attribute to control when jobs run. We recommend using triggers to manage job execution behavior while preventing unnecessary configuration drift. See the following examples:

Trigger on infrastructure change

This approach allows jobs to run automatically as infrastructure changes, whilst preventing unnecessary drift. Create a map with VM hostnames and attributes that change only with infrastructure changes. Use locals and for, where you require iteration to generate the map of multiple VM resources.

Example triggers using vm instance attributes

resource "aap_job" "run" {
  job_template_id                     = data.aap_job_template.this.id
  extra_vars                          = jsonencode(local.extra_vars)
  wait_for_completion                 = true
  wait_for_completion_timeout_seconds = 1000
  triggers                            = { module.vm.hostname = module.vm.ip_address }
}

Trigger on user initiation

This approach provides manual job control for maintenance, testing, or oversight. Set triggers to an arbitrary version map and increment the version to trigger execution. Variable and version changes trigger runs in this scenario.

Example triggers using user supplied variable

resource "aap_job" "run" {
  job_template_id                     = data.aap_job_template.this.id
  extra_vars                          = jsonencode(local.extra_vars)
  wait_for_completion                 = true
  wait_for_completion_timeout_seconds = 1000
  triggers                            = { "version" = "${var.version}" }
}

Develop modules for the AAP provider

We recommend creating and publishing standardized Terraform modules for common AAP consumption patterns, including inventories, hosts, and job and workflow execution.

Design modules with configurable abstraction levels supporting deployments for standard use cases and advanced customization for more complex integration scenarios.

Consistent approach to tenant AAP provider credentials

Use variable sets to establish standardized credentials that map directly to tenant boundaries, ensuring application teams can only access their designated AAP credentials.

If you have access to HashiCorp Vault, implement centralized credential management to securely store and rotate AAP service accounts across tenants. Use the Terraform tfe provider to manage this and store credentials in variable sets, or, use the Vault backed dynamic provider and retrieve credentials using the LDAP secrets engine with static role rotation. Implement credential rotation policies with automated renewal processes with consideration to not disrupting running workflows.

AAP SSH machine credentials management strategy

AAP credential management must align with Terraform image and golden image workflows to ensure there is a clear end to end strategy across platforms. The recommended approach to simplify Ansible Automation Platform machine credentials is to use the AAP credential plugins for HashiCorp Vault. This ensures a consistent security model across Terraform provisioning and AAP configuration management while maintaining centralized credential lifecycle management and short term SSH credentials. For detailed implementation guidance, review Integrate Ansible Automation Platform with HashiCorp Vault for signed SSH credentials.

Day two Terraform operations

Use Event-Driven Ansible EDA with Terraform for day two operations including the ability to tie into Terraform's workspace notifications system. This is a custom integration requiring Ansible Automation Platform EDA rulebooks and job templates/workflows to enable the integration.

In the following example AAP's EDA addresses Terraform drift management by consuming drift notifications and triggering automated remediation workflows, creating a complementary relationship that extends both platforms' operational capabilities. EDA monitors drift events then executes rulebooks that evaluate drift severity and trigger appropriate responses. This integration enables differentiation between routine changes requiring notifications and critical violations demanding immediate automated remediation, addressing operational gaps between infrastructure provisioning and ongoing management while maintaining infrastructure integrity at scale.

We are working on a detailed validated pattern for integration of HCP Terraform with Event-Driven Ansible.

Conclusion

This guide provides a comprehensive and opinionated approach to integrating HCP Terraform and Ansible Automation Platform, showing how these tools can work in tandem across the infrastructure lifecycle. By delineating each product’s role, teams can streamline automation while preserving flexibility and control. As HCP Terraform and Ansible Automation Platform continue to evolve we expect deeper and more seamless integrations to emerge.

Related resources

• Integrate Ansible Automation Platform with HashiCorp Vault for signed SSH credentials
• Terraform AAP provider documentation