Resource update policies AppStream 2.0 update policy AutoScalingReplacing update policy AutoScalingRollingUpdate policy AutoScalingScheduledAction policy UseOnlineResharding policy EnableVersionUpgrade policy CodeDeployLambdaAlias Update policy Examples

`UpdatePolicy` attribute

Use the UpdatePolicy attribute to specify how AWS CloudFormation handles updates to the following resources:

Resource update policies

For AWS::AppStream::Fleet resource, CloudFormation can update your Image Builder with newer AppStream 2.0 agent software. For more information see, Manage AppStream 2.0 Versions.
For AWS::AutoScaling::AutoScalingGroup resources, CloudFormation invokes one of three update policies depending on the type of change you make or whether a scheduled operation is associated with the Auto Scaling group.
- The AutoScalingReplacingUpdate and AutoScalingRollingUpdate policies apply only when you complete one or more of the following:
  - Change the Auto Scaling group's AWS::AutoScaling::LaunchConfiguration.
  - Change the Auto Scaling group's VPCZoneIdentifier property.
  - Change the Auto Scaling group's LaunchTemplate property.
  - Update an Auto Scaling group that contains instances that don't match the current LaunchConfiguration.
  If both the AutoScalingReplacingUpdate and AutoScalingRollingUpdate policies are specified, setting the WillReplace property to true gives AutoScalingReplacingUpdate precedence.
- The AutoScalingScheduledAction policy applies when you update a stack that includes an Auto Scaling group with an associated scheduled action.
For AWS::ElastiCache::ReplicationGroup resources, CloudFormation can modify a replication group's shards by adding or removing shards, rather than replacing the entire resource. For more information, see UseOnlineResharding policy.
For AWS::OpenSearchService::Domain and legacy AWS::Elasticsearch::Domain resources, CloudFormation can upgrade an OpenSearch Service domain to a new version of OpenSearch or Elasticsearch without replacing the entire resource. For more information, see EnableVersionUpgrade policy.
For AWS::Lambda::Alias resources, CloudFormation performs an CodeDeploy deployment when the version changes on the alias. For more information, see CodeDeployLambdaAlias Update policy.

AppStream 2.0 update policy

AppStream 2.0 configuration for an update policy.

Syntax

JSON


{
    "UpdatePolicy": {
        "StopBeforeUpdate": {
            "Type": "Boolean"
        },
        "StartAfterUpdate": {
            "Type": "Boolean"
        }
    }
}

YAML


UpdatePolicy:
  StopBeforeUpdate:
    Type: Boolean
  StartAfterUpdate:
    Type: Boolean

StopBeforeUpdate

Stops the specified fleet before the update.

Required: No

StartAfterUpdate

Starts the specified fleet after the update.

Required: No

AutoScalingReplacing update policy

To specify how AWS CloudFormation handles replacement updates for an Auto Scaling group, use the AutoScalingReplacingUpdate policy. This policy enables you to specify whether AWS CloudFormation replaces an Auto Scaling group with a new one or replaces only the instances in the Auto Scaling group.

Important

Before attempting an update, ensure that you have sufficient Amazon EC2 capacity for both your old and new Auto Scaling groups.

Syntax

JSON


"UpdatePolicy" : {
  "AutoScalingReplacingUpdate" : {
    "WillReplace" : Boolean
  }
}

YAML


UpdatePolicy:
  AutoScalingReplacingUpdate:
    WillReplace: Boolean

Properties

WillReplace

Specifies whether an Auto Scaling group and the instances it contains are replaced during an update. During replacement, CloudFormation retains the old group until it finishes creating the new one. If the update fails, CloudFormation can roll back to the old Auto Scaling group and delete the new Auto Scaling group.

While CloudFormation creates the new group, it doesn't detach or attach any instances. After successfully creating the new Auto Scaling group, CloudFormation deletes the old Auto Scaling group during the cleanup process.

When you set the WillReplace parameter, remember to specify a matching CreationPolicy. If the minimum number of instances (specified by the MinSuccessfulInstancesPercent property) don't signal success within the Timeout period (specified in the CreationPolicy policy), the replacement update fails and AWS CloudFormation rolls back to the old Auto Scaling group.

Type: Boolean

Required: No

AutoScalingRollingUpdate policy

