Set conditions for deployment runs

Learn how to configure auto-approve, eager plan, and failure tolerance rules in deployment groups to control how HCP Terraform plans and applies your deployments at scale.

Create deployment groups

You can create deployment groups in your deployment configuration file to define rules that control how your deployments behave. Each deployment group can contain multiple deployments.

If you do not explicitly define a group for a deployment, Terraform automatically creates a default deployment group associated with that deployment. You cannot define custom rules on default deployment groups.

Add the deployment_group block to your deployment configuration to create a new group:

deployment_group "staging_group" {
   # ...
}

Auto-approve

The deployment_auto_approve rule is helpful when you know you want a certain type of plan to go ahead without manual intervention. For example, Stacks have a default auto-approve rule named empty_plan, which automatically approves a plan if it has no changes.

Use the deployment_auto_approve block to define an auto-approval rule that automatically approves a deployment plan if the condition you set is met. In the following example, the no_changes rule automatically approves a deployment plan if it has no changes:

deployment_auto_approve "no_changes" {
  check {
    condition = context.plan.changes.total == 0
    reason    = "Plan contains too many changes for automatic approval."
  }
}

The condition argument in the deployment_auto_approve block has access to the context of the current deployment run. To learn more about context, refer to the deployment_auto_approve reference.

After defining your auto-approval rule, add that rule to your deployment group using the auto_approve_checks argument. In the following example, the staging_group deployment group enforces the no_changes rule:

deployment_auto_approve "no_changes" {
  check {
    condition = context.plan.changes.total == 0
    reason    = "Plan contains too many changes for automatic approval."
  }
}

deployment_group "staging_group" {
  auto_approve_checks = [
    deployment_auto_approve.no_changes
  ]
}

After assigning auto-approve rules to your deployment group, you can add a deployment to that group. In the following example, the staging deployment is added to the staging_group deployment group:

deployment_auto_approve "no_changes" {
  check {
    condition = context.plan.changes.total == 0
    reason    = "Plan contains too many changes for automatic approval."
  }
}

deployment_group "staging_group" {
  auto_approve_checks = [
    deployment_auto_approve.no_changes
  ]
}

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

  deployment_group = deployment_group.staging_group
}

The staging deployment now automatically approves all runs that do not change any resources in that deployment.

You can add multiple auto-approve rules to a deployment group to build more sophisticated conditions. The following example adds another auto-approve rule named successful_plans:

deployment_auto_approve "no_changes" {
  check {
    condition = context.plan.changes.total == 0
    reason    = "Plan contains too many changes for automatic approval."
  }
}

deployment_auto_approve "successful_plans" {
  check {
    condition = context.success == true
    reason    = "Operation failed and requires manual intervention."
  }
}

deployment_group "staging_group" {
  auto_approve_checks = [
    deployment_auto_approve.approve_staging,
    deployment_auto_approve.successful_plans
  ]
}

Now, the staging_group deployment group automatically approves all runs on the staging deployment if they are successful and do not change any resources.

Eager plan

By default, all Stack deployments start planning immediately. With a large number of deployments, this can quickly exhaust your organization's concurrent operation capacity.

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.

The following example sets eager_plan to "off" for the staging deployment:

deployment_group "staging_group" {
  eager_plan = "off"
}

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

  deployment_group = deployment_group.staging_group
}

Failure tolerance

By default, a deployment group places no limit on the number of failed deployments. Use failure_tolerance to set a maximum number of failures the deployment group will tolerate before halting its automated rollout. When the threshold is exceeded, Terraform stops applying further deployments in the group.

failure_tolerance also controls how many deployments run concurrently. Terraform applies up to failure_tolerance + 1 deployments at a time. A tolerance of 0 means deployments run one at a time, a tolerance of 1 allows two to run concurrently, and so on.

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

The following example sets failure_tolerance to 0 for the app_group deployment group. Because the group contains two deployments, they apply sequentially. If the first fails, the rollout halts before the second begins.

deployment_group "app_group" {
  failure_tolerance = 0
}

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

  deployment_group = deployment_group.app_group
}

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

  deployment_group = deployment_group.app_group
}

Next steps

With your Stack and deployment configurations complete, your Stack is ready to be deployed by HCP Terraform. To learn more about creating a Stack in HCP Terraform, refer to Create a Stack.