community.general.terraform module – Manages a Terraform deployment (and plans)
Note
This module is part of the community.general collection (version 10.1.0).
You might already have this collection installed if you are using the ansible package.
It is not included in ansible-core.
To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.general.
You need further requirements to be able to use this module,
see Requirements for details.
To use it in a playbook, specify: community.general.terraform.
Synopsis
Provides support for deploying resources with Terraform and pulling resource information back into Ansible.
Requirements
The below requirements are needed on the host that executes this module.
terraform
Parameters
Parameter |
Comments |
|---|---|
A group of key-values to provide at init stage to the -backend-config parameter. |
|
The path to a configuration file to provide at init state to the -backend-config parameter. This can accept a list of paths to multiple configuration files. |
|
The path of a terraform binary to use, relative to the ‘service_path’ unless you supply an absolute path. |
|
Apply only when no resources are destroyed. Note that this only prevents “destroy” actions, but not “destroy and re-create” actions. This option is ignored when Choices:
|
|
Enable/disable capability to handle complex variable structures for If When disabled, supports only simple variables (strings, integers, and floats), and passes them on unquoted. Choices:
|
|
To avoid duplicating infra, if a state file can’t be found this will force a Choices:
|
|
Forces backend reconfiguration during init. Choices:
|
|
Enable statefile locking, if you use a service that accepts locks (such as S3+DynamoDB) to store your statefile. Choices:
|
|
How long to maintain the lock on the statefile, if you use a service that accepts locks (such as S3+DynamoDB). |
|
Run init even if Choices:
|
|
Restrict concurrent operations when Terraform applies the plan. |
|
The path to an existing Terraform plan file to apply. If this is not specified, Ansible will build a new TF plan and execute it. Note that this option is required if ‘state’ has the ‘planned’ value. |
|
List of paths containing Terraform plugin executable files. Plugin executables can be downloaded from https://releases.hashicorp.com/. When set, the plugin discovery and auto-download behavior of Terraform is disabled. The directory structure in the plugin path can be tricky. The Terraform docs https://learn.hashicorp.com/tutorials/terraform/automate-terraform#pre-installed-plugins show a simple directory of files, but actually, the directory structure has to follow the same structure you would see if Terraform auto-downloaded the plugins. See the examples below for a tree output of an example plugin directory. |
|
The path to the root of the Terraform directory with the vars.tf/main.tf/etc to use. |
|
Allows Terraform init to upgrade providers to versions specified in the project’s version constraints. Choices:
|
|
Only works with state = absent If true, the workspace will be deleted after the “terraform destroy” action. The ‘default’ workspace will not be deleted. Choices:
|
|
Goal state of given stage/project Choices:
|
|
The path to an existing Terraform state file to use when building plan. If this is not specified, the default This option is ignored when plan is specified. |
|
A list of specific resources to target in this plan/application. The resources selected here will also auto-include any dependencies. Default: |
|
A group of key-values pairs to override template variables or those in variables files. By default, only string and number values are allowed, which are passed on unquoted. Support complex variable structures (lists, dictionaries, numbers, and booleans) to reflect terraform variable syntax when Ansible integers or floats are mapped to terraform numbers. Ansible strings are mapped to terraform strings. Ansible dictionaries are mapped to terraform objects. Ansible lists are mapped to terraform lists. Ansible booleans are mapped to terraform booleans. Note passwords passed as variables will be visible in the log output. Make sure to use |
|
The path to a variables file for Terraform to fill into the TF configurations. This can accept a list of paths to multiple variables files. |
|
The terraform workspace to work with. This sets the Default: |
Attributes
Attribute |
Support |
Description |
|---|---|---|
Support: full |
Can run in |
|
Support: full added in community.general 8.3.0 |
Will return details on what has changed (or possibly needs changing in |
Notes
Note
To just run a
terraform plan, use check mode.
Examples
- name: Basic deploy of a service
community.general.terraform:
project_path: '{{ project_dir }}'
state: present
- name: Define the backend configuration at init
community.general.terraform:
project_path: 'project/'
state: "{{ state }}"
force_init: true
backend_config:
region: "eu-west-1"
bucket: "some-bucket"
key: "random.tfstate"
- name: Define the backend configuration with one or more files at init
community.general.terraform:
project_path: 'project/'
state: "{{ state }}"
force_init: true
backend_config_files:
- /path/to/backend_config_file_1
- /path/to/backend_config_file_2
- name: Disable plugin discovery and auto-download by setting plugin_paths
community.general.terraform:
project_path: 'project/'
state: "{{ state }}"
force_init: true
plugin_paths:
- /path/to/plugins_dir_1
- /path/to/plugins_dir_2
- name: Complex variables example
community.general.terraform:
project_path: '{{ project_dir }}'
state: present
complex_vars: true
variables:
vm_name: "{{ inventory_hostname }}"
vm_vcpus: 2
vm_mem: 2048
vm_additional_disks:
- label: "Third Disk"
size: 40
thin_provisioned: true
unit_number: 2
- label: "Fourth Disk"
size: 22
thin_provisioned: true
unit_number: 3
force_init: true
### Example directory structure for plugin_paths example
# $ tree /path/to/plugins_dir_1
# /path/to/plugins_dir_1/
# └── registry.terraform.io
# └── hashicorp
# └── vsphere
# ├── 1.24.0
# │ └── linux_amd64
# │ └── terraform-provider-vsphere_v1.24.0_x4
# └── 1.26.0
# └── linux_amd64
# └── terraform-provider-vsphere_v1.26.0_x4
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
|---|---|
Full Returned: always Sample: |
|
A dictionary of all the TF outputs by their assigned name. Use Returned: on success Sample: |
|
Whether Terraform has marked this value as sensitive Returned: always |
|
The type of the value (string, int, etc) Returned: always |
|
The value of the output as interpolated by Terraform Returned: always |
|
Full Returned: always Sample: |