Modify ROS Stack Resources Safely via UpdateStack API - ROS - Alibaba Cloud - Resource Orchestration Service

Updates the resources in a stack.

Operation description

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

If UsePreviousParameters is set to false, the parameter uses its default value from the template. If the parameter does not have a default value, you must specify it in Parameters.
If UsePreviousParameters is set to true, the parameter retains its value from the previous stack creation. If no value was specified at that time and the template provides a default, that default value is used.

This example shows how to update the template for a stack with the ID 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 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: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	A client-generated token to ensure the idempotency of the request. The token must be globally unique. The token can be up to 64 characters long and can contain letters, digits, hyphens (-), and underscores (_). For more information, see How to ensure idempotence.	123e4567-e89b-12d3-a456-42665544****
StackPolicyDuringUpdateBody	string	No	The temporary override for the stack policy body. The policy body can be 1 to 16,384 bytes long. If you want to update protected resources, specify a temporary stack policy override 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 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 stack update, in minutes. Default value: 60. Unit: minutes.	10
TemplateBody	string	No	The template body. The template body can be 1 to 524,288 bytes long. If the template body is large, we recommend that you use the POST request method and pass the parameter in the request body to prevent request failures due to an excessively long URL. Note You can specify only one of the `TemplateBody`, `TemplateURL`, and `TemplateId` parameters.	{"ROSTemplateFormatVersion": "2015-09-01"}
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 Object Storage Service (OSS) bucket, for example, `oss://ros/stack-policy/demo` or `oss://ros/stack-policy/demo?RegionId=cn-hangzhou`. The policy file can be up to 16,384 bytes long. If you do not specify the OSS region in the URL, the region specified by the RegionId parameter is used. Note You can specify only one of the `StackPolicyBody` and `StackPolicyURL` parameters. The URL can be up to 1,350 bytes long.	oss://ros-stack-policy/demo
StackPolicyDuringUpdateURL	string	No	The URL of the file that contains the temporary stack policy override. The URL must point to a policy that is located on a web server (HTTP or HTTPS) or in an Alibaba Cloud OSS bucket, for example, `oss://ros/stack-policy/demo` or `oss://ros/stack-policy/demo?RegionId=cn-hangzhou`. The policy file can be up to 16,384 bytes long. Note If you do not specify the OSS region in the URL, the region specified by the RegionId parameter is used. The URL can be up to 1,350 bytes long. If you want to update protected resources, you must specify a temporary stack policy override 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 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 stack policy body. The policy body can be 1 to 16,384 bytes long. Note You can specify only one of the `StackPolicyBody` and `StackPolicyURL` parameters.	{"Statement": [{"Action": "Update:", "Resource": "", "Effect": "Allow", "Principal": "*"}]}
UsePreviousParameters	boolean	No	Specifies whether to reuse the values of parameters that are not specified in the current request. Valid values: true: The values of unspecified parameters are reused from the previous request. false: The values of unspecified parameters are not reused from the previous request.	true
RegionId	string	Yes	The ID of the region where the stack is located. You can call the DescribeRegions operation to query the most recent list of Alibaba Cloud regions.	cn-beijing
DisableRollback `deprecated`	boolean	No	(This parameter is deprecated and has no effect.)
TemplateURL	string	No	The location of the file that contains the template body. The URL must point to a template (1 to 524,288 bytes) that is located on an HTTP or HTTPS web server or in an Alibaba Cloud OSS bucket. The URL of an OSS bucket is in a format such as oss://ros/template/demo or oss://ros/template/demo?RegionId=cn-hangzhou. If an OSS region is not specified, the region defaults to the one specified by the RegionId parameter. Note You must specify exactly one of the TemplateBody, TemplateURL, or TemplateId parameters.	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 make API calls on your behalf. ROS always uses this role for operations on the stack. If you have permissions to perform operations on the stack, ROS uses this role even if you do not have permissions to use the role. This ensures that the role is granted the minimum required permissions. For more information about how to use RAM roles, see Use stack roles. If you do not specify this value, ROS uses the role that was previously associated with the stack. If no role is available, ROS uses temporary credentials that are generated from your user credentials. The maximum length of the RAM role name is 64 bytes.	test-role
ReplacementOption	string	No	Whether to use a replacement update. When the properties of a resource do not support modification updates, you can use a replacement update to change the resource properties. A replacement update deletes the resource and then recreates it. The physical ID of the new resource will change. Valid values: Enabled: Allows replacement updates. Disabled (default): Does not allow replacement updates. Note Modification updates have a higher priority than replacement updates.	Disabled
TemplateId	string	No	The ID of the template. This parameter applies to shared and private templates. 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. This parameter takes effect only when you specify `TemplateId`.	v1
Parameters	array<object>	No	The parameters of the template.
	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. You can specify a maximum of 200 parameters. Note `Parameters` is an optional parameter. If you specify `Parameters`, you must also specify `Parameters.N.ParameterKey` and `Parameters.N.ParameterValue`.	Amount
ParameterValue	string	Yes	The value of the parameter. You can specify a maximum of 200 parameters. Note `Parameters` is an optional parameter. If you specify `Parameters`, you must also specify `Parameters.N.ParameterKey` and `Parameters.N.ParameterValue`.	12
Tags	array<object>	No	The tags of the stack.
	object	No
