上一篇整理 CloudFormation Template Anatomy，本文整理很重要的概念：Resource Types、Attributes，包含以下：

• Resource Types of CloudFormation
  • AWS::CloudFormation::Init
  • AWS::CloudFormation::WaitCondition
  • AWS::CloudFormation::WaitConditionHandle
  • AWS::CloudFormation::Stack
  • AWS::CloudFormation::Interface
• Resource Attributes:
  • CreationPolicy
  • DeletionPolicy
  • DependsOn
  • UpdatePolicy

Resource Types

AWS::CloudFormation::Init

Metadata Section 有一個重要的 Resource Type: AWS::CloudFormation::Init，可以定義 EC2 的配置，包含軟體安裝、檔案權限、服務的啟動等。需要配合 CNF helper 工具 cfn-init 使用。

cfn-init 會預先安裝在 AWS Linux Image, 但是 Ubuntu 要自己裝。

以下是一個 configSet 的基本結構，config 是預設的名稱：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

Resources:
  MyInstance:
    Type: "AWS::EC2::Instance"
    Metadata:
      AWS::CloudFormation::Init:
        config:
          packages:
            :
          groups:
            :
          users:
            :
          sources:
            :
          files:
            :
          commands:
            :
          services:
            :
    Properties:
      :

configSet 可以有多個，以下的例子定義了兩個 configSets，執行的次序不一樣：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

AWS::CloudFormation::Init:
  configSets:
    ascending:
      - "config1"
      - "config2"
    descending:
      - "config2"
      - "config1"
  config1:
    commands:
      test:
        command: "echo \"$CFNTEST\" > test.txt"
        env:
          CFNTEST: "I come from config1."
        cwd: "~"
  config2:
    commands:
      test:
        command: "echo \"$CFNTEST\" > test.txt"
        env:
          CFNTEST: "I come from config2"
        cwd: "~"

CloudFormation Helper: cfn-init

安裝 for ubuntu

1
2
3
4
5
6
7
8
9

cd /opt
mkdir aws-cfn-bootstrap-latest

apt-get update
apt-get -y install python-setuptools

curl https://s3.amazonaws.com/cloudformation-examples/aws-cfn-bootstrap-latest.tar.gz | tar xz -C aws-cfn-bootstrap-latest --strip-components 1

easy_install aws-cfn-bootstrap-latest

AWS::CloudFormation::WaitCondition

以下狀況可以使用 WaitCondition 或者 CreationPolicy:

• 為了跟其他 Stack 資源狀態配合，像是 VPC Stack 和建立 AD 的 Stack ，後者要等前者建立完成。
• 追蹤配置程序的狀態

重要：針對 EC2 和 Auto Scaling resources，官方建議使用 CreationPolicy attribute 配合 cfn-signal helper 送訊號告訴 CFN 資源已經建立完成，而不是 WaitCondition。
WaitCondition 是一種 Resource Type，CreationPolicy 則是 Resource Property

基本的 Syntax 如下：

1
2
3
4
5

Type: "AWS::CloudFormation::WaitCondition"
Properties:
  Count: Integer
  Handle: String
  Timeout: String

三個 properties 描述：

• Count: 表示繼續執行之前，要收到幾次的成功訊息。如果在指定的時間之內 (Timeout) 沒有收到指定的成功樹，那麼 CFN 就會認定執行失敗，然後開始 rollback.
• Handle: 用 Ref function 參考到 AWS::CloudFormation::WaitConditionHandle，CFN 會回傳一個 presigned URL，然後轉送給 EC2 裡面的應用程式或者 scripts 呼叫。應用程式透過 call 這個 URL 告訴 CFN 程序是否成功。
• Timeout: 等待多久，如果時間到，Count 還沒累加到指定的數字，就會認定執行失敗。

相關文件：

• AWS::CloudFormation::WaitCondition
• AWS::CloudFormation::WaitConditionHandle
• Creating Wait Conditions in a Template

AWS::CloudFormation::WaitConditionHandle

WaitConditionHandle 沒有 properties。會產生一個 presigned URL 讓 EC2 裡的 scripts callback，告訴 CFN ，EC2 裡的程序是否已經成功。

AWS::CloudFormation::Stack

Top-level template 用來參考另一個 nested stack (巢狀)。通常 nested stack 會使用 Outputs Section 把結果寫下，然後 Top-level template 使用 GetAtt Function 取得 Outputs 的結果。

Syntax 如下：

1
2
3
4
5
6
7
8
9
10

Type: "AWS::CloudFormation::Stack"
Properties:
  NotificationARNs:
    - String
  Parameters:
    CloudFormation Stack Parameters Property Type
  Tags:
    - Resource Tag
  TemplateURL: String
  TimeoutInMinutes: Integer

