All Products
Search

This Product

    Resource Orchestration Service:CreateChangeSet

    Document Center

    Resource Orchestration Service:CreateChangeSet

    Last Updated:Aug 27, 2025

    Creates a change set for a stack. You can preview the changes before you execute the change set.

    Operation description

    Scenarios

    Create a stack using a change set

    If you want to manage multiple cloud resources and preview how they are created before the stack is created, you can create the stack using a change set. To do this, set the ChangeSetType parameter to CREATE and configure the other required parameters. For more information about change sets, see Change sets.

    Update a stack using a change set

    If you want to preview the impact of an update on a stack before you apply the changes, you can create a change set for an existing stack. To do this, set the ChangeSetType parameter to UPDATE and configure the other required parameters. For more information about change sets, see Change sets.

    Create a stack from existing resources

    If you want to import existing cloud resources into a new stack for centralized management, you can create a change set. To do this, set the ChangeSetType parameter to IMPORT and configure the other required parameters. For more information about resource import, see Overview.

    Import existing resources to a stack

    If you want to import existing resources into an existing stack for centralized management, you can create a change set. To do this, set the ChangeSetType parameter to IMPORT and configure the other required parameters. For more information about resource import, see Overview.

    Limits

    • You can update only stacks that are in specific states using change sets. For more information, see Update a stack using a change set.

    • A stack can have a maximum of 20 change sets at a time.

    • A change set shows only the changes to a stack. It does not indicate whether the stack will be successfully updated.

    • A change set does not check for potential issues such as exceeded account quotas, attempts to update a resource that cannot be updated, or insufficient permissions to modify a resource. Any of these issues can cause the stack update to fail. If the update fails, ROS attempts to roll back your resources to their previous state.

    This topic provides an example of creating a change set named MyChangeSet in the China (Hangzhou) region (cn-hangzhou). The change set updates the template of a stack with the ID 4a6c9851-3b0f-4f5f-b4ca-a14bf691**** 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:CreateChangeSet

    create

    *Stack

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

    Template

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

    None

    None

    Request parameters

    Parameter

    Type

    Required

    Description

    Example

    StackId

    string

    No

    The ID of the stack for which you want to create the change set. ROS compares the stack information with the information that you submit, such as a modified template or different parameter values, to generate the change set. You can call the ListStacks operation to query the stack ID.

    Note

    This parameter takes effect only when ChangeSetType is set to UPDATE or IMPORT.

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

    StackPolicyURL

    string

    No

    The URL of the file that contains the stack policy. The URL must point to a policy that is located on a web server (HTTP or HTTPS) or in an Alibaba Cloud 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.

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

    Note

    If you do not specify the region of the OSS bucket, the value of RegionId is used.

    When ChangeSetType is set to CREATE, you can specify only one of the StackPolicyBody and StackPolicyURL parameters.

    When ChangeSetType is set to UPDATE, you can specify only one of the following parameters:

    • StackPolicyBody

    • StackPolicyURL

    • StackPolicyDuringUpdateBody

    • StackPolicyDuringUpdateURL

    oss://ros/stack-policy/demo

    StackPolicyBody

    string

    No

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

    When ChangeSetType is set to CREATE, you can specify only one of the StackPolicyBody and StackPolicyURL parameters.

    When ChangeSetType is set to UPDATE, you can specify only one of the following parameters:

    • StackPolicyBody

    • StackPolicyURL

    • StackPolicyDuringUpdateBody

    • StackPolicyDuringUpdateURL

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

    StackName

    string

    No

    The name of the stack for which you want to create the change set. The name can be up to 255 characters in length, and can contain digits, letters, hyphens (-), and underscores (_). The name must start with a digit or a letter.

    Note

    This parameter takes effect only when ChangeSetType is set to CREATE or IMPORT.

    MyStack

    UsePreviousParameters

    boolean

    No

    Specifies whether to use the values of parameters that were last used. Valid values:

    • true

    • false (default)

    Note

    This parameter takes effect only when ChangeSetType is set to UPDATE or IMPORT.

    true

    ChangeSetType

    string

    No

    The type of the change set. Valid values:

    • CREATE: creates a change set for a new stack.

    • UPDATE (default): creates a change set for an existing stack.

    • IMPORT: creates a change set for a new stack or an existing stack to import resources that are not managed by ROS.

    If you set the value of ChangeSetType to CREATE, ROS creates a new stack. The stack is in the REVIEW_IN_PROGRESS state until you execute the change set.

    Note

    • You cannot use the UPDATE type to create a change set for a new stack or the CREATE type to create a change set for an existing stack.

    • You cannot set a stack policy for a change set of the IMPORT type. You can set a stack policy when you create or update a stack.

    UPDATE

    Description

    string

    No

    The description of the change set. The description can be up to 1,024 bytes in length.

    It is a demo.

    RegionId

    string

    Yes

    The region ID of the change set.

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

    cn-hangzhou

    ClientToken

    string

    No

    A 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 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 that is located on a web server (HTTP or HTTPS) 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.

    Note

    If you do not specify the region of the OSS bucket, the value of RegionId is used.

    You can specify only one of the TemplateBody, TemplateURL, and TemplateId parameters.

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

    oss://ros/template/demo

    StackPolicyDuringUpdateURL

    string

    No

    The URL of the file that contains the temporary overriding stack policy. The URL must point to a policy that is located on a web server (HTTP or HTTPS) or in an 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.

    Note

    If you do not specify the region of the OSS bucket, the value of RegionId is used.

    The URL can be up to 1,350 bytes in length. If you want to update protected resources, specify a temporary overriding stack policy during the update. If you do not specify a stack policy, the current policy that is associated with the stack is used. This parameter takes effect only when ChangeSetType is set to UPDATE. You can specify only one of the following parameters:

    • StackPolicyBody

    • StackPolicyURL

    • StackPolicyDuringUpdateBody

    • StackPolicyDuringUpdateURL

    oss://ros/stack-policy/demo

    TemplateBody

    string

    No

    The structure of the template body. The template body must be 1 to 524,288 bytes in length. If the length is large, it is recommended to use the HTTP POST + Body Param method to pass the parameter in the request body, to avoid request failures caused by an excessively long URL.

    Note

    You can specify only one of the TemplateBody, TemplateURL, and TemplateId parameters.

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

    TimeoutInMinutes

    integer

    No

    The amount of time that can elapse before the stack enters the CREATE_FAILED or UPDATE_FAILED state. If ChangeSetType is set to CREATE, this parameter is required. If ChangeSetType is set to UPDATE, this parameter is optional.

    • Unit: minutes.

    • Valid values: 10 to 1440.

    • Default value: 60.

    12

    DisableRollback

    boolean

    No

    Specifies whether to disable rollback when the stack fails to be created. Valid values:

    • true: disables rollback for the stack when the stack fails to be created.

    • false (default): enables rollback for the stack when the stack fails to be created.

    Note

    This parameter takes effect only when ChangeSetType is set to CREATE or IMPORT.

    false

    ChangeSetName

    string

    Yes

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

    Note

    The name of the change set must be unique within the stack.

    MyChangeSet

    StackPolicyDuringUpdateBody

    string

    No

    The structure of the temporary overriding stack policy. The policy body must be 1 to 16,384 bytes in length. If you want to update protected resources, specify a temporary overriding stack policy during the update. If you do not specify a stack policy, the current policy that is associated with the stack is used. This parameter takes effect only when ChangeSetType is set to UPDATE. You can specify only one of the following parameters:

    • StackPolicyBody

    • StackPolicyURL

    • StackPolicyDuringUpdateBody

    • StackPolicyDuringUpdateURL

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

    RamRoleName

    string

    No

    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 always uses this role for all the operations that are performed on the stack. You must pssess the permissions to perform operations on the stack. If you do not possess the permissions, ROS assumes the role that is specified by RamRoleName to perform operations on the stack. If you do not specify RamRoleName, ROS assumes the existing role of the stack. If no role is available, ROS uses a temporary credential that is generated from the credentials of your account. The name of the RAM role can be up to 64 bytes in length.

    For more information about RAM roles, see Stack roles.

    test-role

    ReplacementOption

    string

    No

    Specifies whether to enable replacement update if a resource property is changed and the change does not support modification updates. A replacement update deletes the resource and creates a new resource. The physical ID of the resource is changed. Valid values:

    • Enabled: enables replacement update.

    • Disabled (default): disables replacement update.

    Note

    Modification updates are preferentially used. This parameter takes effect only when ChangeSetType is set to UPDATE.

    Disabled

    TemplateId

    string

    No

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

    You can call the ListTemplates operation to query the template ID.

    Note

    You can specify only one of the TemplateBody, TemplateURL, and TemplateId parameters.

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

    TemplateVersion

    string

    No

    The version of the template.

    Note

    This parameter takes effect only when TemplateId is specified.

    v1

    Parameters

    array<object>

    No

    The parameters that are defined in the template.

    object

    No

    ParameterKey

    string

    Yes

    The name of the parameter 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. The value of N can be up to 200.

    Note

    The Parameters parameter is optional. If you specify Parameters, you must also specify Parameters.N.ParameterKey.

    Amount

    ParameterValue

    string

    Yes

    The value of the parameter that is defined in the template. The value of N can be up to 200.

    Note

    The Parameters parameter is optional. If you specify Parameters, you must also specify Parameters.N.ParameterValue.

    12

    NotificationURLs

    array

    No

    The list of webhook addresses for receiving stack event notifications.

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

    string

    No

    The webhook address for receiving stack event notifications. Valid values:

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

    • eventbridge Stack status changes are sent to the EventBridge service. You can log on to the EventBridge console and click Event Buses in the navigation pane on the left to view event information.

    Note

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

    The value of N can be up to 5. When the status of a stack changes, a notification is sent. If rollback is enabled for the stack, notifications for the CREATE_FAILED and UPDATE_FAILED states are not sent. Instead, notifications for the CREATE_ROLLBACK and ROLLBACK states are sent. The IN_PROGRESS state is not reported. A notification is sent regardless of whether the Outputs parameter is defined for the stack. The following code shows a sample 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-notify

    ResourcesToImport

    array<object>

    No

    The list of resources to be imported.

    object

    No

    ResourceIdentifier

    string

    No

    A key-value mapping between strings. The value is a JSON string that is used to identify the resource to be imported. The key is the identifier property of the resource, such as the VpcId of an ALIYUN::ECS::VPC resource. The value is the value of the property, such as vpc-2zevx9ios****.

    You can call the GetTemplateSummary operation to query the identifier properties of a resource.

    Note

    This parameter takes effect only when ChangeSetType is set to IMPORT. The ResourcesToImport parameter is optional. If you specify ResourcesToImport, you must also specify ResourcesToImport.N.ResourceIdentifier.

    {"VpcId": "vpc-2zevx9ios******"}

    LogicalResourceId

    string

    No

    The logical ID of the resource. The logical ID is the resource name that is defined in the template.

    Note

    This parameter takes effect only when ChangeSetType is set to IMPORT. The ResourcesToImport parameter is optional. If you specify ResourcesToImport, you must also specify ResourcesToImport.N.LogicalResourceId.

    Vpc

    ResourceType

    string

    No

    The type of the resource. The resource type must be the same as the resource type that is defined in the template.

    Note

    This parameter takes effect only when ChangeSetType is set to IMPORT. The ResourcesToImport parameter is optional. If you specify ResourcesToImport, you must also specify ResourcesToImport.N.ResourceType.

    ALIYUN::ECS::VPC

    TemplateScratchId

    string

    No

    The resource scenario ID, which is the resource management scenario ID.

    This parameter takes effect only when ChangeSetType is set to IMPORT. This parameter supports only the creation of new stacks for resource import.

    If you want to import resources in a resource management scenario, specify only this parameter. Do not specify parameters related to templates.

    You can call the ListTemplateScratches operation to query the resource management scenario ID.

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

    Parallelism

    integer

    No

    The maximum number of concurrent operations that can be performed on resources. The default value is empty, which specifies that the value is an integer that is greater than or equal to 0. After you set this parameter, the value is associated with the stack and affects subsequent operations on the stack.

    This parameter takes effect only when ChangeSetType is set to CREATE or UPDATE. Valid values:

    • If ChangeSetType is set to CREATE

      • 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 do not set this parameter, no limit is imposed on ROS stacks. For Terraform stacks, the default value of Terraform is used, which is 10.

    • If ChangeSetType is set to UPDATE

      • If you set this parameter to an integer that is greater than 0, the integer is used.

      • If you set this parameter to 0, no limit is imposed on ROS stacks. For Terraform stacks, the default value of Terraform is used, which is 10.

      • If you do not set this parameter, the value that you specified in the previous operation is used. If you did not set this parameter in the previous operation, no limit is imposed on ROS stacks. For Terraform stacks, the default value of Terraform is used, which is 10.

    1

    Tags

    array<object>

    No

    The tags of the change set.

    object

    No

    The tags of the change set.

    Key

    string

    No

    The tag key of the stack.

    The value of N can be from 1 to 20.

    Note

    • The Tags parameter is optional. If you specify Tags, you must also specify Tags.N.Key.

    • The tag is propagated to each stack resource that supports tags. For more information, see Propagate tags.

    usage

    Value

    string

    No

    The tag value of the stack.

    The value of N can be from 1 to 20.

    Note

    The tag is propagated to each stack resource that supports tags. For more information, see Propagate tags.

    test

    ResourceGroupId

    string

    No

    The resource group ID. If you do not specify this parameter, the stack is added to the default resource group. For more information about resource groups, see What is a resource group?.

    rg-acfmxazb4ph6aiy****

    TaintResources

    array

    No

    The list of resources to be marked as dirty.

    string

    No

    • For ROS stacks, the value is the resource name, such as my_vpc.

    • For Terraform stacks, the value is the resource type and resource name, such as alicloud_vpc.my_vpc

    my_vpc

    For information about common request parameters, see Common parameters.

    Response elements

    Parameter

    Type

    Description

    Example

    object

    ChangeSetId

    string

    The ID of the change set.

    e85abe0c-6528-43fb-ae93-fdf8de22****

    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

    {
  "ChangeSetId": "e85abe0c-6528-43fb-ae93-fdf8de22****",
  "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.