deployment block reference

Use the deployment block to define how many times you want to deploy your Stack's infrastructure. You can define deployment blocks in a <NAME>.tfdeploy.hcl file, which is the deployment configuration file for your Stack.

Background

The deployment block defines how to deploy your Stack's infrastructure. Each deployment represents a separate instance of your Stack infrastructure. Each deployment maintains its own isolated state data, wholly separated from other Stack deployments.

Each Stack requires at least one deployment block, and you can add additional deployment blocks every time you want to deploy your Stack's infrastructure again with different input values. To learn more, refer to Define deployment configuration.

In addition to the deployment block, you can define the following configuration blocks in a tfdeploy.hcl file:

• Use the deployment_auto_approve block to define rules that automatically approve deployment plans based on specific conditions.
• Use the deployment_group block to assign deployment_auto_approve rules to specific deployments.
• Use the identity_token block to authenticate a deployment with a provider configuration using OIDC.
• Use the store block to define key-value secrets in your deployment configuration and use existing variable sets in HCP Terraform.
• Use the locals block to define local values that you can reuse within your deployment configuration.
• Use the publish_output block to output values that you want to be available to other Stacks.
• Use the upstream_input block to source inputs from another Stack.

Configuration model

The deployment block supports the following arguments:

• deployment "<LABEL>"   block
  • inputs   map
  • deployment_group   reference to deployment group
  • destroy   boolean
  • import   boolean

Complete configuration

All available arguments are defined in the following deployment block:

deployment "<LABEL>" {
  inputs = {
    <VARIABLE_NAME> = <VALUE>
  }
  deployment_group = "deployment_group.<NAME>"
  destroy = <BOOLEAN>
}

Specification

A deployment block supports the following configuration.

deployment "<LABEL>"

The label after the deployment keyword is a name for the deployment, which must be unique among all deployments in the same deployment configuration file. The name of a deployment can be any valid identifier.

You cannot rename a deployment after HCP Terraform creates it. Changing a deployment label creates a new deployment with the new label and destroys the previous deployment.

The deployment block supports the following arguments:

inputs

The inputs argument defines a mapping of Stack variable names to values for this specific deployment.

deployment "<LABEL>" {
  inputs = {
    <VARIABLE_NAME> = <VALUE>
    <VARIABLE_NAME_TWO> = <VALUE_TWO>
  }
}

The keys in the inputs map must correspond to the names of the variables defined in your component configuration, and the values must be valid HCL expressions that meet the type constraints of those variables. Input value expressions can reference locals, identity_token, store, and upstream_value blocks.

Summary

• Data type: Object
• Default: None
• Required: Yes

deployment_group

The deployment_group argument lets you specify the deployment group to group this deployment in.

deployment_group "<LABEL>" {
  auto_approve_checks = [deployment_auto_approve.<LABEL>]
}



deployment "<LABEL>" {
  inputs = {
    <VARIABLE_NAME> = <VALUE>
    <VARIABLE_NAME_TWO> = <VALUE_TWO>
  }
  deployment_group = "deployment_group.<LABEL>"
}

You can use deployment groups to enable orchestration rules which can manage your deployment's lifecycle. For more details on deployment groups, refer to the Set conditions for deployment runs.

If a deployment does not specify a deployment group, Terraform automatically generates an independent deployment group for it named <DEPLOYMENT_NAME>_default.

Summary

• Data type: Reference
• Default: By default, Terraform automatically generates a deployment group for deployments that do not specify a group.
• Required: Yes

destroy

The destroy argument lets you declare in configuration that HCP Terraform can destroy this deployment.

deployment "<LABEL>" {
  inputs = {
    <VARIABLE_NAME> = <VALUE>
    <VARIABLE_NAME_TWO> = <VALUE_TWO>
  }
  destroy = true
}

Setting destroy = true tells HCP Terraform to remove this deployment from your Stack. After applying the plan, you can remove the deployment block corresponding to the destroyed deployment from your configuration.

We recommend using the destroy argument to remove deployments to ensure your configuration has the provider authentication necessary to destroy the deployment.

Summary

• Data type: Boolean
• Default: false

import

