Subchapter 18.3
references/deployment-blocks.mdMarkdown9 KBView on GitHub
Complete reference for all blocks available in Terraform Stack deployment configuration files (.tfdeploy.hcl).
Note: For Publish Output and Upstream Input blocks (linked Stacks), see linked-stacks.md.
Generates JWT tokens for OIDC authentication with cloud providers.
identity_token "<token_name>" {
audience = [<audience_strings>]
}Reference the JWT using: identity_token.<n>.jwt
AWS:
identity_token "aws" {
audience = ["aws.workload.identity"]
}Azure:
identity_token "azure" {
audience = ["api://AzureADTokenExchange"]
}Google Cloud:
identity_token "gcp" {
audience = ["//iam.googleapis.com/projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/<POOL_ID>/providers/<PROVIDER_ID>"]
}Setup Documentation: For detailed instructions on configuring OIDC/workload identity for each cloud provider (including IAM roles, trust policies, and federated credentials), see: https://developer.hashicorp.com/terraform/cloud-docs/dynamic-provider-credentials (opens in a new tab)
Single Token:
identity_token "aws" {
audience = ["aws.workload.identity"]
}
deployment "production" {
inputs = {
identity_token = identity_token.aws.jwt
role_arn = var.role_arn
}
}For complete working examples including multi-region identity token usage, see examples.md.
Defines local values for reuse within deployment configuration.
locals {
<n> = <expression>
}locals {
aws_regions = ["us-west-1", "us-east-1", "eu-west-1"]
role_arn = "arn:aws:iam::123456789012:role/hcp-terraform-stacks"
common_inputs = {
project_name = "my-app"
environment = "production"
}
}Defines deployment instances of the Stack.
deployment "<deployment_name>" {
inputs = {
<input_name> = <value>
}
}for_each, count)To safely remove a deployment from your Stack:
destroy = true in the deployment blockImportant: Using the destroy argument ensures your configuration has the provider authentication necessary to properly destroy the deployment’s resources.
Example:
deployment "old_environment" {
inputs = {
aws_region = "us-west-1"
instance_count = 2
role_arn = local.role_arn
identity_token = identity_token.aws.jwt
}
destroy = true # Mark for destruction
}After applying this plan and the deployment is destroyed, remove the entire deployment "old_environment" block from your configuration.
Single Deployment:
deployment "production" {
inputs = {
aws_region = "us-west-1"
instance_count = 5
instance_type = "t3.large"
role_arn = local.role_arn
identity_token = identity_token.aws.jwt
}
}Using Locals for Multiple Deployments:
locals {
common_inputs = {
role_arn = "arn:aws:iam::123456789012:role/terraform"
identity_token = identity_token.aws.jwt
project_name = "my-app"
}
}
deployment "dev" {
inputs = merge(local.common_inputs, {
aws_region = "us-east-1"
instance_count = 1
environment = "dev"
})
}
deployment "prod" {
inputs = merge(local.common_inputs, {
aws_region = "us-west-1"
instance_count = 5
environment = "prod"
})
}For complete multi-environment and multi-region deployment examples, see examples.md.
Groups deployments together to configure shared settings and auto-approval rules (HCP Terraform Premium tier feature).
deployment_group "<group_name>" {
deployments = [<deployment_references>]
}Deployment groups allow you to:
Single Deployment Group (Best Practice):
deployment "production" {
inputs = {
aws_region = "us-west-1"
instance_count = 5
role_arn = local.role_arn
identity_token = identity_token.aws.jwt
}
}
deployment_group "production" {
deployments = [deployment.production]
}Multiple Deployment Groups:
deployment_group "non_production" {
deployments = [
deployment.development,
deployment.staging
]
}
deployment_group "production" {
deployments = [
deployment.prod_us_east,
deployment.prod_us_west,
deployment.prod_eu_west
]
}Defines rules that automatically approve deployment plans based on specific conditions (HCP Terraform Premium feature).
deployment_auto_approve "<rule_name>" {
deployment_group = deployment_group.<group_name>
check {
condition = <boolean_expression>
reason = "<failure_message>"
}
}Access plan information through context object:
context.plan.applyable - Boolean: plan succeeded without errorscontext.plan.changes.add - Number: resources to addcontext.plan.changes.change - Number: resources to changecontext.plan.changes.remove - Number: resources to removecontext.plan.changes.import - Number: resources to importAuto-approve Successful Plans:
deployment_group "canary" {
deployments = [
deployment.dev,
deployment.staging
]
}
deployment_auto_approve "applyable_plans" {
deployment_group = deployment_group.canary
check {
condition = context.plan.applyable
reason = "Plan must be applyable without errors"
}
}Auto-approve Non-Destructive Changes:
deployment_group "production" {
deployments = [
deployment.prod_primary,
deployment.prod_secondary
]
}
deployment_auto_approve "safe_production_changes" {
deployment_group = deployment_group.production
check {
condition = context.plan.changes.remove == 0
reason = "Production deletions require manual approval"
}
check {
condition = context.plan.applyable
reason = "Plan must be successful"
}
}Graduated Rollout Pattern:
deployment_group "canary" {
deployments = [deployment.canary]
}
deployment_group "production" {
deployments = [
deployment.prod_us,
deployment.prod_eu,
deployment.prod_asia
]
}
# Canary auto-approves with strict checks
deployment_auto_approve "canary_strict" {
deployment_group = deployment_group.canary
check {
condition = context.plan.changes.remove == 0
reason = "Canary cannot delete resources"
}
check {
condition = context.plan.changes.change <= 5
reason = "Canary limited to 5 resource changes"
}
check {
condition = context.plan.applyable
reason = "Plan must be applyable"
}
}
# Production requires manual approval after canary validationFor complete deployment configuration examples with all blocks, see examples.md.