Menu
AWS CodeDeploy
User Guide (API Version 2014-10-06)

AWS CodeDeploy Instance Health

AWS CodeDeploy monitors the health status of the instances in a deployment group. It fails deployments if the number of healthy instances falls below the minimum number of healthy instances that have been specified for the deployment group during a deployment. For example, if 85% of instances must remain healthy during a deployment, and the deployment group contains 10 instances, the overall deployment will fail if deployment to even a single instance fails. This is because when an instance is taken offline so the latest application revision can be installed, the available healthy instance counts already drops to 90%. A failed instance plus another offline instance would mean that only 80% of instances are healthy and available. AWS CodeDeploy will fail the overall deployment.

The required minimum number of healthy instances is defined as part of a deployment configuration.

Important

During a blue/green deployment, the deployment configuration and minimum healthy hosts value apply to instances in the replacement environment, not those in the original environment. However, when instances in the original environment are deregistered from the load balancer, the overall deployment is marked as Failed if even a single original instance fails to be deregistered successfully.

AWS CodeDeploy provides three default deployment configurations that have commonly used minimum healthy host values:

Default deployment configuration name Predefined minimum healthy hosts value
CodeDeployDefault.OneAtATime 99%
CodeDeployDefault.HalfAtATime 50%
CodeDeployDefault.AllAtOnce 0

You'll find more information about default deployment configurations in Working with Deployment Configurations in AWS CodeDeploy.

You can create custom deployment configurations in AWS CodeDeploy to define your own minimum healthy host values. You can define these values as whole numbers or percentages when using the following operations:

Health Status

AWS CodeDeploy assigns two health status values to each instance: revision health and instance health.

Revision health

Revision health is based on the application revision currently installed on the instance. It has the following status values:

  • Current: The revision installed on the instance matches the revision for the deployment group's last successful deployment.

  • Old: The revision installed on the instance matches an older version of the application.

  • Unknown: The application revision has not been installed successfully on the instance.

Instance health

Instance health is based on whether deployments to an instance have been successful. It has the following values:

  • Healthy: The last deployment to the instance was successful.

  • Unhealthy: The attempt to deploy a revision to the instance failed, or a revision has not yet been deployed to the instance.

AWS CodeDeploy uses revision health and instance health to schedule the deployment to the deployment group's instances in the following order:

  1. Unhealthy instance health.

  2. Unknown revision health.

  3. Old revision health.

  4. Current revision health.

If the overall deployment succeeds, the revision is updated and the deployment group's health status values are updated to reflect the latest deployment.

  • All current instances that had a successful deployment remain current. Otherwise, they become unknown.

  • All old or unknown instances that had a successful deployment become current. Otherwise, they remain old or unknown.

  • All healthy instances that had a successful deployment remain healthy. Otherwise, they become unhealthy.

  • All unhealthy instances that had a successful deployment become healthy. Otherwise, they remain unhealthy.

If the overall deployment fails or is stopped:

  • Each instance to which AWS CodeDeploy attempted to deploy the application revision has its instance health set to healthy or unhealthy, depending on whether the deployment attempt for that instance succeeded or failed.

  • Each instance to which AWS CodeDeploy did not attempt to deploy the application revision retains its current instance health value.

  • The deployment group's revision remains the same.

Minimum Healthy Instances and Deployments

AWS CodeDeploy allow you to specify a minimum number of healthy instances for the deployment for two main purposes:

  • To determine whether the overall deployment succeeds or fails. Deployment succeeds if the application revision was successfully deployed to at least the minimum number of healthy instances.

  • To determine the number of instances that must be healthy during a deployment to allow the deployment to proceed.

You can specify the minimum number of healthy instances for your deployment group as a number of instances or as a percentage of the total number of instances. If you specify a percentage, then at the start of the deployment, AWS CodeDeploy converts the percentage to the equivalent number of instances, rounding up any fractional instances.

