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 是預設的名稱:

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
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 TypeCreationPolicy 則是 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::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:
AutoScalingCreationPolicy:
MinSuccessfulInstancesPercent: Integer
ResourceSignal:
Count: Integer
Timeout: String
  • AutoScalingCreationPolicy: 指定有多少 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

常見相依的例子:

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

Update Policy

UpdatePolicy Attribute 主要 CFN 執行更新的時候,針對 AWS::AutoScaling::AutoScalingGroup 的處理。

  • AutoScalingReplacingUpdate Policy
  • AutoScalingRollingUpdate Policy
  • AutoScalingScheduledAction Policy

AutoScalingReplacingUpdate

指定 CFN 是否要換掉整個 AutoScalingGroup

1
2
3
UpdatePolicy:
AutoScalingReplacingUpdate:
WillReplace: Boolean

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

如果使用 WillReplace,記得使用 CreationPolicyMinSuccessfulInstancesPercent,指定最小的比例。

AutoScalingRollingUpdate

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

Syntax 如下:

1
2
3
4
5
6
7
8
9
UpdatePolicy:
AutoScalingRollingUpdate:
MaxBatchSize: Integer
MinInstancesInService: Integer
MinSuccessfulInstancesPercent: Integer
PauseTime: String
SuspendProcesses:
- List of processes
WaitOnResourceSignals: Boolean
  • MaxBatchSize
  • MinInstancesInService
  • MinSuccessfulInstancesPercent
  • PauseTime
  • SuspendProcesses
  • WaitOnResourceSignals

相關文件:

AutoScalingScheduledAction

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

1
2
3
UpdatePolicy:
AutoScalingScheduledAction:
IgnoreUnmodifiedGroupSizeProperties: Boolean

延伸閱讀

參考資料


Comments