All Products
Search
Document Center

Resource Orchestration Service:CreateStack

Last Updated:Feb 22, 2024

Creates a stack that contains a collection of resources by using a Resource Orchestration Service (ROS) template.

Operation description

A stack is a collection of ROS resources that you can manage as a single unit. To create a collection of resources, you can create a stack. For more information about stacks, see Overview .
When you call the operation, take note of the following limits:

  • You can create up to 200 stacks within an Alibaba Cloud account.
  • You can create up to 200 resources in a stack.

This topic provides an example on how to create a stack named MyStack in the China (Hangzhou) region by using a template. In this example, TemplateBody is set to {"ROSTemplateFormatVersion":"2015-09-01"}.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer.

Authorization information

The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

  • Operation: the value that you can use in the Action element to specify the operation on a resource.
  • Access level: the access level of each operation. The levels are read, write, and list.
  • Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
    • The required resource types are displayed in bold characters.
    • If the permissions cannot be granted at the resource level, All Resources is used in the Resource type column of the operation.
  • Condition Key: the condition key that is defined by the cloud service.
  • Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.
OperationAccess levelResource typeCondition keyAssociated operation
ros:CreateStackWRITE
  • stack
    acs:ros:{#regionId}:{#accountId}:stack/*
  • template
    acs:ros:{#regionId}:{#accountId}:template/{#templateId}
    none
none

Request parameters

ParameterTypeRequiredDescriptionExample
DisableRollbackbooleanNo

Specifies whether to disable rollback for the resources when the stack fails to be created.

Valid values:

  • true
  • false (default)
false
TemplateBodystringNo

The structure that contains the template body. The template body must be 1 to 524,288 bytes in length. If the length of the template body exceeds the upper limit, we recommend that you add parameters to the HTTP POST request body to prevent request failures caused by excessively long URLs.

Note You must and can specify only one of the following parameters: TemplateBody, TemplateURL, TemplateId, and TemplateScratchId.
{"ROSTemplateFormatVersion":"2015-09-01"}
StackPolicyURLstringNo

The URL of the file that contains the stack policy. The URL must point to a policy that is located on an HTTP or HTTPS web server or in an Object Storage Service (OSS) bucket, such as oss://ros/stack-policy/demo or oss://ros/stack-policy/demo?RegionId=cn-hangzhou. The policy file can be up to 16,384 bytes in length. If you do not specify the region ID of the OSS bucket, the value of RegionId is used.

Note You can specify only one of StackPolicyBody and StackPolicyURL.

The URL can be up to 1,350 bytes in length.

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

The timeout period for creating the stack.

  • Default value: 60.
  • Unit: minutes.
  • Valid values: 10 to 1440.
10
StackPolicyBodystringNo

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

Note You can specify only one of StackPolicyBody and StackPolicyURL.
{"Statement": [{"Action": "Update:*", "Resource": "*", "Effect": "Allow", "Principal": "*"}]}
StackNamestringYes

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

MyStack
RegionIdstringYes

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

cn-hangzhou
ClientTokenstringNo

The client token that is used to ensure the idempotence of the request. You can use the client to generate the token, but you must make sure that the token is unique among different requests. The token can be up to 64 characters in length, and can contain letters, digits, hyphens (-), and underscores (_).

For more information, see Ensure idempotence.

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

The URL of the file that contains the template body. The URL must point to a template that is located on an HTTP or HTTPS web server or in an OSS bucket, such as oss://ros/template/demo or oss://ros/template/demo?RegionId=cn-hangzhou. The template body can be up to 524,288 bytes in length. If you do not specify the region ID of the OSS bucket, the value of RegionId is used.

Note You must and can specify only one of the following parameters: TemplateBody, TemplateURL, TemplateId, and TemplateScratchId.
oss://ros-template/demo
RamRoleNamestringNo

The name of the RAM role. ROS assumes the RAM role to create the stack and uses the credentials of the role to call the APIs of Alibaba Cloud services.
ROS assumes the RAM role to perform operations on the stack. If you have permissions to perform operations on the stack but do not have permissions to use the RAM role, ROS still assumes the RAM role. You must make sure that the least privileges are granted to the RAM role.

If you do not specify this parameter, ROS assumes the existing role that is associated with the stack. If no roles are available, ROS uses a temporary credential that is generated from the credentials of your account.

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

test-role
DeletionProtectionstringNo

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

  • Enabled.
  • Disabled (default). If deletion protection is disabled, you can delete the stack by using the ROS console or by calling the DeleteStack operation.
Note The value of DeletionProtection that you specify for the root stack applies to its nested stacks.
Enabled
CreateOptionstringNo

The creation option for the stack. Valid values:

  • KeepStackOnCreationComplete (default): After the stack is created, the stack and its resources are retained. The quota for the maximum number of stacks that can be created in ROS is consumed.
  • AbandonStackOnCreationComplete: After the stack is created, the stack is deleted, but its resources are retained. The quota for the maximum number of stacks that can be created in ROS is not consumed. If the stack fails to be created, the stack is retained.
  • AbandonStackOnCreationRollbackComplete: When the resources of the stack are rolled back after the stack fails to be created, the stack is deleted. The quota for the maximum number of stacks that can be created in ROS is not consumed. 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.
Note You can specify only one of CreateOption and CreateOptions.
KeepStackOnCreationComplete
CreateOptionsarrayNo

The creation options for the stack.

stringNo

The creation option N for the stack. Valid values:

  • KeepStackOnCreationComplete (default): After the stack is created, the stack and its resources are retained. The quota for the maximum number of stacks that can be created in ROS is consumed.
  • AbandonStackOnCreationComplete: After the stack is created, the stack is deleted, but its resources are retained. The quota for the maximum number of stacks that can be created in ROS is not consumed. If the stack fails to be created, the stack is retained.
  • AbandonStackOnCreationRollbackComplete: When the resources of the stack are rolled back after the stack fails to be created, the stack is deleted. The quota for the maximum number of stacks that can be created in ROS is not consumed. 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.
Note
  • You can specify only one of CreateOption and CreateOptions.

  • The option must be unique. The KeepStackOnCreationComplete option is mutually exclusive with the AbandonStackOnCreationComplete and AbandonStackOnCreationRollbackComplete options.

  • Maximum value of N: 2.

KeepStackOnCreationComplete
TemplateIdstringNo

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

Note You must and can specify only one of the following parameters: TemplateBody, TemplateURL, TemplateId, and TemplateScratchId.
5ecd1e10-b0e9-4389-a565-e4c15efc****
TemplateVersionstringNo

The version of the template. This parameter takes effect only when TemplateId is specified.

v1
Parametersobject []No

The parameters that are defined in the template.

ParameterKeystringYes

The key 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 name and value that are specified in the template.

Maximum value of N: 200.
The name must be 1 to 128 characters in length, and cannot contain http:// or https://. It cannot start with aliyun or acs:.

Note The Parameters parameter is optional. If you specify Parameters, you must specify Parameters.N.ParameterKey and Parameters.N.ParameterValue.
InstanceId
ParameterValuestringYes

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

Maximum value of N: 200.
The value can be up to 128 characters in length, and cannot contain http:// or https://. It cannot start with aliyun or acs:.

Note The Parameters parameter is optional. If you specify Parameters, you must specify Parameters.N.ParameterKey and Parameters.N.ParameterValue.
i-xxxxxx
NotificationURLsarrayNo

The callback URLs that are used to receive stack events. Valid values:

  • HTTP POST URL

Each URL can be up to 1,024 bytes in length.

  • eventbridge

When the status of a stack changes, ROS sends notifications to the EventBridge service. You can view the event information in the EventBridge console.

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

Maximum value of N: 5. When the status of a stack changes, ROS sends a notification to the specified URL. When rollback is enabled for the stack, notifications are sent if the stack is in the CREATE_ROLLBACK or ROLLBACK state, but are not sent if the stack is in the CREATE_FAILED, UPDATE_FAILED, or IN_PROGRESS state.
ROS sends notifications regardless of whether you specify the Outputs section. The following sample code provides an example on the content of a notification:

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

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

  • HTTP POST URL

Each URL can be up to 1,024 bytes in length.

  • eventbridge

When the status of a stack changes, ROS sends notifications to the EventBridge service. You can view the event information in the EventBridge console.

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

Maximum value of N: 5. When the status of a stack changes, ROS sends a notification to the specified URL. When rollback is enabled for the stack, notifications are sent if the stack is in the CREATE_ROLLBACK or ROLLBACK state, but are not sent if the stack is in the CREATE_FAILED, UPDATE_FAILED, or IN_PROGRESS state.
ROS sends notifications regardless of whether you specify the Outputs section. The following sample code provides an example on the content of a 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
Tagsobject []No

The tags that you want to add to the stack.

KeystringYes

The key of tag N that you want to add to the stack.

Valid values of N: 1 to 20.

Note
  • The Tags parameter is optional. If you 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, see Propagate tags.
  • usage
    ValuestringNo

    The value of tag N that you want to add to the stack.

    Valid values of N: 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 Propagate tags.
    test
    ResourceGroupIdstringNo

    The ID of the resource group. If you leave this parameter empty, the stack is added to the default resource group.

    For more information about resource groups, see the "Resource group" section of the What is Resource Management? topic.

    rg-acfmxazb4ph6aiy****
    ParallelismlongNo

    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 that is greater than or equal to 0.

    Note
  • If you set this parameter to an integer that is 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. However, the default value in Terraform is used for Terraform stacks. In most cases, the default value in Terraform is 10.
  • If you set this parameter to a specific value, ROS associates the value with the stack. The value affects subsequent operations on the stack, such as an update operation.
  • 1
    TemplateScratchIdstringNo

    The scenario ID.

    For more information about how to query the scenario ID, see ListTemplateScratches .

    Note You must and can specify only one of the following parameters: TemplateBody, TemplateURL, TemplateId, and TemplateScratchId.
    ts-aa9c62feab844a6b****
    TemplateScratchRegionIdstringNo

    The region ID of the scenario. The default value is the same as the value of RegionId.

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

    cn-hangzhou

    For more information about common request parameters, see Common parameters.

    Response parameters

    ParameterTypeDescriptionExample
    object
    RequestIdstring

    The request ID.

    B288A0BE-D927-4888-B0F7-B35EF84B6E6F
    StackIdstring

    The stack ID.

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

    Examples

    Sample success responses

    JSONformat

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

    Error codes

    For a list of error codes, visit the Service error codes.

    Change history

    Change timeSummary of changesOperation
    2024-01-11The internal configuration of the API is changed, but the call is not affectedsee changesets
    Change itemChange content
    The internal configuration of the API is changed, but the call is not affected.
    2023-04-13The request parameters of the API has changedsee changesets
    Change itemChange content
    Input ParametersThe request parameters of the API has changed.
      Added Input Parameters: CreateOptions