AWS CloudFormation
ユーザーガイド (API バージョン 2010-05-15)

UpdatePolicy 属性

UpdatePolicy 属性を使用して AWS::AutoScaling::AutoScalingGroup リソース、AWS::Lambda::Alias リソース、または AWS::ElastiCache::ReplicationGroup リソースの更新を AWS CloudFormation で処理する方法を指定します。

  • AWS::AutoScaling::AutoScalingGroup リソースの場合、AWS CloudFormation は加える変更のタイプ、またはスケジュールされたアクションが Auto Scaling グループに関連付けられているかどうかに応じて、3 つの更新ポリシーのいずれかを呼び出します。

    • AutoScalingReplacingUpdate ポリシーと AutoScalingRollingUpdate ポリシーは、次の操作が一つ以上実施された場合にのみ適用されます。

      • Auto Scaling グループの AWS::AutoScaling::LaunchConfiguration を変更します。

      • Auto Scaling グループの VPCZoneIdentifier プロパティの変更

      • Auto Scaling グループの LaunchTemplate プロパティの変更

      • 現在の LaunchConfiguration に一致しないインスタンスを含む Auto Scaling グループを更新します。

      AutoScalingReplacingUpdate ポリシーと AutoScalingRollingUpdate ポリシーの両方を指定した場合、WillReplace プロパティを true に設定すると AutoScalingReplacingUpdate が優先されます。

    • AutoScalingScheduledAction ポリシーが適用されるのは、スケジュールされたアクションが関連付けられている Auto Scaling グループを含むスタックを更新する場合です。

  • AWS::Lambda::Alias リソースの場合、エイリアスでバージョンが変更されたときに AWS CloudFormation は CodeDeploy のデプロイを実行します。詳細については、「CodeDeployLambdaAliasUpdate Policy」を参照してください。

  • AWS::ElastiCache::ReplicationGroup リソースの場合、AWS CloudFormation は全体を置き換えるのではなく、シャードを追加または削除してレプリケーショングループのシャードを変更できます。詳細については、「UseOnlineResharding ポリシー」を参照してください。

AutoScalingReplacingUpdate ポリシー

AWS CloudFormation が Auto Scaling グループの置き換え更新を処理する方法を指定するには、AutoScalingReplacingUpdate ポリシーを使用します。このポリシーでは、AWS CloudFormation が Auto Scaling グループを新しいグループで置き換えるのか、Auto Scaling グループ内のインスタンスのみ置き換えるのかを指定できます。

重要

更新を実行する前に、新旧両方の Auto Scaling グループに Amazon EC2 キャパシティーが十分あることを確認してください。

構文

JSON

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

YAML

UpdatePolicy: AutoScalingReplacingUpdate: WillReplace: Boolean

プロパティ

WillReplace

Auto Scaling グループとそこに含まれるインスタンスが更新時に置き換えられるかどうかを指定します。置き換えられる場合、AWS CloudFormation は新しいグループの作成が完了するまで古いグループを保持します。更新に失敗した場合、AWS CloudFormation は古い Auto Scaling グループにロールバックし、新しい Auto Scaling グループを削除できます。

AWS CloudFormation は、新しいグループを作成するとき、インスタンスをデタッチすることもアタッチすることもありません。新しい Auto Scaling グループを正常に作成すると、AWS CloudFormation はクリーンアッププロセス中に古い Auto Scaling グループを削除します。

WillReplace パラメーターを設定するときは、必ず一致する CreationPolicy を指定してください。インスタンスの最小数 (MinSuccessfulInstancesPercent プロパティにより指定) が Timeout 期間内 (CreationPolicy ポリシーにより指定) に成功のシグナルを送信しない場合、置き換え更新に失敗し、AWS CloudFormation は古い Auto Scaling グループにロールバックします。

Type: Boolean

Required: No

AutoScalingRollingUpdate ポリシー