AWS CodeDeploy tracks the health status of the deployment group's instances during the deployment process and uses the deployment's specified minimum number of healthy instances to determine whether to continue the deployment. The basic principle is that a deployment must never cause the number of healthy instances to fall below the minimum number you have specified. The one exception to this rule is when a deployment group initially has less than the specified minimum number of healthy instances. In that case, the deployment process does not reduce the number of healthy instances any further.

Note

AWS CodeDeploy will attempt to deploy to all instances in a deployment group, even those that are currently in a Stopped state. In the minimum healthy host calculation, a stopped instance has the same impact as a failed instance. To resolve deployment failures due to too many stopped instances, either restart instances or change their tags to exclude them from the deployment group.

AWS CodeDeploy starts the deployment process by attempting to deploy the application revision to the deployment group's unhealthy instances. For each successful deployment, AWS CodeDeploy changes the instance's health status to healthy and adds it to the deployment group's healthy instances. AWS CodeDeploy then compares the current number of healthy instances to the specified minimum number of healthy instances.

  • If the number of healthy instances is less than or equal to the specified minimum number of healthy instances, AWS CodeDeploy cancels the deployment to ensure the number of healthy instances doesn't decrease with more deployments.

  • If the number of healthy instances is greater than the specified minimum number of healthy instances by at least one, AWS CodeDeploy deploys the application revision to the original set of healthy instances.

If a deployment to a healthy instance fails, AWS CodeDeploy changes that instance's health status to unhealthy. As the deployment progresses, AWS CodeDeploy updates the current number of healthy instances and compares it to the specified minimum number of healthy instances. If the number of healthy instances falls to the specified minimum number at any point in the deployment process, AWS CodeDeploy stops the deployment. This practice prevents the possibility the next deployment will fail, dropping the number of healthy instances below the specified minimum number.

Note

Make sure the minimum number of healthy instances you specify is less than the total number of instances in the deployment group. If you specify a percentage value, remember it will be rounded up. Otherwise, when the deployment starts, the number of healthy instances will already be less than or equal to the specified minimum number of healthy instances, and AWS CodeDeploy will immediately fail the overall deployment.

AWS CodeDeploy also uses the specified minimum number of healthy instances and the actual number of healthy instances to determine whether and how to deploy the application revision to multiple instances. By default, AWS CodeDeploy deploys the application revision to as many instances as it can without any risk of having the number of healthy instances fall below the specified minimum number of healthy instances. For example:

  • If your deployment group has 10 instances and you set the minimum healthy instances number to 9, AWS CodeDeploy deploys to one instance at a time.

  • If your deployment group has 10 instances and you set the minimum healthy instances number to 0, AWS CodeDeploy deploys to every instance at the same time.

Examples

The following examples assume a deployment group with 10 instances.

Minimum healthy instances: 95%

AWS CodeDeploy rounds the minimum healthy instances number up to 10 instances, which equals the number of healthy instances. The overall deployment immediately fails without deploying the revision to any instances.

Minimum healthy instances: 9

AWS CodeDeploy deploys the revision to one instance at a time. If any of these deployments fail, AWS CodeDeploy immediately fails the overall deployment. The exception to this rule is that if the last instance fails, the deployment still succeeds.

Minimum healthy instances: 8

AWS CodeDeploy deploys the revision to two instances at a time. If two of these deployments fail, AWS CodeDeploy immediately fails the overall deployment. The exception to this rule is that if the last instance is the second to fail, the deployment still succeeds.

Minimum healthy instances: 0

AWS CodeDeploy deploys the revision to the entire deployment group at once. The deployment group can't have fewer than 0 healthy instances, so the overall deployment cannot fail.

Minimum healthy instances: 9

AWS CodeDeploy first deploys the revision to the unhealthy instance.

  • If any deployment fails, the number of healthy instances equals the minimum healthy instances number, so the overall deployment immediately fails. The exception to this rule is that if the last instance fails, the deployment still succeeds.

  • If any deployment succeeds, the deployment group now has 10 healthy instances. AWS CodeDeploy continues the deployment, one instance at a time, until any deployment fails or the overall deployment is complete. The exception to this rule is that if the last instance fails, the deployment still succeeds.