Properties 描述：

• NotificationARNs: 已經建立好的 SNS ARN.
• Parameters: 傳遞給 nested stack 的參數
• Tags: nest stacked 建立時，設定 Tags
• TemplateURL: template 必須存在 s3, 格式一定要是 https://s3.amazonaws.com/.../TemplateName.template
• TimeoutInMinutes: 等待的時間，單位是分鐘，預設是沒有上限時間。CFN 等 nested stack 的回傳狀態，預期狀態是 CREATE_COMPLETE。如果超過等待時間，或者回傳狀態不是 CREATE_COMPLETE，那麼 nested stack 和 parent stack 都會被 rollback。

其中 Parameters, TemplateURL 是必要的。

AWS::CloudFormation::Interface

這是個 metadata Type，用來描述 Parameters 如何在 AWS CloudFormation Console 呈現成 grouped or sorted。Console 預設會使用 alphabetical 排列 Logical Id。

Resource Attributes

Resource Attributes 用來設定 Resource 額外的控制和關聯，一共有以下幾個：

• CreationPolicy Attribute
• DeletionPolicy Attribute
• DependsOn Attribute
• Metadata Attribute
• UpdatePolicy Attribute

Creation Policy

Creation Policy 用來設定當建立資源的時候，告訴 CFN 什麼時候才是完成。CFN 可以透過接收完成的 signals ，然後確認資源是否完成建立。可以使用 cfn-signal helper script 或者 SignalResource API 告訴 CFN。

通常在建立 EC2 Instance 時，配置軟體設定的時候，需要確認是否已經執行完成。例如建立好 EC2 之後，要做以下設定與配置 (參考：Deploying Applications on Amazon EC2 with AWS CloudFormation)：

• 安裝工具 LAMP packages：mysql, php, httpd
• 產生一些檔案 files：
  • /var/www/html/index.php
  • /tmp/setup.mysql
  • /etc/cfn/cfn-hup.conf
  • /etc/cfn/hooks.d/cfn-auto-reloader.conf
• 設定系統啟動服務：mysqld, httpd, cfn-hup
• 配置
  • 設定 MySQL root password
  • 建立 Database

這些動作分成 Install and Run，這些設定放在 AWS::CloudFormation::Init ，然後透過 UserData 執行，如下例子:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

"Properties": {
    "UserData": { "Fn::Base64" : { "Fn::Join" : ["", [
        "#!/bin/bash -xe\n",
        "yum install -y aws-cfn-bootstrap\n",

        "# Install the files and packages from the metadata\n",
        "/opt/aws/bin/cfn-init ",
        "         --stack ", { "Ref" : "AWS::StackName" },
        "         --resource WebServerInstance ",^M
        "         --configsets InstallAndRun ",
        "         --region ", { "Ref" : "AWS::Region" }, "\n"

        "# Signal the status from cfn-init\n",
        "/opt/aws/bin/cfn-signal -e $? ",
        "         --stack ", { "Ref" : "AWS::StackName" },
        "         --resource WebServerInstance ",
        "         --region ", { "Ref" : "AWS::Region" }, "\n"
   ]]}}
 },
 "CreationPolicy" : {
   "ResourceSignal" : {
     "Timeout" : "PT5M"
   }
 }

UserData 內容步驟是：

1. 安裝 CloudFormation bootstrap
2. 透過 cfn-init 觸發 init 程序，指定:

• StackName
• Resource Logical ID
• configsets Name: InstallAndRun
• Region
• 執行 AWS::CloudFormation::Init 裡的 configSet:

3. 接受 cfn-init 的 return code $?，把結果送給 Stack

• CreationPolicy 則根據 Timeout 時間以及 Signal 判斷此資源是否建立成功

完整的例子參考：Deploying Applications on Amazon EC2 with AWS CloudFormation)

只有這三個 Resource Type 支援 Creation Policy:

• AWS::AutoScaling::AutoScalingGroup
• AWS::EC2::Instance
• AWS::CloudFormation::WaitCondition

以下是 Syntax:

1
2
3
4
5
6

CreationPolicy:
  Auto ScalingCreationPolicy:
    MinSuccessfulInstancesPercent: Integer
  ResourceSignal:
    Count: Integer
    Timeout: String

• Auto ScalingCreationPolicy: 指定有多少 instance 必須收到成功 signals
  • MinSuccessfulInstancesPercent: 最小的成功百分比
• ResourceSignal
  • Count: default 1, 計算成功的次數，接收到 CREATE_COMPLETE 則算一次。只要收到失敗就會 rollback.
  • Timeout: default 5min, 格式：PT#H#M#S

