AWS CloudFormation 配置属性参考 - AWS CloudFormation

AWS CloudFormation 配置属性参考

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

配置属性 (控制台)

CodePipeline 控制台显示配置属性,并根据您选择的操作模式指示所需的属性。

注意

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

操作模式

在处理关联的阶段时 CodePipeline 调用的 AWS CloudFormation 操作。选择下列操作模式之一:

  • Create or replace a change set 根据您提交的堆栈名称和模板创建更改集 (如果更改集不存在)。如果更改集存在,AWS CloudFormation 将删除它,然后创建一个新的更改集。

  • Create or update a stack 创建堆栈 (如果指定的堆栈不存在)。如果堆栈存在,AWS CloudFormation 将更新堆栈。可以使用该操作更新现有的堆栈。CodePipeline 不会替换堆栈。

  • Delete a stack 删除堆栈。如果您指定的堆栈不存在,操作将成功完成,而不会删除堆栈。

  • Execute a change set 执行更改集。

  • Replace a failed stack 创建堆栈 (如果指定的堆栈不存在)。如果堆栈存在且处于故障状态(报告为 ROLLBACK_COMPLETEROLLBACK_FAILEDCREATE_FAILEDDELETE_FAILEDUPDATE_ROLLBACK_FAILED),AWS CloudFormation 将删除堆栈,然后创建新的堆栈。如果堆栈未处于故障状态,AWS CloudFormation 将更新堆栈。使用此操作可替换出现故障的堆栈,而无需对其进行恢复或故障排除。您通常将选择此模式以进行测试。

堆栈名称

与现有堆栈或您要创建的堆栈关联的名称。该名称在您创建堆栈的 AWS 区域中必须是唯一的。

注意

堆栈名称只能包含字母数字字符(区分大小写)和连字符。该名称必须以字母字符开头,且不得超过 128 个字符。

更改集名称

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

模板

AWS CloudFormation 模板文件的位置,它采用 ArtifactName::TemplateFileName 格式。

模板配置

模板配置文件的位置,它遵循格式 ArtifactName::TemplateConfigurationFileName。模板配置文件可以包含模板参数值、堆栈策略和标签。如果您将敏感信息 (例如密码) 包括在此文件中,请限制对此文件的访问。有关更多信息,请参阅 AWS CloudFormation 构件

功能

对于包含特定资源的堆栈,明确确认 AWS CloudFormation 可能创建或更新这些资源。例如,如果堆栈模板包含 AWS Identity and Access Management (IAM) 资源,您必须指定 CAPABILITY_IAM。有关更多信息,请参阅 CreateStack 请求参数

如果您的堆栈模板包含 IAM 资源,则必须指定此属性。

您可以指定多个功能。

角色名称

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

Output file name

Advanced (高级) 部分中,您可以指定在执行指定的操作后 CodePipeline 添加到输出构件的输出文件名称,如 CreateStackOutput.json。该输出构件包含一个 JSON 文件,该文件具有 AWS CloudFormation 模板 Outputs 部分的内容。

如果您不指定名称,则 CodePipeline 不会生成输出项目。

Parameter overrides

参数在模板中定义,并允许您在创建或更新堆栈时输入自定义值。您可以指定覆盖模板配置文件中的模板参数值的 JSON 对象。所有参数名称必须位于堆栈模板中。有关更多信息,请参阅在模板中定义参数

注意

ParameterOverrides 属性中可存储的 JSON 对象的大小上限是 1 KB。

建议您使用模板配置文件来指定大多数参数值。仅使用参数覆盖来指定动态参数值。动态参数在您运行管道之前是未知的。

以下示例通过使用参数覆盖函数来定义 ParameterName 参数的值。该函数从 CodePipeline 输入构件中检索值。有关参数覆盖函数的更多信息,请参阅将参数覆盖函数用于 CodePipeline 管道

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

配置属性 (JSON 对象)

当您指定 CloudFormation 作为阶段操作的提供者时,请在 Configuration 属性中定义以下属性。将 JSON 对象用于 AWS CLI、CodePipeline API 或 AWS CloudFormation 模板。有关示例,请参阅 演练:为测试和生产堆栈构建管道AWS CloudFormation 配置属性参考

ActionMode

