Which Terraform workflow should I use? VCS, CLI, or API?

The goal for most organizations is to standardize software development workflows and tooling to simplify operations and ensure security and stability. For provisioning workflows, this means establishing golden workflows and components. However, some applications require more flexibility to build, so experienced developers and operators will need more leeway to provision infrastructure outside certain guardrails.

HCP Terraform (formerly Terraform Cloud) allows this flexibility through API-driven workflows. These workflows offer customization but they are more complex than UI/version control system (VCS) or CLI-driven workflows, so it's recommended that experienced Terraform users manage them. This post will compare the three HCP Terraform run workflows (CLI, UI/VCS, and API), highlighting their use cases and benefits.

»How to choose the right HCP Terraform run workflow

Every organization has a unique journey with infrastructure provisioning shaped by the needs of the business as well as the preferences and skills of the administrators and developers. One size does not fit all when it comes to workflows—each team must evaluate and implement the processes that best align with their unique objectives and dynamics. Below are some essential factors to consider when customizing workflows for your team:

• Setup efforts
• Maintenance efforts
• Security concerns
• Architectural and process complexity

»The 3 HCP Terraform workflows

HCP Terraform has three workflows for managing Terraform runs, and your chosen workflow determines when and how Terraform runs occur.

»UI/VCS

The UI/VCS-driven run workflow is the simplest, most “push-button” method for HCP Terraform runs. In this workflow, HCP Terraform can connect to any of the major VCS providers (e.g. GitHub or Bitbucket). Once connected, HCP Terraform automatically registers webhooks with your VCS provider when you create a workspace. Whenever new commits are merged to the branch of a workspace’s linked repository, HCP Terraform automatically queues a Terraform run. It also performs a speculative plan when a pull request is opened against that branch.

»Use this when

• You need simple traceability and transparency.
• You want to employ a GitOps workflow for managing large-scale deployments.
• You want an easy-to-setup, basic, collaborative provisioning workflow.
• You want to provide users with an easy self-service workflow.

»Setup tasks

• Access: The users need to have access to the VCS and HCP Terraform with the appropriate permissions.
• Define the repository architecture: Set up repositories via your VCS (e.g. GitHub) for internal teams to store the Terraform configuration files.
• Integration: Link your existing Terraform organization to your chosen VCS. For example, if you are using GitHub, you would use GitHub Apps or GitHub OAuth.
• Create an HCP Terraform workspace: For new workspaces, follow the UI guidance to create a workspace with a corresponding repository. A workspace is linked to one branch of a VCS repository and ignores changes to other branches.

»Maintenance tasks

• Repository branch management: Teams need to maintain a disciplined approach to branching and versioning. Regular merging, conflict resolution, and ensuring the branches align with infrastructure changes are all critical tasks.
• VCS provider integration management: For example, if you use GitHub App, you need to manage the user’s access to different sets of repositories. If you use GitHub OAuth, you need to plan how to maintain the VCS providers if the person leaves the company.

»Security concerns

• Users with access to the repository may also be authorized to trigger Terraform runs.

»Architectural and process complexity

• This workflow is highly automated, promoting strong collaboration and thorough review processes.
• It’s easily scalable for teams and multiple environments.

»CLI

The CLI-driven run workflow uses Terraform's CLI tools to execute runs remotely in HCP Terraform. This workflow brings more of Terraform’s collaboration features into the picture. It has strengths from both the VCS and API-driven workflows and is useful for developers who are already comfortable with using the Terraform CLI and it can work with existing CI/CD pipelines.

However, the learning curve is steeper than the UI/VCS-driven workflow if you haven’t been exposed to the various CLI tools (terraform, tfci, etc.). Get familiar with these CLIs before using this workflow.

A CLI-driven run can start by simply running the standard terraform plan and terraform apply commands. You can watch the progress of the run from your terminal or the HCP Terraform UI.

»Use this when

• You are comfortable with the Terraform CLI.
• You want to enable additional commands for provisioning.
• Members of a small team want to test configurations locally.
• You want to start with the CLI-driven workflow, and add VCS providers for those workspaces later.
• Your workspaces are not connected to any VCS repository.

»Setup tasks

• Build: Install and configure the Terraform CLI.
• Authentication setup: Configure authentication for the CLI using API tokens or OAuth. The HCP Terraform CLI must be connected to your HCP environment with the proper access permissions to manage the infrastructure.
• Integration: Integrate with your existing CI/CD pipelines.
• Choose starting point: Start from the UI or from the command line.

