Call UpdateStack to update resource stack - Resource Orchestration Service

Updates the resource information of a created stack.

Operation description

The relationship between the Parameters and UsePreviousParameters parameters in the request. If a parameter defined in the template is not specified in Parameters:

When UsePreviousParameters is set to false: If the parameter in the template has a default value, the default value is used. If the parameter does not have a default value, you must specify it in the Parameters.
When UsePreviousParameters is set to true: When creating a stack: If a value is specified for the parameter, the specified value is used. If no value is specified and the template defines a default value, the default value is used.

This topic provides an example of how to update the template content of a stack with the ID of 4a6c9851-3b0f-4f5f-b4ca-a14bf691**** in the China (Beijing) region 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 support 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:UpdateStack

update

*stack

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

Template

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

None

Request parameters

Parameter	Type	Required	Description	Example
StackId	string	Yes	The stack ID.	4a6c9851-3b0f-4f5f-b4ca-a14bf691****
ClientToken	string	No	Ensures the idempotency of the request. This parameter must be generated by the client and must be globally unique. The value must not exceed 64 characters in length and can contain letters, digits, hyphens (-), and underscores (_). For more information, refer to How to ensure idempotence.	123e4567-e89b-12d3-a456-42665544****
StackPolicyDuringUpdateBody	string	No	The structure that the temporary override for the stack policy body. The length must be between 1 and 16,384 bytes. To update protected resources, you must specify a temporary stack policy override during the update process. If no policy is specified, the current policy associated with the stack will be used. This parameter takes effect only when the change set type is UPDATE. You can specify only one of the following parameters: StackPolicyBody StackPolicyURL StackPolicyDuringUpdateBody StackPolicyDuringUpdateURL	{"Statement": [{"Effect": "Allow", "Action": "Update:", "Principal": "", "Resource": "*"}]}
TimeoutInMinutes	integer	No	The timeout period for the update operation on the stack. Default value: 60. Unit: minutes.	10
TemplateBody	string	No	The structure of the template body. The length must be between 1 to 524,288 bytes. If the template body is large, we recommend that you use the HTTP POST+Body Param method to prevent request failures due to the long URL length. Note You must specify only one of the following parameters: TemplateBody, TemplateURL, or TemplateId.	{"ROSTemplateFormatVersion": "2015-09-01"}
StackPolicyURL	string	No	The location 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 (e.g., 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 the RegionId parameter. Note You can specify only one of the following parameters: StackPolicyBody or StackPolicyURL. The URL can be up to 1,350 bytes in length.	oss://ros-stack-policy/demo
StackPolicyDuringUpdateURL	string	No	The location 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 (e.g., 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. Note If the OSS region is not specified in the URL, it defaults to the value of the RegionId parameter. 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 policy, the existing policy that is associated with the stack is used. This parameter takes effect only when the change set type is UPDATE. You can specify only one of the following parameters: StackPolicyBody StackPolicyURL StackPolicyDuringUpdateBody StackPolicyDuringUpdateURL	oss://ros-stack-policy/demo
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": "*"}]}
UsePreviousParameters	boolean	No	Specifies whether parameters that are not passed will use the values from the previous request. Valid values: true: parameters that are not passed will use the values from the previous request. false: parameters that are not passed will not use the values from the previous request.	true
RegionId	string	Yes	The region ID of the stack. You can call DescribeRegions to query the most recent region list.	cn-beijing
DisableRollback`deprecated`	boolean	No	(This parameter is deprecated and has no effect)	false
TemplateURL	string	No	The URL of the file that contains the template body. The URL must point to a template that is located on an HTTP web server (HTTP or HTTPS) or in an Alibaba Cloud OSS bucket. The template body can be 1 to 524,288 bytes in length. Examples of OSS bucket URLs: oss://ros/template/demo or oss://ros/template/demo?RegionId=cn-hangzhou. If the OSS region is not specified in the URL, it defaults to the value of the RegionId parameter. Note You must specify only one of the following parameters: TemplateBody, TemplateURL, or TemplateId.	oss://ros-template/demo
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 other services. ROS assumes the RAM role to perform operations on the stack. If you have permissions to perform operations on the stack, ROS uses the RAM role even if you do not have permissions to use the role. Make sure that the least privilege principle is followed when you specify the RAM role. For more information about how to use the RAM role, see Use stack roles. If you do not specify this parameter, ROS assumes the existing role of the stack. If no roles are available, ROS uses a temporary credential that is generated from your account. The RAM role name can be up to 64 characters in length.	test-role
ReplacementOption	string	No	Specifies whether to enable the replacement update feature. If you cannot change resource properties, you can enable the replacement update feature to replace the resource properties. A replacement update deletes the existing resource and creates a new one to replace it. The physical ID of the new resource is different from that of the deleted resource. Valid values: Enabled Disabled (default) Note Changes have higher priorities than replacement updates.	Disabled
TemplateId	string	No	The ID of the template. This parameter applies to shared and private templates. Note You must specify only one of the following parameters: TemplateBody, TemplateURL, or TemplateId.	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	No	The parameters.
	object	No
ParameterKey	string	Yes	The name of the parameter. 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. Note Parameters is an optional parameter. To specify Parameters, you must specify both Parameters.N.ParameterKey and Parameters.N.ParameterValue.	Amount
ParameterValue	string	Yes	The value of the parameter. The maximum value of N is 200. Note Parameters is an optional parameter. To specify Parameters, you must specify both Parameters.N.ParameterKey and Parameters.N.ParameterValue.	12
Tags	array	No	The tags of the stack.
	object	No
Key	string	Yes	The tag key of the stack. Valid values of N: 1 to 20. Note Tags is an optional parameter. To specify Tags, you must specify Tags.N.Key. The specified tag is propagated to each resource that supports tags in a stack. For more information, see Tag propagation.	usage
Value	string	No	The tag value of 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 Tag propagation.	test
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 that is greater than 0, the integer is used. If you set this parameter to 0, 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 leave this parameter empty, the value that you specified for this parameter in the previous request is used. If you left this parameter empty in the previous request, 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 can affect subsequent operations on the stack.	1
ResourceGroupId	string	No	The ID of the resource group.	rg-acfmxazb4ph6aiy****
DryRun	boolean	No	Specifies whether only to validate the stack in the request. Valid values: true: only validates the stack, no execution. false (default): execute and update the stack. Note When you update a stack without making changes: If DryRun is set to false, an error is returned with the error code NotSupported. If DryRun is set to true, no error is returned.	false
DryRunOptions	array	No	The list of the dry run option. The list can contain only one item. Note This parameter takes effect only when DryRun is set to true.
	string	No	The dry run option. Valid values: ParameterAnalysis.ConsiderCondition: performs parameter analysis with conditions considered. If you want to perform parameter analysis, we recommend that you use this option. Otherwise, conditions are calculated, and the parameter values before the stack is updated are used for the parameters involved in the calculation. Note This option applies only to ROS stacks. ParameterAnalysis.Disabled: disables parameter analysis. If you set this option, the Parameters* fields are not returned in DryRunResult.	ParameterAnalysis.ConsiderCondition

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

Response parameters

Parameter	Type	Description	Example
	object
RequestId	string	The ID of the request.	B288A0BE-D927-4888-B0F7-B35EF84B6E6F
StackId	string	The ID of the stack.	4a6c9851-3b0f-4f5f-b4ca-a14bf691****
DryRunResult	object	The dry run results. This parameter is returned only when DryRun is set to true.
ParametersAllowedToBeModified	array	The parameters that can be modified.
	string	The parameters that can be modified. If you only change the parameter values in a stack template and use it to update the stack, no validation errors are caused.	param1
ParametersConditionallyAllowedToBeModified	array	The parameters that can be modified under specific conditions.
	string	The parameters that can be modified under specific conditions. If you only change the parameter values in a stack template and use it to update the stack, whether a validation error is triggered depends on the value of the parameter.	param2
ParametersUncertainlyAllowedToBeModified	array	The parameters that can be modified under uncertain conditions.
	string	The parameters that can be modified under uncertain conditions. If you only change the parameter values in a stack template and use it to update the stack, whether modifying this parameter triggers a validation error can only be determined at runtime.	param3
ParametersNotAllowedToBeModified	array	The parameters that cannot be modified. If you only change the parameter values in a stack template and use it to update the stack, a validation error will always be triggered.
	string	The parameters that cannot be modified.	param4
ParametersCauseInterruptionIfModified	array	The parameters whose changes cause service interruptions. Note This parameter is supported only for a small number of resource types. This parameter applies only to ROS stacks.
	string	The parameter whose change causes a service interruption. If you only change the parameter values in a stack template and use it to update the stack, modifying only the parameter values will always cause resource interruption.	param1
ParametersConditionallyCauseInterruptionIfModified	array	The parameters whose changes cause service interruptions under specific conditions. Note This parameter is supported only for a small number of resource types. This parameter applies only to ROS stacks.
	string	The parameter whose change causes service interruptions under specific conditions. If you only change the parameter values in a stack template and use it to update the stack, modifying this parameter may cause resource interruption, depending on the parameter value and the update behavior of the resource.	param2
ParametersUncertainlyCauseInterruptionIfModified	array	The parameters whose changes cause service interruptions under uncertain conditions. Note This parameter is supported only for a small number of resource types. This parameter applies only to ROS stacks.
	string	The parameter whose change causes a service interruption under uncertain conditions. If you only change the parameter values in a stack template and use it to update the stack, whether the parameter causes resource interruption can only be determined at runtime.	param3
ParametersCauseReplacementIfModified	array	The parameters whose changes trigger replacement updates for resources. Note This parameter is returned only when ReplacementOption is set to Enabled. This parameter applies only to ROS stacks.
	string	The parameter whose change triggers a replacement update for resources. If you only change the parameter values in a stack template and use it to update the stack, this will always trigger a resource replacement.	param5
ParametersConditionallyCauseReplacementIfModified	array	The parameters whose changes trigger replacement updates for resources under specific conditions. Note This parameter is returned only when ReplacementOption is set to Enabled. This parameter applies only to ROS stacks.
	string	The parameter whose change triggers a replacement update for resources under specific conditions. If you only change the parameter values in a stack template and use it to update the stack, this may result in resource replacement, depending on the value.	param6
ParametersUncertainlyCauseReplacementIfModified	array	The parameters whose changes trigger replacement updates for resources under uncertain conditions. Note This parameter is returned only when ReplacementOption is set to Enabled. This parameter applies only to ROS stacks.
	string	The parameter whose change triggers a replacement update for resources under uncertain conditions. If you only change the parameter values in a stack template and use it to update the stack, whether this parameter causes a resource replacement can only be determined at runtime.	param7

Examples

Success response

JSON format

{
  "RequestId": "B288A0BE-D927-4888-B0F7-B35EF84B6E6F",
  "StackId": "4a6c9851-3b0f-4f5f-b4ca-a14bf691****",
  "DryRunResult": {
    "ParametersAllowedToBeModified": [
      "param1"
    ],
    "ParametersConditionallyAllowedToBeModified": [
      "param2"
    ],
    "ParametersUncertainlyAllowedToBeModified": [
      "param3"
    ],
    "ParametersNotAllowedToBeModified": [
      "param4"
    ],
    "ParametersCauseInterruptionIfModified": [
      "param1"
    ],
    "ParametersConditionallyCauseInterruptionIfModified": [
      "param2"
    ],
    "ParametersUncertainlyCauseInterruptionIfModified": [
      "param3"
    ],
    "ParametersCauseReplacementIfModified": [
      "param5"
    ],
    "ParametersConditionallyCauseReplacementIfModified": [
      "param6"
    ],
    "ParametersUncertainlyCauseReplacementIfModified": [
      "param7"
    ]
  }
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.