Launch jobs on Ansible Automation Platform with Terraform actions

Use Terraform actions to invoke AAP jobs from your infrastructure workflows, integrating Day 0 provisioning with Day 2 configuration.

You can also read this article on our Substack!

Terraform and Ansible are commonly used together in infrastructure management. Terraform handles Day 0 infrastructure provisioning while Ansible excels at configuration management, and together they provide a foundation for standing up and configuring infrastructure. Coordinating between these platforms becomes even more powerful when they can work within a single workflow.

The Terraform action built for the Red Hat Ansible Automation Platform (AAP) provider enables this seamless workflow. With the aap_job_launch action available in AAP provider v1.4.0 and later, teams can trigger Ansible playbooks directly from Terraform workflows without leaving the infrastructure as code paradigm. This integration helps unify your infrastructure workflow and streamline Day 2 operations.

Consider a common scenario: your team provisions virtual machines using Terraform, but those VMs require specific configuration before they’re ready for usage. Installing security agents, configuring monitoring, applying compliance policies, or joining domain controllers are all Day 2 operations that Ansible handles well. With Terraform actions, you can trigger these Ansible playbooks immediately after provisioning resources, all within a single terraform apply operation.

In this blog post, I demonstrate how to implement and monitor Terraform actions that launch AAP jobs, giving platform teams a practical pattern for bridging Day 0 and Day 2 operations.

Understanding Terraform actions

Actions are preset operations built into providers that let Terraform perform day-two operations. Unlike resources that manage infrastructure state, actions invoke external automations without affecting Terraform’s state tracking. You can think of actions as event-driven hooks that execute operations in response to resource lifecycle events.

Actions offer several advantages for infrastructure workflows:

• Declarative integration: Define actions in your Terraform configuration alongside the resources they relate to, maintaining infrastructure as code principles.
• Lifecycle event triggers: Configure actions to execute after specific resource events, like after_create or after_update, ensuring automations run at the right time.
• Flexible execution modes: Choose whether Terraform should wait for action completion or continue immediately, depending on your workflow requirements.
• Visibility in HCP Terraform: Monitor action execution status, view invocation details, and access job identifiers for troubleshooting.

The aap_job_launch action specifically enables Terraform to dispatch jobs to Ansible Automation Platform. This creates a powerful integration point where Terraform’s infrastructure provisioning capabilities connect directly to Ansible’s configuration management strengths.

How the aap_job_launch action works

The aap_job_launch action launches an AAP job based on a pre-configured job template. Each invocation creates a new job in AAP, passing optional parameters like extra variables or specific inventory selections.

The action supports two execution modes through the wait_for_completion parameter:

• Synchronous mode (wait_for_completion: true): Terraform waits until the AAP job reaches a final state before continuing. This ensures downstream resources or actions don’t execute until configuration is complete. If the job fails, the action reports an error in Terraform, allowing teams to identify failures immediately.
• Asynchronous mode (wait_for_completion: false): Terraform invokes the job and continues immediately without waiting for completion. This mode suits scenarios where Terraform doesn’t need to know the outcome, or where jobs run for extended periods.

You can also configure wait_for_completion_timeout_seconds to control how long Terraform waits before timing out. The default timeout is 120 seconds.

The basic structure of an aap_job_launch action looks like this:

action "aap_job_launch" "configure_vm" {
  config {
    job_template_id     = 1234
    wait_for_completion = true
    extra_vars = jsonencode({
      vm_hostname = "webserver-01"
      environment = "production"
    })
  }
}

To trigger this action based on resource lifecycle events, configure an action_trigger block within a resource’s lifecycle configuration:

resource "terraform_data" "trigger" {
  input = "example"

  lifecycle {
    action_trigger {
      events  = [after_create, after_update]
      actions = [action.aap_job_launch.configure_vm]
    }
  }
}

This configuration invokes the action after creating the resource and again after any updates to the resource configuration. In real-world scenarios, you can add this action_trigger block to resources that create virtual machines, enabling post-creation configuration to run automatically within the same terraform apply operation.

Architecture diagram

Implementing actions with AAP

To demonstrate this integration, I’ve created a GitHub repository with configurations for testing different action scenarios. The repository uses a simple conditional playbook against localhost to illustrate how wait_for_completion and job status affect the Terraform workflow and UI. While simplified, these patterns apply directly to real-world scenarios like VM configuration after provisioning.

In real-world scenarios, teams typically provision infrastructure with Terraform and use actions to trigger AAP playbooks for configuration tasks like installing security agents, configuring monitoring, or applying compliance policies. The wait_for_completion setting is a key decision: should Terraform wait for configuration to complete before continuing, or proceed immediately and rely on external monitoring?

