AI 助理
备案控制台
官方文档
输入文档关键字查找
首页 资源编排 开发参考 API参考 API目录 资源栈相关接口 CreateStack - 创建资源栈

CreateStack - 创建资源栈

更新时间：
产品详情
我的收藏

使用资源编排模板创建资源栈，完成一组资源的创建。

接口说明

资源栈是针对 ROS 资源的管理单元，您可通过创建资源栈来创建一组资源。关于资源栈的更多信息，请参见概览。
使用限制：

  • 每个阿里云账号最多创建 200 个资源栈。

  • 每个资源栈中最多创建 200 个资源。

本文将提供一个示例，在杭州地域创建一个名为MyStack的资源栈，并将资源栈的模板TemplateBody设置为{"ROSTemplateFormatVersion":"2015-09-01"}。

调试

您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

调试

授权信息

下表是API对应的授权信息，可以在RAM权限策略语句的Action元素中使用，用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下：

  • 操作：是指具体的权限点。

  • 访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。

  • 资源类型：是指操作中支持授权的资源类型。具体说明如下：

    • 对于必选的资源类型，用前面加 * 表示。

    • 对于不支持资源级授权的操作，用全部资源表示。

  • 条件关键字：是指云产品自身定义的条件关键字。

  • 关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。

操作

访问级别

资源类型

条件关键字

关联操作

ros:CreateStack

create

*Stack

