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

Updates the resource information of a created stack.

Operation description

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

If UsePreviousParameters is set to false: the default value of the parameter in the template is used if available. If no default value exists, you must specify the parameter in Parameters.
If UsePreviousParameters is set to true: if the parameter was specified when the stack was created, the specified value is used. If the parameter was not specified when the stack was created and the parameter has a default value in the template, the default value is used.

This topic provides an example to show how to update the template content of a stack in the China (Beijing) region to {"ROSTemplateFormatVersion": "2015-09-01"}. The stack ID is 4a6c9851-3b0f-4f5f-b4ca-a14bf691****.

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	The client token that is used to ensure the idempotence of the request. This parameter value is generated by the client and must be globally unique. 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****
StackPolicyDuringUpdateBody	string	No	The structure of the temporary overriding stack policy body. The value must be 1 to 16,384 bytes in length. To update protected resources, specify a temporary overriding stack policy during the update. If you do not specify a stack policy, the current policy 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 updating the stack. Default value: 60. Unit: minutes.	10
TemplateBody	string	No	The structure of the template body. The value must be 1 to 524,288 bytes in length. If the length is large, we recommend that you use the HTTP POST method with the parameter in the request body to avoid request failures caused by an excessively long URL. Note You must and can only specify one of the following parameters: TemplateBody, TemplateURL, or TemplateId.	{"ROSTemplateFormatVersion": "2015-09-01"}
StackPolicyURL	string	No	The URL of the file that contains the stack policy. The URL must point to a policy 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 maximum file size is 16,384 bytes. If the OSS region is not specified, the value of the RegionId parameter is used by default. 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 URL of the file that contains the stack policy for the update. The URL must point to a policy 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 maximum file size is 16,384 bytes. Note If the OSS region is not specified, the value of the RegionId parameter is used by default. The URL can be up to 1,350 bytes in length. To update protected resources, specify a temporary overriding stack policy during the update. If you do not specify a stack policy, the current policy 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 of the stack policy body. The value must be 1 to 16,384 bytes in length. 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 to use the previously specified values for parameters that are not passed in the current request. Valid values: true: The previously specified values are used for parameters that are not passed. false: The previously specified values are not used for parameters that are not passed.	true
RegionId	string	Yes	The region ID of the stack. You can call the DescribeRegions operation to query the most recent region list.	cn-beijing
DisableRollback `deprecated`	boolean	No	[Deprecated] This parameter has no effect.
TemplateURL	string	No	The URL of the file that contains the template body. The URL must point to a template located on an HTTP web server (HTTP or HTTPS) or in an Alibaba Cloud OSS bucket. The template must be 1 to 524,288 bytes in length. Examples of the OSS bucket URL: oss://ros/template/demo or oss://ros/template/demo?RegionId=cn-hangzhou. If the OSS region is not specified, the value of the RegionId parameter is used by default. Note You must and can only specify one of the following parameters: TemplateBody, TemplateURL, or TemplateId.	oss://ros-template/demo
RamRoleName	string	No	The name of the RAM role. Resource Orchestration Service (ROS) assumes the role to create the stack and uses the credentials of the role to call the APIs of each service on behalf of the user. ROS always uses this role for all operations performed on the stack. As long as the user has the permission to perform operations on the stack, ROS uses this role even if the user does not have the permission to use the role. Ensure that the role is granted the least privilege. For more information about how to use RAM roles, see Use a stack role. If you do not specify this parameter, ROS uses the role previously associated with the stack. If no role is available, ROS uses a temporary credential generated from the credentials of your user. The RAM role name can be up to 64 bytes in length.	test-role
ReplacementOption	string	No	Specifies whether to use replacement update. If a resource property does not support modification update, you can use replacement update to change the resource property. Replacement update deletes the resource and then recreates it. The physical ID of the new resource changes. Valid values: Enabled: Replacement update is allowed. Disabled (default): Replacement update is not allowed. Note Modification update takes priority over replacement update.	Disabled
TemplateId	string	No	The template ID. Both shared templates and private templates are supported. Note You must and can only specify one of the following parameters: TemplateBody, TemplateURL, or TemplateId.	5ecd1e10-b0e9-4389-a565-e4c15efc****
TemplateVersion	string	No	The template version. This parameter takes effect only when TemplateId is specified.	v1
Parameters	array<object>	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 specified in the template. Maximum value of N: 200. Note Parameters is optional. If you specify Parameters, you must specify both Parameters.N.ParameterKey and Parameters.N.ParameterValue.	Amount
ParameterValue	string	Yes	The value of the parameter. Maximum value of N: 200. Note Parameters is optional. If you specify Parameters, you must specify both 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. Valid values of N: 1 to 20. Note Tags is optional. If you specify Tags, you must specify Tags.N.Key. This tag is propagated to each resource in the stack that supports tags. For more information, see Propagate tags.	usage
Value	string	No	The tag value of the stack. Valid values of N: 1 to 20. Note This tag is propagated to each resource in the stack that supports tags. For more information, see Propagate tags.	test
Parallelism	integer	No	The maximum number of concurrent resources. Default value: empty. You can enter an integer greater than or equal to zero. Note If you set this parameter to an integer greater than zero, the integer is used. If you set this parameter to zero, no limit is imposed for ROS stacks. For Terraform stacks, the Terraform default value is used, which is typically 10. If you do not set this parameter, the settings from the last operation are used. If no value was set during the last operation, no limit is imposed for ROS stacks. For Terraform stacks, the Terraform default value is used, which is typically 10. If you set this parameter, the value is associated with the stack and affects what to do next on the stack.	1
ResourceGroupId	string	No	The resource group ID.	rg-acfmxazb4ph6aiy****
DryRun	boolean	No	Specifies whether to perform only a validation. Valid values: true: Only validation is performed without actually updating the stack. false (default): The stack is actually updated. Note If no changes are made when updating the stack: if DryRun is set to false, a NotSupported error is returned. If DryRun is set to true, no error is returned.	false
DryRunOptions	array	No	The list of validation options. Maximum length of the list: 1. Note This parameter takes effect only when DryRun is set to true.
	string	No	The validation option. Valid values: ParameterAnalysis.ConsiderCondition: considers the impact of conditions during parameter analysis. If you need to perform parameter analysis, use this option. Otherwise, conditions are evaluated, and the parameter values used during evaluation are the values before the stack update. Note This option takes effect only for ROS stacks. ParameterAnalysis.Disabled: disables parameter analysis. If this option is set, the Parameters* fields are not returned in DryRunResult.	ParameterAnalysis.ConsiderCondition