To specify how CloudFormation handles rolling updates for an Auto Scaling group, use the AutoScalingRollingUpdate policy. Rolling updates enable you to specify whether AWS CloudFormation updates instances that are in an Auto Scaling group in batches or all at once.

Important

During a rolling update, some Auto Scaling processes might make changes to the Auto Scaling group before CloudFormation completes the rolling update. These changes might cause the rolling update to fail. To prevent Auto Scaling from running processes during a rolling update, use the SuspendProcesses property. For more information, see What are some recommended best practices for performing Auto Scaling group rolling updates?

Be aware that, during stack update rollback operations, CloudFormation uses the UpdatePolicy configuration specified in the template before the current stack update operation. For example, suppose you have updated the MaxBatchSize in your stack template's UpdatePolicy from 1 to 10. You then perform a stack update, and that update fails and CloudFormation initiates an update rollback operation. In such a case, CloudFormation will use 1 as the maximum batch size, rather than 10. For this reason, we recommend you make changes to the UpdatePolicy configuration in a stack update separate from and before any updates to the AWS::AutoScaling::AutoScalingGroup resource that are likely to initiate rolling updates.

Syntax

JSON


"UpdatePolicy" : {
  "AutoScalingRollingUpdate" : {
    "MaxBatchSize" : Integer,
    "MinInstancesInService" : Integer,
    "MinSuccessfulInstancesPercent" : Integer,
    "PauseTime" : String,
    "SuspendProcesses" : [ List of processes ],
    "WaitOnResourceSignals" : Boolean
  }
}

YAML


UpdatePolicy:
  AutoScalingRollingUpdate:
    MaxBatchSize: Integer
    MinInstancesInService: Integer
    MinSuccessfulInstancesPercent: Integer
    PauseTime: String
    SuspendProcesses:
      - List of processes
    WaitOnResourceSignals: Boolean

Properties

MaxBatchSize

Specifies the maximum number of instances that CloudFormation updates.

Default: 1

Maximum: 100

Type: Integer

Required: No

MinInstancesInService

Specifies the minimum number of instances that must be in service within the Auto Scaling group while CloudFormation updates old instances. This value must be less than the MaxSize of the Auto Scaling group.

Default: 0

Type: Integer

Required: No

MinSuccessfulInstancesPercent

Specifies the percentage of instances in an Auto Scaling rolling update that must signal success for an update to succeed. You can specify a value from 0 to 100. CloudFormation rounds to the nearest tenth of a percent. For example, if you update five instances with a minimum successful percentage of 50, three instances must signal success.

If an instance doesn't send a signal within the time specified in the PauseTime property, CloudFormation assumes that the instance wasn't updated.

If you specify this property, you must also enable the WaitOnResourceSignals and PauseTime properties.

The MinSuccessfulInstancesPercent parameter applies only to instances only for signaling purpose. To specify the number of instances in your autoscaling group, see the MinSize, MaxSize, and DesiredCapacity properties for the AWS::AutoScaling::AutoScalingGroup resource.

Default: 100

Type: Integer

Required: No

Important

When the MinSuccessfulInstancesPercent property is set to 0, CloudFormation waits for 0% of the capacity instances to be in an InService state. MinSuccessfulInstancesPercent returns immediately and before considering the Auto Scaling group status as Update Complete to move on to the subsequent resources defined in the stack template.

If other Auto Scaling groups are defined in your CloudFormation template, they will update simultaneously. When all Auto Scaling groups are deployed at once with 0% of the capacity instances in an InService state, then you will experience availability issues, due to 0 instances serving customer traffic.

CloudFormation recommends that MinSuccessfulInstancesPercent is set to a value greater than 0, allowing reasonable minimum instances to verify before considering an Auto Scaling groups update to be completed.

PauseTime

The amount of time that CloudFormation pauses after making a change to a batch of instances to give those instances time to start software applications. For example, you might need to specify PauseTime when scaling up the number of instances in an Auto Scaling group.

If you enable the WaitOnResourceSignals property, PauseTime is the amount of time that CloudFormation should wait for the Auto Scaling group to receive the required number of valid signals from added or replaced instances. If the PauseTime is exceeded before the Auto Scaling group receives the required number of signals, the update fails. For best results, specify a time period that gives your applications sufficient time to get started. If the update needs to be rolled back, a short PauseTime can cause the rollback to fail.

