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.

Requirements

This collection requires requests and pydantic>=2.0.0 libraries 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 this collection can be used for various operations on Terraform Cloud/Enterprise. Currently the collection supports:

• Creating, uploading and archiving configuration versions
• Creating, applying, and discarding runs

These modules 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.

---
- name: Playbook using hashicorp.terraform collection
  hosts: localhost
  gather_facts: false
  tasks:
    - name: Create a new configuration version
      hashicorp.terraform.configuration_version:
        workspace_id: "{{ workspace_id }}"
        state: present
        configuration_files_path: "{{ configuration_files }}"
        poll_interval: 3
        poll_timeout: 15
        tf_token: "{{ terraform_cloud_token }}"

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.

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

Latest Release: 1.1.0

New Modules

• configuration_version_info - Retrieve information about configuration versions in Terraform Enterprise/Cloud.
• run_info - Retrieve information about a run in Terraform Enterprise/Cloud.
• view_plan - View Terraform Cloud/Enterprise plan information
• workspace - Manage workspaces in Terraform Enterprise/Cloud.
• workspace_info - Gather information about a workspace in Terraform Enterprise/Cloud.

Bugfixes

• Ensures module invocation parameters in the task execution result aren't overridden by module code logic.

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.