The import argument is a placeholder for future functionality.

deployment "<LABEL>" {
  inputs = {
    <VARIABLE_NAME> = <VALUE>
    <VARIABLE_NAME_TWO> = <VALUE_TWO>
  }
  import = <boolean>
}

Summary

• Data type: Boolean
• Default: false

Examples

The following examples demonstrate common use cases for deployment blocks.

Fundamental deployment

In the following example, the production deployment configures variable values for aws_region, instance_count, and environment:

deployment "production" {
  inputs = {
    aws_region     = "us-west-1"
    instance_count = 2
    environment    = "production"
  }
}

The matching component configuration for this deployment, in a tfcomponent.hcl file, must include the same variable names and types as those defined in the inputs map.

The production deployment does not specify a deployment_group, so Terraform automatically generates a deployment group for it. The generated deployment group for the production deployment is named production_default.

Set deployment group

In the following example, the web deployment is part of the production deployment group:

deployment "web" {
  inputs = {
    aws_region     = "us-west-1"
    instance_count = 2
    environment    = "production"
  }

  deployment_group = "deployment_group.production"
}

You can use deployment groups to enable orchestration rules which can manage your deployment's lifecycle. For more details on deployment groups, refer to the Set conditions for deployment runs.

Multiple deployments

In the following example, Terraform configures two deployments named staging and production:

deployment "staging" {
  inputs = {
    aws_region     = "us-east-1"
    instance_count = 1
    environment    = "staging"
  }
}

deployment "production" {
  inputs = {
    aws_region     = "us-west-1"
    instance_count = 3
    environment    = "production"
  }
}

When you run this configuration, HCP Terraform creates two separate deployments that each use the same component configuration. The staging deployment uses the us-east-1 region and has one instance, while the production deployment uses the us-west-1 region and has three instances.

Reference variable sets

In the following example, the production deployment retrieves database_password and api_key from a variable set in HCP Terraform, with the ID varset-SEtkL6Bq91XujTsR:

store "varset" "secrets" {
  id       = "varset-SEtkL6Bq91XujTsR"
  category = "terraform"
}

deployment "production" {
  inputs = {
    database_password = store.varset.secrets.db_password
    api_key          = store.varset.secrets.api_key
    instance_count   = 5
  }
}

To learn more about referencing variable sets from HCP Terraform in your Stack deployments, refer to the store block.

Authenticate with identity tokens

In the following example, the production deployment uses the JWT from identity_token.aws.jwt for OIDC authentication with the aws provider:

identity_token "aws" {
  audience = ["aws.workload.identity"]
}

deployment "production" {
  inputs = {
    aws_region = "us-west-2"
    role_arn   = "arn:aws:iam::123456789012:role/my-oidc-role"
    aws_token  = identity_token.aws.jwt
  }
}

Stacks have a built-in identity_token block that creates workload identity tokens, also known as JWT tokens. You can use these tokens to authenticate Stacks with Terraform providers securely. To learn more, refer to Authenticate a Stack.

Pass values between Stacks

In the following example, the application deployment exposes a vpc_id output and retrieves the private_subnet_ids from an upstream Stack named networking:

publish_output "vpc_id" {
  description = "The networking Stack's VPC's ID."
  value       = application.network.vpc_id
}

upstream_input "network_stack" {
  type   = "stack"
  source = "app.terraform.io/<ORGANIZATION_NAME>/<PROJECT_NAME>/networking"
}

deployment "application" {
  inputs = {
    subnet_ids       = upstream_input.network_stack.private_subnet_ids
    instance_count   = 3
  }
}

After applying your configuration, any Stack in the same project can now reference your application deployment's vpc_id output by declaring an upstream_input block. To learn more about linking Stacks together, refer to Pass data from one Stack to another.

Destroy a deployment

To destroy a deployment, set the destroy argument to true on a deployment block. In the following example, the web deployment is marked for destruction:

deployment "web" {
  inputs = {
    aws_region     = "us-west-1"
    instance_count = 2
    environment    = "production"
  }

  destroy = true
}

When you run a plan for this deployment, HCP Terraform destroys the web deployment. After applying the plan, you can remove the web deployment block from your configuration.