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 ships a set of scenario guides under docs/docsite/rst/ that render on the Ansible collection docsite:

• Getting started
• Authentication
• Workspaces and projects
• Runs and configuration versions
• Variables and variable sets
• Teams and access
• Workspace bootstrap
• Dynamic inventory
• Lookup plugins
• Execution environments
• Troubleshooting
• Compatibility and support

Requirements

This collection requires the pytfe>=1.2.0 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

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 available version:

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

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

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

As Red Hat Ansible Certified Content, this collection is entitled to support through the Ansible Automation Platform (AAP) using the Create issue button on the top right corner. If a support case cannot be opened with Red Hat and the collection has been obtained either from Galaxy or GitHub, there may community help available 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.