Key	string	Yes	The tag key of the stack. You can specify up to 20 tags. Note `Tags` is an optional parameter. If you specify `Tags`, you must specify `Tags.N.Key`. These tags are propagated to all taggable resources in the stack. For more information, see Tag propagation.	usage
Value	string	No	The tag value of the stack. You can specify up to 20 tags. Note These tags are propagated to all taggable resources 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 specify an integer that is greater than or equal to 0. Note If you set this parameter to a value greater than 0, the value is used. If you set this parameter to 0, no limit is imposed on the number of concurrent operations for ROS-type stacks. For Terraform-type stacks, the default value (typically 10) is used. If you do not specify this parameter, the value from the last operation is used. If this parameter was not specified in the last operation, no limit is imposed for ROS-type stacks, and the default value (typically 10) is used for Terraform-type stacks. If you specify this parameter, the specified value is associated with the stack and affects subsequent operations on the stack.	1
ResourceGroupId	string	No	The resource group ID.	rg-acfmxazb4ph6aiy****
DryRun	boolean	No	Specifies whether to perform only a dry run for the request. Valid values: true: performs a dry run to check the request. The operation is not performed. false (default): performs the operation. Note If you update a stack without making any changes, the operation fails with a NotSupported error if DryRun is false. If DryRun is true, no error is reported.	false
DryRunOptions	array	No	The dry run options. The list can contain a maximum of one item. Note This parameter takes effect only when `DryRun` is set to `true`.
	string	No	The dry run option. Valid values: ParameterAnalysis.ConsiderCondition: We recommend that you use this option if you need to perform parameter analysis. Otherwise, when conditions are calculated, the parameter values that are used are the parameter values before the stack update. Note This option is available only for ROS-type stacks. ParameterAnalysis.Disabled: disables parameter analysis. If you specify this option, the `Parameters` fields are not returned in the `DryRunResult` response.	ParameterAnalysis.ConsiderCondition

For details on common request parameters, see 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****
DryRunResult	object	The dry run result. This parameter is returned only when `DryRun` is set to `true`.
ParametersAllowedToBeModified	array	The parameters that can be modified.
	string	A parameter that can be modified. If you update a stack without changing the template, modifying only the value of this parameter does not cause a validation error.	param1
ParametersConditionallyAllowedToBeModified	array	The parameters that can be modified under specific conditions.
	string	A parameter that can be modified under specific conditions. If you update a stack without changing the template, whether modifying only this parameter's value causes a validation error depends on its new value.	param2
ParametersUncertainlyAllowedToBeModified	array	The parameters for which it is uncertain whether they can be modified.
	string	A parameter for which it is uncertain whether it can be modified. If you update a stack without changing the template, whether modifying only this parameter's value causes a validation error is determined at runtime.	param3
ParametersNotAllowedToBeModified	array	The parameters that cannot be modified.
	string	A parameter that cannot be modified. If you update a stack without changing the template, modifying only this parameter's value always causes a validation error.	param4
ParametersCauseInterruptionIfModified	array	A list of parameters that always cause a resource interruption if modified. Note This feature is supported for only a limited number of resource types. This applies only to ROS stack updates.
	string	A parameter that always causes a resource interruption if modified. If you update a stack without changing the template, modifying only this parameter's value always causes a resource interruption.	param1
ParametersConditionallyCauseInterruptionIfModified	array	A list of parameters that may cause a resource interruption if modified. Note This feature is supported for only a limited number of resource types. This applies only to ROS stack updates.
	string	A parameter that may cause a resource interruption if modified. If you update a stack without changing the template, whether modifying only this parameter's value causes a resource interruption depends on its new value and the resource's update behavior.	param2
ParametersUncertainlyCauseInterruptionIfModified	array	A list of parameters for which it is uncertain whether a modification will cause a resource interruption. Note This feature is supported for only a limited number of resource types. This applies only to ROS stack updates.
	string	A parameter for which it is uncertain whether a modification will cause a resource interruption. If you update a stack without changing the template, whether modifying only this parameter's value causes a resource interruption is determined at runtime.	param3
ParametersCauseReplacementIfModified	array	A list of parameters that always cause a resource replacement if modified. Note This parameter is returned only when `ReplacementOption` is set to `Enabled`. This applies only to ROS stack updates.
	string	A parameter that always causes a resource replacement if modified. If you update a stack without changing the template, modifying only this parameter's value always causes a resource replacement.	param5
ParametersConditionallyCauseReplacementIfModified	array	A list of parameters that may cause a resource replacement if modified. Note This parameter is returned only when `ReplacementOption` is set to `Enabled`. This applies only to ROS stack updates.
	string	A parameter that may cause a resource replacement if modified. If you update a stack without changing the template, whether modifying only this parameter's value causes a resource replacement depends on its new value.	param6
ParametersUncertainlyCauseReplacementIfModified	array	A list of parameters for which it is uncertain whether a modification will cause a resource replacement. Note This parameter is returned only when `ReplacementOption` is set to `Enabled`. This applies only to ROS stack updates.
	string	A parameter for which it is uncertain whether a modification will cause a resource replacement. If you update a stack without changing the template, whether modifying only this parameter's value causes a resource replacement is 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.