Amazon CloudFormation 部署操作参考 - Amazon CodePipeline
操作类型配置参数 输入构件输出构件输出变量操作声明另请参阅
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

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

Amazon CloudFormation 部署操作参考

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

注意：的 CodePipeline 操作 Amazon CloudFormation 不适用于中国（北京）和中国（宁夏）区域。要参考其他可用操作，请参阅 产品和服务与 CodePipeline。

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

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

操作类型

  • 类别：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 是现有更改集的名称或要为指定堆栈创建的新更改集的名称。

以下操作模式需要此属性：CHANGESET_ REPLACE 和 CHANGE _ SET _ EXECUTE。对于所有其他操作模式，将忽略此属性。

RoleArn

必需：条件

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

注意

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

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

  • CREATE_UPDATE

  • REPLACE_开_ FAILURE

  • DELETE_ONLY

  • CHANGE_SET_REPLACE

注意

Amazon CloudFormation 已为模板提供 S3 签名URL；因此，这RoleArn不需要访问工件存储桶的权限。但是，该操作RoleArn确实需要访问工件存储桶的权限才能生成已签名的URL。

TemplatePath

必需：条件

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

Artifactname::TemplateFileName

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

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

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

  • CREATE_UPDATE

  • REPLACE_开_ FAILURE

  • CHANGE_SET_REPLACE

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

注意

包含 Amazon CloudFormation 模板正文的模板文件的最小长度为 1 字节，最大长度为 1 MB。对于中的 Amazon CloudFormation 部署操作 CodePipeline，最大输入项目大小始终为 256 MB。有关更多信息，请参阅 中的配额 Amazon CodePipeline和 Amazon 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 构件。

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

输出构件

  • 构件数：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"
        }
    ]
},

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