»Maintenance tasks

• Terraform version updates: Updating Terraform versions (CLI and provider plugins) on local machines or CI servers requires version management.
• Branch management: You need to maintain a disciplined approach to branching and versioning the Terraform configuration files locally and/or through your CI/CD pipeline.

»Security concerns

• Administrators need to have a plan to manage credentials, such as the HCP Terraform API tokens. Other variables can be managed through the HCP Terraform workspace.
• Administrators need to apply access controls on the configuration files.

»Architectural and process complexity

• Uses the Terraform binary (a wrapper around the go-tfe API client)
• This workflow is familiar to those with experience using the Terraform Community Edition, where the CLI workflow is the default workflow.
• Compared to the VCS-driven workflow, it takes more effort to integrate into your CI/CD.

»API

The API-driven run workflow is more flexible than the other two workflows, but it requires the creation of some tooling in most cases. It operates based on an orchestrator capable of monitoring changes to your Terraform code and making a series of calls to HCP Terraform to perform runs (e.g. a CI/CD system or something else capable of monitoring changes to your Terraform code and performing actions in response). The orchestrator can automatically decide when your configuration has changed and a run should occur.

To automate API-driven workflows, users often create custom tooling by wrapping the HCP Terraform API. This enables them to make specific API calls before or after a Terraform run, performing actions based on the output or conditions. For instance, after a Terraform run, this custom wrapper could trigger a tool like Ansible. This approach is commonly used to meet organizational needs, address specific requirements, or handle custom workflows that standardized solutions cannot fully support.

This workflow has the steepest learning curve of the three. Get familiar with the HCP Terraform API before you start using this workflow. The workflow author should have expertise in CI/CD integrations and scalable practices.

»Use this when

• You need a custom workflow that is integrated with your specific toolchain.
• You need highly granular controls for each step of the workflow.
• You want workflows that go beyond Terraform provisioning.
• You want to run low-touch, heavily automated workflows.
• When you don’t want the user to access the HCP Terraform UI or CLI, or the VCS directly. The organization wants to trigger those tools only through integration with a different central platform, such as ServiceNow or a custom system.

»Setup tasks:

• Requirements: Choose the orchestration tool (e.g. your CI/CD system) you want to automate HCP Terraform with. Research its integration points.
• Authentication setup: Set up API token for authentication with HCP Terraform.
• Automation scripts: Build scripts that interact with the Terraform API. This can involve using tools like curl, Postman, or writing scripts in languages like Python or Go to interact with the HCP Terraform API.
• Webhook configuration: Set up webhooks to trigger automated workflows when specific events occur. Set up triggers to call Terraform runs or apply changes via the API.
• Integration: Build a wrapper to integrate workflow with any tools/systems.

»Maintenance tasks:

• API changes and deprecation: Continuously monitor the API for updates or deprecations. As HCP Terraform or other third-party services update their APIs, you’ll need to maintain your scripts to ensure compatibility.
• Run tracking: You’ll also want to use the API’s capabilities to monitor and track the progress of runs.
• Error handling and logging: Have logging and alerting mechanisms in place to ensure that the system provides enough detailed information in real-time, enabling quick issue detection and efficient troubleshooting.

»Security concerns

• Credential management: Administrators need to have a plan to manage credentials, including the HCP Terraform API token.
• Granular access control: Ensure that proper access control policies (e.g., OAuth scopes, permissions) are in place to limit the exposure of infrastructure.
• API endpoint security: Ensure that all API calls are made over HTTPS to avoid man-in-the-middle (MITM) attacks.
• Implement a security strategy: Set up and manage your own authentication, authorization, monitoring, and anomaly detection.

»Architectural and process complexity

• This workflow is complex to set up, maintain, and debug, especially if integrating with multiple systems.

»Workflows change and evolve

In real-world infrastructure development, the workflows used can vary depending on the stage of the project. They may even shift from one to another as the project evolves. It's crucial to consider the project's goals, timeline, maintenance costs, and team skill levels to determine the most suitable workflow for your current state.

»Summary chart

Every organization has a different journey with infrastructure provisioning, and every journey is unique at the organizational, team, and individual level.

• Terraform users need to identify what workflows suit them.
• Standardization across one team might not suit the other.
• More flexible requirements typically result in a more complex implementation.

Here is a quick reference table for each of the three HCP Terraform workflows:

»Additional references

• Use the VCS-driven workflow
• Create a CLI-driven workspace
• The API-driven run workflow