Hashicorp Terraform Collection

This repository contains the hashicorp.terraform Ansible Collection.

Description

The primary purpose of this collection is to provide seamless integration between Ansible Automation Platform and Terraform Cloud/Enterprise. It contains modules and plugins that support creating runs, uploading new configuration versions, viewing plans, retrieving information about workspaces, projects, etc.

Being Red Hat Ansible Certified Content, this collection is eligible for support through the Ansible Automation Platform.

Documentation

In addition to the per-module reference (available with ansible-doc, for example ansible-doc hashicorp.terraform.workspace), this collection provides a documentation index. The links below open the rendered guides on GitHub, including when this README is viewed from Automation Hub:

End-to-End Cookbooks

• Provision with Terraform, configure with Ansible
• Application onboarding factory
• Governed drift reconciliation
• Event-driven post-apply automation
• Ephemeral preview environments

Advanced Platform Cookbooks

• Promote one known-good configuration
• Replace an agent pool blue-green
• Run a fleet Terraform upgrade campaign
• Respond to drift through an EDA workflow
• Migrate a workspace to dynamic credentials
• Decommission infrastructure safely
• Rehearse disaster recovery end to end
• Roll out compliance controls safely
• Publish a signed private provider
• Govern day-two operations with Terraform Actions
• Rotate an HCP Terraform HYOK key
• Onboard and observe an HCP Terraform Stack

Feature Guides

• Getting started
• Authentication
• Workspaces and projects
• Runs and configuration versions
• Drift-safe Day 2 operations (plan analyze / guard / safe)
• Enforcing tf-policy compliance
• Variables and variable sets
• Teams and access
• Workspace bootstrap
• Private registry modules
• Dynamic inventory
• Lookup plugins
• Execution environments
• Troubleshooting
• Compatibility and support

Requirements

This collection requires the pytfe>=1.4.1 Python library to be installed.

Some modules and plugins may require other external libraries. Please check the requirements for each plugin or module you use in the documentation to check the requirements.

Ansible version compatibility

This collection has been tested against the following Ansible versions: >=2.16.0.

Plugins and modules within a collection may be tested with only specific Ansible versions. A collection may contain metadata that identifies these versions. PEP440 is the schema used to describe the versions of Ansible.

Python version compatibility

This collection requires Python >= 3.10.

Installation

The certified collection artifact is distributed through Red Hat Automation Hub. The collection is not published to the public Ansible Galaxy service. For community use, you can also install the collection directly from Git or build a collection artifact from this repository. Git and self-built artifacts are not the certified artifact distributed through Automation Hub.

Install from Automation Hub

To install this collection from Automation Hub, the following needs to be added to ansible.cfg:

[galaxy]
server_list=automation_hub

[galaxy_server.automation_hub]
url=https://console.redhat.com/api/automation-hub/content/published/
auth_url=https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token
token=<SuperSecretToken>

To download contents from Automation Hub using ansible-galaxy CLI, you would need to generate and use an offline token. If you already have a token, please ensure that it has not expired. Visit Connect to Hub to obtain the necessary token.

With this configured, simply run the following command:

ansible-galaxy collection install hashicorp.terraform

You can also include it in a requirements.yml file and install it via ansible-galaxy collection install -r requirements.yml using the format:

collections:
  - name: hashicorp.terraform

To upgrade the collection to the latest available version, run the following command:

ansible-galaxy collection install hashicorp.terraform --upgrade

You can also install a specific version of the collection, for example, if you need to downgrade when something is broken in the latest version (please report an issue in this repository). Use the following syntax where X.Y.Z can be any version available in Automation Hub:

ansible-galaxy collection install hashicorp.terraform:==X.Y.Z

Install directly from Git

Add the repository to your requirements.yml file. The version value can be a branch, tag, or commit SHA:

---
collections:
  - name: https://github.com/hashicorp/terraform-ansible-collection.git
    type: git
    version: main

Install the collection and its Python dependency into the environment where Ansible runs:

ansible-galaxy collection install -r requirements.yml --force
python -m pip install "pytfe>=1.4.1"

Pin version to a release tag or commit SHA for reproducible environments. Despite its name, ansible-galaxy is also the CLI used to install collections from Git; the configuration above does not download this collection from the public Ansible Galaxy service.

Build and install from source

Clone the repository, check out the source revision you want to use, and build the collection artifact:

