CircleCI is a continuous integration and delivery platform for automating software builds, tests, and deployments. The CI/CD paradigm establishes version control repositories as the source of truth for deployments. It also helps teams quickly ship new features and fixes by defining pipelines that help ensure the stability and resilience of services through testing and automation. You can build deployment pipelines of varying complexity to satisfy organization requirements for production deployments.

Using Terraform to manage infrastructure as code enables the benefits of the CI/CD workflow for infrastructure deployments. Since infrastructure is codified, teams can collaborate and review it and deploy it using automated pipelines instead of manual orchestration. To automate Terraform operations in a remote environment, remote state storage must be configured so Terraform can access and manage project state across runs.

CircleCI and Terraform Automation Fundamentals

In this tutorial context, CircleCI and Terraform are used to deploy an S3-backed web application. The workflow configures and reviews an automated Terraform workflow and uses HCP Terraform for remote state storage.

The tutorial assumes familiarity with Terraform and HCP Terraform workflows. If new to Terraform, Get Started tutorials should be completed first.

Terraform allows for repeatable infrastructure deployment, so by adding Terraform to a CircleCI workflow, infrastructure can be deployed alongside software in the same pipeline. Terraform Cloud allows for remote state and automated runs from CircleCI, so infrastructure can be deployed in the same way.

CI/CD plus Terraform equals Dev/Ops. Whether a developer is responsible for software deployment or a sysadmin building underlying systems, skills can be used to deploy infrastructure as code, resulting in a working application to test.

The learning track covers creating underlying infrastructure for a static website with Terraform and deploying a webapp with CircleCI in the same workflow. It starts by learning how to use a CircleCI workflow in a standard deployment cycle.

A typical workflow definition includes:

yaml workflows: version: 2 build_plan_approve_apply: jobs: - build - plan: requires: - build - apply: requires: - plan - deployment: requires: - apply - hold: type: approval requires: - deployment - destroy: requires: - hold

The guide also covers creating a Terraform Cloud workspace and integrating infrastructure into CircleCI build settings.

By the end of the guide, a successful deployment and a safe destruction process are achieved. CircleCI will also generate a plan to destroy the infrastructure and wait for approval before running the destroy job.

Remote State and HCP Terraform Configuration

This configuration uses HCP Terraform for project state storage. A new workspace is created to use for the project and configured for local execution. When using local execution with HCP Terraform, Terraform operations occur in the environment that runs the Terraform CLI, in this case the Docker executor configured for the build, and HCP Terraform stores the state file for shared access across builds and runs.

In the HCP Terraform UI, create a new CLI-driven workspace named learn-terraform-circleci.

On the workspace overview page, click on the current Execution Mode to navigate to general settings. Under Execution Mode, select Local. Then click Save Settings at the bottom of the page.

Navigate to the CircleCI dashboard. Make sure you are in the correct organization with access to your GitHub account by confirming the organization in the top left corner. Then select Projects in the left sidebar.

Search for your forked learn-terraform-circleci repository. Then click the Set Up Project button.

Select the Fastest configuration option to use the CircleCI configuration file in the repository. Enter the main branch as the branch to track.

Terraform Orb for CircleCI Pipelines

CircleCI is known for fast builds and a clean configuration format. If a team uses CircleCI for application deployments, it makes sense to keep Terraform infrastructure pipelines there too. CircleCI's workflow system, approval jobs, and context-based secrets work well for the plan-review-apply pattern that Terraform deployments need.

This setup covers setting up Terraform in CircleCI from scratch, including using the official Terraform orb, building custom pipelines, and configuring multi-environment deployments with approval gates.

Run Terraform in CircleCI Pipelines with the Terraform Orb. Integrate Infrastructure-as-Code to help provision and manage any cloud, infrastructure, or service of choice.

CircleCI orbs are reusable packages of configuration. The official Terraform orb from CircleCI gives pre-built commands and jobs.

The orb handles Terraform installation, initialization, and command execution.

A sample configuration using the orb is:

```yaml

.circleci/config.yml

version: 2.1

Import the Terraform orb

orbs:
terraform: circleci/[email protected]

Use orb commands directly

workflows:
deploy:
jobs:
- terraform/validate:
checkout: true
path: terraform
- terraform/plan:
checkout: true
path: terraform
context: aws-credentials
persist-workspace: true
requires:
- terraform/validate
- hold:
type: approval
requires:
- terraform/plan
- terraform/apply:
attach-workspace: true
path: terraform
plan: plan.out
context: aws-credentials
requires:
- hold
filters:
branches:
only: main
```

The orb can be used to integrate Infrastructure-as-Code to help provision and manage any cloud, infrastructure, or service.

Orb Version Management

For the best experience, squash-and-merge and use Conventional Commit Messages.

Find the current version of the orb. You can run:

circleci orb info circleci/terraform | grep "Latest"

to see the current version.

Create a new Release on GitHub. Click Choose a tag and create a new semantically versioned tag. Ex: v1.0.0.

We will have an opportunity to change this before we publish if needed after the next step.

Click Choose a tag and create a new semantically versioned tag. Ex: v1.0.0.

Click + Auto-generate release notes. This will create a summary of all merged pull requests since the previous release.

If Conventional Commit Messages have been used it will be easy to determine what types of changes were made, allowing the correct version tag to be published.

Now ensure the version tag selected is semantically accurate based on changes included.

Click Publish Release. This will push a new tag and trigger publishing pipeline on CircleCI.

Orb Commands and Jobs

The official registry page documents all versions, executors, commands, and jobs.

CircleCI Orb Docs cover using, creating, and publishing CircleCI Orbs.

A summary of common Terraform orb workflow elements is:

Element	Purpose
terraform/validate	Validates Terraform configuration syntax and provider requirements
terraform/plan	Generates an execution plan using AWS credentials from context
terraform/apply	Applies the saved plan after approval
persist-workspace	Preserves plan file between jobs
attach-workspace	Restores plan file for apply job
hold	Approval gate for manual review

CircleCI Terraform Provider for IaC Management

The officially supported CircleCI Terraform provider is now available. The Terraform provider supports administrative tasks for managing projects, pipelines, triggers, and contexts. As a part of the Platform Team Toolkit, the Terraform provider can be used to leverage infrastructure as code practices and make managing CircleCI projects fast and easy.

The CircleCI Terraform Provider enables customers to manage CircleCI projects with IaC patterns, matching the same patterns used to manage GitHub repos. For large-scale organizations, this enables automated project creation for new teams or projects.

The current documentation is found in the repository. Define the provider:

```hcl
terraform {
required_providers {
circleci = {
source = "CircleCI-Public/circleci"
version = "0.1.1"
}
}
}

provider "circleci" {
host = "https://circleci.com/api/v2"

key = "*" # here you set you CircleCI API Key

runner_host = "https://runner.circleci.com" # required for self-hosted runner resources on CircleCI server

}
```

Start defining Data Sources and Resources. For example:

hcl resource "circleci_project" "test_project" { name = "Project_Name" organization_id = "********-****-****-****-****************" }

Use the Official CircleCI API documentation to check which valid values might be needed for some resources.

This repository was created following the Terraform plugin framework defined by Hashicorp.

This repository makes use of Task. It may be installed on MacOS with:

$ brew install go-task/tap/go-task

See the full list of available tasks by running task -l, or see the Taskfile.yml script.

Available tasks include:

task lint
task fmt
task generate
Run all the tests
Run the tests for one package
Run all the quick tests

The provider supports administrative tasks for managing projects, pipelines, triggers, and contexts.

Workflow Patterns and Best Practices

Using Terraform to manage infrastructure as code enables collaboration and review and deployment using automated pipelines instead of manual orchestration.

CircleCI's workflow system, approval jobs, and context-based secrets work well for the plan-review-apply pattern that Terraform deployments need.

A standard deployment cycle includes build, plan, apply, deployment, hold for approval, and destroy with approval.

Deploy and destroy are both covered. By the end of the guide, a successful deployment and a safe destruction process are achieved.

Try the new guide with demo code. To run through a live deployment with an accompanying code repo, visit HashiCorp Learn.

If you would like to learn more about CircleCI or automated Terraform workflow, additional resources are available.

Key integration points between CircleCI and Terraform are:

Remote state storage via HCP Terraform for shared access across builds and runs
Local execution mode where Terraform CLI runs in the Docker executor configured for the build
Approval jobs for plan review before apply
Context-based secrets for AWS credentials
Workspace persistence to pass plan artifacts between jobs
Terraform Orb for installation, initialization, and command execution
CircleCI Terraform Provider for managing CircleCI projects with IaC

Conclusion

CircleCI and Terraform together provide a complete pipeline for infrastructure as code with automated plan review, approval gates, and remote state management. Using HCP Terraform for remote state storage with local execution allows Terraform operations to run inside the CircleCI executor while state remains shared and consistent across runs. The official Terraform orb reduces boilerplate by providing pre-built validate, plan, and apply jobs that integrate with CircleCI contexts, workspaces, and approval holds.

For organizations managing many CircleCI projects, the official CircleCI Terraform provider adds a second layer of automation by enabling projects, pipelines, triggers, and contexts to be defined as code. This mirrors the same IaC patterns used for cloud resources and supports automated project creation for new teams.

Combining these capabilities yields repeatable infrastructure deployment alongside application deployment in the same workflow, with safe destruction processes and manual approval steps for production safety.

CircleCI Terraform Integration for Infrastructure as Code Automation