View a markdown version of this page

CloudFormation 配置属性参考 - AWS CloudFormation
配置属性 (控制台)配置属性 (JSON 对象)另请参阅

CloudFormation 配置属性参考

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

配置属性 (控制台)

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

注意

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

操作模式

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

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

  • Create or update a stack 创建堆栈 (如果指定的堆栈不存在)。如果堆栈存在，CloudFormation 将更新堆栈。使用此操作更新现有堆栈。CodePipeline 不会取代堆栈。

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

  • Execute a change set 执行更改集。

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

堆栈名称

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

注意

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

更改集名称

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

模板

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

模板配置

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

功能

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

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

您可以指定多个功能。

角色名称

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

Output file name

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

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

Parameter overrides

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

注意

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

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

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

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

配置属性 (JSON 对象)

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

ActionMode

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

  • CHANGE_SET_EXECUTE 执行更改集。

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

  • CREATE_UPDATE 创建堆栈 (如果指定的堆栈不存在)。如果堆栈存在，CloudFormation 将更新堆栈。使用此操作更新现有堆栈。CodePipeline 不会取代堆栈。

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

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

该属性是必需属性。

Capabilities

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

该属性是条件属性。如果您的堆栈模板包含 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_REPLACE 和 CHANGE_SET_EXECUTE。对于所有其他操作模式，将忽略此属性。

OutputFileName

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

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

ParameterOverrides

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

以下示例显示了如何将 InstanceType 和 KeyName 参数覆盖添加到模板：

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

在操作堆栈中的资源时 CloudFormation 担任的 IAM 服务角色的 Amazon 资源名称（ARN）。

以下操作模式需要此属性：CREATE_UPDATE、REPLACE_ON_FAILURE、DELETE_ONLY 和 CHANGE_SET_REPLACE。执行更改集时不应用 RoleArn。如果您不使用 CodePipeline 来创建更改集，请确保更改集或堆栈具有关联的角色。

StackName

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

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

TemplateConfiguration

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

Artifactname::TemplateConfigurationFileName

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

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

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

该属性是可选属性。

TemplatePath

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

Artifactname::TemplateFileName

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

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

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

另请参阅

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