在处理关联的阶段时,CodePipeline 调用的 AWS CloudFormation 操作。仅指定下列操作模式之一:

  • CHANGE_SET_EXECUTE 执行更改集。

  • CHANGE_SET_REPLACE 根据您提交的堆栈名称和模板创建更改集(如果更改集不存在)。如果更改集存在,AWS CloudFormation 将删除它,然后创建一个新的更改集。

  • CREATE_UPDATE 创建堆栈 (如果指定的堆栈不存在)。如果堆栈存在,AWS CloudFormation 将更新堆栈。可以使用该操作更新现有的堆栈。CodePipeline 不会替换堆栈。

  • DELETE_ONLY 删除堆栈。如果您指定的堆栈不存在,操作将成功完成,而不会删除堆栈。

  • REPLACE_ON_FAILURE 创建堆栈(如果指定的堆栈不存在)。如果堆栈存在并处于失败状态(报告为 ROLLBACK_COMPLETEROLLBACK_FAILEDCREATE_FAILEDDELETE_FAILEDUPDATE_ROLLBACK_FAILED),AWS CloudFormation 将删除堆栈,然后创建新的堆栈。如果堆栈未处于故障状态,AWS CloudFormation 将更新堆栈。使用自操作可自动替换出现故障的堆栈,而无需对其进行恢复或故障排除。您通常将选择此模式以进行测试。

该属性是必需属性。

Capabilities

对于包含特定资源的堆栈,明确确认 AWS CloudFormation 可能创建或更新这些资源。例如,如果堆栈模板包含 AWS Identity and Access Management (IAM) 资源,您必须指定 CAPABILITY_IAM。有关更多信息,请参阅 CreateStack 请求参数

该属性是条件属性。如果您的堆栈模板包含 IAM 资源,则必须指定此属性。

您可以指定多个功能。下面的示例将 CAPABILITY_IAM 和 CAPABILITY_AUTO_EXPAND 属性添加到模板:

YAML
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'
JSON
"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_REPLACECHANGE_SET_EXECUTE。对于所有其他操作模式,将忽略该属性。

OutputFileName

输出文件的名称,如 CreateStackOutput.json。在执行指定的操作后,CodePipeline 将该文件添加到输出构件中。该输出构件包含一个 JSON 文件,该文件具有 AWS CloudFormation 模板 Outputs 部分的内容。

此属性是可选属性。如果您不指定名称,则 CodePipeline 不会生成输出构件。

ParameterOverrides

参数在模板中定义,并允许您在创建或更新堆栈时输入自定义值。您可以指定覆盖模板配置文件中的模板参数值的 JSON 对象。所有参数名称必须位于堆栈模板中。有关更多信息,请参阅在模板中定义参数

以下示例显示了如何将 InstanceTypeKeyName 参数覆盖添加到模板:

YAML
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'
JSON
"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 管道

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

该属性是可选属性。

RoleArn

在处理堆栈中的资源时 AWS CloudFormation 担任的 IAM 服务角色的 Amazon 资源名称 (ARN)。

以下操作模式需要此属性:CREATE_UPDATEREPLACE_ON_FAILUREDELETE_ONLYCHANGE_SET_REPLACE。执行更改集时不应用 RoleArn。如果您不使用 CodePipeline 来创建更改集,请确保更改集或堆栈具有关联的角色。

StackName

现有堆栈的名称或要创建的堆栈的名称。

所有操作模式都需要该属性。

TemplateConfiguration

TemplateConfiguration 是模板配置文件。您需在针对此操作的输入构件中包含该文件。模板配置文件名遵循此格式:

Artifactname::TemplateConfigurationFileName

Artifactname 是输入构件在 CodePipeline 中显示的名称。例如,源阶段利用构件名称 SourceArtifact 和文件名 test-configuration.json 创建 TemplateConfiguration 名称,如以下示例所示:

"TemplateConfiguration": "SourceArtifact::test-configuration.json"

模板配置文件可包含模板参数值和堆栈策略。如果您将敏感信息 (例如密码) 包括在此文件中,请限制对此文件的访问。有关示例模板配置文件,请参阅 AWS CloudFormation 构件

此属性是可选属性。

TemplatePath

TemplatePath 表示 AWS CloudFormation 模板文件。您需在针对此操作的输入构件中包含该文件。文件名称遵循以下格式:

Artifactname::TemplateFileName

Artifactname 是输入构件在 CodePipeline 中显示的名称。例如,源阶段利用构件名称 SourceArtifact 和文件名 template.yaml 创建 TemplatePath 名称,如以下示例所示:

"TemplatePath": "SourceArtifact::template.yaml"

以下操作模式需要此属性:CREATE_UPDATEREPLACE_ON_FAILURECHANGE_SET_REPLACE。对于所有其他操作模式,将忽略此属性。

另请参阅

下列相关资源可帮助您处理这些参数。

  • 有关 CodePipeline 中 AWS CloudFormation 操作参数的更多信息,请参阅 AWS CodePipeline 用户指南 中的 AWS CloudFormation 操作配置引用。

  • 有关操作提供方的模板值示例,例如 Owner 字段或 configuration 字段的值,请参阅 AWS CodePipeline 用户指南 中的操作结构引用

  • 要下载 YAML 或 JSON 格式的示例管道堆栈模板,请参阅 AWS CodePipeline 用户指南使用 AWS CloudFormation 创建管道下的教程。

  • 有关示例模板配置文件,请参阅 AWS CloudFormation 构件