Create and review configuration versions

Each Stack deployment uses a configuration version to determine what infrastructure to create, update, or delete. You can rollout changes to your Stack deployments by creating new configuration versions. HCP Terraform is the interface for keeping track of your Stack configuration over time and the corresponding deployments for each version of your configuration.

Background

A Stack configuration version is a snapshot of all of the pieces that make up your Stack. A Stack configuration version includes:

• Your component configuration, in tfcomponent.hcl files.
• Your deployment configuration, in the tfdeploy.hcl file.
• The modules that implement your individual Stack components
• The input values that deployment block passes to your Stack components.

Requirements

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

• Organization-level Manage all projects or higher
• Project-level Read or higher

Create a configuration version

HCP Terraform creates a new configuration version each time any of the following change:

• Your configuration changes and VCS automatically fetches that change
• Your configuration changes and you manually fetch that change in HCP Terraform
• You manually upload a configuration
• An upstream_input that your Stack depends on changes.

Each configuration version creates a deployment run for every deployment of your Stack to implement the changes in that version. To learn more about how deployments and how they plan and apply infrastructure, refer to Stack deployment runs.

VCS-linked repositories

Stacks automatically detect when you push changes to your configuration from a VCS-linked repository. Every time you push changes to your repository, HCP Terraform automatically fetches your configuration and creates a new configuration version.

Whether automatic or manual, every time HCP Terraform fetches a new version of your configuration file, it creates a new configuration version, whether you made changes to that file or not.

Each configuration version creates a deployment run for every deployment of your Stack in order to implement the changes in that version. Learn more about reviewing and approving deployment runs.

Manually create a configuration version

If something changes outside of your VCS-linked repository you can manually create a configuration version to update your Stack deployments. For example, if a value in a variable set changes or if someone changes resources directly in the AWS console.

If your Stack is linked to a VCS repository, you can manually generate a new configuration version by doing the following:

1. Sign in to HCP Terraform, and select the organization that contains your Stack.
2. In the navigation menu, Select Projects under Manage.
3. Select the project containing your Stack.
4. Select the Stack you want to review.
5. Click Fetch configurations from VCS.

Upload configuration with the CLI

You can use the terraform stacks configuration upload command to manually upload your configuration files to create a new configuration version. This command is useful if your Stack is not linked to a VCS repository, or if you want to upload configuration changes outside of your VCS repository.

For more details, refer to the terraform stacks configuration upload reference.

Upload configuration with the API

You can also create a configuration version using the HCP Terraform API. To learn more, refer to the Stacks API.

Review configuration versions

The Configurations page contains a numbered sequential list of your configuration versions.

Configuration versions create deployment runs for each of your Stack's deployments. HCP Terraform marks each configuration version as Completed if it created deployment runs for all of your Stack's deployments, or Failed if it failed out and could not create the necessary deployment runs.

Clicking on an individual configuration version reveals the following:

• How long ago the configuration version was created.
• The latest commit that HCP Terraform based this configuration version on and who made that commit.
• The deployment runs that correspond to this configuration version. Each deployment run lists:
  • The name of the deployment associated with this run.
  • The name of the deployment group associated with this run.
  • The status of the run.

Clicking the ellipsis next to a run reveals options to View deployment run or Approve all plans. Note that you can only approve plans in the Pending state.

Clicking Details reveals any associated commit message with the run, and if there were any updates for components sourced from any registry modules or external repositories.

Clicking on a Stack’s Inputs reveals a list of the inputs this Stack has access to from upstream_input blocks, along with the upstream Stacks that supply those inputs. Clicking on a Stack’s Outputs reveals a list of the outputs of this Stack and any downstream Stacks that intake those outputs. To learn more about passing data from one Stack to another, refer to Pass data from one Stack to another.

Next steps

Learn about deployment runs or how to approve or discard deployment run plans to manage your deployments.