Amazon CloudFormation 部署操作参考 - Amazon CodePipeline
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

Amazon CloudFormation 部署操作参考

在 Amazon CloudFormation 堆栈上执行操作。堆栈是可作为单个单元管理的一系列 Amazon 资源。堆栈中的资源均由堆栈的 Amazon CloudFormation 模板定义。更改集会创建比较,您可以查看比较而不会更改原始堆栈。有关可在堆栈和更改集上执行的 Amazon CloudFormation 操作类型的信息,请参阅 ActionMode 参数。

注意:Amazon CloudFormation 的 CodePipeline 操作在中国(北京)和中国(宁夏)区域不可用。要参考其他可用操作,请参阅 产品和服务与 CodePipeline

要为堆栈操作失败的 Amazon CloudFormation 操作构造错误消息,CodePipeline 会调用 Amazon CloudFormation DescribeStackEvents API。如果操作 IAM 角色有权访问该 API,则有关第一个失败资源的详细信息将包含在 CodePipeline 错误消息中。否则,如果角色策略没有相应的权限,CodePipeline 将忽略对 API 的访问,而是显示一条通用的错误消息。为此,必须将 cloudformation:DescribeStackEvents 权限添加到管道的服务角色或其他 IAM 角色中。

如果您不希望资源详细信息出现在管道错误消息中,可以通过删除 cloudformation:DescribeStackEvents 权限为操作 IAM 角色撤销此权限。

操作类型

  • 类别:Deploy

  • 拥有者:AWS

  • 提供方:CloudFormation

  • 版本:1

配置参数

ActionMode

必需:是

ActionMode 是 Amazon CloudFormation 在堆栈或更改集上执行的操作的名称。提供以下操作模式:

  • CHANGE_SET_EXECUTE 会基于一组指定资源更新执行资源堆栈的更改集。执行此操作时,Amazon CloudFormation 会开始更改堆栈。

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

  • CREATE_UPDATE 会在堆栈不存在时创建堆栈。如果堆栈存在,Amazon CloudFormation 将更新堆栈。使用此操作更新现有堆栈。与 REPLACE_ON_FAILURE 不同,如果堆栈存在且处于故障状态,CodePipeline 不会删除并替换堆栈。

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

  • REPLACE_ON_FAILURE 会在堆栈不存在时创建堆栈。如果堆栈存在且处于故障状态,Amazon CloudFormation 将删除堆栈,然后创建新的堆栈。如果堆栈未处于故障状态,Amazon CloudFormation 将更新堆栈。

    Amazon CloudFormation 中显示以下任意状态类型时,堆栈处于故障状态:

    • ROLLBACK_FAILED

    • CREATE_FAILED

    • DELETE_FAILED

    • UPDATE_ROLLBACK_FAILED

    使用自操作可自动替换出现故障的堆栈,而无需对其进行恢复或故障排除。

    重要

    我们建议您仅将 REPLACE_ON_FAILURE 用于测试目的,因为它可能会删除您的堆栈。

StackName

必需:是

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

功能

必需:条件

使用 Capabilities 即确认此模板可能具备创建和更新一些资源的功能,并且这些功能由模板资源的类型决定。

如果您的堆栈模板中有 IAM 资源或者您直接从包含宏的模板创建堆栈,则此属性是必需的。要想让 Amazon CloudFormation 操作以这种方式成功执行,您必须通过下列功能之一明确确认希望它这样做:

  • CAPABILITY_IAM

  • CAPABILITY_NAMED_IAM

  • CAPABILITY_AUTO_EXPAND

您可以通过在功能之间添加逗号(无空格)的方式指定多个功能。操作声明中的示例显示了同时具有 CAPABILITY_IAM 和 CAPABILITY_AUTO_EXPAND 属性的条目。

有关 Capabilities 的更多信息,请参阅 Amazon CloudFormation API 参考UpdateStack 下的属性。

ChangeSetName

必需:条件

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

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

RoleArn

必需:条件

RoleArn 是 Amazon CloudFormation 在对指定堆栈中的资源执行操作时代入的 IAM 服务角色的 ARN。在执行更改集时,RoleArn 不适用。如果您不使用 CodePipeline 来创建更改集,请确保更改集或堆栈具有关联的角色。

注意

按照操作声明 RoleArn 中的配置,此角色必须与正在运行的操作的角色位于同一个账户。

