> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# circleci/terraform

Deploy your infrastructure via a CircleCI pipeline using the Terraform orb. Integrate Infrastructure-as-Code (IaC) to help provision and manage any cloud, infrastructure, or service of your choice.


## Commands

### apply

Execute 'terraform apply' to apply desired configuration changes to state.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `backend_config` | string |  | "Comma separated list of backend configs to set, e.g. 'foo=bar'"
 |
| `backend_config_file` | string |  | Path to a backend config file |
| `cli_config_file` | string |  | Path to terraform cli config file |
| `lock-timeout` | string | 30s | Configure a custom state lock timeout |
| `parallelism` | integer | 10 | Limit the number of concurrent operation Terraform is running. Defaults to 10 |
| `path` | string | . | Path to the terraform module |
| `plan` | string |  | Optionally provide a plan file to supply to the 'apply' command. |
| `timeout` | string | 10m | Configure a custom timeout limit |
| `var` | string |  | Comma separated list of var to set, e.g. 'foo=bar,bas=foo' |
| `var_file` | string |  | Comma separated list of var file paths |
| `workspace` | string |  | Name of the terraform workspace |

### destroy

Execute 'terraform destroy' on current state.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `backend_config` | string |  | "Comma separated list of backend configs to set, e.g. 'foo=bar'"
 |
| `backend_config_file` | string |  | Path to a backend config file |
| `cli_config_file` | string |  | Path to terraform cli config file |
| `path` | string | . | Path to the terraform module |
| `timeout` | string | 10m | Configure a custom timeout limit |
| `var` | string |  | Comma separated list of var to set, e.g. 'foo=bar,bas=foo' |
| `var_file` | string |  | Comma separated list of var file paths |
| `workspace` | string |  | Name of the terraform workspace |

### fmt

Execute 'terraform fmt' in specified module path.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `path` | string | . | Path to the terraform module |
| `recursive` | boolean | false | Process files in subdirectories |
| `timeout` | string | 10m | Configure a custom timeout limit |

### init

Execute 'terraform init' in directory specified in 'path' parameter.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `backend` | boolean | true | Enable backend configuration or not |
| `backend_config` | string |  | "Comma separated list of backend configs to set, e.g. 'foo=bar'"
 |
| `backend_config_file` | string |  | Path to a backend config file |
| `cli_config_file` | string |  | Path to terraform cli config file |
| `path` | string | . | Path to the terraform module |
| `timeout` | string | 10m | Configure a custom timeout limit |
| `upgrade` | boolean | false | Install the latest terraform module and provider versions |

### install

Install specified version of terraform.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `arch` | enum | amd64 | Specify the platform architecture to install. Must be one of these values: amd64, arm64 |
| `os` | enum | linux | Specify the operating system version to install. Must be one of these values: linux, darwin |
| `terraform_version` | string | latest | Version of Terraform to install. Only stable versions are supported. You can specify the version in three ways:
* latest: most recent version
* full version number (1.2.3): a specific version
* anything else (1.2, 1): the most recent stable version which matches this prefix.
Defaults to latest.
 |
| `timeout` | string | 10m | Configure a custom timeout limit |

### plan

Execute 'terraform plan' against current state.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `backend_config` | string |  | "Comma separated list of backend configs to set, e.g. 'foo=bar'"
 |
| `backend_config_file` | string |  | Path to a backend config file |
| `cli_config_file` | string |  | Path to terraform cli config file |
| `destroy_plan` | boolean | false | Run this plan as a destroy plan. |
| `lock` | boolean | true | Enable the lock on the state file or not |
| `lock-timeout` | string | 30s | Configure a custom state lock timeout |
| `out` | string | plan.out | The file path to save your terraform plan to. Set this to "" if you are using terraform cloud. |
| `parallelism` | integer | 10 | Limit the number of concurrent operation Terraform is running. Defaults to 10 |
| `path` | string | . | Path to the terraform module |
| `timeout` | string | 10m | Configure a custom timeout limit |
| `var` | string |  | Comma separated list of var to set, e.g. 'foo=bar,bas=foo' |
| `var_file` | string |  | Comma separated list of var file paths |
| `workspace` | string |  | Name of the terraform workspace |

### validate

Execute 'terraform validate' against modules specified in 'path' variable.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `cli_config_file` | string |  | Path to terraform cli config file |
| `path` | string | . | Path to the terraform module |
| `timeout` | string | 10m | Configure a custom timeout limit |
| `workspace` | string |  | Name of the terraform workspace |

## Jobs

### apply

Execute terraform plan


| Parameter | Type | Default | Description |
|---|---|---|---|
| `attach-workspace` | boolean | false | Attach (CircleCI) workspace to job. |
| `backend_config` | string |  | "Comma separated list of backend configs to set, e.g. 'foo=bar'"
 |