git clone https://github.com/hashicorp/terraform-ansible-collection.git
cd terraform-ansible-collection
git checkout <tag-branch-or-commit>
python -m pip install -r requirements.txt
ansible-galaxy collection build --force
ansible-galaxy collection install ./hashicorp-terraform-X.Y.Z.tar.gz --force

Replace X.Y.Z with the version declared in galaxy.yml. The generated tarball can also be used as the collection source for a controlled or disconnected environment.

For containerized execution, use the Git-based requirements.yml above as the galaxy dependency in an ansible-builder execution-environment definition, or make the built tarball available to the build. See the execution environments guide for a complete build and controller workflow.

See Ansible Using Collections for more details.

Use Cases

Modules in the collection can be called by their Fully Qualified Collection Name (FQCN), such as hashicorp.terraform.configuration_version, or by their short name if you list the hashicorp.terraform collection in the playbook's collections keyword. For examples on how to use modules included in this collection, please refer to their documentation.

Authentication is done via the tfe_token parameter (alias: tf_token), or by setting the TFE_TOKEN environment variable. Use module_defaults with the group/hashicorp.terraform.terraform module group to avoid repeating credentials across tasks.

Manage workspaces

---
- name: Manage Terraform workspaces
  hosts: localhost
  gather_facts: false
  module_defaults:
    group/hashicorp.terraform.terraform:
      tfe_token: "{{ terraform_cloud_token }}"
  tasks:
    - name: Create a workspace
      hashicorp.terraform.workspace:
        workspace: my-workspace
        organization: my-org
        description: Managed by Ansible
        execution_mode: remote
        auto_apply: true
        terraform_version: "1.12.2"
        tag_bindings:
          env: dev
          owner: platform-team
        state: present
      register: workspace_result

    - name: Lock a workspace
      hashicorp.terraform.workspace:
        workspace_id: "{{ workspace_result.id }}"
        lock_reason: Maintenance in progress
        state: locked

    - name: Delete a workspace
      hashicorp.terraform.workspace:
        workspace_id: "{{ workspace_result.id }}"
        state: absent

Manage projects

---
- name: Manage Terraform projects
  hosts: localhost
  gather_facts: false
  module_defaults:
    group/hashicorp.terraform.terraform:
      tfe_token: "{{ terraform_cloud_token }}"
  tasks:
    - name: Create a project
      hashicorp.terraform.project:
        organization: my-org
        project: my-project
        description: Platform infrastructure project
        default_execution_mode: remote
        auto_destroy_activity_duration: "14d"
        tag_bindings:
          - key: env
            value: production
        state: present
      register: project_result

    - name: Delete a project
      hashicorp.terraform.project:
        project_id: "{{ project_result.id }}"
        state: absent

Upload configuration and trigger a run

---
- name: Upload config and run Terraform
  hosts: localhost
  gather_facts: false
  module_defaults:
    group/hashicorp.terraform.terraform:
      tfe_token: "{{ terraform_cloud_token }}"
  tasks:
    - name: Upload a configuration version
      hashicorp.terraform.configuration_version:
        workspace_id: "{{ workspace_id }}"
        configuration_files_path: "{{ playbook_dir }}/terraform"
        auto_queue_runs: false
        poll_interval: 5
        poll_timeout: 60
        state: present
      register: config_version

    - name: Create and plan a run
      hashicorp.terraform.run:
        workspace_id: "{{ workspace_id }}"
        configuration_version: "{{ config_version.id }}"
        run_message: Deployed by Ansible
        poll: true
        poll_interval: 10
        poll_timeout: 300
        state: present
      register: run_result

    - name: Apply the run
      hashicorp.terraform.run:
        run_id: "{{ run_result.id }}"
        poll: true
        poll_interval: 10
        poll_timeout: 300
        state: applied

Retrieve Terraform outputs

---
- name: Retrieve Terraform state outputs
  hosts: localhost
  gather_facts: false
  module_defaults:
    group/hashicorp.terraform.terraform:
      tfe_token: "{{ terraform_cloud_token }}"
  tasks:
    - name: Get all outputs for a workspace
      hashicorp.terraform.output:
        workspace: my-workspace
        organization: my-org
      register: all_outputs

    - name: Get a specific output by name
      hashicorp.terraform.output:
        workspace: my-workspace
        organization: my-org
        name: vpc_id
      register: vpc_output

    - name: Get a specific output including its sensitive value
      hashicorp.terraform.output:
        workspace: my-workspace
        organization: my-org
        name: db_password
        display_sensitive: true
      register: sensitive_output

