Create a Stack

Stacks enable you to provision and coordinate your infrastructure lifecycle at scale, offering an organized and reusable approach that expands upon infrastructure as code (IaC).

Hands-on: Try out the Deploy a Stack with HCP Terraform tutorial to get started with Stacks quickly.

Before creating a Stack in HCP Terraform, write a component configuration file to define your Stack's infrastructure, and a deployment configuration file to tell HCP Terraform how to deploy your Stack.

Requirements

Note

Stacks are not available for users on legacy HCP Terraform team plans. Learn more about migrating to current HCP Terraform plans.

To create a Stack in HCP Terraform, you must be a member of a team in your organization with one of the following permissions:

Create a Stack

You can create a Stack using any of the following methods:

The HCP Terraform API
The HCP Terraform UI
The Terraform CLI

If you are creating a Stack in an organization for the first time, you must enable Stacks for your organization. Navigate to your organization’s Settings page, and in the General settings, check the box next to Stacks.

HCP Terraform workflow

Stacks live alongside workspaces in a project. To create a new Stack in HCP Terraform UI, perform the following steps:

Sign in to HCP Terraform, and select the organization where you want to create your Stack.
In the navigation menu, click Projects under Manage.
Select the project where you want to create your Stack.
Click New, then Stack.
Select a version control provider from the list.
Choose an organization and repository from the filterable list. If your repository is missing, enter its ID in the text field below the list. The list only displays the first 100 repositories from your VCS provider.
Enter a new Stack Name.
- The name must be unique within the project and can include letters, numbers, dashes (-), and underscores (_). We recommend using 90 characters or less for the name of your Stack.
You can optionally add a description for your Stack.
By default, HCP Terraform fetches your Stack's configuration after creating your Stack. To fetch your Stack configuration manually, uncheck Fetch configuration after HCP Terraform creates stack.
Click Create Stack.

Terraform CLI workflow

Stacks live alongside workspaces in an HCP Terraform project. To create a new Stack using the Terraform CLI, perform the following steps:

Create an account or sign in to HCP Terraform.
Run terraform login to authenticate with HCP Terraform. Alternatively, you can manually configure credentials in the CLI config file or through environment variables. Refer to CLI Configuration for details.
Run the terraform stacks create command, replacing the placeholders with your organization name, project name, and desired Stack name:
```
$ terraform stacks create -organization-name <ORGANIZATION_NAME> -project-name <PROJECT_NAME> -stack-name <STACK_NAME>
```
A Stack name must be unique within the project and can include letters, numbers, dashes (-), and underscores (_). We recommend using 90 characters or less for the name of your Stack.
After running the command, you can view your new Stack in the HCP Terraform UI, or by running the terraform stacks list command:
```
$ terraform stacks list -organization <ORGANIZATION_NAME> -project <PROJECT_NAME>
```
After creating your Stack, you can push up your Stack component and deployment configuration files to create a new configuration version. Use the terraform stacks configuration upload command to manually upload your configuration files:
```
$ terraform stacks configuration upload -organization <ORGANIZATION_NAME> -project <PROJECT_NAME> -stack-name <STACK_NAME>
```
The Terraform CLI uploads the configuration files, and returns a new configuration version ID and sequence number:
```
Uploading stack configuration...

Configuration for Stack (id: 'st-MLQLSJVrdtGazA4aU') was uploaded
Configuration ID: stc-6fSRO81hOzTPKMM
Sequence Number: 1

See run at: <URL>
```
A Stack configuration version is a snapshot of all of the pieces that make up your Stack. Each configuration version creates a deployment run for every deployment of your Stack in order to implement the changes in that version. To learn more, refer to Stack deployment runs.
After uploading your configuration, you can watch your Stack's configuration roll out using terraform stacks configuration watch to review a list of the deployment groups in your configuration:
```
$ terraform stacks configuration watch -organization <ORGANIZATION_NAME> -project <PROJECT_NAME>
```
The Terraform CLI then displays the status of each deployment group in your Stack:
```
[Stack Id: st-MLQLSJVrdtGazA4aU]
✓ Configuration: 'stc-6fSRO81hOzTPKMM'                    [Completed]    [11s]
↻ Deployment Group: 'many_default'                        [Pending]      [58s]
↻ Deployment Group: 'some_default'                        [Pending]      [58s]
↻ Deployment Group: 'single_default'                      [Failed]       [6s]

Press q to quit
```
You can continue to use the terraform stacks CLI commands to directly approve deployment runs, review configuration versions, and manage your Stack. To learn more, refer to the terraform stacks commands.
Note that though you can create a Stack from the Terraform CLI, you cannot deploy a Stack locally. You can only deploy a Stack remotely in HCP Terraform, or by running your a Stack on a custom HCP Terraform agent. To learn more, refer to Stack deployment runs.

Next steps

After creating your Stack, you can continue to iterate on your configuration and review configuration versions or learn how to review your Stack’s deployment runs.