| `backend_config_file` | string |  | Path to a backend config file |
| `checkout` | boolean | false | Perform checkout as first step in job. |
| `cli_config_file` | string |  | Path to terraform cli config file |
| `lock-timeout` | string | 30s | Configure a custom state lock timeout |
| `parallelism` | integer | 10 | Limit the number of concurrent operation Terraform is running. Defaults to 10 |
| `path` | string | . | Path to the terraform module |
| `persist-workspace` | boolean | false | Boolean parameter to indicate whether or not to attach to an existing workspace. |
| `plan` | string |  | Optionally provide a plan file to supply to the 'apply' command. |
| `resource_class` | string | medium | Specify the resource class for Docker Executor |
| `tag` | string | 1.0.0 | Specify the Terraform Docker image tag for the executor |
| `timeout` | string | 10m | Configure a custom timeout limit |
| `var` | string |  | Comma separated list of vars to set, e.g. 'foo=bar,bas=foo' |
| `var_file` | string |  | Comma separated list of var file paths |
| `workspace` | string |  | Name of the terraform workspace |
| `workspace-path` | string | . | Path of the workspace to persist to relative to workspace-root.  |
| `workspace-root` | string | . | Workspace root path that is either an absolute path or a path relative to the working directory. Defaults to '.' (the working directory) |

### destroy

Destroy current state


| Parameter | Type | Default | Description |
|---|---|---|---|
| `attach-workspace` | boolean | false | Attach (CircleCI) workspace to job. |
| `backend_config` | string |  | "Comma separated list of backend configs to set, e.g. 'foo=bar'"
 |
| `backend_config_file` | string |  | Path to a backend config file |
| `checkout` | boolean | false | Perform checkout as first step in job. |
| `cli_config_file` | string |  | Path to terraform cli config file |
| `path` | string | . | Path to the terraform module |
| `resource_class` | string | medium | Specify the resource class for Docker Executor |
| `tag` | string | 1.0.0 | Specify the Terraform Docker image tag for the executor |
| `timeout` | string | 10m | Configure a custom timeout limit |
| `var` | string |  | Comma separated list of vars to set, e.g. 'foo=bar,bas=foo' |
| `var_file` | string |  | Comma separated list of vars file paths |
| `workspace` | string |  | Name of the terraform workspace |
| `workspace-root` | string | . | Workspace root path that is either an absolute path or a path relative to the working directory. Defaults to '.' (the working directory) |

### fmt

Run terraform fmt


| Parameter | Type | Default | Description |
|---|---|---|---|
| `attach-workspace` | boolean | false | Attach (CircleCI) workspace to job. |
| `checkout` | boolean | false | Perform checkout as first step in job. |
| `path` | string | . | Path to the terraform module |
| `recursive` | boolean | false | Process files in subdirectories |
| `resource_class` | string | medium | Specify the resource class for Docker Executor |
| `tag` | string | 1.0.0 | Specify the Terraform Docker image tag for the executor |
| `timeout` | string | 10m | Configure a custom timeout limit |
| `workspace-root` | string | . | Workspace root path that is either an absolute path or a path relative to the working directory. Defaults to '.' (the working directory) |

### init

Inits terraform directory


| Parameter | Type | Default | Description |
|---|---|---|---|
| `attach-workspace` | boolean | false | Do cool stuff with workspaces |
| `checkout` | boolean | false | Perform checkout as first step in job. |
| `cli_config_file` | string |  | Path to terraform cli config file |
| `path` | string | . | Path to the terraform module |
| `resource_class` | string | medium | Specify the resource class for Docker Executor |
| `tag` | string | 1.0.0 | Specify the Terraform Docker image tag for the executor |
| `timeout` | string | 10m | Configure a custom timeout limit |
| `workspace-root-dir` | string | . | circleci workspaces...not terraform |

### plan

Run Terraform plan against current state


| Parameter | Type | Default | Description |
|---|---|---|---|
| `attach-workspace` | boolean | false | Do cool stuff with workspaces |
| `backend_config` | string |  | "Comma separated list of backend configs to set, e.g. 'foo=bar'"
 |
