# CloudFormation 配置属性参考
<a name="continuous-delivery-codepipeline-action-reference"></a>

当您构建 CodePipeline 管道时，可向此管道添加 `Deploy` 操作并将 CloudFormation 作为该操作的提供者。随后，您必须指定管道调用的 CloudFormation 操作以及该操作的设置。本主题介绍 CloudFormation 配置属性。要指定属性，您可以使用 CodePipeline 控制台，也可以创建 JSON 对象以用于 AWS CLI、CodePipeline API 或 CloudFormation 模板。

**Topics**
+ [配置属性 (控制台)](#continuous-delivery-codepipeline-action-reference-console)
+ [配置属性 (JSON 对象)](#continuous-delivery-codepipeline-action-reference-json)
+ [另请参阅](#continuous-delivery-codepipeline-action-reference-see-also)

## 配置属性 (控制台)
<a name="continuous-delivery-codepipeline-action-reference-console"></a>

CodePipeline [控制台](https://console.aws.amazon.com/codepipeline/)显示配置属性，并根据您选择的操作模式指示所需的属性。

**注意**  
当您创建管道时，可以仅指定 **Create or update a stack (创建或更新堆栈)** 或 **Create or replace a change set (创建或替换更改集)** 操作模式。**Advanced (高级)** 部分的属性仅在您编辑管道时可用。

**操作模式**  
在处理关联的阶段时 CodePipeline 调用的 CloudFormation 操作。选择下列操作模式之一：  
+ **Create or replace a change set** 根据您提交的堆栈名称和模板创建更改集 (如果更改集不存在)。如果更改集存在，CloudFormation 将删除它，然后创建一个新的更改集。
+ **Create or update a stack** 创建堆栈 (如果指定的堆栈不存在)。如果堆栈存在，CloudFormation 将更新堆栈。使用此操作更新现有堆栈。CodePipeline 不会取代堆栈。
+ **Delete a stack** 删除堆栈。如果您指定的堆栈不存在，操作将成功完成，而不会删除堆栈。
+ **Execute a change set** 执行更改集。
+ **Replace a failed stack** 创建堆栈 (如果指定的堆栈不存在)。如果堆栈存在且处于故障状态（报告为 `ROLLBACK_COMPLETE`、`ROLLBACK_FAILED`、`CREATE_FAILED`、`DELETE_FAILED`、`UPDATE_ROLLBACK_FAILED`），CloudFormation 将删除堆栈，然后创建新的堆栈。如果堆栈未处于故障状态，CloudFormation 将更新堆栈。使用此操作可替换出现故障的堆栈，而无需对其进行恢复或故障排除。您通常将选择此模式以进行测试。

**堆栈名称**  
与现有堆栈或您要创建的堆栈关联的名称。名称在您创建堆栈的 AWS 区域中必须是唯一的。  
堆栈名称只能包含字母数字字符（区分大小写）和连字符。该名称必须以字母字符开头，且不得超过 128 个字符。

**更改集名称**  
现有更改集的名称或要为指定堆栈创建的新更改集的名称。

**模板**  
CloudFormation 模板文件的位置，它采用 `{{ArtifactName}}::{{TemplateFileName}}` 格式。

**模板配置**  
模板配置文件的位置，它遵循格式 `{{ArtifactName}}::{{TemplateConfigurationFileName}}`。模板配置文件可以包含模板参数值、堆栈策略和标签。如果您将敏感信息 (例如密码) 包括在此文件中，请限制对此文件的访问。有关更多信息，请参阅 [CloudFormation 构件](continuous-delivery-codepipeline-cfn-artifacts.md)。

**功能**  
对于包含特定资源的堆栈，明确确认 CloudFormation 可能创建或更新这些资源。例如，如果堆栈模板包含 `CAPABILITY_IAM`（IAM）资源，您必须指定 AWS Identity and Access Management。有关更多信息，请参阅 [https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_CreateStack.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_CreateStack.html) API 操作请求参数。  
如果您的堆栈模板包含 IAM 资源，则必须指定此属性。  
您可以指定多个功能。

**角色名称**  
CloudFormation 在处理指定的堆栈中的资源时担任的 IAM 服务角色的名称。

**Output file name**  
在 **Advanced (高级)** 部分中，您可以指定在执行指定的操作后 CodePipeline 添加到[输出构件](https://docs.aws.amazon.com/codepipeline/latest/userguide/concepts.html#concepts-artifacts)的输出文件名称，如 `CreateStackOutput.json`。该输出构件包含一个 JSON 文件，该文件具有 CloudFormation 模板 `Outputs` 部分的内容。  
如果您不指定名称，则 CodePipeline 不会生成输出构件。

**Parameter overrides**  
参数在模板中定义，并允许您在创建或更新堆栈时输入自定义值。您可以指定覆盖模板配置文件中的模板参数值的 JSON 对象。所有参数名称必须位于堆栈模板中。有关更多信息，请参阅 [CloudFormation 模板 Parameters 语法](parameters-section-structure.md)。  
`ParameterOverrides` 属性中可存储的 JSON 对象的大小上限是 1 KB。
建议您使用模板配置文件来指定大多数参数值。仅使用参数覆盖来指定动态参数值。动态参数在您运行管道之前是未知的。  
以下示例通过使用参数覆盖函数来定义 `ParameterName` 参数的值。该函数从 CodePipeline 输入构件中检索值。有关参数覆盖函数的更多信息，请参阅[将参数覆盖函数用于 CodePipeline 管道](continuous-delivery-codepipeline-parameter-override-functions.md)。  

```
{
  "ParameterName" : { "Fn::GetParam" : ["ArtifactName", "config-file-name.json", "ParamName"]}
}
```

## 配置属性 (JSON 对象)
<a name="continuous-delivery-codepipeline-action-reference-json"></a>

当您指定 `CloudFormation` 作为阶段操作的提供者时，请在 `Configuration` 属性中定义以下属性。将 JSON 对象用于 AWS CLI、CodePipeline API 或 CloudFormation 模板。有关示例，请参阅 [演练：为测试和生产堆栈构建管道](continuous-delivery-codepipeline-basic-walkthrough.md) 和 [CloudFormation 配置属性参考](#continuous-delivery-codepipeline-action-reference)。

`ActionMode`  
在处理关联的阶段时 CodePipeline 调用的 CloudFormation 操作。仅指定下列操作模式之一：  
+ `CHANGE_SET_EXECUTE` 执行更改集。
+ `CHANGE_SET_REPLACE` 根据您提交的堆栈名称和模板创建更改集（如果更改集不存在）。如果更改集存在，CloudFormation 将删除它，然后创建一个新的更改集。
+ `CREATE_UPDATE` 创建堆栈 (如果指定的堆栈不存在)。如果堆栈存在，CloudFormation 将更新堆栈。使用此操作更新现有堆栈。CodePipeline 不会取代堆栈。
+ `DELETE_ONLY` 删除堆栈。如果您指定的堆栈不存在，操作将成功完成，而不会删除堆栈。
+ `REPLACE_ON_FAILURE` 创建堆栈（如果指定的堆栈不存在）。如果堆栈存在并处于失败状态（报告为 `ROLLBACK_COMPLETE`、`ROLLBACK_FAILED`、`CREATE_FAILED`、`DELETE_FAILED` 或 `UPDATE_ROLLBACK_FAILED`），CloudFormation 将删除堆栈，然后创建新的堆栈。如果堆栈未处于故障状态，CloudFormation 将更新堆栈。使用自操作可自动替换出现故障的堆栈，而无需对其进行恢复或故障排除。您通常将选择此模式以进行测试。
该属性是必需属性。

`Capabilities`  
对于包含特定资源的堆栈，明确确认 CloudFormation 可能创建或更新这些资源。例如，如果堆栈模板包含 `CAPABILITY_IAM`（IAM）资源，您必须指定 AWS Identity and Access Management。有关更多信息，请参阅 [https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_CreateStack.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_CreateStack.html) API 操作请求参数。  
该属性是条件属性。如果您的堆栈模板包含 IAM 资源，则必须指定此属性。  
您可以指定多个功能。以下示例将 `CAPABILITY_IAM` 和 `CAPABILITY_AUTO_EXPAND` 属性添加到模板中：  

```
configuration:
  ActionMode: CHANGE_SET_REPLACE
  {{Capabilities: CAPABILITY_IAM,CAPABILITY_AUTO_EXPAND}}
  ChangeSetName: pipeline-changeset
  RoleArn: CloudFormation_Role_ARN
  StackName: my-pipeline-stack
  TemplateConfiguration: 'my-pipeline-stack::template-configuration.json'
  TemplatePath: 'my-pipeline-stack::template-export.yml'
```

```
 "configuration": {
        "ActionMode": "CHANGE_SET_REPLACE",
        {{"Capabilities": "CAPABILITY_IAM,CAPABILITY_AUTO_EXPAND",}}
        "ChangeSetName": "pipeline-changeset",
        "RoleArn": "CloudFormation_Role_ARN",
        "StackName": "my-pipeline-stack",
        "TemplateConfiguration": "my-pipeline-stack::template-configuration.json",
        "TemplatePath": "my-pipeline-stack::template-export.yml"
    }
```

`ChangeSetName`  
现有更改集的名称或要为指定堆栈创建的新更改集的名称。  
以下操作模式需要该属性：`CHANGE_SET_REPLACE` 和 `CHANGE_SET_EXECUTE`。对于所有其他操作模式，将忽略此属性。

`OutputFileName`  
输出文件的名称，例如 `CreateStackOutput.json`。在执行指定的操作后，CodePipeline 将该文件添加到[输出构件](https://docs.aws.amazon.com/codepipeline/latest/userguide/concepts.html#concepts-artifacts)中。该输出构件包含一个 JSON 文件，该文件具有 CloudFormation 模板 `Outputs` 部分的内容。  
该属性是可选属性。如果您不指定名称，则 CodePipeline 不会生成输出构件。

`ParameterOverrides`  
参数在模板中定义，并允许您在创建或更新堆栈时输入自定义值。您可以指定覆盖模板配置文件中的模板参数值的 JSON 对象。所有参数名称必须位于堆栈模板中。有关更多信息，请参阅 [CloudFormation 模板 Parameters 语法](parameters-section-structure.md)。  
以下示例显示了如何将 `InstanceType` 和 `KeyName` 参数覆盖添加到模板：  

```
configuration:
  ActionMode: CHANGE_SET_REPLACE
  Capabilities: CAPABILITY_NAMED_IAM
  ChangeSetName: pipeline-changeset
  {{ParameterOverrides: '{"InstanceType": "t2.small","KeyName": "my-keypair"}'}}
  RoleArn: CloudFormation_Role_ARN
  StackName: my-pipeline-stack
  TemplateConfiguration: 'my-pipeline-stack::template-configuration.json'
  TemplatePath: 'my-pipeline-stack::template-export.yml'
```

```
"configuration": {
        "ActionMode": "CHANGE_SET_REPLACE",
        "Capabilities": "CAPABILITY_NAMED_IAM",
        "ChangeSetName": "pipeline-changeset",
        {{"ParameterOverrides": "{\"InstanceType\": \"t2.small\",\"KeyName\": \"my-keypair\"}",}}
        "RoleArn": "CloudFormation_Role_ARN",
        "StackName": "my-pipeline-stack",
        "TemplateConfiguration": "my-pipeline-stack::template-configuration.json",
        "TemplatePath": "my-pipeline-stack::template-export.yml"
    }
```
可以存储在 `ParameterOverrides` 属性中的 JSON 对象的最大大小为 1 KB。
建议您使用模板配置文件来指定大多数参数值。仅使用参数覆盖来指定动态参数值。动态参数值在您运行管道之前是未知的。  
以下示例通过使用参数覆盖函数来定义 `ParameterName` 参数的值。该函数从 CodePipeline 输入构件中检索值。有关参数覆盖函数的更多信息，请参阅[将参数覆盖函数用于 CodePipeline 管道](continuous-delivery-codepipeline-parameter-override-functions.md)。  

```
{
  "ParameterName" : { "Fn::GetParam" : ["ArtifactName", "config-file-name.json", "ParamName"]}
}
```
该属性是可选属性。

`RoleArn`  
在操作堆栈中的资源时 CloudFormation 担任的 IAM 服务角色的 Amazon 资源名称（ARN）。  
以下操作模式需要此属性：`CREATE_UPDATE`、`REPLACE_ON_FAILURE`、`DELETE_ONLY` 和 `CHANGE_SET_REPLACE`。执行更改集时不应用 `RoleArn`。如果您不使用 CodePipeline 来创建更改集，请确保更改集或堆栈具有关联的角色。

`StackName`  
现有堆栈的名称或要创建的堆栈的名称。  
所有操作模式都需要该属性。

`TemplateConfiguration`  
`TemplateConfiguration` 是模板配置文件。您需在针对此操作的输入构件中包含该文件。模板配置文件名遵循以下格式：  
`{{Artifactname}}::{{TemplateConfigurationFileName}}`  
`Artifactname` 是输入构件在 CodePipeline 中显示的名称。例如，源阶段利用构件名称 `SourceArtifact` 和文件名 `test-configuration.json` 创建 `TemplateConfiguration` 名称，如以下示例所示：  

```
"TemplateConfiguration": "SourceArtifact::test-configuration.json"
```
模板配置文件可包含模板参数值和堆栈策略。如果您将敏感信息 (例如密码) 包括在此文件中，请限制对此文件的访问。有关示例模板配置文件，请参阅 [CloudFormation 构件](continuous-delivery-codepipeline-cfn-artifacts.md)。  
该属性是可选属性。

`TemplatePath`  
`TemplatePath` 表示 CloudFormation 模板文件。您需在针对此操作的输入构件中包含该文件。文件名称遵循以下格式：  
`{{Artifactname}}::{{TemplateFileName}}`  
`Artifactname` 是输入构件在 CodePipeline 中显示的名称。例如，源阶段利用构件名称 `SourceArtifact` 和文件名 `template.yaml` 创建 `TemplatePath` 名称，如以下示例所示：  

```
"TemplatePath": "SourceArtifact::template.yaml"
```
以下操作模式需要此属性：`CREATE_UPDATE`、`REPLACE_ON_FAILURE` 和 `CHANGE_SET_REPLACE`。对于所有其他操作模式，将忽略此属性。

## 另请参阅
<a name="continuous-delivery-codepipeline-action-reference-see-also"></a>

下列相关资源可帮助您处理这些参数。
+ 有关 CodePipeline 中 CloudFormation 操作参数的更多信息， 请参阅*《AWS CodePipeline 用户指南》*中的 [CloudFormation 部署操作配置引用](https://docs.aws.amazon.com/codepipeline/latest/userguide/action-reference-CloudFormation.html)。
+ 有关操作提供方的示例模板值，例如 `Owner` 字段或 `configuration` 字段的值，请参阅*《AWS CodePipeline 用户指南》*中的[操作结构参考](https://docs.aws.amazon.com/codepipeline/latest/userguide/action-reference.html)。
+ 要下载 YAML 或 JSON 格式的示例管道堆栈模板，请参阅*《AWS CodePipeline 用户指南》*中[教程：使用 CloudFormation 创建管道](https://docs.aws.amazon.com/codepipeline/latest/userguide/tutorials-cloudformation.html)。