Terraform workflows

By adopting IaC practices, organizations have gained agility, efficiency, and reliability in deploying cloud-native resources. This section details integration of version control systems (VCS) and building efficient infrastructure deployment pipelines for Terraform.

Streamlining IaC

As you automate Infrastructure as Code (IaC) provisioning and management, you can streamline the process, similar to automating source code build and deployment with Continuous Integration/Continuous Deployment (CI/CD) pipelines. To simplify this automation and integrate with version control systems (VCS) repositories, HCP Terraform and Terraform Enterprise offer powerful features.

You can take advantage of the VCS integration feature in HCP Terraform and Terraform Enterprise, which uses webhooks to directly integrates with VCS repositories. This allows you to implement a GitOps workflow without the need for custom pipelines.

Most scaled customers have strategic CI/CD pipeline orchestrators. In situations where you prefer to utilize these, HCP Terraform and Terraform Enterprise form the infrastructure management component of such pipelines.

Personas

As with other recommendations in this document, we recommend the platform team designs and owns the infrastructure deployment pipeline design. Work with the following other personas to ensure efficiency of design end-to-end.

VCS-driven workflow

When it comes to managing your infrastructure as code, Terraform offers a VCS-driven workflow that streamlines the process and enhances collaboration among your team members. This approach automatically triggers runs based on changes made in your VCS repositories, making it easier to keep track of modifications and ensuring that your infrastructure configuration stays up-to-date.

By establishing shared repositories as the definitive source of truth, your team can work concurrently on the same infrastructure code, promoting increased collaboration. You can also associate this workflow with webhooks on your preferred VCS providers, streamlining the process of triggering runs and ensuring efficient synchronization between code changes and infrastructure updates.

Prerequisite(s)

Before proceeding with the VCS-driven workflow, ensure you complete the following pre-work for each category:

1. VCS repository:

   • Set up a Version Control System (VCS) repository that contains the source code for the deployment.

2. VCS authentication:

   • Establish VCS authentication enabling access to the repository securely for HCP Terraform.

3. VCS permissions:

   • Define the required VCS permissions for individuals, specifying appropriate access levels such as read-only, merge, and so on.

4. Deployment orchestration:

   • Choose whether to use workspaces or Stacks to orchestrate your Terraform deployments.

     If using workspaces:

     • Define workspace naming convention to maintain consistency.
     • Define workspace permissions, ensuring that the right users have the necessary access for collaboration.
     • Configure workspace settings, including enabling speculative plans, auto apply, and other relevant options.
     • Decide on a specific git tag format for auto apply(opens in new tab) to streamline the deployment process.

     If using Stacks:

     • Define Stack naming convention to maintain consistency.
     • Set permissions on the Stack at the project level
     • Configure Stack settings, including enabling speculative plans, branch versus tag based VCS trigger, and other relevant options.

Workflow overview

These are the high level steps one would take to implement a successful VCS-driven workflow in Terraform.

1. Configure VCS integration: Establish a VCS integration for your organization to connect HCP Terraform and Terraform Enterprise with your VCS.
2. Connect workspace or Stack to repository: Link your workspace or Stack to the desired branch in your VCS repository, enabling automatic synchronization of code changes.
3. Adopt branching strategy: Adopt a suitable branching strategy, such as standard feature branching, to effectively manage different stages of development and deployment within your VCS repository.
4. Enable speculative plan runs: Automate speculative plan runs for each branch, allowing you to preview changes and validate configurations without impacting the live infrastructure.
5. Define PR process: Apply your organisation's standard PR process.
6. (optional) Configure automatic run triggers: Set up VCS run triggers for the plan phase based on git tag pushes, streamlining the deployment process and enhancing efficiency.

VCS integration

Incorporating the VCS provider is crucial to establishing an automated workflow that predicts, plans, and initiates runs seamlessly. In the VCS-driven approach, a specific VCS repository backs each workspace or Stack. To access configurations from the VCS, Terraform requires permissions for the following tasks.

• Access a list of repositories: This enables you to search for repositories when creating new workspaces or Stacks.
• Register webhooks with your VCS provider: Webhooks keep HCP Terraform informed about new commits to your chosen branch.
• Download repository contents at a specific commit: This action allows Terraform to execute with the specified code.

HCP Terraform uses webhooks to monitor new commits, pull requests and tags. An automatic run based on the configured repository branch triggers a workspace or Stacks run. Similarly, initiating a pull request or merge request activates speculative plans.

VCS connection

