UpdatePolicy attribute

Use the UpdatePolicy attribute to specify how AWS CloudFormation handles updates to certain resources during stack update operations.

Overview

By using the UpdatePolicy attribute, you can control how the following resources are updated, as described here:

The sections that follow describe the syntax and properties for the UpdatePolicy attribute supported by each resource type.

AppStream 2.0 update policy

To stop an AppStream 2.0 fleet before an update and restart it after an update, use the AppStream 2.0 update policy.

Syntax

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

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

AutoScalingReplacingUpdate policy

To replace the Auto Scaling group and the instances it contains, use the AutoScalingReplacingUpdate policy.

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

Syntax

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

UpdatePolicy:
  AutoScalingReplacingUpdate:
    WillReplace: Boolean

Properties

AutoScalingRollingUpdate policy

To perform a rolling update of the instances in an Auto Scaling group rather than wait for scaling activities to gradually replace older instances with newer instances, use the AutoScalingRollingUpdate policy. This policy provides you the flexibility to specify whether CloudFormation replaces instances that are in an Auto Scaling group in batches or all at once without replacing the entire resource.

Things to consider when using an AutoScalingRollingUpdate policy:

Syntax

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

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

Properties

AutoScalingScheduledAction policy

To specify how 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

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

UpdatePolicy:
  AutoScalingScheduledAction:
    IgnoreUnmodifiedGroupSizeProperties: Boolean

Properties

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:

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

Syntax

"UpdatePolicy" : {
  "UseOnlineResharding" : Boolean
}

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

"UpdatePolicy" : {
  "EnableVersionUpgrade" : Boolean
}

UpdatePolicy:
  EnableVersionUpgrade: Boolean

CodeDeployLambdaAliasUpdate policy

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

Syntax

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

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

Properties

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.

"ASG" : {
  "Type":"AWS::AutoScaling::AutoScalingGroup",
  "Properties":{
    "VPCZoneIdentifier":[ "subnetIdAz1", "subnetIdAz2", "subnetIdAz3" ],
    "LaunchTemplate":{
      "LaunchTemplateId":{
        "Ref":"logicalName"
      },
      "Version":{
        "Fn::GetAtt":[
          "logicalName",
          "LatestVersionNumber"
        ]
      }
    },
    "MaxSize":"4",
    "MinSize":"1"
  },
  "UpdatePolicy":{
    "AutoScalingScheduledAction":{
      "IgnoreUnmodifiedGroupSizeProperties":"true"
    },
    "AutoScalingRollingUpdate":{
      "MinInstancesInService":"1",
      "MaxBatchSize":"2",
      "WaitOnResourceSignals":"true",
      "PauseTime":"PT10M",
      "SuspendProcesses":[
        "HealthCheck",
        "ReplaceUnhealthy",
        "AZRebalance",
        "AlarmNotification",
        "ScheduledActions",
        "InstanceRefresh"
      ]
    }
  }
}

ASG:
  Type: 'AWS::AutoScaling::AutoScalingGroup'
  Properties:
    VPCZoneIdentifier:
      - subnetIdAz1
      - subnetIdAz2
      - subnetIdAz3
    LaunchTemplate:
      LaunchTemplateId: !Ref logicalName
      Version: !GetAtt logicalName.LatestVersionNumber
    MaxSize: '4'
    MinSize: '1'
  UpdatePolicy:
    AutoScalingScheduledAction:
      IgnoreUnmodifiedGroupSizeProperties: 'true'
    AutoScalingRollingUpdate:
      MinInstancesInService: '1'
      MaxBatchSize: '2'
      WaitOnResourceSignals: 'true'
      PauseTime: PT10M
      SuspendProcesses:
        - HealthCheck
        - ReplaceUnhealthy
        - AZRebalance
        - AlarmNotification
        - ScheduledActions
        - InstanceRefresh

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.

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

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.

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.

"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"
      }
    }
  }
}

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