community.general.terraform – Manages a Terraform deployment (and plans)

From Get docs
Ansible/docs/2.10/collections/community/general/terraform module


community.general.terraform – Manages a Terraform deployment (and plans)

Note

This plugin is part of the community.general collection (version 1.3.2).

To install it use: ansible-galaxy collection install community.general.

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 Choices/Defaults Comments

backend_config

dictionary

A group of key-values to provide at init stage to the -backend-config parameter.

backend_config_files

list / elements=path

added in 0.2.0 of community.general

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.

binary_path

path

The path of a terraform binary to use, relative to the 'service_path' unless you supply an absolute path.

force_init

boolean

  • no

  • yes

To avoid duplicating infra, if a state file can't be found this will force a `terraform init`. Generally, this should be turned off unless you intend to provision an entirely new Terraform deployment.

init_reconfigure

boolean

added in 1.3.0 of community.general

  • no

  • yes

Forces backend reconfiguration during init.

lock

boolean

  • no
  • yes

Enable statefile locking, if you use a service that accepts locks (such as S3+DynamoDB) to store your statefile.

lock_timeout

integer

How long to maintain the lock on the statefile, if you use a service that accepts locks (such as S3+DynamoDB).

plan_file

path

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.

project_path

path / required

The path to the root of the Terraform directory with the vars.tf/main.tf/etc to use.

purge_workspace

boolean

  • no

  • yes

Only works with state = absent

If true, the workspace will be deleted after the "terraform destroy" action.

The 'default' workspace will not be deleted.

state

string

  • planned
  • present

  • absent

Goal state of given stage/project

state_file

path

The path to an existing Terraform state file to use when building plan. If this is not specified, the default `terraform.tfstate` will be used.

This option is ignored when plan is specified.

targets

list / elements=string

A list of specific resources to target in this plan/application. The resources selected here will also auto-include any dependencies.

variables

dictionary

A group of key-values to override template variables or those in variables files.

variables_files

list / elements=path

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.

Up until Ansible 2.9, this option was usable as variables_file.


aliases: variables_file

workspace

string

Default:

"default"

The terraform workspace to work with.



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

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key Returned Description

command

string

always

Full `terraform` command built by this module, in case you want to re-run the command outside the module or debug a problem.


Sample:

terraform apply ...

outputs

complex

on success

A dictionary of all the TF outputs by their assigned name. Use `.outputs.MyOutputName.value` to access the value.


Sample:

{"bukkit_arn": {"sensitive": false, "type": "string", "value": "arn:aws:s3:::tf-test-bukkit"}

sensitive

boolean

always

Whether Terraform has marked this value as sensitive


type

string

always

The type of the value (string, int, etc)


value

string

always

The value of the output as interpolated by Terraform


stdout

string

always

Full `terraform` command stdout, in case you want to display it or examine the event log





Authors

  • Ryan Scott Brown (@ryansb)

© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.10/collections/community/general/terraform_module.html