本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
Amazon CloudFormation 部署操作参考
在 Amazon CloudFormation 堆栈上执行操作。堆栈是您可以作为一个单元管理的 Amazon 资源集合。堆栈中的资源均由堆栈的 Amazon CloudFormation
模板定义。更改集会创建比较,您可以查看比较而不会更改原始堆栈。有关可以对堆栈和更改集执行的 Amazon CloudFormation 操作类型的信息,请参阅ActionMode
参数。
注意:的 CodePipeline 操作 Amazon CloudFormation 不适用于中国(北京)和中国(宁夏)区域。要参考其他可用操作,请参阅 产品和服务与 CodePipeline。
要为堆栈操作失败的 Amazon CloudFormation 操作构造错误消息, CodePipeline 请调用 Amazon CloudFormation DescribeStackEvents
API。如果操作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 CloudFormationRoleArn
在执行更改集时不适用。如果您不使用创建 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 部署操作中的变量的管道。
操作声明
另请参阅
下列相关资源在您使用此操作的过程中会有所帮助。
-
配置属性参考 —《Amazon CloudFormation 用户指南》中的本参考章节提供了有关这些 CodePipeline 参数的更多描述和示例。
-
Amazon CloudFormation API参考-参考中的CreateStack参数描述了 Amazon CloudFormation 模板的堆栈参数。Amazon CloudFormation API