View a Terraform plan

---
- name: View a Terraform plan
  hosts: localhost
  gather_facts: false
  module_defaults:
    group/hashicorp.terraform.terraform:
      tfe_token: "{{ terraform_cloud_token }}"
  tasks:
    - name: View plan diff for a run
      hashicorp.terraform.view_plan:
        run_id: "{{ run_id }}"
        output_format: diff

    - name: Retrieve plan as structured JSON
      hashicorp.terraform.view_plan:
        run_id: "{{ run_id }}"
        output_format: json
      register: plan_json

Detect drift, analyze it, and approve only safe changes

Plan → Analyze → Plan Guard → Plan Safe → Apply: run a refresh-only plan to detect drift, classify it with plan_analyze, gate it with plan_guard/plan_safe against an allow/deny rule set, then either confirm (apply) the same run when it's safe or discard it when it isn't. See the drift-safe Day 2 operations guide for the full option reference and worked scenarios.

---
- name: Detect drift, analyze it, and approve only safe changes
  hosts: localhost
  gather_facts: false
  module_defaults:
    group/hashicorp.terraform.terraform:
      tfe_token: "{{ terraform_cloud_token }}"
  vars:
    allow_rules:
      - "aws_instance.*.tags"
      - "aws_instance.*.tags_all"
    deny_rules:
      - "aws_instance.*.instance_type"
      - "aws_instance.*.ami"
  tasks:
    - name: Create a refresh-only plan (do not auto-apply)
      hashicorp.terraform.run:
        workspace_id: "{{ workspace_id }}"
        run_message: "Detect drift before Day 2 reconciliation"
        refresh_only: true
        auto_apply: false
        poll: true
        state: present
      register: refresh_run

    - name: Analyze the plan for THIS run
      hashicorp.terraform.plan_analyze:
        run_id: "{{ refresh_run.id }}"
        detect_drift: true
      register: drift_analysis

    - name: Gate the decision
      ansible.builtin.set_fact:
        guard: >-
          {{ drift_analysis | hashicorp.terraform.plan_guard(
               allow=allow_rules, deny=deny_rules, mode='strict') }}

    - name: Confirm (apply) the SAME run only when safe
      hashicorp.terraform.run:
        run_id: "{{ refresh_run.id }}"
        state: applied
        poll: true
      when: guard.safe_to_refresh

    - name: Discard the run when drift was rejected
      hashicorp.terraform.run:
        run_id: "{{ refresh_run.id }}"
        state: discarded
      when: not guard.safe_to_refresh

Testing

GitHub Actions workflows are used to run tests for the hashicorp.terraform collection. These workflows include jobs to run the unit tests, integration tests, sanity tests, linters, changelog check and doc related checks. The following table lists the python and ansible versions against which these jobs are run.

Jobs	Description	Python Versions	Ansible Versions
changelog	Checks for the presence of Changelog fragments	3.12	N/A
build-import	Builds collection and runs galaxy_importer	3.12	latest ansible-core release
ansible-lint	Runs latest ansible-lint in production profile	3.12	latest ansible-core release
Linters	Runs black, flake8 and isort on plugins and tests	3.11	N/A
Sanity	Runs ansible-test sanity	3.10, 3.11, 3.12, 3.13	stable-2.16, stable-2.17, stable-2.18, stable-2.19, devel, milestone
Unit tests	Executes the unit test cases	3.10, 3.11, 3.12, 3.13	stable-2.16, stable-2.17, stable-2.18, stable-2.19, devel, milestone
Integration tests	Executes the integration test suite	3.12, 3.13	devel, stable-2.19, stable-2.16

Note: Not all listed Python versions are applicable to all ansible-core versions. The actual compatibility depends on ansible-core supported Python versions for a given release.

Support

The certified artifact distributed through Red Hat Automation Hub may be eligible for support through your Ansible Automation Platform subscription. Git and self-built artifacts are community installation paths; use the project issue tracker for reproducible defects or ask for community help on the Ansible Forum.

Release Notes and Roadmap

See the changelog.

Related Information

• Ansible collection development forum
• Ansible User guide
• Ansible Developer guide
• Ansible Collections Checklist
• Ansible Community code of conduct
• The Bullhorn (the Ansible Contributor newsletter)
• News for Maintainers

Licensing Information

GNU General Public License v3.0 or later.

See LICENSE to see the full text.