acs:ros:{#regionId}:{#accountId}:stack/*

Template

acs:ros:{#regionId}:{#accountId}:template/{#TemplateId}

 无 无

请求参数

名称

类型

必填

描述

示例值
DisableRollback

boolean

否

当创建资源栈失败时，是否禁用回滚。

取值：

  • true：禁用回滚，即在创建资源栈失败时不进行回滚。

  • false（默认值）：不禁用回滚，即在创建资源栈失败时进行回滚。

false
TemplateBody

string

否

模板主体的结构。长度为 1~524,288 个字节。如果长度较长，则建议通过 HTTP POST+Body Param 的方式，将参数放在请求体中进行传递，避免因 URL 过长而导致请求失败。

说明

您必须且仅能指定 TemplateBody、TemplateURL、TemplateId 或 TemplateScratchId 其中一个参数。

{"ROSTemplateFormatVersion":"2015-09-01"}
StackPolicyURL

string

否

包含资源栈策略的文件的位置。URL 必须指向位于 Web 服务器（HTTP 或 HTTPS）或阿里云 OSS 存储空间（例如：oss://ros/stack-policy/demo、oss://ros/stack-policy/demo?RegionId=cn-hangzhou）中的策略，策略文件最大长度为 16,384 个字节。如未指定 OSS 地域，默认与接口参数 RegionId 相同。

说明

您仅能指定 StackPolicyBody 或 StackPolicyURL 其中一个参数。

URL 最大长度为 1350 个字节。

oss://ros-stack-policy/demo
TimeoutInMinutes

integer

否

创建资源栈的超时时间。

  • 默认值：60。

  • 单位：分钟。

  • 取值范围：10~1440。

10
StackPolicyBody

string

否

包含资源栈策略主体的结构，长度为 1~16,384 个字节。

说明

您仅能指定 StackPolicyBody 或 StackPolicyURL 其中一个参数。

{"Statement": [{"Action": "Update:*", "Resource": "*", "Effect": "Allow", "Principal": "*"}]}
StackName

string

是

资源栈名称。
长度不超过 255 个字符，必须以英文字母开头，可包含数字、英文字母、短划线（-）和下划线（_）。

MyStack
RegionId

string

是

资源栈所属的地域 ID。您可以调用 DescribeRegions 查看最新的阿里云地域列表。

cn-hangzhou
ClientToken

string

否

保证请求的幂等性。该值由客户端生成，并且必须是全局唯一的。长度不超过 64 个字符，可包含英文字母、数字、短划线（-）和下划线（_）。

更多信息，请参见如何保证幂等性。

123e4567-e89b-12d3-a456-42665544****
TemplateURL

string

否

包含模板主体的文件的位置。URL 必须指向位于 Web 服务器（HTTP 或 HTTPS）或阿里云 OSS 存储空间（例如：oss://ros/stack-policy/demo、oss://ros/stack-policy/demo?RegionId=cn-hangzhou）中的模板，模板的最大长度为 524,288 个字节。如未指定 OSS 地域，默认与 RegionId 取值相同。

说明

您必须且仅能指定 TemplateBody、TemplateURL、TemplateId 或 TemplateScratchId 其中一个参数。

oss://ros-template/demo
RamRoleName

string

否

RAM 角色名称。ROS 会扮演该角色创建资源栈，使用角色的凭证代表用户进行接口调用。
ROS 始终将此角色用于资源栈上将进行的操作。只要用户有权在资源栈上进行操作，即使用户无权使用角色，ROS 也会使用此角色，确保角色授予最少的权限。关于如何使用 RAM 角色，请参见使用资源栈角色。

如果用户未指定该值，ROS 将使用以前与资源栈关联的角色。如果没有可用角色，ROS 将使用从您的用户凭证中生成的临时凭证。

RAM 角色名称最大长度为 64 个字符。

test-role
DeletionProtection

string

否

是否开启资源栈删除保护。取值：

  • Enabled：开启资源栈删除保护。

  • Disabled（默认）：关闭资源栈删除保护。此时支持通过控制台或 API（DeleteStack）释放资源栈。

说明

嵌套资源栈删除保护与根资源栈一致。

Enabled
CreateOption

string

否

创建选项，用于控制创建资源栈的行为。取值：

  • KeepStackOnCreationComplete（默认值）：创建资源栈成功后保留资源栈及资源栈中的资源，占用 ROS 允许创建的资源栈数量限额。

  • AbandonStackOnCreationComplete：创建资源栈成功后删除资源栈，但保留所有资源，不占用 ROS 允许创建的资源栈数量限额。如果创建资源栈失败，资源栈会保留。

  • AbandonStackOnCreationRollbackComplete：创建资源栈回滚成功后删除资源栈，不占用 ROS 允许创建的资源栈数量限额。其他情况则保留资源栈。

  • ManuallyPay：在创建资源栈过程中手动支付包年包月的资源。目前支持手动支付的资源类型包括ALIYUN::ECS::InstanceGroup、ALIYUN::RDS::DBInstance、ALIYUN::SLB::LoadBalancer、ALIYUN::VPC::EIP、ALIYUN::VPC::VpnGateway。

说明

仅能指定 CreateOption 和 CreateOptions 其中一个参数。

KeepStackOnCreationComplete
CreateOptions

array

否

创建选项列表。

string

否

创建选项，用于控制创建资源栈的行为。取值：

  • KeepStackOnCreationComplete（默认值）：创建资源栈成功后保留资源栈及资源栈中的资源，占用 ROS 允许创建的资源栈数量限额。

  • AbandonStackOnCreationComplete：创建资源栈成功后删除资源栈，但保留所有资源，不占用 ROS 允许创建的资源栈数量限额。如果创建资源栈失败，资源栈会保留。

  • AbandonStackOnCreationRollbackComplete：创建资源栈回滚成功后删除资源栈，不占用 ROS 允许创建的资源栈数量限额。其他情况则保留资源栈。

  • ManuallyPay：在创建资源栈过程中手动支付包年包月的资源。目前支持手动支付的资源类型包括ALIYUN::ECS::InstanceGroup、ALIYUN::RDS::DBInstance、ALIYUN::SLB::LoadBalancer、ALIYUN::VPC::EIP、ALIYUN::VPC::VpnGateway。

说明

  • 仅能指定 CreateOption 和 CreateOptions 其中一个参数。

  • 创建选项不可重复，且 KeepStackOnCreationComplete 与 AbandonStackOnCreationComplete、AbandonStackOnCreationRollbackComplete 两个选项互斥。

  • N 最大值为 2。

KeepStackOnCreationComplete
TemplateId

string

否

模板 ID。支持共享模板和私有模板。

说明

您必须且仅能指定 TemplateBody、TemplateURL、TemplateId 或 TemplateScratchId 其中一个参数。

5ecd1e10-b0e9-4389-a565-e4c15efc****
TemplateVersion

string

否

模板版本。仅在指定 TemplateId 时生效。

v1
Parameters

array

否

模板中已定义的参数。

object

否

ParameterKey

string

是

模板中已定义的参数的名称。如果未指定参数的名称和值，则 ROS 将使用模板中指定的默认值。

N 最大值为 200。
长度为 1~128 个字符，不能以aliyun和acs:开头，不能包含http://或者https:// 。

说明

Parameters 为可选参数。如果需要指定 Parameters，则 Parameters.N.ParameterKey 和 Parameters.N.ParameterValue 必须同时指定。

InstanceId
ParameterValue

string

是

模板中已定义的参数的取值。

N 最大值为 200。
长度为 0~128 个字符，不能以aliyun和acs:开头，不能包含http://或者https:// 。

说明

Parameters 为可选参数。如果需要指定 Parameters，则 Parameters.N.ParameterKey 和 Parameters.N.ParameterValue 必须同时指定。

i-xxxxxx
NotificationURLs

array

否

接收资源栈事件的回调地址。取值：

  • HTTP POST URL
    每个 URL 最大长度为 1024 个字节。

  • eventbridge
    资源栈状态变更会通知到事件总线（EventBridge）服务。您可以在事件总线控制台查看事件信息。

说明

当前支持华东 1（杭州）、华东 2（上海）、华北 2（北京）、中国（香港）、华北 3（张家口）五个地域。

N 最大值为 5。资源栈的状态发生变化时，会进行通知。当资源栈启用回滚时，CREATE_FAILED（创建失败）和 UPDATE_FAILED（更新失败）不会通知，而 CREATE_ROLLBACK（创建失败回滚）和 ROLLBACK（更新失败回滚）会进行通知。IN_PROGRESS 状态不会通知。
无论资源栈是否定义了 Outputs 都会进行通知。通知内容示例如下：

{
   "Outputs": [
       {
           "Description": "No description given",
           "OutputKey": "InstanceId",
           "OutputValue": "i-xxx"
       }
   ],
   "StackId": "80bd6b6c-e888-4573-ae3b-93d29113****",
   "StackName": "test-notification-url",
   "Status": "CREATE_COMPLETE"
}

http://my-site.com/ros-event

string

否

接收资源栈事件的回调地址。取值：

  • HTTP POST URL
    每个 URL 最大长度为 1024 个字节。

  • eventbridge
    资源栈状态变更会通知到事件总线（EventBridge）服务。您可以在事件总线控制台查看事件信息。

说明

当前支持华东 1（杭州）、华东 2（上海）、华北 2（北京）、中国（香港）、华北 3（张家口）五个地域。

N 最大值为 5。资源栈的状态发生变化时，会进行通知。当资源栈启用回滚时，CREATE_FAILED（创建失败）和 UPDATE_FAILED（更新失败）不会通知，而 CREATE_ROLLBACK（创建失败回滚）和 ROLLBACK（更新失败回滚）会进行通知。IN_PROGRESS 状态不会通知。
无论资源栈是否定义了 Outputs 都会进行通知。通知内容示例如下：

{
   "Outputs": [
       {
           "Description": "No description given",
           "OutputKey": "InstanceId",
           "OutputValue": "i-xxx"
       }
   ],
   "StackId": "80bd6b6c-e888-4573-ae3b-93d29113****",
   "StackName": "test-notification-url",
   "Status": "CREATE_COMPLETE"
}

http://example.com/ros-event
Tags

array

否

资源栈的标签。

object

否

Key

string

是

资源栈的标签键。

N 的取值范围为 1~20。

说明

  • Tags 为可选参数。如果需要指定 Tags，则 Tags.N.Key 必须指定。

  • 此标签会传递到资源栈中每个支持标签的资源中。更多信息，请参见标签传递。

usage
Value

string

否

资源栈的标签值。

N 的取值范围为 1~20。

说明

此标签会传递到资源栈中每个支持标签的资源中。更多信息，请参见标签传递。

test
ResourceGroupId

string

否

资源组 ID。如果不指定该参数，资源栈将加入默认资源组。

关于资源组的更多信息，请参见什么是资源组。

rg-acfmxazb4ph6aiy****
Parallelism

integer

否

资源最大并发数。

默认为空，用户可以输入大于等于零的整数。

说明

  • 若设置为大于零的整数，则使用该整数；若设置为零或者不设置，对于 ROS 类型资源栈不限制，Terraform 类型资源栈使用 Terraform 默认值（通常为 10）。

  • 若设置了该值，将与资源栈进行关联，影响资源栈的后续操作，比如更新资源栈。

1
TemplateScratchId

string

否

资源场景 ID。

关于如何获取资源场景 ID，请参见 ListTemplateScratches 。

说明

您必须且仅能指定 TemplateBody、TemplateURL、TemplateId 或 TemplateScratchId 其中一个参数。

ts-aa9c62feab844a6b****
TemplateScratchRegionId

string

否

资源场景所属的地域 ID，默认与 RegionId 取值相同。

您可以调用 DescribeRegions 查看最新的阿里云地域列表。

cn-hangzhou

关于公共请求参数的详情，请参见公共参数。

返回参数

名称

类型

描述

示例值

object

RequestId

string

请求 ID。

B288A0BE-D927-4888-B0F7-B35EF84B6E6F
StackId

string

资源栈 ID。

4a6c9851-3b0f-4f5f-b4ca-a14bf691****

示例

正常返回示例

JSON格式

{
  "RequestId": "B288A0BE-D927-4888-B0F7-B35EF84B6E6F",
  "StackId": "4a6c9851-3b0f-4f5f-b4ca-a14bf691****"
}

错误码

访问错误中心查看更多错误码。

变更历史

更多信息，参考变更详情。

上一篇：资源栈相关接口下一篇：DeleteStack - 删除资源栈