Review deployment plans

Deployment plans are a combination of an individual configuration version and one of your stack’s deployments. As in the traditional Terraform workflow, HCP Terraform creates plans every time a new configuration version introduces potential changes for a deployment.

This guide explains how to review and approve deployment plans in HCP Terraform.

Requirements

To view a Stack and its plans, you must also be a member of a team in your organization with one of the following permissions:

• Organization-level View all projects or higher
• Project-level Write or higher

View a deployment

If you are not already on your stack’s deployment page, navigate to it:

1. In the navigation menu, click Projects under Manage.
2. Select the project containing your Stack.
3. Click Stacks in the navigation menu.
4. Select the Stack you want to review.

A stack’s Overview page displays the following information:

• The number of your stack’s components and deployments
• Your deployment’s current health
• The latest configuration version
• A chart listing each deployment’s recent configuration versions

To view all of the plans for a deployment, click the name of the deployment you want to review.

A deployment’s page lists its components and the last five deployment plans. Clicking on a component reveals all of the resources it contains. Opening the Inspect dropdown menu on a deployment's page reveals the option to download:

• State description downloads that deployment’s current state.
• Provider schemas downloads the schema of the providers of your deployment.

View plans

A Stack deployment can have multiple plans. In a deployment's page, underneath Latest plans, each deployment plan lists:

• The plan name
• The trigger why HCP Terraform created this plan
• The configuration version HCP Terraform created the plan with
• When HCP Terraform created the plan

You can see a plan’s full details by clicking the plan’s name or an abbreviated list of the plan’s changes by clicking Quick View. You can also click View all plans to display a list of all the plans for this deployment. You can filter plans by health status in the list of all plans.

Each plan includes a timeline detailing when the plan started, when it received its configuration version, and when it was approved.

Check deployment health

Click Overview in the sidebar of your Stack to view the status of each of your deployments.

Download plan data

You can download Stack plan data to debug and analyze how your Stack changes over time.

Select one of the following options in the Inspect drop-down to perform the associated action:

• View plan orchestration results displays HCP Terraform's decisions while making this plan.
• Download plan event stream downloads a log file of your plan’s events.
• Download plan description downloads a file with all plan information.
• View apply orchestration results displays HCP Terraform's decisions to apply this plan.
• Download apply event stream downloads a log file of your plan’s events.
• Download apply description downloads a file with all the information about this applied plan.

Approve plans

Like traditional Terraform plans, Stack deployment plans list the changes that will occur if you approve that plan. Each component lists its expected resource changes, and you can review those changes as you decide whether to apply a plan.

When viewing a deployment plan, HCP Terraform notes if that plan is awaiting approval. Click Approve plan if you want HCP Terraform to apply a plan to this deployment or Discard plan to ignore it. You manage each deployment independently, so any plans you approve only affect the current deployment you are interacting with.

Convergence checks

After applying any plan, HCP Terraform automatically triggers a plan called a convergence check. A convergence check is a re-plan to ensure components do not have any deferred changes. HCP Terraform continues to trigger new plans until the convergence check returns a plan that does not contain changes.

By default, each Stack has an auto-approve rule named empty_plan, which auto-approves a plan if it does not contain changes. When a convergence check contains no changes, HCP Terraform auto-applies that plan.

Deferred changes

Like with Terraform configuration files, HCP Terraform generates a dependency graph and creates resources defined in *.tfstack.hcl and *.tfdeploy.hcl files.

When you deploy a Stack with resources that depend on resources provisioned by other components in your stack, HCP Terraform recognizes the dependency between components and automatically defers that plan until HCP Terraform can complete it successfully. Plans with deferred changes are plans with resources that depend on resources that don't exist yet, requiring follow-up plans.

HCP Terraform notifies you in the UI if a plan contains deferred changes. Approving a plan with deferred changes makes HCP Terraform automatically create a follow-up plan to properly set up resources in the order of operations those resources require.

After applying a plan with deferred changes, HCP Terraform notifies you of any replans it creates with a link to View replan. You can review the replan to ensure HCP Terraform created your resources as expected.