deployment_group block reference

Use the deployment_group block to define a group that can manage deployments and add orchestration rules for those deployments.

Background

The deployment_group block defines a new group that you can assign individual deployments to join. You can assign a deployment to a group using the deployment_group argument in a deployment block. If you don't assign a deployment to a group, Terraform automatically creates a default deployment group for that deployment.

Deployment groups let you enforce orchestration rules on the deployments within the group. To learn more, refer to Set conditions for deployment runs.

Configuration model

The deployment_group block supports the following arguments:

• deployment_group "<LABEL>"   block
  • auto_approve_checks   list of references
  • eager_plan   string
  • failure_tolerance   number

Complete configuration

All available arguments are defined in the following deployment_group block:

deployment_group "<LABEL>" {
  auto_approve_checks = [
    deployment_auto_approve.<LABEL>,
    deployment_auto_approve.<LABEL_TWO>
  ]
  eager_plan = "off"
  failure_tolerance = 1
}

Specification

A deployment_group block supports the following configuration.

deployment_group "<LABEL>"

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

The deployment_group block supports the following arguments:

auto_approve_checks

The auto_approve_checks argument specifies a list of references to deployment_auto_approve blocks. Terraform evaluates each deployment_auto_approve block to determine whether a deployment's plan automatically applies without manual approval.

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

When you reference multiple deployment_auto_approve blocks, every check must pass for the deployment's plan to automatically apply. If any deployment_auto_approve check fails, then the plan requires manual approval.

Summary

• Data type: List of references
• Default: Empty list (no auto-approval)
• Required: Yes

eager_plan

The eager_plan argument specifies whether deployments in the group should start planning immediately. Set eager_plan to "off" in a deployment group to prevent its deployments from planning until you explicitly start the group from the UI or API. This lets you review a subset of plans first and decide whether to proceed with the rest.

deployment_group "<LABEL>" {
  eager_plan = "off"
}

Summary

• Data type: String
• Default: "on"
• Required: No

failure_tolerance

The failure_tolerance argument specifies the maximum number of failed deployments the group will tolerate before halting its automated rollout. When the threshold is exceeded, Terraform stops applying further deployments in the group.

Omitting the field, or setting it to null, restores the default behavior of unlimited failures.

deployment_group "<LABEL>" {
  failure_tolerance = 1
}

Summary

• Data type: Number
• Default: null (unlimited failures)
• Required: No

Examples

The following examples demonstrate common use cases for deployment_group blocks.

Using deployment groups with deployments

In the following example, the production deployment group contains the production_us and production_eu deployments.

deployment_group "production" {
  auto_approve_checks = [
    deployment_auto_approve.no_destroys
  ]
}

deployment "production_us" {
  inputs = {
    environment = "production"
    region      = "us-east-1"
  }

  deployment_group = deployment_group.production
}

deployment "production_eu" {
  inputs = {
    environment = "production"
    region      = "eu-west-1"
  }

  deployment_group = deployment_group.production
}

If you don't specify a deployment group, Terraform automatically creates a default group for that deployment.

Deployment group with auto-approval

In the following example, the web deployment is in the production deployment group. The production group references the no_destroys rule, which lets plans automatically apply if they do not plan to destroy resources.

deployment_auto_approve "no_destroys" {
  check {
    condition = context.plan.changes.remove == 0
    reason    = "Plan removes ${context.plan.changes.remove} resources."
  }
}

deployment_group "production" {
  auto_approve_checks = [
    deployment_auto_approve.no_destroys
  ]
}

deployment "web" {
  inputs = {
    environment = "production"
    region      = "us-west-2"
  }

  deployment_group = deployment_group.production
}

HCP Terraform now automatically approves any plan on the web deployment that does not destroy resources. If a plan does destroy resources, it requires manual approval.

Multiple auto-approval checks

In the following example, the staging deployment group references two deployment_auto_approve blocks, allow_plans and apply_staging.

deployment_auto_approve "allow_plans" {
  check {
    condition = context.operation == "plan"
    reason    = "Apply operations need manual approval."
  }
}

deployment_auto_approve "apply_staging" {
  check {
    condition = context.plan.deployment == deployment.staging
    reason = "Automatically applying staging deployment."
  }
}

deployment_group "staging" {
  auto_approve_checks = [
    deployment_auto_approve.no_destroys,
    deployment_auto_approve.cost_limit
  ]
}

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

  deployment_group = deployment_group.staging
}

The staging deployment group now automatically approves planning runs that target the staging deployment. If either of these checks fails, then the plan requires manual approval.

Deployment group with a failure tolerance

In the following example, failure_tolerance is set to 1 for the app deployment group. Because the group contains three deployments, two run concurrently at a time. If one fails, the rollout halts before the remaining deployment begins.

deployment_group "app" {
  failure_tolerance = 1
}

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

  deployment_group = deployment_group.app
}

deployment "production_us" {
  inputs = {
    environment = "production"
    region      = "us-east-1"
  }

  deployment_group = deployment_group.app
}

deployment "production_eu" {
  inputs = {
    environment = "production"
    region      = "eu-west-1"
  }

  deployment_group = deployment_group.app
}