AWS CloudFormation 部署操作参考 - AWS CodePipeline
操作类型配置参数 输入构件输出构件输出变量操作声明另请参阅

AWS CloudFormation 部署操作参考

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

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

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

操作类型

  • 类别：Deploy

  • 拥有者：AWS

  • 提供方：CloudFormation

  • 版本：1

配置参数

ActionMode

必需：是

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

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

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

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

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

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

    AWS CloudFormation 中显示以下任意状态类型时，堆栈处于故障状态：

    • ROLLBACK_FAILED

    • CREATE_FAILED

    • DELETE_FAILED

    • UPDATE_ROLLBACK_FAILED

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

    重要

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

StackName

必需：是

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

功能

必需：条件

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

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

  • CAPABILITY_IAM

  • CAPABILITY_NAMED_IAM

  • CAPABILITY_AUTO_EXPAND

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

有关 Capabilities 的更多信息，请参阅 AWS CloudFormation API 参考 中 UpdateStack 下的属性。

ChangeSetName

必需：条件

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

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

RoleArn

必需：条件

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

注意

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

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

  • CREATE_UPDATE

  • REPLACE_ON_FAILURE

  • DELETE_ONLY

  • CHANGE_SET_REPLACE

注意

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

TemplatePath

必需：条件

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

Artifactname::TemplateFileName

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

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

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

  • CREATE_UPDATE

  • REPLACE_ON_FAILURE

  • CHANGE_SET_REPLACE

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

注意

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

OutputFileName

必需：否

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

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

ParameterOverrides

必需：否

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

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

注意

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

TemplateConfiguration

必需：否

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

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

Artifactname::TemplateConfigurationFileName

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

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

输入构件

  • 构件数：0 to 10

  • 描述：作为输入，AWS CloudFormation 操作可以选择接受构件用于下列用途：

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

    • 提供要使用的模板配置文件。（请参阅 TemplateConfiguration 参数。） 有关模板配置文件格式的更多信息，请参阅 AWS CloudFormation 构件。

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

输出构件

  • 构件数：0 to 1

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

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

输出变量

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

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

  • CHANGE_SET_EXECUTE

  • CHANGE_SET_REPLACE

  • CREATE_UPDATE

  • REPLACE_ON_FAILURE

有关更多信息，请参阅 变量参考。有关向您展示如何在使用 CloudFormation 输出变量的管道中使用 CloudFormation 部署操作创建管道的教程，请参阅教程：创建使用 AWS 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"
        }
    ]
},

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