以下操作模式需要此属性:

  • CREATE_UPDATE

  • REPLACE_ON_FAILURE

  • DELETE_ONLY

  • CHANGE_SET_REPLACE

注意

Amazon CloudFormation 将获得模板的 S3 签名 URL;因此,此 RoleArn 不需要用于访问构件桶的权限。但是,为了生成签名 URL,操作 RoleArn 确实 需要用于访问构件桶的权限。

TemplatePath

必需:条件

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

Artifactname::TemplateFileName

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

"TemplatePath": "SourceArtifact::template-export.json"

以下操作模式需要此属性:

  • CREATE_UPDATE

  • REPLACE_ON_FAILURE

  • CHANGE_SET_REPLACE

对于所有其他操作模式,将忽略此属性。

注意

包含模板正文的 Amazon CloudFormation 模板文件的最小长度为 1 字节,最大长度为 1 MB。对于 CodePipeline 中的 Amazon CloudFormation 部署操作,最大输入构件大小始终为 256 MB。有关更多信息,请参阅 中的配额 Amazon CodePipelineAmazon CloudFormation 限制

OutputFileName

必需:否

使用 OutputFileName 指定输出文件名(例如 CreateStackOutput.json),CodePipeline 会将该文件添加到此操作的管道输出构件中。JSON 文件包含来自 Amazon CloudFormation 堆栈的 Outputs 部分中的内容。

如果不指定名称,则 CodePipeline 不会生成输出文件或构件。

ParameterOverrides

必需:否

参数在堆栈模板中定义,并允许您在堆栈创建或更新时为这些参数提供值。您可以使用 JSON 对象设置模板中的参数值。(这些值会覆盖在模板配置文件中设置的值。) 有关使用参数覆盖的更多信息,请参阅配置属性(JSON 对象)

对于大多数参数值,建议您使用模板配置文件。仅对在管道运行前未知的值使用参数覆盖。有关更多信息,请参阅 Amazon CloudFormation 用户指南 中的将参数覆盖函数与 CodePipeline 管道一起使用

注意

所有参数名称必须位于堆栈模板中。

TemplateConfiguration

必需:否

TemplateConfiguration 是模板配置文件。您需在针对此操作的输入构件中包含该文件。它可包含模板参数值和堆栈策略。有关模板配置文件格式的更多信息,请参阅 Amazon CloudFormation 构件

模板配置文件名遵循以下格式:

Artifactname::TemplateConfigurationFileName

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

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

输入构件

  • 构件数:0 to 10

  • 描述:作为输入,Amazon CloudFormation 操作可以选择接受构件用于下列用途:

    • 提供要执行的堆栈模板文件。(请参阅 TemplatePath 参数。)

    • 提供要使用的模板配置文件。(请参阅 TemplateConfiguration 参数。) 有关模板配置文件格式的更多信息,请参阅 Amazon CloudFormation 构件

    • 为要作为 Amazon CloudFormation 堆栈一部分进行部署的 Lambda 函数提供构件。

输出构件

  • 构件数:0 to 1

  • 描述:如果指定了 OutputFileName 参数,则此操作生成输出构件,其中包含具有指定名称的 JSON 文件。JSON 文件包含来自 Amazon CloudFormation 堆栈的输出部分中的内容。

    有关您可为 Amazon CloudFormation 操作创建的输出部分的更多信息,请参阅输出

输出变量

配置后,此操作会生成变量,该变量可由管道中下游操作的操作配置引用。您可以使用命名空间配置操作,以使这些变量可用于下游操作的配置。

对于 Amazon CloudFormation 操作,变量是根据在堆栈模板的 Outputs 部分中指定的任何值生成的。请注意,生成输出的仅有的 CloudFormation 操作模式是那些导致创建或更新堆栈的操作模式,例如堆栈创建、堆栈更新和更改集执行。生成变量的相应操作模式包括:

  • CHANGE_SET_EXECUTE

  • CHANGE_SET_REPLACE

  • CREATE_UPDATE

  • REPLACE_ON_FAILURE

有关更多信息,请参阅 变量参考。有关向您展示如何在使用 CloudFormation 输出变量的管道中使用 CloudFormation 部署操作创建管道的教程,请参阅教程:创建使用 Amazon CloudFormation 部署操作中的变量的管道

操作声明

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" } ] },

下列相关资源在您使用此操作的过程中会有所帮助。