CreateChangeSet

Creates a change set for a stack so you can preview changes before execution.

Operation description

Scenarios

Create a stack using a change set

To manage cloud resources and preview creation results before the stack is created, set ChangeSetType to CREATE. Change sets.

Update a stack using a change set

To preview the impact of an update before applying changes, set ChangeSetType to UPDATE. Change sets.

Create a stack from existing resources

To import existing cloud resources into a new stack, set ChangeSetType to IMPORT. Overview.

Import existing resources to a stack

To import existing resources into an existing stack, set ChangeSetType to IMPORT. Overview.

Limits

Only stacks in specific states can be updated using change sets. 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 issues such as exceeded account quotas, non-updatable resources, or insufficient permissions. These issues can cause the stack update to fail. If the update fails, ROS attempts to roll back resources to their previous state.

In this example, a change set named MyChangeSet is created in the China (Hangzhou) region (cn-hangzhou) to update the template of stack 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

Request parameters

Parameter	Type	Required	Description	Example
StackId	string	No	The stack ID. ROS compares the stack information with the submitted changes, such as a modified template or different parameter values, to generate the change set. Call ListStacks to query stack IDs. 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 stack policy file. The URL must point to a policy 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. Maximum policy file size: 16,384 bytes. Maximum URL length: 1,350 bytes. 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 stack name. Maximum length: 255 characters. The name can contain digits, letters, hyphens (-), and underscores (_), and must start with a digit or 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. Call DescribeRegions to query available regions.	cn-hangzhou
ClientToken	string	No	The client token used to ensure request idempotence. The token must be unique across requests and can be up to 64 characters in length, containing letters, digits, hyphens (-), and underscores (_). How to ensure idempotence.	123e4567-e89b-12d3-a456-42665544****
TemplateURL	string	No	The URL of the template file. The URL must point to a template 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. Maximum template body size: 524,288 bytes. 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 temporary overriding stack policy file. The URL must point to a policy 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. Maximum policy file size: 16,384 bytes. Note If you do not specify the region of the OSS bucket, the value of RegionId is used. Maximum URL length: 1,350 bytes. To update protected resources, specify a temporary overriding stack policy. If unspecified, the current stack policy applies. 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 template body. Length: 1 to 524,288 bytes. For large templates, use HTTP POST with a body parameter to avoid URL length limits. Note You can specify only one of the TemplateBody, TemplateURL, and TemplateId parameters.	{"ROSTemplateFormatVersion":"2015-09-01"}
TimeoutInMinutes	integer	No	The timeout period before the stack enters CREATE_FAILED or UPDATE_FAILED state. Required when ChangeSetType is CREATE. Optional when ChangeSetType is UPDATE. Unit: minutes. Valid values: 10 to 1440. Default value: 60.	12
DisableRollback	boolean	No	Specifies whether to disable rollback on stack creation failure. Valid values: true: disables rollback on creation failure. false (default): enables rollback on creation failure. Note This parameter takes effect only when ChangeSetType is set to CREATE or IMPORT.	false
ChangeSetName	string	Yes	The change set name. Maximum length: 255 characters. The name can contain digits, letters, hyphens (-), and underscores (_), and must start with a digit or letter. Note The name of the change set must be unique within the stack.	MyChangeSet
StackPolicyDuringUpdateBody	string	No	The temporary overriding stack policy body. Length: 1 to 16,384 bytes. To update protected resources, specify a temporary overriding policy. If unspecified, the current stack policy applies. 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 RAM role name. ROS assumes this role to call Alibaba Cloud service APIs and always uses it for all stack operations. If you lack the required permissions, ROS assumes the role specified by RamRoleName. If unspecified, ROS uses the existing stack role. If no role is available, ROS uses a temporary credential from your account. Maximum length: 64 bytes. Stack roles.	test-role
ReplacementOption	string	No	Specifies whether to enable replacement update when a resource property change does not support modification updates. A replacement update deletes the existing resource and creates a new one with a new physical ID. 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. Call ListTemplates to query template IDs. 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. Maximum: 5 URLs. Notifications are sent on stack status changes. With rollback enabled, CREATE_FAILED and UPDATE_FAILED are replaced by CREATE_ROLLBACK and ROLLBACK notifications. IN_PROGRESS is not reported. Notifications are sent regardless of the Outputs parameter. 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**`. Call GetTemplateSummary to query resource identifier properties. 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. Call ListTemplateScratches to query scenario IDs.	4a6c9851-3b0f-4f5f-b4ca-a14bf691****
Parallelism	integer	No	The maximum number of concurrent resource operations. By default, this value is empty. Once set, the value is associated with the stack and affects subsequent operations. 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. 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 unspecified, the stack is added to the default resource group. 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

This API also uses Common parameters.

Response elements

Element	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.