All Products
Search

This Product

    Resource Orchestration Service:CreateStack

    Document Center

    Resource Orchestration Service:CreateStack

    Last Updated:Sep 30, 2025

    Use Resource Orchestration Service (ROS) template to create a stack and deploy a group of resources.

    Operation description

    A stack is a management unit for ROS resources. You can create a group of resources by creating a stack. For more information about stacks, refer to Overview. Limits:

    • Each Alibaba Cloud account can create up to 200 stacks.

    • Each stack can contain up to 200 resources.

    This topic provides an example of how to create a stack named MyStack in the China (Hangzhou) region with the stack template TemplateBody set to {"ROSTemplateFormatVersion":"2015-09-01"}.

    Try it now

    Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

    Test

    RAM authorization

    The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

    • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

    • API: The API that you can call to perform the action.

    • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

    • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

      • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

      • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

    • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

    • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

    Action

    Access level

    Resource type

    Condition key

    Dependent action

    ros:CreateStack

    create

    *Stack

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

    Template

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

    None

    None

    Request parameters

    Parameter

    Type

    Required

    Description

    Example

    DisableRollback

    boolean

    No

    Specifies whether to disable rollback when stack creation failed.

    Valid values:

    • true: disables rollback.

    • false (default): enables rollback.

    false

    TemplateBody

    string

    No

    The template body. The length must be between 1 and 524,288 bytes. If the content is large, it is recommended to use the HTTP POST method with Body parameters to pass the data in the request body, in order to avoid request failures caused by long URLs.

    Note

    You must specify only one of the following parameters: TemplateBody, TemplateURL, TemplateId, or TemplateScratchId.

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

    StackPolicyURL

    string

    No

    The URL of the file that contains the stack policy. The URL must point to a policy file hosted on a web server (HTTP or HTTPS) or in Alibaba Cloud OSS bucket (for example, oss://ros/stack-policy/demo or oss://ros/stack-policy/demo?RegionId=cn-hangzhou). The maximum size of the policy file is 16,384 bytes. If the OSS region is not specified in the URL, it defaults to the value of RegionId parameter of the API request.

    Note

    You can specify only one of the following parameters: StackPolicyBody or StackPolicyURL.

    The maximum length of the URL is 1,350 bytes.

    oss://ros-stack-policy/demo

    TimeoutInMinutes

    integer

    No

    The timeout period that is allowed to create the stack. Unit: minutes.

    • Default value: 60.

    • Valid values: 10 to 1440.

    10

    StackPolicyBody

    string

    No

    The structure that contains the stack policy body. The length must be between 1 to 16,384 bytes.

    Note

    You can specify only one of the following parameters: StackPolicyBody or StackPolicyURL.

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

    StackName

    string

    Yes

    The name of the stack. The length of the name is up to 255 characters. The value must start with a letter and can contain letters, digits, hyphens (-), and underscores (_).

    MyStack

    RegionId

    string

    Yes

    The region ID of the stack. You can call DescribeRegions to query the most recent region list.

    cn-hangzhou

    ClientToken

    string

    No

    Ensures the idempotency of the request. This value must be generated by the client and must be globally unique. The length is up to 64 characters and can contain letters, digits, hyphens (-), and underscores (_).

    For more information, refer to How to ensure idempotence.

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

    TemplateURL

    string

    No

    The URL of the file that contains the template body. The URL must point to a template hosted on a web server (HTTP or HTTPS) or in Alibaba Cloud OSS bucket (for example, oss://ros/stack-policy/demo or oss://ros/stack-policy/demo?RegionId=cn-hangzhou). The maximum size of the template is 524,288 bytes. If the OSS region is not specified in the URL, it defaults to the value of RegionId parameter of the API request.

    Note

    You must specify only one of the following parameters: TemplateBody, TemplateURL, TemplateId, or TemplateScratchId.

    oss://ros-template/demo

    RamRoleName

    string

    No

    The name of the RAM role. ROS assumes this role to create the stack and uses the credentials of the role to call API on behalf of the user. ROS always uses this role for operations performed on the stack. As long as users have permissions to operations on the stack, ROS uses this role even if the users do not have permissions to use the role, ensuring that the role grants the least permissions. For more information about how to use a RAM role, refer to Use a stack role.

    If this value is not specified, ROS uses the existing role that is associated with the stack. If no available role exists, ROS uses a temporary credential that is generated from your account.

    The name of the RAM role can be up to 64 characters in length.

    test-role

    DeletionProtection

    string

    No

    Specifies whether to enable deletion protection on the stack. Valid values:

    • Enabled: enables deletion protection.

    • Disabled (default): disables deletion protection. You can delete the stack using the ROS console or by calling DeleteStack API.

    Note

    The deletion protection of a nested stack is the same as that of its root stack.

    Enabled

    CreateOption

    string

    No

    The option for the stack after the stack is created. Valid values:

    • KeepStackOnCreationComplete (default): retains the stack and its resources after the stack is created. The stack occupies a quota of the total number of stacks that you can create.

    • AbandonStackOnCreationComplete: deletes the stack but retains all resources after the stack is created. The stack does not occupy a quota of the total number of stacks that you can create. If the stack fails to be created, the stack is retained.

    • AbandonStackOnCreationRollbackComplete: deletes the stack after the stack is rolled back. The stack does not occupy a quota of the total number of stacks that you can create. In other rollback scenarios, the stack is retained.

    • ManuallyPay: When you create the stack, you must manually pay for the subscription resources that are used. The following resource types support manual payment: ALIYUN::ECS::InstanceGroup, ALIYUN::RDS::DBInstance, ALIYUN::SLB::LoadBalancer, ALIYUN::VPC::EIP, and ALIYUN::VPC::VpnGateway.

    • RetryOnNoStock：If resource creation fails due to insufficient inventory, it will automatically retry. Currently, the supported resource type for retry includes ALIYUN::RDS::DBInstance.

    Note

    You can specify only one of the following parameters: CreateOption or CreateOptions.

    KeepStackOnCreationComplete

    CreateOptions

    array

    No

    The creation options for the stack.

    string

    No

    The creation option N for the stack. Valid values:

    • KeepStackOnCreationComplete (default): retains the stack and its resources after the stack is created. The stack occupies a quota of the total number of stacks that you can create.

    • AbandonStackOnCreationComplete: deletes the stack but retains all resources after the stack is created. The stack does not occupy a quota of the total number of stacks that you can create. If the stack fails to be created, the stack is retained.

    • AbandonStackOnCreationRollbackComplete: deletes the stack after the stack is rolled back because of a creation failure. The stack does not occupy a quota of the total number of stacks that you can create. In other rollback scenarios, the stack is retained.

    • ManuallyPay: When you create the stack, you must manually pay for the subscription resources that are used. The following resource types support manual payment: ALIYUN::ECS::InstanceGroup, ALIYUN::RDS::DBInstance, ALIYUN::SLB::LoadBalancer, ALIYUN::VPC::EIP, and ALIYUN::VPC::VpnGateway.

    • RetryOnNoStock：If resource creation fails due to insufficient inventory, it will automatically retry. Currently, the supported resource type for retry includes ALIYUN::RDS::DBInstance.

    Note

    • You can specify only one of the following parameters: CreateOption or CreateOptions.

    • Creation options cannot be repeated. The KeepStackOnCreationComplete option is mutually exclusive with the AbandonStackOnCreationComplete and AbandonStackOnCreationRollbackComplete options.

    • The maximum value of N is 4.

    KeepStackOnCreationComplete

    TemplateId

    string

    No

    The template ID. This parameter applies to shared and private templates.

    Note

    You must specify only one of the following parameters: TemplateBody, TemplateURL, TemplateId, or TemplateScratchId.

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

    TemplateVersion

    string

    No

    The version of the template. This parameter takes effect only when you specify TemplateId.

    v1

    Parameters

    array<object>

    No

    The parameters that are defined in the template.

    object

    No

    ParameterKey

    string

    Yes

    The name of parameter N that is defined in the template. If you do not specify the name and value of a parameter, ROS uses the default value that is specified in the template.

    The maximum value of N is 200. The name must be between 1 to 128 characters and cannot start with aliyun or acs:. The name cannot contain http:// or https://.

    Note

    Parameters is an optional parameter. To specify Parameters, you must specify both Parameters.N.ParameterKey and Parameters.N.ParameterValue.

    InstanceId

    ParameterValue

    string

    Yes

    The value of parameter N that is defined in the template.

    The maximum value of N is 200. The value must be between 0 to 128 characters and cannot start with aliyun or acs:. The value cannot contain http:// or https://.

    Note

    Parameters is an optional parameter. To specify Parameters, you must specify both Parameters.N.ParameterKey and Parameters.N.ParameterValue.

    i-xxxxxx

    NotificationURLs

    array

    No

    The callback URL that is used to receive stack events. Valid values:

    • HTTP POST URL The length of each URL can be up to 1,024 bytes.

    • eventbridge EventBridge service will receives notification when the stack status changes. You can view event information in EventBridge console.

    Note

    This feature is supported in the following regions: China (Hangzhou), China (Shanghai), China (Beijing), China (Hong Kong), and China (Zhangjiakou).

    The maximum value of N is 5. When the status of a stack changes, ROS sends a notification to the specified URL. When rollback is enabled for a stack, ROS does not send notifications when the CREATE_FAILED or UPDATE_FAILED event occurs but sends notifications when the CREATE_ROLLBACK or ROLLBACK event occurs. ROS does not send notifications when the IN_PROGRESS event occurs. ROS always send notifications whether the stack defines Outputs. The following sample code provides an example on the content of an event notification: 

    {
   "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

    No

    The callback URL that is used to receive stack event N. Valid values:

    • HTTP POST URL The length of each URL can be up to 1,024 bytes.

    • eventbridge EventBridge service will receives notification when the stack status changes. You can view event information in EventBridge console.

    Note

    This feature is supported in the following regions: China (Hangzhou), China (Shanghai), China (Beijing), China (Hong Kong), and China (Zhangjiakou).

    The maximum value of N is 5. When the status of a stack changes, ROS sends a notification to the specified URL. When rollback is enabled for a stack, ROS does not send notifications when the CREATE_FAILED or UPDATE_FAILED event occurs but sends notifications when the CREATE_ROLLBACK or ROLLBACK event occurs. ROS does not send notifications when the IN_PROGRESS event occurs. ROS always send notifications whether the stack defines Outputs. The following sample code provides an example on the content of an event notification: 

    {
   "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>

    No

    The tags of the stack.

    object

    No

    Key

    string

    Yes

    The key of tag N of the stack.

    Valid values: 1 to 20.

    Note

    • Tags is an optional parameter. To specify Tags, you must specify Tags.N.Key.

    • The tag of a stack is propagated to each resource that supports the tag feature in the stack. For more information, refer to Tag propagation.

    usage

    Value

    string

    No

    The value of tag N of the stack.

    Valid values: 1 to 20.

    Note

    The tag of a stack is propagated to each resource that supports the tag feature in the stack. For more information, see Tag propagation.

    test

    ResourceGroupId

    string

    No

    The ID of the resource group. If you do not specify this parameter, the stack is added to the default resource group.

    For more information about resource groups, refer to What is a resource group.

    rg-acfmxazb4ph6aiy****

    Parallelism

    integer

    No

    The maximum number of concurrent operations that can be performed on resources.

    By default, this parameter is empty. You can set this parameter to an integer greater than or equal to 0.

    Note

    • If you set this parameter to an integer greater than 0, the integer is used. If you set this parameter to 0 or leave this parameter empty, no limit is imposed on ROS stacks, and the default value of Terraform (typically 10) is used for Terraform stacks.

    • If you set this parameter to a specific value, ROS associates the value with the stack and the value can affect subsequent operations on the stack, such as an update operation on the stack.

    1

    TemplateScratchId

    string

    No

    The ID of the resource scenario.

    For information about how to obtain the ID of a resource scenario, refer to ListTemplateScratches.

    Note

    You must specify only one of the following parameters: TemplateBody, TemplateURL, TemplateId, or TemplateScratchId.

    ts-aa9c62feab844a6b****

    TemplateScratchRegionId

    string

    No

    The region ID of the resource scenario. Default value: the value of RegionId.

    You can call DescribeRegions to query the most recent region list.

    cn-hangzhou

    For more information about request common parameters, refer to Common parameters.

    Response elements

    Element

    Type

    Description

    Example

    object

    RequestId

    string

    The request ID.

    B288A0BE-D927-4888-B0F7-B35EF84B6E6F

    StackId

    string

    The stack ID.

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

    Examples

    Success response

    JSON format

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

    Error codes

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.