本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
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 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 构件。 -
为要作为 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 部署操作中的变量的管道。
操作声明
另请参阅
下列相关资源在您使用此操作的过程中会有所帮助。
-
配置属性参考:Amazon CloudFormation 用户指南 中的此参考章节提供了有关这些 CodePipeline 参数的更多说明和示例。
-
Amazon CloudFormation API 参考:Amazon CloudFormation API 参考 中的 CreateStack 参数描述了 Amazon CloudFormation 模板的堆栈参数。