TaintResources	array	No	The list of resources to be marked as tainted.
	string	No	For ROS stacks, set this to the resource name, such as my_vpc. For Terraform stacks, set this to the resource type and resource name, such as alicloud_vpc.my_vpc.	my_vpc

For more information about 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 validation result. This parameter is returned only when DryRun is set to true.
ParametersAllowedToBeModified	array	The parameters that are allowed to be modified.
	string	The parameter that is allowed to be modified. When updating the stack, if the template remains unchanged and only the parameter value is modified, modifying this parameter does not cause a validation error.	param1
ParametersConditionallyAllowedToBeModified	array	The parameters that may be allowed to be modified.
	string	The parameter that may be allowed to be modified. When updating the stack, if the template remains unchanged and only the parameter value is modified, whether modifying this parameter causes a validation error depends on the parameter value.	param2
ParametersUncertainlyAllowedToBeModified	array	The parameters that are uncertain to be allowed to be modified.
	string	The parameter that is uncertain to be allowed to be modified. When updating the stack, if the template remains unchanged and only the parameter value is modified, whether modifying this parameter causes a validation error can only be determined at runtime.	param3
ParametersNotAllowedToBeModified	array	The parameters that are not allowed to be modified.
	string	The parameter that is not allowed to be modified. When updating the stack, if the template remains unchanged and only the parameter value is modified, a validation error is always caused.	param4
ParametersCauseInterruptionIfModified	array	The list of parameters that will definitely cause resource interruption. Note Only a small number of resource types are supported. This applies only to updating ROS stacks.
	string	The parameter that will definitely cause resource interruption. When updating the stack, if the template remains unchanged and only the parameter value is modified, resource interruption is always caused.	param1
ParametersConditionallyCauseInterruptionIfModified	array	The list of parameters that may cause resource interruption. Note Only a small number of resource types are supported. This applies only to updating ROS stacks.
	string	The parameter that may cause resource interruption. When updating the stack, if the template remains unchanged and only the parameter value is modified, whether modifying this parameter causes resource interruption depends on the parameter value and the update behavior of the resource.	param2
ParametersUncertainlyCauseInterruptionIfModified	array	The list of parameters that are uncertain to cause resource interruption. Note Only a small number of resource types are supported. This applies only to updating ROS stacks.
	string	The parameter that is uncertain to cause resource interruption. When updating the stack, if the template remains unchanged and only the parameter value is modified, whether this parameter causes resource interruption can only be determined at runtime.	param3
ParametersCauseReplacementIfModified	array	The list of parameters that will definitely cause resource replacement update. Note This is returned only when ReplacementOption is set to Enabled. This applies only to updating ROS stacks.
	string	The parameter that will definitely cause resource replacement update. When updating the stack, if the template remains unchanged and only the parameter value is modified, resource replacement update is always caused.	param5
ParametersConditionallyCauseReplacementIfModified	array	The list of parameters that may cause resource replacement update. Note This is returned only when ReplacementOption is set to Enabled. This applies only to updating ROS stacks.
	string	The parameter that may cause resource replacement update. When updating the stack, if the template remains unchanged and only the parameter value is modified, whether resource replacement update is caused depends on the parameter value.	param6
ParametersUncertainlyCauseReplacementIfModified	array	The list of parameters that are uncertain to cause resource replacement update. Note This is returned only when ReplacementOption is set to Enabled. This applies only to updating ROS stacks.
	string	The parameter that is uncertain to cause resource replacement update. When updating the stack, if the template remains unchanged and only the parameter value is modified, whether this parameter causes resource replacement update 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.