The demo creates four workspaces to test different combinations of wait_for_completion and job outcomes.

Demo diagram

• AAP job templates that define the playbooks, inventory, and default variables
• HCP Terraform workspaces with different wait_for_completion settings and different variable values passed to the AAP playbook that determines job success or failure

Create the GitHub repository that contains the Ansible playbook

The code for this section is available in the tf/01-tf-github-repo-playbook directory. Follow the instructions in the README to configure your GitHub credentials and apply the Terraform configuration.

This creates a GitHub repository containing a conditional Ansible playbook that succeeds or fails based on a variable passed from Terraform. This playbook enables testing different scenarios, such as handling successful configurations versus dealing with failures.

GitHub repo with Ansible playbook

Configure AAP resources

The code for this section is available in the tf/02-ansible-playbook-create directory. Follow the instructions to configure your AAP credentials and run the Ansible playbook that sets up AAP resources.

This creates several AAP resources:

• Project linked to the GitHub repository containing the Ansible playbook.
• Inventory with a localhost host for executing playbooks.
• Job template that references the project and inventory, defining which playbook to execute.

The job template ties everything together, specifying which playbook to run and which inventory to use.

Job template details

Create HCP Terraform workspaces

The code for this section is available in the tf/03-tf-workspaces directory. Follow the instructions to configure your HCP Terraform credentials and apply the configuration.

This creates a GitHub repository named tf-action-aap-job-launch-workspace that contains a simple Terraform main.tf file.

GitHub repo with Terraform configuration

The Terraform configuration creates an HCP Terraform project with four workspaces, each testing a different combination of wait_for_completion settings and expected playbook outcomes:

[embed]

Project workspaces

The variation in test scenarios is configured by the variable values in each workspace. For example, the workspace action-wait-fail has aap_job_launch_wait_for_completion set to true and var_from_tf_aap_job_launch set to fail.

Workspace variables

Each workspace connects to a GitHub repository via VCS integration and includes variables that control the action behavior and playbook outcome. A project-level variable set provides AAP credentials to all workspaces, ensuring they can authenticate to AAP when invoking jobs.

Project variable set variables

Testing action behaviors

With the infrastructure deployed, let’s examine how actions behave in different scenarios. These tests illustrate important considerations for teams implementing actions in real-world workflows.

Scenario 1: Wait for successful completion

This scenario demonstrates the path where Terraform waits for an AAP job to complete successfully before finishing the apply operation.

When you run terraform apply on the action-wait-success workspace, HCP Terraform shows 1 action to invoke in the plan output.

action-wait-success workspace plan

After confirming, the apply operation starts and the action shows a Starting status. The AAP job begins executing. In the AAP UI, you can watch the playbook run against the configured inventory. Since wait_for_completion is true, Terraform waits for the AAP job to finish before reporting the job status.

action-wait-success workspace terraform apply

While Terraform waits, the playbook executes in AAP. You can monitor the job’s progress in the AAP interface.

Ansible playbook running

The playbook is configured to pause for 60 seconds before conditionally passing or failing the run, depending on the value of var_from_tf_aap_job_launch.

Ansible playbook success

When the playbook completes successfully, the action status changes to Invoked and the terraform apply completes. The apply output confirms successful execution and the action panel displays the job completion status.

action-wait-success workspace terraform apply finished

This scenario suits workflows where downstream operations depend on successful configuration. For example, after provisioning a database server and configuring it with Ansible, you might provision application servers that connect to that database. Waiting for configuration completion ensures the database is ready before provisioning dependent resources.

Scenario 2: Wait for failed completion

This scenario shows how Terraform handles AAP job failures when wait_for_completion is true.

The workspace configuration passes a variable that causes the Ansible playbook to fail intentionally. After running terraform apply and confirming the plan, the action starts and the AAP job begins executing. During the apply operation, Terraform waits for the AAP job to complete just as in the success scenario.

action-wait-fail workspace terraform apply

When the playbook encounters the failure condition, the job fails in AAP.

Ansible playbook failed

Because Terraform is waiting for completion, it detects this failure and marks the action as Errored in the HCP Terraform UI. The error panel displays the AAP job ID, enabling teams to navigate directly to AAP for detailed failure information. However, the specific failure message from the playbook is not shown in Terraform and teams must check AAP to understand what went wrong.

action-wait-fail workspace terraform apply errored

This behavior is valuable for detecting configuration failures during infrastructure deployment. In a VM provisioning scenario, if a playbook fails to install required security agents or apply compliance policies, the synchronous mode ensures Terraform reports the failure immediately. The HCP Terraform UI shows the errored action with the AAP job ID, providing a clear link between the failed Terraform run and the specific AAP job that failed. Teams can click through to AAP using the job ID, examine the detailed failure output, identify whether the issue was a playbook error or an environmental problem, and determine the appropriate remediation. This tight integration between Terraform and AAP status enables faster incident response and clearer troubleshooting workflows.

