Study Notes - CloudFormation Template Anatomy


本文整理 CloudFormation 整理官方文件學習筆記,主要是 Template Anatomy (結構) 的部分。


名詞說明

以下是文件中常見的名詞,或者縮寫。

  • CFN: CloudFormation 的縮寫
  • Templates: 用 json or yaml 描述資源的文件,也是 CFN 最重要的部分
  • Stacks: 透過 Templates 的描述檔,產生的實體 (physical) 資源 (resources) 集合稱為 Stacks,這些資源可以是 EC2 Instances, RDS, EIP, VPC, Security Groups …. 等,幾乎支援 AWS 所有的資源。
  • ChangeSets: 針對已經建立的 Stacks 做異動,你可以讓 CFN 先產生一個 ChangeSets,他會把整個異動的結果顯示給你參考,告訴你可能產生的影響以及變動。
  • Resource Type: 定義 AWS 資源的類型,用 AWS::aws-product-name::data-type-name 表示資源,像是 EC2 Instance 是 AWS::EC2::Instance
  • Resource Properties: 描述每個 Resource Type 的屬性。

Working with Templates

CloudFormation Template 是用來描述資源的文件,支援 jsonyaml 兩種資料格式。我個人比較推薦 yaml,因為可讀性比 json 好很多,另外很重要的是:yaml 可以註解,json 不行。

我覺得 Template 可以算 Infra as Code 的 DSL (Domain-specific language),雖然他不是完整的 Programming Language,但已經具備 variables, functions / libraries, lambdas (Conditions) 等概念,甚至是 data type (custom resources)。

Templates 的設計有很多方式,以下是三種主要的方法:

  • 透過 AWS Console 上的視覺化工具:CloudFormation Designer 設計。
  • 使用官方提供的範例:Template SnippetsSample Templates
  • 利用 AWS CloudFormer,產生目前的 Infra 的 Template。他也是用 CFN 動態生出一台 EC2,上面跑了 RoR 的應用程式,過程當中需要給這個 Stack 一定的權限,他會讀取所有資源的資訊,一系列的問答之後,最後產生一個 Template 檔案。

Template Anatomy

一份 Template 結構 會有以下 Sections,其中只有 Resources 是必要的,其他都是 Optional:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
---
# Specifies the AWS CloudFormation template version that the template conforms to.
AWSTemplateFormatVersion: "version date"

Description:

# Provide additional information about the template.
Metadata:

# 指定 Template 的參數,把 Template 想像成程式的 Function,這個就是 Input。對應的有 Outputs
Parameters:

# 通常透過 Fn::FindInMap 找對應資料使用,像是不同 Region 的 AMI、或者資源等。
Mappings:

# 定義控制條件,建立資源時,可以參考控制條件,決定是否建立。例如環境是 Prod,則建立某一個資源。
Conditions:

# Serverless Application Model (AWS SAM) 新增的 Sections
Transform:

# 最主要的資源描述都在這個 Sections, 也是 Template 裡唯一必要的。
Resources:

# 輸出,將執行結果輸出。可以單純當作顯示,也可以給其他 Stack 使用。
Outputs:

Templates 的結構有很多東西,整理三個最重要的:Parameters、Resources、Outputs

Parameters Section

Parameters 是定義 Template 可以輸入哪一些參數,有點像程式的 Function 參數的宣告。

基本的 Syntax 如下:

1
2
3
4
Parameters:
ParameterLogicalID:
Type: DataType
ParameterProperty: value

ParameterLogicalID 表示參數名稱,有點像是變數名稱。

要注意的是,文件並沒有提到可以用哪一些字元,但實際上只能使用 [A-Z],不能有 - (dash) or _ (underline)。

Type 可以指定資料型態,基本的有 String, Number, List<Number>, CommaDelimitedListCommaDelimitedList 通常會用來指定環境,像是 "test,dev,prod" 這樣的內容。

Type 也可以指定 AWS 的資源型別 (AWS-specific parameter types),像是 特定的 EC2 instance id、Security Group Id … 也可以用 List 方式,讓使用者選擇。整理如下:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
AWS::EC2::AvailabilityZone::Name
AWS::EC2::Image::Id
AWS::EC2::Instance::Id
AWS::EC2::KeyPair::KeyName
AWS::EC2::SecurityGroup::GroupName
AWS::EC2::SecurityGroup::Id
AWS::EC2::Subnet::Id
AWS::EC2::Volume::Id
AWS::EC2::VPC::Id
AWS::Route53::HostedZone::Id
List<AWS::EC2::AvailabilityZone::Name>
List<AWS::EC2::Image::Id>
List<AWS::EC2::Instance::Id>
List<AWS::EC2::SecurityGroup::GroupName>
List<AWS::EC2::SecurityGroup::Id>
List<AWS::EC2::Subnet::Id>
List<AWS::EC2::Volume::Id>
List<AWS::EC2::VPC::Id>
List<AWS::Route53::HostedZone::Id>

ParameterProperty 有很多個選項,都是作為輸入條件篩選、限制、預設、說明、安全性隱藏 (像是密碼) … 等,條例如下:

  • AllowedPattern
  • AllowedValues
  • ConstraintDescription
  • Default
  • Description
  • MaxLength
  • MaxValue
  • MinLength
  • MinValue
  • NoEcho

Group and Sort Parameters in the AWS CloudFormation Console

Parameters 的清單預設使用 alphabetically 排序,如果想在 Console 做排序或者 Group,則可以透過 AWS::CloudFormation::Interface 調整。

AWS::CloudFormation::Interface

AWS CLI and API Support

參數可以透過 --parameters 傳遞,如下:

1
2
3
4
aws cloudformation create-stack \
--stack-name ${STACK_NAME} \
--template-body file://${TEMPLATE}
--parameters Param1=Value1,Param2=Value2,...

Resources Section

Resources 是 CFN 最主要的 Section,每個 Resource 由幾個 Fields 組成:

  • Logical ID: 使用者自訂名稱,只能使用 A-Za-z0-9,Template 使用此 ID 做為參考
  • Resource type: 主要參考 AWS Resource Types
  • Resource properties: 主要用來描述每個資源額外的屬性。每個 Resource Type 會有不同的 properties
1
2
3
4
5
Resources:
Logical ID:
Type: Resource type
Properties:
Set of properties

Outputs Section

Outputs 定義了哪一些產出的資源 (Resources):

  • 可以在 AWS CloudFormation Console 顯示
  • 可以給其他的 Stack 使用

Outputs 主要由以下 Fields 組成:

  • Logical ID: 顯示的 ID, 必須是 a-z, A-Z, 0-9
  • Description (optional)
  • Value (required): 通常是回傳 Physical ID,像是 EC2 Instance ID 可以用 {LogicalId}.InstanceID 取得
  • Export (optional): 給 cross stack 使用的 ID

格式如下:

1
2
3
4
5
6
Outputs:
Logical ID:
Description: Information about the value
Value: Value to return
Export:
Name: Value to export

結論

簡單整理剛開始學習 CloudFormation 時要接觸的基本資訊,其中最重要的,也就是 DevOps Engineer 主要的任務:Template 的開發。開發 Template 之前要認識他的基本概念、名詞與結構。了解大結構之後,下一篇介紹的是重要的特性:Resource Types and Attributes


延伸閱讀

系列文章

相關文章

參考資料

更新紀錄

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

Comments