本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。
使用 AWS::CloudFormation::Init
類型在 Amazon EC2 執行個體上包含cfn-init
協助程式指令碼的中繼資料。如果您的範本呼叫cfn-init
指令碼,指令碼會尋找根目錄在中繼資料金鑰中的資源AWS::CloudFormation::Init
中繼資料。如需詳細資訊,請參閱cfn-init。
cfn-init
支援 Linux 系統的所有中繼資料類型。亦支援適用於 Windows 的中繼資料類型 (但必須符合以下幾節所述的條件)。
如需使用 AWS::CloudFormation::Init
和 cfn-init
協助程式指令碼建立 Linux 堆疊的範例,請參閱 在 Amazon EC2 上部署應用程式。如需 Windows 堆疊範例,請參閱 引導 AWS CloudFormation Windows 堆疊。
語法
組態會分為不同區段。下列範本程式碼片段說明如何將 的中繼資料連接到範本中的 EC2 cfn-init
執行個體資源。
系統已將中繼資料整編為組態金鑰,而您可以將這些金鑰分組至各個組態集;您可以在範本cfn-init
中呼叫 時指定組態集。如果您未指定組態集, cfn-init
會尋找名為組態的單一組態金鑰。
注意
cfn-init
協助程式指令碼會依下列順序處理這些組態區段:套件、群組、使用者、來源、檔案、命令,以及 服務。如果您需要以不同順序進行處理,請將各區段分成不同的組態金鑰,接著使用組態集來指定處理組態金鑰時應採用的順序。
JSON
"Resources": {
"MyInstance": {
"Type": "AWS::EC2::Instance",
"Metadata" : {
"AWS::CloudFormation::Init" : {
"config" : {
"packages" : {
:
},
"groups" : {
:
},
"users" : {
:
},
"sources" : {
:
},
"files" : {
:
},
"commands" : {
:
},
"services" : {
:
}
}
}
},
"Properties": {
:
}
}
}
YAML
Resources:
MyInstance:
Type: AWS::EC2::Instance
Metadata:
AWS::CloudFormation::Init:
config:
packages:
:
groups:
:
users:
:
sources:
:
files:
:
commands:
:
services:
:
Properties:
:
注意
下列各節包含以類似 Unix 的 shell 指令碼語言撰寫的指令碼範例,例如 Bash。若要改為為 PowerShell 建立指令碼,請確定您已熟悉 PowerShell 語言。PowerShell 語法與類似 Unix 的 shell 不同,因此您需要熟悉 PowerShell 的做事方式。
組態集
如果您想要建立多個組態金鑰,並讓 以特定順序cfn-init
處理,請建立包含所需順序組態金鑰的組態集。
單一組態集
下列範本程式碼片段會建立名為 ascending
與 descending
的組態集,並分別在當中包含兩個組態金鑰。
JSON
"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" : "~"
}
}
}
}
YAML
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: "~"
相關cfn-init
呼叫
下列範例會呼叫 來cfn-init
參考上述範例組態集。為了清楚起見,範例呼叫會進行縮寫。如需完整的語法,cfn-init請參閱 。
-
如果呼叫
cfn-init
ascending
指定組態集:cfn-init -c ascending
指令碼會處理
config1
,然後處理config2
,而test.txt
檔案會包含文字I come from config2
。 -
如果呼叫
cfn-init
descending
指定組態集:cfn-init -c descending
指令碼會處理
config2
,然後處理config1
,而test.txt
檔案會包含文字I come from config1
。
多個組態集
您可以建立多個組態集,並使用cfn-init
指令碼呼叫一系列組態集。而每個組態集皆能包含組態金鑰清單或參考其他組態集。以下列範本程式碼片段為例,其將建立三個組態集。第一個組態集 test1
會包含一個名為 1
的組態金鑰;第二個組態集 test2
會參考 test1
組態集,並涵蓋一個名為 2
的組態金鑰;而第三個預設組態集則會參考 test2
組態集。
JSON
"AWS::CloudFormation::Init" : {
"configSets" : {
"test1" : [ "1" ],
"test2" : [ { "ConfigSet" : "test1" }, "2" ],
"default" : [ { "ConfigSet" : "test2" } ]
},
"1" : {
"commands" : {
"test" : {
"command" : "echo \"$MAGIC\" > test.txt",
"env" : { "MAGIC" : "I come from the environment!" },
"cwd" : "~"
}
}
},
"2" : {
"commands" : {
"test" : {
"command" : "echo \"$MAGIC\" >> test.txt",
"env" : { "MAGIC" : "I am test 2!" },
"cwd" : "~"
}
}
}
}
YAML
AWS::CloudFormation::Init:
1:
commands:
test:
command: "echo \"$MAGIC\" > test.txt"
env:
MAGIC: "I come from the environment!"
cwd: "~"
2:
commands:
test:
command: "echo \"$MAGIC\" >> test.txt"
env:
MAGIC: "I am test 2!"
cwd: "~"
configSets:
test1:
- "1"
test2:
-
ConfigSet: "test1"
- "2"
default:
-
ConfigSet: "test2"
相關cfn-init
呼叫
下列呼叫會cfn-init
參考上述範本程式碼片段中宣告configSets。為了清楚起見,範例呼叫會進行縮寫。如需完整的語法,cfn-init請參閱 。
-
若僅指定
test1
:cfn-init -c test1
cfn-init
1
只會處理組態金鑰。 -
若僅指定
test2
:cfn-init -c test2
cfn-init
會處理組態金鑰,1
然後處理組態金鑰2
。 -
若指定
default
組態集 (或未指定任何組態集):cfn-init -c default
系統的行為會與指定組態集
test2
時相同。
命令
透過 commands 金鑰,即可在 EC2 執行個體上執行命令;而系統會依照名稱的字母順序來處理這些命令。
金錀 | 必要 | 描述 |
---|---|---|
|
必要 |
以陣列或字串來指定要執行的命令。如果使用陣列,則不需跳脫空格字元或用引號括起指令參數。請勿使用陣列指定多個命令。 |
|
選用 |
可藉由此金鑰設定命令的環境變數。此屬性會進行覆寫,而非附加至現有的環境。 |
|
選用 |
工作目錄。 |
|
選用 |
測試命令,可判斷 是否 若作業系統為 Linux,測試命令必須傳回結束代碼 |
|
選用 |
布林值,可判斷命令金鑰中包含的命令是否失敗 (傳回非零值) 時是否 |
|
選用 |
僅適用於 Windows 系統。可藉由此金鑰指定命令完成後的等待時間 (以秒為單位),以防該命令導致系統重新啟動。預設值為 60 秒,且值為「永遠」會指示 只在重新啟動完成後 |
範例
下列範例程式碼片段在 ~/test.txt
檔案不存在時,會呼叫 echo 命令。
JSON
"commands" : {
"test" : {
"command" : "echo \"$MAGIC\" > test.txt",
"env" : { "MAGIC" : "I come from the environment!" },
"cwd" : "~",
"test" : "test ! -e ~/test.txt",
"ignoreErrors" : "false"
},
"test2" : {
"command" : "echo \"$MAGIC2\" > test2.txt",
"env" : { "MAGIC2" : "I come from the environment!" },
"cwd" : "~",
"test" : "test ! -e ~/test2.txt",
"ignoreErrors" : "false"
}
}
YAML
commands:
test:
command: "echo \"$MAGIC\" > test.txt"
env:
MAGIC: "I come from the environment!"
cwd: "~"
test: "test ! -e ~/test.txt"
ignoreErrors: "false"
test2:
command: "echo \"$MAGIC2\" > test2.txt"
env:
MAGIC2: "I come from the environment!"
cwd: "~"
test: "test ! -e ~/test2.txt"
ignoreErrors: "false"
檔案
透過 files
金鑰,即可在 EC2 執行個體上建立檔案。該內容可能會內嵌於範本中,亦能從 URL 取得;檔案會依詞典編纂順序寫入磁碟。下表會列出支援的金鑰。
金錀 | 描述 |
---|---|
|
此金鑰可能是字串或格式正確的 JSON 物件。如果您採用 JSON 物件做為內容,則系統會將 JSON 寫入磁碟上的檔案。您必須評估 注意如果要建立符號連結,協助程式指令碼即會修改目標檔案的許可。目前要建立符號連結,仍必須先修改目標檔案的許可。 |
|
用來載入檔案的 URL,您無法使用 content 金鑰來指定此選項。 |
|
編碼格式;唯有在內容是字串時,才能使用此金鑰。編碼並不適用於來源。 有效值: |
|
擁有此檔案的群組名稱,Windows 系統不支援此金鑰。 |
|
擁有此檔案的使用者名稱,Windows 系統不支援此金鑰。 |
|
六位數的 8 進制值,代表此檔案的模式;Windows 系統不支援此金鑰。請使用前三位數來建立符號連結,並採用後三位數來設定許可。若要建立符號連結,請指定 |
|
要使用的身分驗證方法名稱,此金鑰會覆寫任何預設的身分驗證。透過此屬性,即可選取 AWS::CloudFormation::Authentication 資源所定義的身分驗證方法。 |
|
指定要處理為Mustache範本 |
範例
下列範例程式碼片段會建立名為 的檔案,setup.mysql
做為大型安裝的一部分。
JSON
"files" : {
"/tmp/setup.mysql" : {
"content" : { "Fn::Join" : ["", [
"CREATE DATABASE ", { "Ref" : "DBName" }, ";\n",
"CREATE USER '", { "Ref" : "DBUsername" }, "'@'localhost' IDENTIFIED BY '",
{ "Ref" : "DBPassword" }, "';\n",
"GRANT ALL ON ", { "Ref" : "DBName" }, ".* TO '", { "Ref" : "DBUsername" },
"'@'localhost';\n",
"FLUSH PRIVILEGES;\n"
]]},
"mode" : "000644",
"owner" : "root",
"group" : "root"
}
}
YAML
files:
/tmp/setup.mysql:
content: !Sub |
CREATE DATABASE ${DBName};
CREATE USER '${DBUsername}'@'localhost' IDENTIFIED BY '${DBPassword}';
GRANT ALL ON ${DBName}.* TO '${DBUsername}'@'localhost';
FLUSH PRIVILEGES;
mode: "000644"
owner: "root"
group: "root"
完整範本可在 https://https://s3.amazonaws.com/cloudformation-templates-us-east-1/Drupal_Single_Instance.template
下列範例程式碼片段所建立的符號連結 /tmp/myfile2.txt
會指向現有檔案 /tmp/myfile1.txt
;而目標檔案 /tmp/myfile1.txt
的許可則是由模式 644
所定義。
JSON
"files" : {
"/tmp/myfile2.txt" : {
"content" : "/tmp/myfile1.txt",
"mode" : "120644"
}
}
YAML
files:
/tmp/myfile2.txt:
content: "/tmp/myfile1.txt"
mode: "120644"
Mustache 範本主要用來建立組態檔案。舉例來說,不需使用 Fn::Join,您亦可以在 S3 儲存貯體中存放組態檔案,並從範本插入 Ref 與 GetAtt。下列範例程式碼片段輸出Content for test9
至 /tmp/test9.txt
。
JSON
"files" : {
"/tmp/test9.txt" : {
"content" : "Content for {{name}}",
"context" : { "name" : "test9" }
}
}
YAML
files:
/tmp/test9.txt:
content: "Content for {{name}}"
context:
name: "test9"
使用 Mustache 範本時,請注意以下事項:
-
要處理的檔案皆必須具備 context 金鑰。
-
context 金鑰必須是金鑰值映射,但可以將該金鑰設為巢狀。
-
您可以透過 content 金鑰來處理具備內嵌內容的檔案,並採用 source 金鑰處理遠端檔案。
-
Mustache 支援的內容將視 pystache 版本而定,而版本 0.5.2 可支援 Mustache 1.1.2 規格
。
群組
透過 groups 金鑰,即可建立 Linux/UNIX 群組和指派群組 ID。請注意,Windows 系統並不支援 groups 金鑰。
若要建立群組,請新增一組新的索引鍵/值組,此對組會將新的群組名稱對應至選用的群組 ID。groups 金鑰可以包含一個或多個群組名稱。下表會列出可用的金鑰。
金錀 | 描述 |
---|---|
|
群組 ID 編號。 如果指定了群組 ID,而該群組的名稱已存在,則群組建立作業會失敗;如果另一個群組具有指定的群組 ID,作業系統可能會拒絕建立群組。 範例: |
範例程式碼片段
下列範例程式碼片段會指定名為 groupOne
的群組,但未指派群組 ID;同時還會建立另一個名為 groupTwo
的群組,並將群組 ID 值指定為 45
。
JSON
"groups" : {
"groupOne" : {},
"groupTwo" : { "gid" : "45" }
}
YAML
groups:
groupOne: {}
groupTwo:
gid: "45"
套件
透過 packages 金鑰,即可下載預先封裝的應用程式與元件,然後加以安裝。但在 Windows 系統上,packages 金鑰僅支援 MSI 安裝程式。
支援的套件格式
cfn-init
指令碼目前支援下列套件格式:apt、msi、python、rpm、 rubygems、yum 和 Zypper。處理套件時,系統會採用以下順序:首先是 rpm、yum/apt/zypper,接著則是 rubygems 和 python。rubygems 和 python 之間不分順序,而系統在安裝每個套件管理工具中的套件時,不保證會按照任何順序。
指定版本
在每個套件管理工具中,系統會以套件名稱和版本清單來指定各個套件。版本可以是字串、版本清單,亦能是空白字串或清單;空白字串或清單代表要安裝最新版本。如果管理工具為 rpm 格式,則系統會以磁碟上的檔案路徑或 URL 來指定版本。
如果您指定套件的版本,即使執行個體已安裝較新的套件版本, cfn-init
仍會嘗試安裝該版本。部分套件管理工具支援多個版本,有些則不支援。如需詳細資訊,請參閱套件管理工具的文件。如果您未指定版本,且已安裝套件版本,則cfn-init
指令碼不會安裝新版本,它會假設您想要保留並使用現有版本。
範例程式碼片段
RPM、yum、Rubygems 與 Zypper
下列程式碼片段將指定 rpm 的版本 URL、請求 yum 與 Zypper 的最新版本,並使用 rubygems 的 chef 0.10.2 版:
JSON
"rpm" : {
"epel" : "http://download.fedoraproject.org/pub/epel/5/i386/epel-release-5-4.noarch.rpm"
},
"yum" : {
"httpd" : [],
"php" : [],
"wordpress" : []
},
"rubygems" : {
"chef" : [ "0.10.2" ]
},
"zypper" : {
"git" : []
}
YAML
rpm:
epel: "http://download.fedoraproject.org/pub/epel/5/i386/epel-release-5-4.noarch.rpm"
yum:
httpd: []
php: []
wordpress: []
rubygems:
chef:
- "0.10.2"
zypper:
git: []
MSI 套件
下列程式碼片段將指定 MSI 套件的 URL:
JSON
"msi" : {
"awscli" : "https://s3.amazonaws.com/aws-cli/AWSCLI64.msi"
}
YAML
msi:
awscli: "https://s3.amazonaws.com/aws-cli/AWSCLI64.msi"
服務
透過 services 金鑰,即可定義執行個體啟動時應啟用或停用的服務。Linux 系統會透過 sysvinit 或 systemd 來支援此金鑰,而 Windows 系統則會透過 Windows 服務管理員進行支援。
服務金鑰也可讓您指定來源、套件和檔案的相依性,以便在安裝檔案時需要重新啟動時, cfn-init
會負責服務重新啟動。例如,如果您下載了 Apache HTTP 伺服器套件,則在堆疊建立程序期間,系統會自動啟動 Apache HTTP 伺服器套件安裝作業。然而,如果您稍後在堆疊建立程序中更新 Apache HTTP 伺服器組態,便必須重新啟動 Apache 伺服器,更新內容才會生效。您可以使用 services 金鑰來確保系統已重新啟動 Apache HTTP 服務。
下表會列出支援的金鑰。
金錀 | 描述 |
---|---|
|
設定為 true,以確保服務在完成之後執行 設定為 false,以確保服務在完成之後不會執行 如果略過此金鑰,將不會改變服務狀態。 |
|
將此金鑰設為 true,即可確保開機時會自動啟動服務。 將此金鑰設為 false,即可確保開機時不會自動啟動服務。 如果略過此金鑰,將不會改變此屬性。 |
|
檔案清單。如果直接透過檔案區塊 |
sources |
目錄清單。如果 將封存 |
packages |
對應套件管理工具與套件名稱清單。如果 |
commands |
命令名稱清單。如果 |
範例
Linux
下列 Linux 程式碼片段所設定的服務如下:
-
如果
/etc/nginx/nginx.conf
或 修改/var/www/html
,nginx 服務將會重新啟動cfn-init
。 -
如果使用 yum
cfn-init
安裝或更新 php 或 spawn-fcgi,將會重新啟動 php-fastcgi 服務。 -
系統將透過 systemd 停止並停用 sendmail 服務。
JSON
"services" : {
"sysvinit" : {
"nginx" : {
"enabled" : "true",
"ensureRunning" : "true",
"files" : ["/etc/nginx/nginx.conf"],
"sources" : ["/var/www/html"]
},
"php-fastcgi" : {
"enabled" : "true",
"ensureRunning" : "true",
"packages" : { "yum" : ["php", "spawn-fcgi"] }
}
},
"systemd": {
"sendmail" : {
"enabled" : "false",
"ensureRunning" : "false"
}
}
}
YAML
services:
sysvinit:
nginx:
enabled: "true"
ensureRunning: "true"
files:
- "/etc/nginx/nginx.conf"
sources:
- "/var/www/html"
php-fastcgi:
enabled: "true"
ensureRunning: "true"
packages:
yum:
- "php"
- "spawn-fcgi"
systemd:
sendmail:
enabled: "false"
ensureRunning: "false"
要將 systemd 與服務搭配使用,則服務必須已設定 systemd 單位檔案。以下單位檔案允許 systemd 啟動和停止多使用者服務目標中的 cfn-hup 常駐程式:
[Unit]
Description=cfn-hup daemon
[Service]
ExecStart=/usr/bin/cfn-hup -v
PIDFile=/var/run/cfn-hup.pid
[Install]
WantedBy=multi-user.target
此組態假設 cfn-hup
安裝在 /usr/bin
目錄下。不過,cfn-hup
安裝 的實際位置在不同平台上可能會有所不同。您可以在 中建立覆寫檔案來覆寫此組態/etc/systemd/system/cfn-hup.service.d/override.conf
,如下所示:
# In this example, cfn-hup executable is available under /usr/local/bin
[Service]
ExecStart=
ExecStart=/usr/local/bin/cfn-hup -v
Windows
下列 Windows 程式碼片段會啟動 cfn-hup 服務並將其設為自動執行;而在 cfn-init
修改指定的組態檔案時,則會重新啟動服務:
JSON
"services" : {
"windows" : {
"cfn-hup" : {
"enabled" : "true",
"ensureRunning" : "true",
"files" : ["c:\\cfn\\cfn-hup.conf", "c:\\cfn\\hooks.d\\cfn-auto-reloader.conf"]
}
}
}
YAML
services:
windows:
cfn-hup:
enabled: "true"
ensureRunning: "true"
files:
- "c:\\cfn\\cfn-hup.conf"
- "c:\\cfn\\hooks.d\\cfn-auto-reloader.conf"
來源
透過 sources 金鑰,即可下載封存檔案,並在 EC2 執行個體上的目標目錄中進行解壓縮。Linux 與 Windows 系統完全支援此金鑰。
支援的格式
支援的格式包括:
-
tar
-
tar+gzip
-
tar+bz2
-
zip
範例
GitHub
如果您使用 GitHub 做為來源控制系統,您可以使用 cfn-init
和來源套件機制來提取應用程式的特定版本。GitHub 讓您能透過 URL 從特定版本建立 .zip 或 .tar 檔案,如下所示:
https://github.com/<your directory>/(zipball|tarball)/<version>
例如,下列程式碼片段會將版本提取main
為 .tar
檔案。
JSON
"sources" : {
"/etc/puppet" : "https://github.com/user1/cfn-demo/tarball/main"
}
YAML
sources:
/etc/puppet: "https://github.com/user1/cfn-demo/tarball/main"
S3 儲存貯體
以下範例從 S3 儲存貯體下載了 tarball,並將其解壓縮至 /etc/myapp
:
注意
您可以針對來源使用身分驗證憑證,但不能將 authentication 金鑰放入 sources 區塊。反之,您可以在 S3AccessCreds
區塊中加入 buckets 金鑰。如需 Amazon S3 驗證憑證的詳細資訊,請參閱 AWS::CloudFormation::Authentication。
如需範例,請參閱 https://https://s3.amazonaws.com/cloudformation-templates-us-east-1/S3Bucket_SourceAuth.template
JSON
"sources" : {
"/etc/myapp" : "https://s3.amazonaws.com/amzn-s3-demo-bucket
/myapp.tar.gz"
}
YAML
sources:
/etc/myapp: "https://s3.amazonaws.com/amzn-s3-demo-bucket
/myapp.tar.gz"
使用者
透過 users 金鑰,即可在 EC2 執行個體上建立 Linux/UNIX 使用者。Windows 系統不支援 users
金鑰。
下表會列出支援的金鑰。
金錀 | 描述 |
---|---|
|
使用者 ID。如果使用者名稱具有不同的使用者 ID,則建立程序會失敗。若該使用者 ID 已指派給現有的使用者,作業系統可能會拒絕建立請求。 |
|
群組名稱清單。系統會將使用者新增至清單中的各群組。 |
|
使用者的主目錄。 |
範例
會使用 /sbin/nologin
的 shell,來將使用者建立為非互動式系統的使用者。這是設計本身所致,無法修改。
JSON
"users" : {
"myUser" : {
"groups" : ["groupOne", "groupTwo"],
"uid" : "50",
"homeDir" : "/tmp"
}
}
YAML
users:
myUser:
groups:
- "groupOne"
- "groupTwo"
uid: "50"
homeDir: "/tmp"