AWS CloudFormation が Auto Scaling グループのローリング更新を処理する方法を指定するには、AutoScalingRollingUpdate ポリシーを使用します。ローリング更新では、AWS CloudFormation が Auto Scaling グループ内のインスタンスをバッチで更新するか、一度にすべて更新するかを指定できます。

重要

ローリング更新中、AWS CloudFormation がローリング更新を完了する前に、一部の Auto Scaling プロセスが Auto Scaling グループに変更を行うことがあります。これらの変更により、ローリング更新が失敗する場合があります。ローリング更新中の Auto Scaling プロセスの実行を防止するには、SuspendProcesses プロパティを使用します。詳細については、「Auto Scaling グループローリング更新を実行するための推奨ベストプラクティスは何か?」を参照してください。

スタック更新のロールバックオペレーション中に、CloudFormation は現在のスタックの更新処理の前にテンプレートで指定されている UpdatePolicy 設定を使用することに注意してください。たとえば、スタックテンプレートの UpdatePolicyMaxBatchSize を 1 から 10 に変更したとします。その後、スタック更新を実行して、更新が失敗すると CloudFormation は更新ロールバックオペレーションを開始します。このような場合、CloudFormation は最大バッチサイズとして 10 ではなく 1 を使用します。このため、ローリング更新をトリガーする可能性が高い AWS::AutoScaling::AutoScalingGroup リソースへのアップデートとは別に、事前にスタック更新で UpdatePolicy 設定を変更することをお勧めします。

構文

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

プロパティ

MaxBatchSize

AWS CloudFormation が更新するインスタンスの最大数を指定します。

デフォルト: 1

Type: Integer

Required: No

MinInstancesInService

AWS CloudFormation が古いインスタンスを更新している間、Auto Scaling グループ内で使用中となる必要があるインスタンスの最小数を指定します。この値は Auto Scaling グループの MaxSize よりも小さくする必要があります。

デフォルト: 0

Type: Integer

Required: No

MinSuccessfulInstancesPercent

更新を成功させるために成功のシグナルを送信する必要があるインスタンスの、 Auto Scaling ローリング更新における割合を指定します。0100 の値を指定できます。AWS CloudFormation は、10% ごとに丸められます。たとえば、成功の最小割合が 50 の 5 つのインスタンスを更新する場合、3 つのインスタンスが成功のシグナルを送信する必要があります。

PauseTime プロパティで指定された時間内にインスタンスから信号が送信されない場合、AWS CloudFormation ではインスタンスが更新されなかったとみなされます。

このプロパティを指定する場合、WaitOnResourceSignals プロパティと PauseTime プロパティも有効にする必要があります。

MinSuccessfulInstancesPercent パラメータは、シグナリング目的のインスタンスにのみ適用されます。Auto Scaling グループ内のインスタンス数を指定するには、AWS::AutoScaling::AutoScalingGroup リソースの MinSize プロパティ、MaxSize プロパティ、および DesiredCapacity プロパティを参照してください。

デフォルト: 100

Type: Integer

Required: No

PauseTime

インスタンスにソフトウェアアプリケーションを起動する時間を与えるために、それらのインスタンスのバッチに変更を加えた後 AWS CloudFormation が一時停止する時間の長さ。たとえば、Auto Scaling グループ内のインスタンスの数をスケールアップする場合は PauseTime を指定する必要があります。

WaitOnResourceSignals プロパティを有効にした場合、PauseTime は、Auto Scaling グループが追加されたインスタンスか置き換えられたインスタンスから有効なシグナルを必要な数受け取るのを AWS CloudFormation が待機する必要がある時間の長さです。Auto Scaling グループが受け取るシグナルが所定の数に達する前に PauseTime を超過すると、更新は失敗します。最良の結果を得るには、アプリケーションが起動する十分な時間を確保できる期間を指定します。更新をロールバックする必要がある場合、PauseTime が短いとロールバックに失敗する可能性があります。