Deletion Policy

刪除 Stack 的時候，可以透過 Deletion Policy 指定特定的資源，是否保留或者刪除。CFN 執行 Delete Stack 時預設每個資源都會被刪除。

Syntax 如下：

1
2
3
4

Resources:
  myS3Bucket:
    Type: AWS::S3::Bucket
    DeletionPolicy: Retain

DeletionPolicy 的選項：

• Delete: 預設 CFN 會刪除。
  • 如果是 s3 bucket，必須裡面的 object 都被刪除，才有辦法刪除 bucekt.
• Retain: 保留, CFN 不會刪除
• Snapshot: 以下 Resource Type 支援刪除前執行 Snapshot
  • AWS::EC2::Volume
  • AWS::ElastiCache::CacheCluster
  • AWS::ElastiCache::ReplicationGroup
  • AWS::RDS::DBInstance
  • AWS::RDS::DBCluster
  • AWS::Redshift::Cluster

DependsOn

如果資源建立的過程彼此有相依性，可以透過 DependsOn attribute 指定依賴關係，通常是 Application 需要相依 Database，如下：

1
2
3
4
5
6
7
8
9
10
11
12

Resources:
  Ec2Instance:
    Type: AWS::EC2::Instance
    Properties:
      ImageId: ami-xxxxxxx
    DependsOn: myDB
  myDB:
    Type: AWS::RDS::DBInstance
    Properties:
      AllocatedStorage: '5'
      DBInstanceClass: db.m1.small
      Engine: MySQL

常見相依的例子：

• Auto ScalingGroup DependsOn LaunchConfiguration
• ECS DependsOn Auto ScalingGroup
• 如果 Resource 有使用 EIP，那麼要 DependsOn VPC-gateway，不管是 Internet or NAT Gateway.

Update Policy

UpdatePolicy Attribute 主要 CFN 執行更新的時候，針對 AWS::Auto Scaling::Auto ScalingGroup 的處理。

• Auto ScalingReplacingUpdate Policy
• Auto ScalingRollingUpdate Policy
• Auto ScalingScheduledAction Policy

Auto ScalingReplacingUpdate

指定 CFN 是否要換掉整個 Auto ScalingGroup

1
2
3

UpdatePolicy:
  Auto ScalingReplacingUpdate:
    WillReplace: Boolean

置換的過程中，CFN 會先保留舊的 ASG，直到新的建立完成。如果建立失敗，CFN 會把新的砍掉，然後 Rollback 回去舊的。

如果使用 WillReplace，記得使用 CreationPolicy 的 MinSuccessfulInstancesPercent，指定最小的比例。

Auto ScalingRollingUpdate

指定 CFN 如果處理 Auto Scaling 的 rolling update。可以指定 CFN 用 批次 (Batch) 或者一次性 (Once) 更新 ASG 裡的 Instances。

Syntax 如下：

1
2
3
4
5
6
7
8
9

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

• MaxBatchSize
• MinInstancesInService
• MinSuccessfulInstancesPercent
• PauseTime
• SuspendProcesses
• WaitOnResourceSignals

相關文件:

• What are some recommended best practices for performing Auto Scaling group rolling updates?

Auto ScalingScheduledAction

當 ASG Resource 有指定 Scheduled action，指定 CFN 更新 MinSize, MaxSize, and DesiredCapacity

1
2
3

UpdatePolicy:
  Auto ScalingScheduledAction:
    IgnoreUnmodifiedGroupSizeProperties: Boolean

結論

Resource Type 和 Attribute 是 Template 裡很重要的概念，了解其基本概念之後，開發 Template 過程，才知道如何找到對應的資源與資訊，做到想要的架構。

了解了 Template 大致上的結構、相關資訊之後，接下來就是如何拿來使用了。下一篇整理如何利用 Template 產生出來的資源集合：Stack，包含工作流程、狀態圖、如何更新 StackSet。

延伸閱讀

系列文章

• Study Notes - CloudFormation
• Study Notes - CloudFormation Template Anatomy
• Study Notes - CloudFormation Resource Types and Attributes
• Study Notes - CloudFormation Stack
• Study Notes - CloudFormation Debugging

延伸閱讀 (站內)

• Resource Provisioning and DevOps
• AWS Study Roadmap

參考資料

• Resource Attributes: CreationPolicy, DeletionPolicy, DependsOn, Metadata, UpdatePolicy
• UpdatePolicy Attribute
• Faster Auto Scaling in AWS CloudFormation Stacks with Lambda-backed Custom Resources

更新紀錄

• 2017/03/31: 初版
• 2018/12/22: 調整排版