Specify PauseTime in the ISO8601 duration format (in the format PT#H#M#S, where each # is the number of hours, minutes, and seconds, respectively). The maximum PauseTime is one hour (PT1H).

Default: PT0S (0 seconds). If the WaitOnResourceSignals property is set to true, the default is PT5M.

Type: String

Required: No

SuspendProcesses

Specifies the Auto Scaling processes to suspend during a stack update. Suspending processes prevents Auto Scaling from interfering with a stack update. For example, you can suspend alarming so that Amazon EC2 Auto Scaling doesn't initiate scaling policies associated with an alarm. For valid values, see the ScalingProcesses.member.N parameter for the SuspendProcesses action in the Amazon EC2 Auto Scaling API Reference.

Default: Not specified

Type: List of Auto Scaling processes

Required: No

WaitOnResourceSignals

Specifies whether the Auto Scaling group waits on signals from new instances during an update. Use this property to ensure that instances have completed installing and configuring applications before the Auto Scaling group update proceeds. AWS CloudFormation suspends the update of an Auto Scaling group after new EC2 instances are launched into the group. AWS CloudFormation must receive a signal from each new instance within the specified PauseTime before continuing the update. To signal the Auto Scaling group, use the cfn-signal helper script or SignalResource API.

To have instances wait for an Elastic Load Balancing health check before they signal success, add a health-check verification by using the cfn-init helper script. For an example, see the verify_instance_health command in the Auto Scaling rolling updates sample template.

Default: false

Type: Boolean

Required: Conditional. If you specify the MinSuccessfulInstancesPercent property, you must also enable the WaitOnResourceSignals and PauseTime properties.

AutoScalingScheduledAction policy

To specify how AWS CloudFormation handles updates for the MinSize, MaxSize, and DesiredCapacity properties when the AWS::AutoScaling::AutoScalingGroup resource has an associated scheduled action, use the AutoScalingScheduledAction policy.

With scheduled actions, the group size properties of an Auto Scaling group can change at any time. When you update a stack with an Auto Scaling group and scheduled action, CloudFormation always sets the group size property values of your Auto Scaling group to the values that are defined in the AWS::AutoScaling::AutoScalingGroup resource of your template, even if a scheduled action is in effect.

If you don't want CloudFormation to change any of the group size property values when you have a scheduled action in effect, use the AutoScalingScheduledAction update policy and set IgnoreUnmodifiedGroupSizeProperties to true to prevent CloudFormation from changing the MinSize, MaxSize, or DesiredCapacity properties unless you have modified these values in your template.

Syntax

JSON


"UpdatePolicy" : {
  "AutoScalingScheduledAction" : {
    "IgnoreUnmodifiedGroupSizeProperties" : Boolean
  }
}

YAML


UpdatePolicy:
  AutoScalingScheduledAction:
    IgnoreUnmodifiedGroupSizeProperties: Boolean

Properties

IgnoreUnmodifiedGroupSizeProperties

If true, AWS CloudFormation ignores differences in group size properties between your current Auto Scaling group and the Auto Scaling group described in the AWS::AutoScaling::AutoScalingGroup resource of your template during a stack update. If you modify any of the group size property values in your template, AWS CloudFormation uses the modified values and updates your Auto Scaling group.

Default: false

Type: Boolean

Required: No

UseOnlineResharding policy

To modify a replication group's shards by adding or removing shards, rather than replacing the entire AWS::ElastiCache::ReplicationGroup resource, use the UseOnlineResharding update policy.

If UseOnlineResharding is set to true, you can update the NumNodeGroups and NodeGroupConfiguration properties of the AWS::ElastiCache::ReplicationGroup resource, and CloudFormation will update those properties without interruption. When UseOnlineResharding is set to false, or not specified, updating the NumNodeGroups and NodeGroupConfiguration properties results in CloudFormation replacing the entire AWS::ElastiCache::ReplicationGroup resource.

The UseOnlineResharding update policy has no properties.

Things to consider when setting the UseOnlineResharding update policy to true:

We strongly recommend you perform updates to the NumNodeGroups and NodeGroupConfiguration properties as the only updates in a given stack update operation.

Updating the node group configuration of a replication group is a resource-intensive operation. If a stack update fails, CloudFormation doesn't roll back changes to the node group configuration of a replication group. However, CloudFormation will roll back any other properties that were changed as part of the failed update operation.
Any node group updates require identifying all node groups.

If you specify the NodeGroupConfiguration property, you must also specify the NodeGroupId for each node group configuration in order for CloudFormation to update the number of nodes without interruption.

When creating a replication group, if you don't specify an ID for each node group, ElastiCache automatically generates an ID for each node group. To update the replication group without interruption, use the ElastiCache console (https://console.aws.amazon.com/elasticache/) or DescribeReplicationGroups to retrieve the IDs for all node groups in the replication group. Then specify the ID for each node group in your stack template before attempting to add or remove shards.

Note
As a best practice, when you create a replication group in a stack template, include an ID for each node group you specify.

In addition, updating the number of nodes without interruption requires that you have accurately specified the PrimaryAvailabilityZone, ReplicaAvailabilityZones, and ReplicaCount properties for each NodeGroupConfiguration as well. Again, you can use the ElastiCache console (https://console.aws.amazon.com/elasticache/) or DescribeReplicationGroups to retrieve the actual values for each node group and compare them to the values in your stack template. You can update the property values of the node groups as a separate stack update, or as part of the same stack update that changes the number of node groups.

When you use an UseOnlineResharding update policy to update the number of node groups without interruption, ElastiCache evenly distributes the keyspaces between the specified number of slots. This can't be updated later. Therefore, after updating the number of node groups in this way, you should remove the value specified for the Slots property of each NodeGroupConfiguration from the stack template, as it no longer reflects the actual values in each node group.
Actual node group removal results may vary.

When you specify a NumNodeGroups value that's less than the current number of node groups, CloudFormation instructs ElastiCache to remove as many node groups as necessary to reach the specified number of nodes. However, ElastiCache may not always be able to remove the desired number of node groups. In the event ElastiCache can't remove the desired number of node groups, CloudFormation generates a stack event alerting you to this. In cases where ElastiCache can't remove any node groups, the CloudFormation resource update fails.

For more information on modifying replication groups, see ModifyReplicationGroupShardConfiguration in the Amazon ElastiCache API Reference.

Syntax

JSON


"UpdatePolicy" : {
  "UseOnlineResharding" : Boolean
}

YAML


UpdatePolicy:
  UseOnlineResharding: Boolean

EnableVersionUpgrade policy

To upgrade an OpenSearch Service domain to a new version of OpenSearch or Elasticsearch rather than replacing the entire AWS::OpenSearchService::Domain or AWS::Elasticsearch::Domain resource, use the EnableVersionUpgrade update policy.

If EnableVersionUpgrade is set to true, you can update the EngineVersion property of the AWS::OpenSearchService::Domain resource (or the ElasticsearchVersion property of the legacy AWS::Elasticsearch::Domain resource), and CloudFormation will update that property without interruption. When EnableVersionUpgrade is set to false, or not specified, updating the EngineVersion or ElasticsearchVersion property results in CloudFormation replacing the entire AWS::OpenSearchService::Domain/AWS::Elasticsearch::Domain resource.

The EnableVersionUpgrade update policy has no properties.

For more information about upgrading OpenSearch Service domains, see UpgradeDomain in the Amazon OpenSearch Service Developer Guide.

Syntax

JSON


"UpdatePolicy" : {
  "EnableVersionUpgrade" : Boolean
}

YAML


UpdatePolicy:
  EnableVersionUpgrade: Boolean

CodeDeployLambdaAlias Update policy

To perform an CodeDeploy deployment when the version changes on an AWS::Lambda::Alias resource, use the CodeDeployLambdaAliasUpdate update policy.

Syntax

JSON


"UpdatePolicy" : {
  "CodeDeployLambdaAliasUpdate" : {
    "AfterAllowTrafficHook" : String,
    "ApplicationName" : String,
    "BeforeAllowTrafficHook" : String,
    "DeploymentGroupName" : String
  }
}

YAML


UpdatePolicy:
  CodeDeployLambdaAliasUpdate:
    AfterAllowTrafficHook: String
    ApplicationName: String
    BeforeAllowTrafficHook: String
    DeploymentGroupName: String

Properties

AfterAllowTrafficHook

The name of the Lambda function to run after traffic routing completes.

Required: No

Type: String

ApplicationName

The name of the CodeDeploy application.

Required: Yes

Type: String

BeforeAllowTrafficHook

The name of the Lambda function to run before traffic routing starts.

Required: No

Type: String

DeploymentGroupName

The name of the CodeDeploy deployment group. This is where the traffic-shifting policy is set.

Required: Yes

Type: String

For an example that specifies the UpdatePolicy attribute for an AWS::Lambda::Alias resource, see Lambda alias update policy.

Examples

The following examples show how to add an update policy to an Auto Scaling group and how to maintain availability when updating metadata.

Add an `UpdatePolicy` to an Auto Scaling group

The following example shows how to add an update policy. During an update, the Auto Scaling group updates instances in batches of two and keeps a minimum of one instance in service. Because the WaitOnResourceSignals flag is set, the Auto Scaling group waits for new instances that are added to the group. The new instances must signal the Auto Scaling group before it updates the next batch of instances.

JSON


"ASG" : {
   "Type" : "AWS::AutoScaling::AutoScalingGroup",
   "Properties" : {
      "AvailabilityZones" : [
         "us-east-1a",
         "us-east-1b"
      ],
      "DesiredCapacity" : "1",
      "LaunchConfigurationName" : {
         "Ref" : "LaunchConfig"
      },
      "MaxSize" : "4",
      "MinSize" : "1"
   },
   "UpdatePolicy" : {
      "AutoScalingScheduledAction" : {
         "IgnoreUnmodifiedGroupSizeProperties" : "true"
      },
      "AutoScalingRollingUpdate" : {
         "MinInstancesInService" : "1",
         "MaxBatchSize" : "2",
         "WaitOnResourceSignals" : "true",
         "PauseTime" : "PT10M"
      }
   }
 },
"ScheduledAction" : {
   "Type" : "AWS::AutoScaling::ScheduledAction",
   "Properties" : {
      "AutoScalingGroupName" : {
         "Ref" : "ASG"
      },
      "DesiredCapacity" : "2",
      "StartTime" : "2017-06-02T20 : 00 : 00Z"
   }
}

YAML


ASG:
  Type: 'AWS::AutoScaling::AutoScalingGroup'
  Properties:
    AvailabilityZones:
    - us-east-1a
    - us-east-1b
    DesiredCapacity: '1'
    LaunchConfigurationName:
      Ref: LaunchConfig
    MaxSize: '4'
    MinSize: '1'
  UpdatePolicy:
    AutoScalingScheduledAction:
      IgnoreUnmodifiedGroupSizeProperties: 'true'
    AutoScalingRollingUpdate:
      MinInstancesInService: '1'
      MaxBatchSize: '2'
      WaitOnResourceSignals: 'true'
      PauseTime: PT10M
ScheduledAction:
  Type: 'AWS::AutoScaling::ScheduledAction'
  Properties:
    AutoScalingGroupName:
      Ref: ASG
    DesiredCapacity: '2'
    StartTime: '2017-06-02T20 : 00 : 00Z'

AutoScalingReplacingUpdate policy

The following example declares a policy that forces an associated Auto Scaling group to be replaced during an update. For the update to succeed, a percentage of instances (specified by the MinSuccessfulPercentParameter parameter) must signal success within the Timeout period.

JSON


"UpdatePolicy" : {
  "AutoScalingReplacingUpdate" : {
    "WillReplace" : "true"
  }
},
"CreationPolicy" : {
  "ResourceSignal" : {
    "Count" : { "Ref" : "ResourceSignalsOnCreate"},
    "Timeout" : "PT10M"
  },
  "AutoScalingCreationPolicy" : {
    "MinSuccessfulInstancesPercent" : { "Ref" : "MinSuccessfulPercentParameter" }
  }
}

YAML


UpdatePolicy:
  AutoScalingReplacingUpdate:
    WillReplace: 'true'
CreationPolicy:
  ResourceSignal:
    Count: !Ref 'ResourceSignalsOnCreate'
    Timeout: PT10M
  AutoScalingCreationPolicy:
    MinSuccessfulInstancesPercent: !Ref 'MinSuccessfulPercentParameter'

Maintain availability when updating the metadata for the cfn-init helper script

When you install software applications on your instances, you might use the AWS::CloudFormation::Init metadata key and the cfn-init helper script to bootstrap the instances in your Auto Scaling group. CloudFormation installs the packages, runs the commands, and performs other bootstrapping actions described in the metadata.

When you update only the metadata (for example, when updating a package to another version), you can use the cfn-hup helper daemon to detect and apply the updates. However, the cfn-hup daemon runs independently on each instance. If the daemon happens to runs at the same time on all instances, your application or service might be unavailable during the update. To guarantee availability, you can force a rolling update so that CloudFormation updates your instances one batch at a time.

Important

Forcing a rolling update requires CloudFormation to create a new instance and then delete the old one. Any information stored on the old instance is lost.

To force a rolling update, change the logical ID of the launch configuration resource, and then update the stack and any references pointing to the original logic ID (such as the associated Auto Scaling group). CloudFormation triggers a rolling update on the Auto Scaling group, replacing all instances.

Original template


"LaunchConfig": {
  "Type" : "AWS::AutoScaling::LaunchConfiguration",
  "Metadata" : {
    "Comment" : "Install a simple PHP application",
    "AWS::CloudFormation::Init" : {
    ...
    }
  }
}

Updated logical ID


"LaunchConfigUpdateRubygemsPkg": {
  "Type" : "AWS::AutoScaling::LaunchConfiguration",
  "Metadata" : {
    "Comment" : "Install a simple PHP application",
    "AWS::CloudFormation::Init" : {
    ...
    }
  }
}

Lambda alias update policy

The following example specifies the UpdatePolicy attribute for an AWS::Lambda::Alias resource. All the details for the deployment are defined by the application and deployment group that are passed into the policy.

JSON


"Alias": {
  "Type": "AWS::Lambda::Alias",
  "Properties": {
    "FunctionName": {
      "Ref": "LambdaFunction"
    },
    "FunctionVersion": {
      "Fn::GetAtt": [
        "FunctionVersionTwo",
        "Version"
      ]
    },
    "Name": "MyAlias"
  },
  "UpdatePolicy": {
    "CodeDeployLambdaAliasUpdate": {
      "ApplicationName": {
        "Ref": "CodeDeployApplication"
      },
      "DeploymentGroupName": {
        "Ref": "CodeDeployDeploymentGroup"
      },
      "BeforeAllowTrafficHook": {
        "Ref": "PreHookLambdaFunction"
      },
      "AfterAllowTrafficHook": {
        "Ref": "PreHookLambdaFunction"
      }
    }
  }
}

YAML


Alias:
  Type: 'AWS::Lambda::Alias'
  Properties:
    FunctionName: !Ref LambdaFunction
    FunctionVersion: !GetAtt FunctionVersionTwo.Version
    Name: MyAlias
  UpdatePolicy:
    CodeDeployLambdaAliasUpdate:
      ApplicationName: !Ref CodeDeployApplication
      DeploymentGroupName: !Ref CodeDeployDeploymentGroup
      BeforeAllowTrafficHook: !Ref PreHookLambdaFunction
      AfterAllowTrafficHook: !Ref PreHookLambdaFunction

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Metadata

UpdateReplacePolicy

UpdatePolicy attribute

Resource update policies

AppStream 2.0 update policy

Syntax

JSON

YAML

AutoScalingReplacing update policy

Important

Syntax

JSON

YAML

Properties

AutoScalingRollingUpdate policy

Important

Syntax

JSON

YAML

Properties

Important

AutoScalingScheduledAction policy

Syntax

JSON

YAML

Properties

UseOnlineResharding policy

Note

Syntax

JSON

YAML

EnableVersionUpgrade policy

Syntax

JSON

YAML

CodeDeployLambdaAlias Update policy

Syntax

JSON

YAML

Properties

Examples

Add an UpdatePolicy to an Auto Scaling group

JSON

YAML

AutoScalingReplacingUpdate policy

JSON

YAML

Maintain availability when updating the metadata for the cfn-init helper script

Important

Original template

Updated logical ID

Lambda alias update policy

JSON

YAML

`UpdatePolicy` attribute

Add an `UpdatePolicy` to an Auto Scaling group