Hands-on: Try the Get Started — HCP Terraform tutorials.
HCP Terraform provides a central interface for running Terraform within a large collaborative organization. If you're accustomed to running Terraform from your workstation, the way HCP Terraform manages runs can be unfamiliar.
This page describes the basics of how runs work in HCP Terraform.
HCP Terraform is designed as an execution platform for Terraform, and can perform Terraform runs on its own disposable virtual machines. This provides a consistent and reliable run environment, and enables advanced features like Sentinel policy enforcement, cost estimation, notifications, version control integration, and more.
Terraform runs managed by HCP Terraform are called remote operations. Remote runs can be initiated by webhooks from your VCS provider, by UI controls within HCP Terraform, by API calls, or by Terraform CLI. When using Terraform CLI to perform remote operations, the progress of the run is streamed to the user's terminal, to provide an experience equivalent to local operations.
Disabling Remote OperationsMany of HCP Terraform's features rely on remote execution and are not available when using local operations. This includes features like Sentinel policy enforcement, cost estimation, and notifications.
You can disable remote operations for any workspace by changing its Execution Mode to Local. This causes the workspace to act only as a remote backend for Terraform state, with all execution occurring on your own workstations or continuous integration workers.
Protecting Private EnvironmentsHCP Terraform agents are a paid feature that allows HCP Terraform to communicate with isolated, private, or on-premises infrastructure. The agent polls HCP Terraform or Terraform Enterprise for any changes to your configuration and executes the changes locally, so you do not need to allow public ingress traffic to your resources. Agents allow you to control infrastructure in private environments without modifying your network perimeter.
HCP Terraform agents also support running custom programs, called hooks, during strategic points of a Terraform run. For example, you may create a hook to dynamically download software required by the Terraform run or send an HTTP request to a system to kick off an external workflow.
HCP Terraform always performs Terraform runs in the context of a workspace. The workspace serves the same role that a persistent working directory serves when running Terraform locally: it provides the configuration, state, and variables for the run.
Configuration VersionsEach workspace is associated with a particular Terraform configuration, but that configuration is expected to change over time. Thus, HCP Terraform manages configurations as a series of configuration versions.
Most commonly, a workspace is linked to a VCS repository, and its configuration versions are tied to revisions in the specified VCS branch. In workspaces that aren't linked to a repository, new configuration versions can be uploaded via Terraform CLI or via the API.
Ordering and TimingEach workspace in HCP Terraform maintains its own queue of runs, and processes those runs in order.
Whenever a new run is initiated, it's added to the end of the queue. If there's already a run in progress, the new run won't start until the current one has completely finished — HCP Terraform won't even plan the run yet, because the current run might change what a future run would do. Runs that are waiting for other runs to finish are in a pending state, and a workspace might have any number of pending runs.
There are two exceptions to the run queue, which can proceed at any time and do not block the progress of other runs:
When you initiate a run, HCP Terraform locks the run to a particular configuration version and set of variable values. If you change variables or commit new code before the run finishes, it will only affect future runs, not runs that are already pending, planning, or awaiting apply.
Workspace LocksWhen a workspace is locked, HCP Terraform can create new runs (automatically or manually), but those runs do not begin until you unlock the workspace.
When a run is in progress, that run locks the workspace, as described above under "Ordering and Timing".
There are two kinds of run operation that can ignore workspace locking:
A user or team can also deliberately lock a workspace, to perform maintenance or for any other reason. For more details, see Locking Workspaces (Preventing Runs).
HCP Terraform has three main workflows for managing runs, and your chosen workflow determines when and how Terraform runs occur. For detailed information, see:
You can use the following methods to initiate HCP Terraform runs:
terraform apply command when the CLI integration is configuredHCP Terraform enforces Terraform's division between plan and apply operations. It always plans first, then uses that plan's output for the apply.
In the default configuration, HCP Terraform waits for user approval before running an apply, but you can configure workspaces to automatically apply successful plans. Some plans can't be auto-applied, like plans queued by run triggers or by users without permission to apply runs for the workspace. (More about permissions.)
If a plan contains no changes, HCP Terraform does not attempt to apply it. Instead, the run ends with a status of "Planned and finished". The allow empty apply run mode can override this behavior.
Speculative PlansIn addition to normal runs, HCP Terraform can run speculative plans to test changes to a configuration during editing and code review. Speculative plans are plan-only runs. They show possible changes, and policies affected by those changes, but cannot apply any changes.
Speculative plans can begin without waiting for other runs to finish because they don't affect real infrastructure. HCP Terraform lists past speculative plan runs alongside a workspace's other runs.
There are three ways to run speculative plans:
terraform plan on the command line starts a speculative plan. The plan output streams to the terminal, and a link to the plan is also included.configuration-versions API for more information.If a speculative plan fails due to an external factor, you can run it again using the "Retry Run" button on its page:
Retrying a plan requires permission to queue plans for that workspace. (More about permissions.) Only failed or canceled plans can be retried.
Retrying the run will create a new run with the same configuration version. If it is a VCS-backed workspace, the pull request interface will receive the status of the new run, along with a link to the new run.
Saved PlansVersion note: Using saved plans from the CLI with HCP Terraform requires at least Terraform CLI v1.6.0.
HCP Terraform also supports saved plan runs. If you have configured the CLI integration you can use terraform plan -out <FILE> to perform and save a plan, terraform apply <FILE> to apply a saved plan, and terraform show <FILE> to inspect a saved plan before applying it. You can also create saved plan runs via the API by using the save-plan option.
Saved plan runs affect the run queue differently from normal runs, and can sometimes be automatically discarded. For more details, refer to Run Modes and Options: Saved Plans.
In addition to the normal run workflows described above, HCP Terraform supports destroy runs, refresh-only runs, and several planning options that can modify the behavior of a run. For more details, see Run Modes and Options.
HCP Terraform shows the progress of each run as it passes through each run state (pending, plan, policy check, apply, and completion). In some states, the run might require confirmation before continuing or ending; see Managing Runs: Interacting with Runs for more information.
In the list of workspaces on HCP Terraform's main page, each workspace shows the state of the run it's currently processing. (Or, if no run is in progress, the state of the most recent completed run.)
For full details about the stages of a run, see Run States and Stages.
We recommend using import blocks, introduced in Terraform 1.5, to import resources in HCP Terraform.
HCP Terraform does not support remote execution for the terraform import command. For this command the workspace acts only as a remote backend for Terraform state, with all execution occurring on your own workstations or continuous integration workers.
Since terraform import runs locally, environment variables defined in the workspace are not available. Any environment variables required by the provider you're importing from must be defined within your local execution scope.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4