# terraform – Manages a Terraform deployment (and plans)

New in version 2.5.

- Synopsis

- Requirements

- Parameters

- Notes

- Examples

- Return Values

- Status

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

- This module is not guaranteed to have a backwards compatible interface. [preview]

- This module is maintained by the Ansible Community. [community]

### Authors

- Ryan Scott Brown (@ryansb)

Hint

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