Integrating the VCS provider is essential for the workflow to work. HCP Terraform uses the OAuth protocol to authenticate with VCS providers, and each provider may have distinct methods and steps to configure this connection. Refer to the respective guide for specific details.

Connecting your Terraform workspace or Stack to the desired branch in your VCS repository is a key step in the VCS-driven workflow. By linking the workspace and the branch, you enable automatic synchronization of runs with code changes.

HCP Terraform provides three main options to specify which changes trigger runs in your repository.

1. When a specific branch changes. This implies long-running branches or merged feature branches to the default branch.

2. Any tags to a repository matching a pattern (per (1)). Branches are irrelevant for this option. A single change in a repository can cause changes in multiple workspaces if customers are mapping a given repo-branch combination to multiple workspaces. This option instructs HCP Terraform to begin new runs only for changes that have a specific tag format. You can choose between various tag format options:

   • Semantic versioning: It matches tags in the popular semantic versioning format. For example, 0.4.2.
   • Version contains a prefix: It matches tags which have an additional prefix before the semantic versioning format. For example, version-0.4.2.
   • Version contains a suffix: It matches tags which have an additional suffix after the semantic versioning format. For example, 0.4.2-alpha.
   • Custom Regular Expression: You can define your own regular expression for HCP Terraform to match against tags.

Auto apply

Terraform offers a auto apply option, which applies changes from successful plans without prompting for approval (this is irrespective of way the plan triggers - VCS, API and so on). This feature is useful in non-interactive non-production environments to automatically run a terraform apply on a successful plan.

Auto apply is a configurable setting per workspace, which means you can control which workspaces run automatically and which need approval. A typical pattern is to allow auto apply for pre-production workspaces, but not for production workspaces where change control is a requirement.

If using Stacks, deployment group orchestration rules govern auto apply behavior, which the deployment configuration codifies. This gives you greater control over which deployments need approval, for example, auto apply only if the deployment is pre-production and where the run plan cites no resources to destroy.

Branching strategy

Having a well-defined branching strategy is important as it allows for effective management of different stages of development and deployment, providing control over the code changes introduced at each phase. The guidance differs for workspaces and Stacks, due to their different approaches to the promotion of changes through environments.

Branching strategy for workspaces

Deploy each environment or stage using a separate workspace or set of workspaces, and the branching strategy must reflect that mapping. As an overview, here are workspace configuration guidelines that assist you in maintaining a well-organized, scalable, and efficient Terraform workflow:

• Unique repository/branch mapping: The recommended pattern is to assign each workspace to a unique combination of a repository and branch. When changing the associated repository and branch, a Terraform run automatically triggers the corresponding workspace.
• Sub folders within repository: While sub folders can exist within the repository, it is important to ensure that the same workspace manages all resources in the repository. This practice promotes isolation and organization, making it easier to manage and maintain Terraform configurations.
• Branches for related workspaces: Utilize different branches to represent related workspaces. For example, you can have a branch named main for production and another branch named dev for development. This approach helps to separate and manage configurations for different environments efficiently.
• Pull request (PR) workflow: When a PR opens against a specific workspace branch, the PR must only contain information about that particular workspace. This focused approach allows for clearer review and approval of changes specific to the intended workspace.
• Release workflow: The workflow for releasing changes follows standard development practices. Developers make changes on a feature branch, which is later merged into a long-lived branch like dev. Merge changes from the dev branch into the main workspace, enabling a controlled and streamlined release process.

Recommendation