| `backend_config_file` | string |  | Path to a backend config file |
| `checkout` | boolean | true | Perform checkout as first step in job. |
| `cli_config_file` | string |  | Path to terraform cli config file |
| `destroy_plan` | boolean | false | Run this plan as a destroy plan. |
| `lock` | boolean | true | Enable the lock on the state file or not |
| `lock-timeout` | string | 30s | Configure a custom state lock timeout |
| `out` | string | plan.out | The file path to save your terraform plan to. Set this to "" if you are using terraform cloud. |
| `parallelism` | integer | 10 | Limit the number of concurrent operation Terraform is running. Defaults to 10 |
| `path` | string | . | Path to the terraform module |
| `persist-workspace` | boolean | false | Persist files to (cci) workspace for use in subsequent jobs |
| `resource_class` | string | medium | Specify the resource class for Docker Executor |
| `tag` | string | 1.0.0 | Specify the Terraform Docker image tag for the executor |
| `timeout` | string | 10m | Configure a custom timeout limit |
| `var` | string |  | Comma separated list of vars to set, e.g. 'foo=bar,bas=foo' |
| `var_file` | string |  | Comma separated list of var file paths |
| `workspace` | string |  | Name of the terraform workspace |
| `workspace-path` | string | . | Path of the workspace to persist to relative to workspace-root. |
| `workspace-root` | string | . | Workspace root path that is either an absolute path or a path relative to the working directory. Defaults to '.' (the working directory) |

### validate

Validate Terraform files


| Parameter | Type | Default | Description |
|---|---|---|---|
| `attach-workspace` | boolean | false | Attach (CircleCI) workspace to job. |
| `backend` | boolean | true | Enable backend configuration or not |
| `backend_config` | string |  | "Comma separated list of backend configs to set, e.g. 'foo=bar'"
 |
| `backend_config_file` | string |  | Path to a backend config file |
| `checkout` | boolean | false | Perform checkout as first step in job. |
| `cli_config_file` | string |  | Path to terraform cli config file |
| `path` | string | . | Path to the terraform module |
| `resource_class` | string | medium | Specify the resource class for Docker Executor |
| `tag` | string | 1.0.0 | Specify the Terraform Docker image tag for the executor |
| `timeout` | string | 10m | Configure a custom timeout limit |
| `workspace` | string |  | Name of the terraform workspace |
| `workspace-root` | string | . | Workspace root path that is either an absolute path or a path relative to the working directory. Defaults to '.' (the working directory) |

## Executors

### default

Simple Docker based Terraform executor.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `resource_class` | string | medium | Specify the resource class for Docker Executor |
| `tag` | string | latest | Specify the Terraform Docker image tag for the executor. Default to latest. |

## Examples

### deploy_infrastructure

Deploy infrastructure leveraging a sequence of jobs and workspaces to create and persist a terraform plan.

Apply will 'apply' the result of a terraform plan.


```yaml
version: '2.1'
orbs:
  terraform: circleci/terraform@3.5
workflows:
  deploy_infrastructure:
    jobs:
      - terraform/fmt:
          checkout: true
          context: terraform
      - terraform/validate:
          checkout: true
          context: terraform
          requires:
            - terraform/fmt
      - terraform/plan:
          checkout: true
          context: terraform
          persist-workspace: true
          requires:
            - terraform/validate
      - terraform/apply:
          attach-workspace: true
          context: terraform
          filters:
            branches:
              only: main
          requires:
            - terraform/plan
```

### deploy_infrastructure_job

Deploy infrastructure by leveraging a sequence of commands to create and apply subsequent terraform plan.


```yaml
version: '2.1'
orbs:
  terraform: circleci/terraform@3.5
jobs:
  single-job-lifecycle:
    executor: terraform/default
    steps:
      - checkout
      - terraform/init:
          path: .
      - terraform/validate:
          path: .
      - terraform/fmt:
          path: .
      - terraform/plan:
          path: .
      - terraform/apply:
          path: .
      - terraform/plan:
          destroy_plan: true
          path: .
      - terraform/destroy:
          path: .
    working_directory: ~/src
workflows:
  single-job-lifecycle:
    jobs:
      - single-job-lifecycle
```

### deploy_using_remote_backend

Deploy infrastructure that uses a remote backend to manage state. This example uses a Terraform Cloud example and references a remote.hcl file to specify the backend config.


```yaml
version: '2.1'
orbs:
  terraform: circleci/terraform@3.5
jobs:
  single-job-lifecycle:
    executor: terraform/default
    steps:
      - checkout
      - run:
          command: >-
            echo "credentials \"app.terraform.io\" {token =
            \"$TERRAFORM_TOKEN\"}" > $HOME/.terraformrc
          name: Create .terraformrc file locally
      - terraform/install:
          arch: amd64
          os: linux
          terraform_version: 0.14.2
      - terraform/fmt:
          path: .
      - terraform/validate:
          path: .
      - terraform/init:
          backend: true
          backend_config_file: backend.hcl
          path: .
      - terraform/plan:
          backend_config_file: backend.hcl
          path: .
      - terraform/apply:
          backend_config_file: backend.hcl
          path: .
      - terraform/destroy:
          path: .
    working_directory: ~/src
workflows:
  single-job-lifecycle:
    jobs:
      - single-job-lifecycle
```