AWS CloudFormation 部署操作参考 - AWS CodePipeline
操作类型配置参数 输入构件输出构件输出变量服务角色权限： AWS CloudFormation 操作操作声明另请参阅

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

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。对于中的 AWS CloudFormation 部署操作 CodePipeline，最大输入项目大小始终为 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 构件。

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

输出构件

  • 构件数：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 部署操作中的变量的管道。

服务角色权限： AWS CloudFormation 操作

CodePipeline 运行操作时， CodePipeline 服务角色策略需要以下权限，这些权限的范围适当地缩小到管道资源 ARN，以便以最低权限保持访问权限。例如，在您的政策声明中添加以下内容：

JSON
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "AllowCFNStackAccess",
            "Effect": "Allow",
            "Action": [
                "cloudformation:CreateStack",
                "cloudformation:UpdateStack",
                "cloudformation:DeleteStack",
                "cloudformation:DescribeStacks",
                "cloudformation:DescribeStackResources",
                "cloudformation:DescribeStackEvents",
                "cloudformation:GetTemplate",
                "cloudformation:DescribeChangeSet",
                "cloudformation:CreateChangeSet",
                "cloudformation:DeleteChangeSet",
                "cloudformation:ExecuteChangeSet"
            ],
            "Resource": [
                "arn:aws:cloudformation:*:111122223333:stack/[[cfnDeployStackNames]]/*"
            ]
        },
        {
            "Sid": "ValidateTemplate",
            "Effect": "Allow",
            "Action": [
                "cloudformation:ValidateTemplate"
            ],
            "Resource": "*"
        },
        {
            "Sid": "AllowIAMPassRole",
            "Effect": "Allow",
            "Action": [
                "iam:PassRole"
            ],
            "Resource": [
                "arn:aws:iam::111122223333:role/[[cfnExecutionRoles]]"
            ],
            "Condition": {
                "StringEqualsIfExists": {
                    "iam:PassedToService": [
                        "cloudformation.amazonaws.com"
                    ]
                }
            }
        }
    ]
}

请注意，该 cloudformation:DescribeStackEvents 权限是可选的。它允许 AWS CloudFormation 操作显示更详细的错误消息。如果您不希望资源详细信息出现在管道错误消息中，可以撤销 IAM 角色的此权限。

操作声明

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

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

  • 配置属性参考 —《AWS CloudFormation 用户指南》中的本参考章节提供了有关这些 CodePipeline 参数的更多描述和示例。

  • AWS CloudFormation API 参考 — AWS CloudFormation API 参考中的CreateStack参数描述了 AWS CloudFormation 模板的堆栈参数。