terraform – Manages a Terraform deployment (and plans)

New in version 2.5.

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
-
added in 2.7
A group of key-values to provide at init stage to the -backend-config parameter.
binary_path
-
The path of a terraform binary to use, relative to the 'service_path' unless you supply an absolute path.
force_init
boolean
    Choices:
  • 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.
lock
boolean
    Choices:
  • no
  • yes
Enable statefile locking, if you use a service that accepts locks (such as S3+DynamoDB) to store your statefile.
lock_timeout
-
How long to maintain the lock on the statefile, if you use a service that accepts locks (such as S3+DynamoDB).
plan_file
-
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
- / required
The path to the root of the Terraform directory with the vars.tf/main.tf/etc to use.
purge_workspace
boolean
added in 2.7
    Choices:
  • 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
-
    Choices:
  • planned
  • present ←
  • absent
Goal state of given stage/project
state_file
-
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
-
A list of specific resources to target in this plan/application. The resources selected here will also auto-include any dependencies.
variables
-
A group of key-values to override template variables or those in variables files.
variables_file
-
The path to a variables file for Terraform to fill into the TF configurations.
workspace
-
added in 2.7
 Default:
"default"
The terraform workspace to work with.

Notes

Note

  • To just run a terraform plan, use check mode.

Examples

# Basic deploy of a service
- terraform:
    project_path: '{{ project_dir }}'
    state: present

# Define the backend configuration at init
- terraform:
    project_path: 'project/'
    state: "{{ state }}"
    force_init: true
    backend_config:
      region: "eu-west-1"
      bucket: "some-bucket"
      key: "random.tfstate"

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
-
 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


Status

Authors

  • Ryan Scott Brown (@ryansb)

Hint

If you notice any issues in this documentation you can edit this document to improve it.