Study Notes - CloudFormation Resource Types and Attributes

上一篇整理 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 是預設的名稱：

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

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

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

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 如下：

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::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 如下：

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 執行，如下例子:

"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 內容步驟是：

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

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

接受 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:

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 如下：

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，如下：

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 如下：

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 Resource Types and Attributes

Resource Types

AWS::CloudFormation::Init

CloudFormation Helper: cfn-init

AWS::CloudFormation::WaitCondition

AWS::CloudFormation::WaitConditionHandle

AWS::CloudFormation::Stack

AWS::CloudFormation::Interface

Resource Attributes

Creation Policy

Deletion Policy

DependsOn

Update Policy

Auto ScalingReplacingUpdate

Auto ScalingRollingUpdate

Auto ScalingScheduledAction

結論

延伸閱讀

系列文章

延伸閱讀 (站內)

參考資料

更新紀錄

Comments

About

著作

演講

Facebook

AWS Certifications