本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# CloudFormation 部署動作參考
在 CloudFormation 堆疊上執行 操作。堆疊是您可以單一單位管理的一組 AWS 資源。堆疊中的資源都是由堆疊的 CloudFormation 範本定義。變更集會建立比較，無須變更原始堆疊即可檢視。如需可在堆疊和變更集上執行之 CloudFormation 動作類型的相關資訊，請參閱 `ActionMode` 參數。
若要針對堆疊操作失敗 CloudFormation 的動作建構錯誤訊息，CodePipeline 會 CloudFormation `DescribeStackEvents`呼叫 API。如果動作 IAM 角色具有存取該 API 的許可，則有關第一個失敗資源的詳細資訊將包含在 CodePipeline 錯誤訊息中。否則，如果角色政策沒有適當的許可，CodePipeline 將忽略存取 API，並改為顯示一般錯誤訊息。若要這樣做，必須將 `cloudformation:DescribeStackEvents`許可新增至管道的服務角色或其他 IAM 角色。
如果您不希望資源詳細資訊出現在管道錯誤訊息中，您可以透過移除許可來撤銷動作 IAM 角色的此`cloudformation:DescribeStackEvents`許可。
**Topics**
+ [動作類型](#action-reference-CloudFormation-type)
+ [組態參數](#action-reference-CloudFormation-config)
+ [Input artifacts (輸入成品)](#action-reference-CloudFormation-input)
+ [輸出成品](#action-reference-CloudFormation-output)
+ [輸出變數](#action-reference-CloudFormation-variables)
+ [服務角色許可： CloudFormation 動作](#edit-role-cloudformation)
+ [動作宣告](#action-reference-CloudFormation-example)
+ [另請參閱](#action-reference-CloudFormation-links)
## 動作類型
+ 類別：`Deploy`
+ 擁有者：`AWS`
+ 提供者：`CloudFormation`
+ 版本：`1`
## 組態參數
**ActionMode**
必要：是
`ActionMode` 是 動作在堆疊或變更集 CloudFormation 上執行的名稱。以下是可用的動作模式：
+ `CHANGE_SET_EXECUTE` 根據一組指定的資源更新，為資源堆疊執行變更集。在此動作中， 會 CloudFormation 開始修改堆疊。
+ `CHANGE_SET_REPLACE` 根據您提交的堆疊名稱和範本建立變更組 (若不存在的話)。如果變更集存在， 會將其 CloudFormation 刪除，然後建立新的變更集。
+ `CREATE_UPDATE` 建立堆疊 (如果堆疊不存在)。如果堆疊存在， 會 CloudFormation 更新堆疊。使用此動作來更新現有堆疊。與 不同`REPLACE_ON_FAILURE`，如果堆疊存在且處於失敗狀態，CodePipeline 不會刪除和取代堆疊。
+ `DELETE_ONLY` 刪除堆疊。若您指定不存在的堆疊，動作會成功完成，而不會刪除任何堆疊。
+ `REPLACE_ON_FAILURE` 建立堆疊 (若堆疊不存在)。如果堆疊存在且處於失敗狀態， 會 CloudFormation 刪除堆疊，然後建立新的堆疊。如果堆疊未處於失敗狀態， 會 CloudFormation 更新它。
若在 CloudFormation中顯示下列任何狀態類型，堆疊會處於故障狀態：
+ `ROLLBACK_FAILED`
+ `CREATE_FAILED`
+ `DELETE_FAILED`
+ `UPDATE_ROLLBACK_FAILED`
使用此動作來自動取代故障的堆疊，無須復原或故障診斷。
**重要**
建議您使用 `REPLACE_ON_FAILURE` 僅作為測試目的，因為它可能會刪除您的堆疊。
**StackName**
必要：是
`StackName` 是現有堆疊或您希望建立之堆疊的名稱。
**功能**
必要：有條件
使用 `Capabilities` 可確認範本具有自行建立和更新一些資源的功能，而且這些功能是根據範本中的資源類型來決定。
如果您的堆疊範本中有 IAM 資源，或您直接從包含巨集的範本建立堆疊，則此屬性為必要。為了讓 CloudFormation 動作以這種方式成功運作，您必須明確確認您希望它使用下列其中一個功能來執行此操作：
+ `CAPABILITY_IAM`
+ `CAPABILITY_NAMED_IAM`
+ `CAPABILITY_AUTO_EXPAND`
您可以透過在功能間使用逗號 (無空格) 來指定多個功能。[動作宣告](#action-reference-CloudFormation-example) 中的範例顯示具有 CAPABILITY\$1IAM 和 CAPABILITY\$1AUTO\$1EXPAND 屬性的項目。
如需 的詳細資訊`Capabilities`，請參閱 *AWS CloudFormation API 參考*中 [UpdateStack](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_UpdateStack.html) 下的屬性。
**ChangeSetName**
必要：有條件
`ChangeSetName` 是現有變更集或您希望為指定堆疊建立之新變更集的名稱。
針對下列動作模式，此屬性為必要：CHANGE\$1SET\$1REPLACE 和 CHANGE\$1SET\$1EXECUTE。針對其他所有動作模式，可忽略此屬性。
**RoleArn**
必要：有條件
`RoleArn` 是在指定堆疊中的資源上操作時 CloudFormation 所假設 IAM 服務角色的 ARN。執行變更集時，不會套用 `RoleArn`。若您不使用 CodePipeline 來建立變更集，請確定變更集或堆疊具有關聯角色。
此角色必須與正在執行之動作的角色位於相同的帳戶中，如動作宣告 中所設定`RoleArn`。
針對下列動作模式，此屬性為必要：
+ CREATE\$1UPDATE
+ REPLACE\$1ON\$1FAILURE
+ DELETE\$1ONLY
+ CHANGE\$1SET\$1REPLACE
CloudFormation 為範本提供 S3-signed URL；因此，這`RoleArn`不需要存取成品儲存貯體的許可。不過， 動作`RoleArn`*確實*需要存取成品儲存貯體的許可，才能產生已簽署的 URL。
**TemplatePath**
必要：有條件
`TemplatePath` 代表 CloudFormation 範本檔案。您將檔案包含在此動作的輸入成品中。該檔案名稱遵循此格式：
`Artifactname::TemplateFileName`
`Artifactname` 是出現在 CodePipeline 中的輸入成品名稱。例如，來源階段的成品名稱為 `SourceArtifact` 且 `template-export.json` 檔案名稱建立 `TemplatePath` 名稱，如此範例所顯示：
```
"TemplatePath": "SourceArtifact::template-export.json"
```
針對下列動作模式，此屬性為必要：
+ CREATE\$1UPDATE
+ REPLACE\$1ON\$1FAILURE
+ CHANGE\$1SET\$1REPLACE
針對其他所有動作模式，可忽略此屬性。
包含 CloudFormation 範本內文的範本檔案長度下限為 1 位元組，長度上限為 1 MB。對於 CodePipeline 中的 CloudFormation 部署動作，輸入成品大小上限一律為 256 MB。如需詳細資訊，請參閱[AWS CodePipeline 中的配額](limits.md)和 [CloudFormation 的限制](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cloudformation-limits.html)。
**OutputFileName**
必要：否
使用 `OutputFileName`指定輸出檔案名稱，例如 CodePipeline `CreateStackOutput.json`新增至此動作的管道輸出成品。JSON 檔案包含 CloudFormation 堆疊中 `Outputs`區段的內容。
如果您未指定名稱，CodePipeline 不會產生輸出檔案或成品。
**ParameterOverrides**
必要：否
參數會定義於您的堆疊範本中，並可讓您在建立或更新堆疊時為其提供值。您可以使用 JSON 物件在您的範本中設定參數值。(這些值會覆寫範本組態檔案中設定的值。) 如需使用參數覆寫的詳細資訊，請參閱 [組態屬性 (JSON 物件)](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/continuous-delivery-codepipeline-action-reference.html#w4363ab1c13c13b9)。
我們建議您大多數的參數值都使用範本組態檔案。僅對管道執行前未知的值使用參數覆寫。如需詳細資訊，請參閱*AWS CloudFormation 《 使用者指南*》中的[使用參數覆寫函數搭配 CodePipeline 管道](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/continuous-delivery-codepipeline-parameter-override-functions.html)。
所有參數名稱都必須在堆疊範本中存在。
**TemplateConfiguration**
必要：否
`TemplateConfiguration` 是範本組態檔案。您將檔案包含在此動作的輸入成品中。它可以包含範本參數值和堆疊政策。如需範本組態檔案格式的詳細資訊，請參閱[AWS CloudFormation 成品](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/continuous-delivery-codepipeline-cfn-artifacts.html)。
範本組態檔案名稱遵循此格式：
`Artifactname::TemplateConfigurationFileName`
`Artifactname` 是出現在 CodePipeline 中的輸入成品名稱。例如，來源階段的成品名稱為 `SourceArtifact` 且 `test-configuration.json` 檔案名稱建立 `TemplateConfiguration` 名稱，如此範例所顯示：
```
"TemplateConfiguration": "SourceArtifact::test-configuration.json"
```
## Input artifacts (輸入成品)
+ **成品數量：** `0 to 10`
+ **描述：**作為輸入， CloudFormation 動作可選擇性地接受用於這些目的的成品：
+ 提供要執行的堆疊範本檔案。(請參閱 `TemplatePath` 參數。)
+ 提供要使用的範本組態檔案。(請參閱 `TemplateConfiguration` 參數。) 如需範本組態檔案格式的詳細資訊，請參閱[AWS CloudFormation 成品](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/continuous-delivery-codepipeline-cfn-artifacts.html)。
+ 提供將 Lambda 函數部署為 CloudFormation 堆疊一部分的成品。
## 輸出成品
+ **成品數量：** `0 to 1`
+ **Description: (描述：)** 如果指定 `OutputFileName` 參數，則此動作會產生一個包含具有指定名稱的 JSON 檔案的輸出成品。JSON 檔案包含 CloudFormation 堆疊中 Outputs (輸出) 區段的內容。
如需您可為 CloudFormation 動作建立輸出區段的詳細資訊，請參閱 [Outputs (輸出)](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/outputs-section-structure.html)。
## 輸出變數
設定時，此動作會產生變數，供管道中的下游動作的動作組態所參考。您可以設定動作的命名空間，讓這些變數可供下游動作的組態使用。
對於 CloudFormation 動作，變數會從堆疊範本 `Outputs`區段中指定的任何值產生。請注意，產生輸出的唯一 CloudFormation 動作模式是造成堆疊建立或更新的模式，例如堆疊建立、堆疊更新和變更集執行。產生變數的相應動作模式如下：
+ `CHANGE_SET_EXECUTE`
+ `CHANGE_SET_REPLACE`
+ `CREATE_UPDATE`
+ `REPLACE_ON_FAILURE`
如需詳細資訊，請參閱[變數參考](reference-variables.md)。如需教學，向您展示如何在使用 CloudFormation 輸出變數的管道中，使用 CloudFormation 部署動作建立管道，請參閱 [教學課程：建立使用 AWS CloudFormation 部署動作變數的管道](tutorials-cloudformation-action.md)。
## 服務角色許可： CloudFormation 動作
CodePipeline 執行 動作時，CodePipeline 服務角色政策需要下列許可，適當範圍縮小至管道資源 ARN，以維持最低權限的存取。例如，將下列項目新增至您的政策陳述式：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowCFNStackAccess",
"Effect": "Allow",
"Action": [
"cloudformation:CreateStack",
"cloudformation:UpdateStack",
"cloudformation:DeleteStack",
"cloudformation:DescribeStacks",
"cloudformation:DescribeStackResources",
"cloudformation:DescribeStackEvents",
"cloudformation:GetTemplate",
"cloudformation:DescribeChangeSet",
"cloudformation:CreateChangeSet",
"cloudformation:DeleteChangeSet",
"cloudformation:ExecuteChangeSet"
],
"Resource": [
"arn:aws:cloudformation:*:111122223333:stack/[[cfnDeployStackNames]]/*"
]
},
{
"Sid": "ValidateTemplate",
"Effect": "Allow",
"Action": [
"cloudformation:ValidateTemplate"
],
"Resource": "*"
},
{
"Sid": "AllowIAMPassRole",
"Effect": "Allow",
"Action": [
"iam:PassRole"
],
"Resource": [
"arn:aws:iam::111122223333:role/[[cfnExecutionRoles]]"
],
"Condition": {
"StringEqualsIfExists": {
"iam:PassedToService": [
"cloudformation.amazonaws.com"
]
}
}
}
]
}
```
------
請注意， `cloudformation:DescribeStackEvents`許可是選用的。它允許 CloudFormation 動作顯示更詳細的錯誤訊息。如果您不希望資源詳細資訊出現在管道錯誤訊息中，可以從 IAM 角色撤銷此許可。
## 動作宣告
------
#### [ YAML ]
```
Name: ExecuteChangeSet
ActionTypeId:
Category: Deploy
Owner: AWS
Provider: CloudFormation
Version: '1'
RunOrder: 2
Configuration:
ActionMode: CHANGE_SET_EXECUTE
Capabilities: CAPABILITY_NAMED_IAM,CAPABILITY_AUTO_EXPAND
ChangeSetName: pipeline-changeset
ParameterOverrides: '{"ProjectId": "my-project","CodeDeployRole": "CodeDeploy_Role_ARN"}'
RoleArn: CloudFormation_Role_ARN
StackName: my-project--lambda
TemplateConfiguration: 'my-project--BuildArtifact::template-configuration.json'
TemplatePath: 'my-project--BuildArtifact::template-export.yml'
OutputArtifacts: []
InputArtifacts:
- Name: my-project-BuildArtifact
```
------
#### [ JSON ]
```
{
"Name": "ExecuteChangeSet",
"ActionTypeId": {
"Category": "Deploy",
"Owner": "AWS",
"Provider": "CloudFormation",
"Version": "1"
},
"RunOrder": 2,
"Configuration": {
"ActionMode": "CHANGE_SET_EXECUTE",
"Capabilities": "CAPABILITY_NAMED_IAM,CAPABILITY_AUTO_EXPAND",
"ChangeSetName": "pipeline-changeset",
"ParameterOverrides": "{\"ProjectId\": \"my-project\",\"CodeDeployRole\": \"CodeDeploy_Role_ARN\"}",
"RoleArn": "CloudFormation_Role_ARN",
"StackName": "my-project--lambda",
"TemplateConfiguration": "my-project--BuildArtifact::template-configuration.json",
"TemplatePath": "my-project--BuildArtifact::template-export.yml"
},
"OutputArtifacts": [],
"InputArtifacts": [
{
"Name": "my-project-BuildArtifact"
}
]
},
```
------
## 另請參閱
以下相關資源可協助您使用此動作。
+ [組態屬性參考](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/continuous-delivery-codepipeline-action-reference.html) – *AWS CloudFormation 使用者指南*中的此參考章節提供這些 CodePipeline 參數的更多說明和範例。
+ [AWS CloudFormation API 參考](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/) – *AWS CloudFormation API 參考*中的 [CreateStack](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_CreateStack.html) 參數說明 範本的 CloudFormation 堆疊參數。