PauseTime は、ISO8601 期間形式 (PT#H#M#S の形式。それぞれの # は時間数、分数、秒数を示します) で指定します。最大 PauseTime は 1 時間 (PT1H) です。

デフォルト: PT0S (ゼロ秒)。WaitOnResourceSignals プロパティを true に設定すると、デフォルトは PT5M になります。

Type: String

Required: No

SuspendProcesses

スタックの更新中に Auto Scaling プロセスが停止されるように指定します。プロセスを停止すると、Auto Scaling がスタックの更新に干渉しなくなります。たとえば、Amazon EC2 Auto Scaling がアラームに関連付けられたスケーリングポリシーを実行しないようにアラームを停止できます。有効な値については、Amazon EC2 Auto Scaling API リファレンスSuspendProcesses アクションの ScalingProcesses.member.N パラメータを参照してください。

デフォルト: 指定されていません

タイプ: Auto Scaling プロセスのリスト

Required: No

WaitOnResourceSignals

Auto Scaling グループが更新中に新しいインスタンスからのシグナルを待機するかどうかを指定します。インスタンスがインストールを完了し、アプリケーションを設定した後で、Auto Scaling グループの更新を実施するようにする場合は、このプロパティを使用します。新しい EC2 インスタンスが Auto Scaling グループで起動されると AWS CloudFormation はグループの更新を停止します。AWS CloudFormation が更新を続行するには、指定された PauseTime 内に新しいインスタンスからシグナルを受け取る必要があります。Auto Scaling グループにシグナルを送信するには、cfn-signal ヘルパースクリプトまたは SignalResource API を使用します。

インスタンスが Elastic Load Balancing ヘルスチェックに成功してから成功シグナルを送信する場合は、cfn-init ヘルパースクリプトを使用してヘルスチェック検証を追加します。例については、Auto Scaling ローリング更新のサンプルテンプレートで verify_instance_health コマンドを参照してください。

デフォルト: false

Type: Boolean

Required: Conditional.MinSuccessfulInstancesPercent プロパティを指定する場合、WaitOnResourceSignals プロパティと PauseTime プロパティも有効にする必要があります。

AutoScalingScheduledAction ポリシー

AWS::AutoScaling::AutoScalingGroup リソースがスケジュールされたアクションに関連付けられている場合に、AWS CloudFormation が MinSizeMaxSizeDesiredCapacity の各プロパティの更新を処理する方法を指定するには、AutoScalingScheduledAction ポリシーを使用します。

スケジュールされたアクションを使用すると、Auto Scaling グループのグループサイズプロパティはいつでも変化する可能性があります。Auto Scaling グループやスケジュールされたアクションを含むスタックが更新される場合、スケジュールされたアクションが有効になっている場合でも、AWS CloudFormation は Auto Scaling グループのグループサイズのプロパティ値を、テンプレート内の AWS::AutoScaling::AutoScalingGroup リソースで定義されている値に設定します。

スケジュールされたアクションが有効なときに AWS CloudFormation がどのグループサイズプロパティ値も変更しないようにする場合、AutoScalingScheduledAction 更新ポリシーを使用して、テンプレートで値を変更しない限り AWS CloudFormation が MinSizeMaxSize、または DesiredCapacity プロパティを変更しないようにします。

構文

JSON

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

プロパティ

IgnoreUnmodifiedGroupSizeProperties

スタックの更新中に、現在の Auto Scaling グループと、テンプレートの AWS::AutoScaling::AutoScalingGroup リソースに記述されている Auto Scaling グループの間のグループサイズプロパティの違いを AWS CloudFormation が無視するかどうかを指定します。テンプレートのグループサイズプロパティ値のいずれかを変更した場合、AWS CloudFormation は変更後の値を使用して、Auto Scaling グループを更新します。

デフォルト: false

Type: Boolean

Required: No

CodeDeployLambdaAliasUpdate Policy

CodeDeployLambdaAliasUpdate リソースでのバージョンの変更時に CodeDeploy デプロイを実行するには、AWS::Lambda::Alias 更新ポリシーを使用します。

構文

JSON

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

プロパティ

AfterAllowTrafficHook

トラフィックのルーティングが完了した後に実行する Lambda 関数の名前。

必須: いいえ

タイプ: 文字列

ApplicationName

CodeDeploy アプリケーションの名前。

必須:: はい

タイプ: 文字列

BeforeAllowTrafficHook

トラフィックのルーティングが開始する前に実行する Lambda 関数の名前。

必須: いいえ

タイプ: 文字列

DeploymentGroupName

CodeDeploy デプロイグループの名前。ここでは、トラフィック移行ポリシーが設定されます。

必須:: はい

タイプ: 文字列

AWS::Lambda::Alias リソースの UpdatePolicy 属性を指定する例については、「Lambda エイリアスの更新ポリシー」を参照してください。

UseOnlineResharding ポリシー

AWS::ElastiCache::ReplicationGroup リソース全体を置き換えるのではなく、シャードを追加または削除してレプリケーションを変更するには、UseOnlineResharding 更新ポリシーを使用します。

UseOnlineReshardingtrue に設定されている場合、AWS::ElastiCache::ReplicationGroup リソースの NumNodeGroups プロパティと NodeGroupConfiguration プロパティを更新でき、CloudFormation は中断することなく、これらのプロパティを更新します。UseOnlineReshardingfalse に設定されている場合、または指定しない場合、NumNodeGroups プロパティおよび NodeGroupConfiguration プロパティを更新すると、AWS::ElastiCache::ReplicationGroup リソース全体が CloudFormation に置き換えられます。

UseOnlineResharding 更新ポリシーにはプロパティがありません。

UseOnlineResharding 更新ポリシーを true に設定するときは、次の点を考慮します。

  • 指定されたスタック更新オペレーションの唯一の更新として、NodeGroupConfiguration プロパティおよび NumNodeGroups プロパティの更新を実行することを強くお勧めします。

    レプリケーショングループのノードグループ構成の更新は、リソースに大きな負荷がかかります。スタックの更新が失敗した場合、CloudFormation はレプリケーショングループのノードグループ設定の変更をロールバックしません。ただし、CloudFormation は失敗した更新オペレーションの一部として変更された他のすべてのプロパティをロールバックします。

  • ノードグループを更新するために、すべてのノードグループを特定する

    NodeGroupConfiguration プロパティを指定した場合、CloudFormation が中断することなくノードの数を更新するために、各ノードグループ設定に対して NodeGroupId も指定する必要があります。

    レプリケーショングループの作成時に、各ノードグループの ID を指定しない場合、ElastiCache は各ノードグループの ID を自動的に生成します。中断することなくレプリケーショングループを更新するには、ElastiCache コンソール (https://console.aws.amazon.com/elasticache/)、または DescribeReplicationGroups を使用して、レプリケーショングループのすべてのノードグループの ID を取得します。次に、シャードの追加や削除を行う前に、スタックテンプレートの各ノードグループの ID を指定します。

    注記

    ベストプラクティスとして、スタックテンプレートでレプリケーショングループを作成するときに、指定した各ノードグループの ID を含めます。

    さらに、中断することなくノードの数を更新するには、各 NodeGroupConfiguration に対して PrimaryAvailabilityZoneReplicaAvailabilityZonesReplicaCount のプロパティを正確に指定する必要があります。ここでも、ElastiCache コンソール (https://console.aws.amazon.com/elasticache/) または DescribeReplicationGroups を使用して、各ノードグループの実際の値を取得しスタックテンプレートの値と比較します。ノードグループのプロパティ値は、個別のスタックの更新として、またはノードグループの数を変更する同じスタックの更新の一部として更新できます。

    UseOnlineResharding 更新ポリシーを使用して中断することなくノードグループの数を更新すると、ElastiCache は指定された数のスロット間でキースペースを均等に分散します。これは後から更新できません。したがって、この方法でノードグループの数を更新した後で、各ノードグループ内の実際の値が反映されなくなるため、スタックテンプレートからそれぞれの NodeGroupConfigurationSlots プロパティに指定された値を削除する必要があります。

  • 実際のノードグループの削除結果は異なる場合がある

    現在のノードグループの数より小さい NumNodeGroups 値を指定すると、CloudFormation は ElastiCache に指定した数のノードに到達できるように必要な数のノードグループを削除するように指示します。ただし、ElastiCache は必ずしも必要な数のノードグループを削除できるとは限りません。イベントで ElastiCache が必要な数のノードグループを削除できない場合、CloudFormation ではこれを警告するスタックイベントが生成されます。ElastiCache がノードグループを削除できない場合、CloudFormation リソースの更新は失敗します。

レプリケーショングループの変更方法の詳細については、Amazon ElastiCache API Reference の「ModifyReplicationGroupShardConfiguration.html」を参照してください。

構文

JSON

"UpdatePolicy" : { "UseOnlineResharding" : Boolean }

YAML

UpdatePolicy: UseOnlineResharding: Boolean

次の例では、更新グループを Auto Scaling グループに追加する方法と、メタデータの更新時に可用性を維持する方法を示します。

Auto Scaling グループに UpdatePolicy を追加します。

次の例は、更新ポリシーの追加方法を示しています。更新中、Auto Scaling グループは 2 個のインスタンスのバッチを更新し、少なくとも 1 つのインスタンスをサービスで最低 1 個のインスタンスを稼動状態にします。WaitOnResourceSignals フラグが設定されているため、Auto Scaling グループはグループに追加される新しいインスタンスを待機します。新しいインスタンスは、次のインスタンスのバッチを更新する前に、Auto Scaling グループにシグナルを送信する必要があります。

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 ポリシー

次の例では、関連付けられた Auto Scaling グループを更新時に強制的に置き換えるポリシーを宣言しています。更新が成功するためには、インスタンスの割合 (MinSuccessfulPercentParameter パラメーターにより指定) が Timeout 期間内に成功のシグナルを送信する必要があります。

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'

cfn-init Helper スクリプトのメタデータを更新する際の可用性の維持

インスタンスにソフトウェアアプリケーションをインストールするとき、AWS::CloudFormation::Init メタデータキーと cfn-init ヘルパースクリプトを使用して、Auto Scaling グループ内のインスタンスをブートストラップします。AWS CloudFormation は、パッケージをインストールしてコマンドを実行し、メタデータに記述された他のブートストラップアクションを実行します。

メタデータのみ更新する場合 (たとえば、パッケージを別のバージョンに更新する場合)、cfn-hup ヘルパーデーモンを使用して更新を検出し、適用できます。ただし、cfn-hup デーモンはインスタンスごとに別個に実行されます。デーモンがすべてのインスタンスで同時に実行されてしまった場合、アプリケーションまたはサービスが更新中に使用不可能になる可能性があります。可用性を確保するには、AWS CloudFormation が一度に 1 つのバッチでインスタンスを更新するようにローリング更新を強制します。

重要

ローリング更新ポリシーを強制するには、AWS CloudFormation が新しいインスタンスを作成した後、古いインスタンスを削除する必要があります。古いインスタンスに保存されている情報は失われます。

ローリング更新を強制するには、起動設定リソースの論理 ID を変更した後、スタックと、元のロジック ID (関連付けられた Auto Scaling グループなど) を指すすべての参照を更新します。AWS CloudFormation は、Auto Scaling グループでローリング更新をトリガーして、すべてのインスタンスを置き換えます。

元のテンプレート

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

更新された論理 ID

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

Lambda エイリアスの更新ポリシー

次の例では、UpdatePolicy リソースの AWS::Lambda::Alias 属性を指定します。デプロイの詳細はすべて、ポリシーに渡されるアプリケーションおよびデプロイグループによって定義されます。

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