Scenario 3: Don’t wait for successful completion

This scenario demonstrates asynchronous action invocation where Terraform continues immediately after launching the job.

With wait_for_completion set to false, terraform applycompletes as soon as the action successfully dispatches the job to AAP. The action shows an Invoked status immediately, and Terraform considers the apply operation successful. Notice how quickly the apply completes compared to the synchronous scenarios. Terraform doesn’t wait for the playbook to finish.

action-no-wait-success workspace terraform apply finished

The AAP job runs asynchronously after Terraform completes. HCP Terraform always reports success, regardless of whether the AAP job actually succeeds or fails.

Ansible playbook running

This mode suits scenarios where job completion doesn’t affect subsequent Terraform operations. For example, triggering a non-critical monitoring configuration or initiating a background cleanup task where failure doesn’t prevent continued infrastructure deployment.

Scenario 4: Don’t wait for failed completion

This scenario highlights an important consideration when using asynchronous actions: Terraform cannot detect job failures when wait_for_completion is false.

After terraform apply completes successfully, the AAP job runs and eventually fails. However, the HCP Terraform workspace shows the run as successful because Terraform only verified that the job was dispatched, not that it completed successfully. The apply completes immediately and shows success, just as in scenario 3.

action-no-wait-fail workspace terraform apply finished

The AAP job begins executing after Terraform has already marked the run as successful.

Ansible playbook running

Eventually, after the configured 60-second wait, the job fails because the value of var_from_tf_aap_job_launch passed from Terraform is fail.

Ansible playbook failed

Even after the job failure is visible in AAP, the Terraform workspace continues to show the run as successful.

action-no-wait-fail workspace terraform apply finished

The workspace’s overview also has no indication of the failed AAP job.

action-no-wait-fail workspace overview

This behavior has significant implications for real-world workflows. Consider a scenario where Terraform provisions 10 VMs and triggers AAP playbooks to configure each one with wait_for_completion set to false. Terraform completes the run showing success, but if one or more configuration playbooks fail, there’s no indication in the Terraform UI. Teams might assume all VMs are properly configured when some are actually incomplete or misconfigured.

To safely use asynchronous actions, teams must establish a robust notification and correlation workflow:

• Configure AAP notifications: Set up AAP to send alerts when jobs fail. This might involve webhook notifications to incident management systems, email alerts to operations teams, or integrations with ChatOps platforms.
• Implement verification workflows: For critical configurations, consider implementing separate verification jobs that check configuration state and alert if systems aren’t properly configured, even when the initial job appears to have been dispatched successfully.
• Use tagging and metadata: Pass identifying information through extra_vars that appears in AAP job details, making it easier to correlate failed jobs with the infrastructure they were meant to configure.

Without these notification mechanisms, asynchronous actions create a visibility gap where configuration failures might go unnoticed until they cause downstream problems. For critical VM configuration tasks like security hardening or compliance enforcement, synchronous mode with wait_for_completion: true provides better visibility at the cost of longer Terraform execution times.

Best practices for actions with AAP

Based on implementing and testing these action scenarios, several best practices emerge:

• Use synchronous mode for critical configurations: When downstream resources depend on a successful configuration, enable wait_for_completion to ensure Ansible finishes before Terraform continues. This prevents deploying dependent infrastructure before prerequisites are ready.
• Configure appropriate timeouts: The default 120-second timeout may be insufficient for complex playbooks. Set wait_for_completion_timeout_seconds based on your playbook’s expected execution time, adding a buffer for variability.
• Implement monitoring for asynchronous actions: When using asynchronous mode, establish monitoring in AAP to detect job failures. Configure alerts for failed jobs so teams are notified when configuration issues occur.
• Pass dynamic variables with extra_vars: Use extra_vars to pass resource attributes from Terraform to Ansible.

Next steps

Terraform actions for AAP create a powerful integration point between infrastructure provisioning and configuration management. By invoking AAP jobs directly from Terraform workflows, teams can automate the complete infrastructure lifecycle from initial provisioning through Day 2 configuration.

The pattern demonstrated in this blog provides a foundation that teams can adapt to their specific requirements. Some organizations might trigger post-provisioning security hardening, others might use actions for compliance enforcement, and still others might coordinate complex multi-stage deployments across Terraform and Ansible. So what are you waiting for? Get started with this pattern by following the steps in the accompanying GitHub repository!

HCP Terraform with RedHat Ansible Automation Platform