Amazon CloudFormation 配置属性参考
当您构建 CodePipeline 管道时,可向此管道添加 Deploy
操作并将 Amazon CloudFormation 作为该操作的提供者。随后,您必须指定管道调用的 Amazon CloudFormation 操作以及该操作的设置。本主题介绍 Amazon CloudFormation 配置属性。要指定属性,您可以使用 CodePipeline 控制台,也可以创建 JSON 对象以用于 Amazon CLI、CodePipeline API 或 Amazon CloudFormation 模板。
配置属性 (控制台)
CodePipeline 控制台
注意
当您创建管道时,可以仅指定 Create or update a stack (创建或更新堆栈) 或 Create or replace a change set (创建或替换更改集) 操作模式。Advanced (高级) 部分的属性仅在您编辑管道时可用。
- 操作模式
-
在处理关联的阶段时 CodePipeline 调用的 Amazon CloudFormation 操作。选择下列操作模式之一:
-
Create or replace a change set 根据您提交的堆栈名称和模板创建更改集 (如果更改集不存在)。如果更改集存在,Amazon CloudFormation 将删除它,然后创建一个新的更改集。
-
Create or update a stack 创建堆栈 (如果指定的堆栈不存在)。如果堆栈存在,Amazon CloudFormation 将更新堆栈。使用此操作更新现有堆栈。CodePipeline 不会取代堆栈。
-
Delete a stack 删除堆栈。如果您指定的堆栈不存在,操作将成功完成,而不会删除堆栈。
-
Execute a change set 执行更改集。
-
Replace a failed stack 创建堆栈 (如果指定的堆栈不存在)。如果堆栈存在且处于故障状态(报告为
ROLLBACK_COMPLETE
、ROLLBACK_FAILED
、CREATE_FAILED
、DELETE_FAILED
、UPDATE_ROLLBACK_FAILED
),Amazon CloudFormation 将删除堆栈,然后创建新的堆栈。如果堆栈未处于故障状态,Amazon CloudFormation 将更新堆栈。使用此操作可替换出现故障的堆栈,而无需对其进行恢复或故障排除。您通常将选择此模式以进行测试。
-
- 堆栈名称
-
与现有堆栈或您要创建的堆栈关联的名称。名称在您创建堆栈的 Amazon 区域中必须是唯一的。
注意
堆栈名称只能包含字母数字字符(区分大小写)和连字符。该名称必须以字母字符开头,且不得超过 128 个字符。
- 更改集名称
-
现有更改集的名称或要为指定堆栈创建的新更改集的名称。
- 模板
-
Amazon CloudFormation 模板文件的位置,它采用
格式。ArtifactName
::TemplateFileName
- 模板配置
-
模板配置文件的位置,它遵循格式
。模板配置文件可以包含模板参数值、堆栈策略和标签。如果您将敏感信息 (例如密码) 包括在此文件中,请限制对此文件的访问。有关更多信息,请参阅 Amazon CloudFormation 构件。ArtifactName
::TemplateConfigurationFileName
- 功能
-
对于包含特定资源的堆栈,明确确认 Amazon CloudFormation 可能创建或更新这些资源。例如,如果堆栈模板包含
CAPABILITY_IAM
(IAM)资源,您必须指定 Amazon Identity and Access Management。有关更多信息,请参阅 CreateStack API 操作请求参数。如果您的堆栈模板包含 IAM 资源,则必须指定此属性。
您可以指定多个功能。
- 角色名称
-
Amazon CloudFormation 在处理指定的堆栈中的资源时担任的 IAM 服务角色的名称。
- Output file name
-
在 Advanced (高级) 部分中,您可以指定在执行指定的操作后 CodePipeline 添加到输出构件的输出文件名称,如
CreateStackOutput.json
。该输出构件包含一个 JSON 文件,该文件具有 Amazon CloudFormation 模板Outputs
部分的内容。如果您不指定名称,则 CodePipeline 不会生成输出构件。
- Parameter overrides
-
参数在模板中定义,并允许您在创建或更新堆栈时输入自定义值。您可以指定覆盖模板配置文件中的模板参数值的 JSON 对象。所有参数名称必须位于堆栈模板中。有关更多信息,请参阅 CloudFormation 模板 Parameters 语法。
注意
ParameterOverrides
属性中可存储的 JSON 对象的大小上限是 1 KB。建议您使用模板配置文件来指定大多数参数值。仅使用参数覆盖来指定动态参数值。动态参数在您运行管道之前是未知的。
以下示例通过使用参数覆盖函数来定义
ParameterName
参数的值。该函数从 CodePipeline 输入构件中检索值。有关参数覆盖函数的更多信息,请参阅将参数覆盖函数用于 CodePipeline 管道。{ "ParameterName" : { "Fn::GetParam" : ["ArtifactName", "config-file-name.json", "ParamName"]} }
配置属性 (JSON 对象)
当您指定 CloudFormation
作为阶段操作的提供者时,请在 Configuration
属性中定义以下属性。将 JSON 对象用于 Amazon CLI、CodePipeline API 或 Amazon CloudFormation 模板。有关示例,请参阅 演练:为测试和生产堆栈构建管道 和 Amazon CloudFormation 配置属性参考。
ActionMode
-
在处理关联的阶段时 CodePipeline 调用的 Amazon CloudFormation 操作。仅指定下列操作模式之一:
-
CHANGE_SET_EXECUTE
执行更改集。 -
CHANGE_SET_REPLACE
根据您提交的堆栈名称和模板创建更改集(如果更改集不存在)。如果更改集存在,Amazon CloudFormation 将删除它,然后创建一个新的更改集。 -
CREATE_UPDATE
创建堆栈 (如果指定的堆栈不存在)。如果堆栈存在,Amazon CloudFormation 将更新堆栈。使用此操作更新现有堆栈。CodePipeline 不会取代堆栈。 -
DELETE_ONLY
删除堆栈。如果您指定的堆栈不存在,操作将成功完成,而不会删除堆栈。 -
REPLACE_ON_FAILURE
创建堆栈(如果指定的堆栈不存在)。如果堆栈存在并处于失败状态(报告为ROLLBACK_COMPLETE
、ROLLBACK_FAILED
、CREATE_FAILED
、DELETE_FAILED
或UPDATE_ROLLBACK_FAILED
),Amazon CloudFormation 将删除堆栈,然后创建新的堆栈。如果堆栈未处于故障状态,Amazon CloudFormation 将更新堆栈。使用自操作可自动替换出现故障的堆栈,而无需对其进行恢复或故障排除。您通常将选择此模式以进行测试。
该属性是必需属性。
-
Capabilities
-
对于包含特定资源的堆栈,明确确认 Amazon CloudFormation 可能创建或更新这些资源。例如,如果堆栈模板包含
CAPABILITY_IAM
(IAM)资源,您必须指定 Amazon Identity and Access Management。有关更多信息,请参阅 CreateStack API 操作请求参数。该属性是条件属性。如果您的堆栈模板包含 IAM 资源,则必须指定此属性。
您可以指定多个功能。以下示例将
CAPABILITY_IAM
和CAPABILITY_AUTO_EXPAND
属性添加到模板中: ChangeSetName
-
现有更改集的名称或要为指定堆栈创建的新更改集的名称。
以下操作模式需要该属性:
CHANGE_SET_REPLACE
和CHANGE_SET_EXECUTE
。对于所有其他操作模式,将忽略此属性。 OutputFileName
-
输出文件的名称,例如
CreateStackOutput.json
。在执行指定的操作后,CodePipeline 将该文件添加到输出构件中。该输出构件包含一个 JSON 文件,该文件具有 Amazon CloudFormation 模板Outputs
部分的内容。该属性是可选属性。如果您不指定名称,则 CodePipeline 不会生成输出构件。
ParameterOverrides
-
参数在模板中定义,并允许您在创建或更新堆栈时输入自定义值。您可以指定覆盖模板配置文件中的模板参数值的 JSON 对象。所有参数名称必须位于堆栈模板中。有关更多信息,请参阅 CloudFormation 模板 Parameters 语法。
以下示例显示了如何将
InstanceType
和KeyName
参数覆盖添加到模板:注意
可以存储在
ParameterOverrides
属性中的 JSON 对象的最大大小为 1 KB。建议您使用模板配置文件来指定大多数参数值。仅使用参数覆盖来指定动态参数值。动态参数值在您运行管道之前是未知的。
以下示例通过使用参数覆盖函数来定义
ParameterName
参数的值。该函数从 CodePipeline 输入构件中检索值。有关参数覆盖函数的更多信息,请参阅将参数覆盖函数用于 CodePipeline 管道。{ "ParameterName" : { "Fn::GetParam" : ["ArtifactName", "config-file-name.json", "ParamName"]} }
该属性是可选属性。
RoleArn
-
在操作堆栈中的资源时 Amazon 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"
模板配置文件可包含模板参数值和堆栈策略。如果您将敏感信息 (例如密码) 包括在此文件中,请限制对此文件的访问。有关示例模板配置文件,请参阅 Amazon CloudFormation 构件。
该属性是可选属性。
TemplatePath
-
TemplatePath
表示 Amazon CloudFormation 模板文件。您需在针对此操作的输入构件中包含该文件。文件名称遵循以下格式:Artifactname
::TemplateFileName
Artifactname
是输入构件在 CodePipeline 中显示的名称。例如,源阶段利用构件名称SourceArtifact
和文件名template.yaml
创建TemplatePath
名称,如以下示例所示:"TemplatePath": "SourceArtifact::template.yaml"
以下操作模式需要此属性:
CREATE_UPDATE
、REPLACE_ON_FAILURE
和CHANGE_SET_REPLACE
。对于所有其他操作模式,将忽略此属性。
另请参阅
下列相关资源可帮助您处理这些参数。
-
有关 CodePipeline 中 CloudFormation 操作参数的更多信息, 请参阅《Amazon CodePipeline 用户指南》中的 Amazon CloudFormation 部署操作配置引用。
-
有关操作提供方的示例模板值,例如
Owner
字段或configuration
字段的值,请参阅《Amazon CodePipeline 用户指南》中的操作结构参考。 -
要下载 YAML 或 JSON 格式的示例管道堆栈模板,请参阅《Amazon CodePipeline 用户指南》中教程:使用 Amazon CloudFormation 创建管道。