本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# CloudFormation 部署操作参考
在 CloudFormation 堆栈上执行操作。堆栈是您可以作为一个单元管理的 AWS 资源集合。堆栈中的资源均由堆栈的 CloudFormation 模板定义。更改集会创建比较，您可以查看比较而不会更改原始堆栈。有关可以对堆栈和更改集执行的 CloudFormation 操作类型的信息，请参阅`ActionMode`参数。
要为堆栈操作失败的 CloudFormation 操作构造错误消息， CodePipeline 请调用 CloudFormation `DescribeStackEvents` API。如果操作 IAM 角色有权访问该 API，则有关第一个失败资源的详细信息将包含在 CodePipeline 错误消息中。否则，如果角色策略没有相应的权限，则 CodePipeline 会忽略访问该 API，而是显示一条通用的错误消息。为此，必须将 `cloudformation:DescribeStackEvents` 权限添加到管道的服务角色或其他 IAM 角色中。
如果您不希望资源详细信息出现在管道错误消息中，可以通过删除 `cloudformation:DescribeStackEvents` 权限为操作 IAM 角色撤销此权限。
**Topics**
+ [操作类型](#action-reference-CloudFormation-type)
+ [配置参数](#action-reference-CloudFormation-config)
+ [输入构件](#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 签名 URL；因此，这`RoleArn`不需要访问工件存储桶的权限。但是，为了生成签名 URL，操作 `RoleArn` *确实* 需要用于访问构件桶的权限。
**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。对于中的 CloudFormation 部署操作 CodePipeline，最大输入项目大小始终为 256 MB。有关更多信息，请参阅 [AWS CodePipeline 中的限额](limits.md)和 [CloudFormation 限制](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cloudformation-limits.html)。
**OutputFileName**
必需：否
`OutputFileName`用于指定输出文件名，例如`CreateStackOutput.json`，该文件名 CodePipeline 将添加到该操作的管道输出对象中。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"
```
## 输入构件
+ **构件数：**`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`
+ **描述：**如果指定了 `OutputFileName` 参数，则此操作生成输出构件，其中包含具有指定名称的 JSON 文件。JSON 文件包含来自 CloudFormation 堆栈的输出部分中的内容。
有关您可为 CloudFormation 操作创建的输出部分的更多信息，请参阅[输出](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 模板的堆栈参数。