Consider adopting a branching strategy similar to GitHub Flow, if GitHub is your primary version control tool. This trunking-based model utilizes short-lived branches instead of feature tags. With this approach, you create a branch from the main branch, make your changes (in our Terraform use case, these changes would be within the environment's specified workspace folder) and commit the changes. Then you push a pull request, merge the changes into the main branch, and then delete the branch. The main objective of this model is to have short-lived branches, ensuring that the main branch always reflects the latest features or changes at any given time.

As a general approach, we suggest aligning the dev, stage, and production branches with their respective workspaces for applications. This alignment promotes a clear and structured workflow, enabling smooth transitions between different development stages and deployments.

Here are the steps that align with the GitHub Flow Git Branching Model:

1. Start by creating a repository with three branches - dev, stage, and prod. Commit your initial code in the dev branch.
2. For each feature development, create a separate feature branch off the dev branch. For example: feature/app1-web-tier.
3. Make your changes and commit them to your branch. Ensure that each commit contains an isolated and complete change for convenient reversion and feedback.
4. Push your changes to your feature branch and create a pull request.
5. Address any comments, issues, tasks, or questions from reviewers during the pull request review process.
6. The reviewer merges your pull request, incorporating your feature branch into the dev branch.
7. The final reviewer performs a squash commits and merge, streamlining the changes into the dev branch.
8. Delete the feature branch after merging to maintain only long-lived branches for each environment (dev, stage, and prod).

Speculative plan

Speculative plans play a crucial role as they allow you to preview and validate changes before merging them into the main branches. This ensures that your infrastructure remains stable and reliable. Here are the steps for the code update workflow, taking advantage of the recommended branching strategy and utilizing speculative plans:

1. Create a feature branch from the dev branch to work on specific changes.
2. Test and validate the features in the feature branch.
3. Open the PR. This triggers a speculative run.
4. Review, approve and merge the changes into the dev branch.
5. Repeat the steps 3 and 4 for stage branch and then the main production branch.
6. Delete the feature branch to avoid the maintenance of long-lived feature branches.

Speculative plans are a valuable feature for reviewing proposed changes. Terraform can automatically run speculative plans for pull requests or merge requests. You can view speculative plans in the UI. Also, if you are using GitHub, Terraform adds a link to the run in the pull request itself, along with an indicator of the run's status. When you update a pull request, Terraform performs new speculative plans and updates the link.

Although any contributor to the repository can see the status indicators for pull request plans, only members of your Terraform organization with permission to read runs for the affected workspaces can click through and view the complete plan output.

When creating a pull request or updating one, Terraform checks whether a speculative plan connected to that repository needs to run in the connected workspace, based on the following rules:

• Only pull requests that originate from within the same repository can trigger speculative plans.
• Pull requests can only trigger runs in workspaces with automatic speculative plans enabled. You can turn off automatic speculative plans in the workspace VCS settings.
• A pull request only triggers speculative plans in workspaces connected to that pull request's destination branch. In order to trigger an apply run, close the PR and merged into the branch, which means statuses are no longer registered.

HCP Terraform does not update the status checks on a pull request with the status of an associated apply. This means that a commit with a successful plan but an apply error still shows the passing commit status from the plan.

Branching strategy for Stacks

In the preceding VCS-backed workspace workflow, we recommend controlling promotion across environments through version control, typically using pull/merge requests to move changes from one environment branch to the next. In practice, teams often find it difficult to keep environment branches fully aligned, and configuration drift is common, increasing the risk of unintended differences across environments.

Stacks uses an alternative approach: deployments represent application infrastructure environments within the same Stack and therefore track the same codebase, typically the main branch. All deployments plan in parallel when a new configuration version uploads to the Stack. Independent approval or cancellation of each deployment follows. You can control roll out across environments by manually approving deployment runs in the desired order. You can apply the lowest environment (development) without approval by defining auto apply conditions on the deployment group.

Examples of this concept follow.

• A Stack contains three deployments (dev, staging, prod) that share the same component structure.
• Auto-apply rules within the dev deployment group cause automatic apply of the dev environment as long as the plan meets the specified conditions, such as where the change schedule does not include resource destruction.
• Once the dev deployment run is complete and the environment build is successful, manually approve the staging deployment group.
• If encountering a problem at any stage, either in completing the apply or in the health of the resulting infrastructure, cancel the plans in the subsequent deployments. Fix any problems in the code and push a new configuration version and repeat the process.
• Apply and test the staging environment, then arrange for the approval of the change request for the production deployment to complete.

Additional workflow options

While the recommended VCS-driven workflow offers seamless collaboration and automation through integration with your version control system, it is good to consider alternative approaches that might better suit your organization's specific needs. The VCS-driven workflow provides a convenient way to implement an IaC workflow without requiring custom CI/CD pipelines. It is beneficial to explore other two workflows: the command line-driven and API-driven workflows. These approaches have their advantages and can be valuable additions to your Terraform workflow.

API-driven workflow

When working with HCP Terraform and Terraform Enterprise, the API-driven workflow offers complete control over the IaC process, making it highly compatible with custom CI/CD pipelines utilizing the HCP Terraform and Terraform Enterprise API. If your requirement involves seamless integration with external CI tools, an API-driven workflow can be the most suitable approach, providing flexibility to utilize your current CI tools for tracking state and maintaining continuous linkage between Terraform and your code. As the most advanced approach, this workflow is often adopted by large organizations with complex requirements, either directly or as an evolution from the command line-driven workflow.

The API-driven workflow offers distinct advantages over the recommended VCS approach, including unparalleled flexibility for integration with existing CI/CD pipelines, additional testing capabilities, and full integration with third-party platforms. It also enables centralized code management, retains current CI/CD configurations, and leverages existing programming languages for a more tailored Terraform workflow.

API workflow overview

The high-level API-driven workflow utilizing HCP Terraform and Terraform Enterprise API endpoints includes the following steps:

1. Define variables for organization, workspace, and projects using team or user API tokens.
2. Prepare the configuration file for upload using the configuration version API.
3. Solicit the workspace ID using the configuration version API.
4. Create a configuration version using the configuration version API.
5. Upload the configuration version using the run apply API.

Pipeline templates

The API-driven workflow can be further enhanced by leveraging pipeline templates, which bring numerous benefits to integrating HCP Terraform and Terraform Enterprise with various CI/CD platforms. These templates provide clear and predefined examples, making the integration process straightforward and less time-consuming. With a fast-start approach, organizations can streamline their integration process, accelerating the deployment of Terraform in their CI/CD workflows while ensuring consistency across the pipelines. By utilizing existing templates, organizations save effort and resources that is otherwise spent developing custom API-driven workflows. Moreover, these prescriptive templates cater to various CI/CD platforms, ensuring compatibility and smooth integration with existing tools. As an added advantage, the templates are continuously maintained and updated by the Terraform community, allowing organizations to benefit from the latest improvements and best practices, keeping their Terraform workflow up-to-date and efficient.

When integrating Terraform into your existing CI/CD pipelines, consider the convenience and efficiency of leveraging prescriptive pipeline templates. These templates provide explicit examples of how to integrate with HCP Terraform and Terraform Enterprise on various CI/CD platforms, offering a straightforward way to get started without the need to develop templates from scratch. By following these steps, you can incorporate Terraform into your CI/CD workflows.

1. Choose a pipeline template that aligns with your CI/CD platform and meets your specific integration needs with HCP Terraform and Terraform Enterprise.
2. Tailor the template to suit your organization's requirements by adjusting configurations, adding or removing steps, and integrating it with other tools in your CI/CD pipeline.
3. Integrate the customized template into your CI/CD pipeline and thoroughly test it to ensure it aligns with your desired workflows.

Examples

HashiCorp offers GitHub Actions that integrate with HCP Terraform and Terraform Enterprise APIs, empowering you to create customized CI/CD workflows tailored to your organization's specific needs.

A typical GitHub Action workflow includes generating a plan for each commit to a pull request branch. This is then reviewed in HCP Terraform. Once you update the VCS branch, the configuration is automatically applied.

Upon configuring the GitHub Action, you can create and merge a pull request to test the workflow. HCP Terraform has built-in support for webhooks to facilitate this generic workflow. Also, by using HashiCorp's Terraform GitHub Actions, you can design a custom workflow with additional steps before or after your Terraform operations, enhancing your automation capabilities.

For additional information and resources, you can refer to the following documentation:

• Announcement(opens in new tab)
• Tutorial(opens in new tab)

Command line-driven workflow

The command line-driven workflow, you can transition from using OSS command line commands to HCP Terraform Agents for triggering the build process. This workflow offers the flexibility to iterate on your configuration and work locally, allowing for efficient development and testing. Moreover, it simplifies integration with CI/CD tools, enabling the addition of testing steps and enhancing deployment reliability, streamlining the process compared to the VCS-driven approach. Also, the command line workflow promotes centralized code management, fostering effective collaboration and version control, which is valuable for organizations with complex requirements. Furthermore, it permits convenient local development of workspaces, minimizing the need for frequent code commits and enhancing the overall development experience. For organizations with existing CI/CD configurations, transitioning to the command line workflow can be straightforward, allowing them to retain their current setups and reducing the need for major adjustments. Lastly, the command line workflow provides faster feedback to practitioners, enabling greater flexibility in deploying changes across different environments, making it an attractive alternative to the VCS-driven approach for those who require rapid iterations and deployments.

Workflow overview

This high-level command line-driven workflow includes the following steps:

1. Generate a command line token for use as a CI/CD tool or local user.
2. Create a workspace and update the backend configuration block.
3. Construct CI/CD pipelines to include pre-plan checks like linting, security scanning, and unit testing.
4. Trigger the plan using the terraform plan, apply, or destroy command line command, whether invoked by a human user or a CI/CD script.
5. Configure your CI/CD tool to automatically trigger plans based on branch or directory changes.
6. Set up different pipelines for pull requests, pushes to specific branches, and so on.

After making and validating code changes, merge pull requests to the main branch.