PreviewStack - Resource Orchestration Service - Alibaba Cloud Documentation Center

Previews the information about a stack that you want to create based on a template. You can call this operation to verify whether the template resources are valid.

Operation description

This topic provides an example on how to create a stack named MyStack in the China (Hangzhou) region by using a template and preview the information about the stack. In this example, the template body is {"ROSTemplateFormatVersion":"2015-09-01"}.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer.

Debug

Authorization information

The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

Operation: the value that you can use in the Action element to specify the operation on a resource.
Access level: the access level of each operation. The levels are read, write, and list.
Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
- The required resource types are displayed in bold characters.
- If the permissions cannot be granted at the resource level, All Resources is used in the Resource type column of the operation.
Condition Key: the condition key that is defined by the cloud service.
Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.

Operation	Access level	Resource type	Condition key	Associated operation
ros:PreviewStack	get	Stack acs:ros:{#regionId}:{#accountId}:stack/{#StackId}	none	none

Request parameters

Parameter	Type	Required	Description	Example
DisableRollback	boolean	No	Specifies whether to disable rollback for the resources when the stack fails to be created. Valid values: true false (default)	false
TimeoutInMinutes	long	No	The timeout period for creating the stack. Unit: minutes. Default value: 60.	60
TemplateBody	string	No	The structure that contains the template body. The template body must be 1 to 524,288 bytes in length. If the length of the template body exceeds the upper limit, we recommend that you add parameters to the HTTP POST request body to prevent request failures caused by excessively long URLs. Note You must and can specify only one of the following parameters: TemplateBody, TemplateURL, TemplateId, and TemplateScratchId.	{"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 an HTTP or HTTPS web server or in an Object Storage Service (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. If you do not specify the region ID of the OSS bucket, the value of RegionId is used. Note You can specify only one of StackPolicyBody and StackPolicyURL. The URL can be up to 1,350 bytes in length.	oss://ros-stack-policy/demo
RegionId	string	Yes	The region ID of the stack. You can call the DescribeRegions operation to query the most recent region list.	cn-hangzhou
StackPolicyBody	string	No	The structure that contains the stack policy body. The stack policy body must be 1 to 16,384 bytes in length. Note You can specify only one of StackPolicyBody and StackPolicyURL.	{"Statement": [{"Action": "Update:", "Resource": "", "Effect": "Allow", "Principal": "*"}]}
StackName	string	No	The stack name. You can use this parameter to preview the stack that you want to create. The name can be up to 255 characters in length, and can contain digits, letters, hyphens (-), and underscores (_). It must start with a digit or letter. Note You must and can specify only one of StackName and StackId.	MyStack
ClientToken	string	No	The 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, underscores (_), and hyphens (-). For more information, see 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 an HTTP or HTTPS web server 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. If you do not specify the region ID of the OSS bucket, the value of RegionId is used. Note You must and can specify only one of the following parameters: TemplateBody, TemplateURL, TemplateId, and TemplateScratchId.	oss://ros-template/demo
TemplateId	string	No	The template ID. This parameter applies to shared and private templates. Note You must and can specify only one of the following parameters: TemplateBody, TemplateURL, TemplateId, and TemplateScratchId.	5ecd1e10-b0e9-4389-a565-e4c15efc****
TemplateVersion	string	No	The version of the template. This parameter takes effect only when TemplateId is specified.	v1
Parameters	array<object>	No	The parameters of the stack.
	object	No
ParameterKey	string	Yes	The name of the parameter N. If you do not specify the name and value of a parameter, Resource Orchestration Service (ROS) uses the default name and value that are specified in the template. Maximum value of N: 200. Note If you specify Parameters, you must specify Parameters.N.ParameterKey.	ALIYUN::AccountId
ParameterValue	string	Yes	The value of parameter N. Maximum value of N: 200. Note If you specify Parameters, you must specify Parameters.N.ParameterValue.	151266687691****
Parallelism	long	No	The maximum number of concurrent operations that can be performed on resources. This parameter takes effect only for Terraform stacks. By default, this parameter is empty. You can set this parameter to an integer that is greater than or equal to 0. Note If you set this parameter to an integer greater than 0, the integer is used. If you set this parameter to 0 or leave this parameter empty, the default value of Terraform is used. In most cases, the default value of Terraform is 10.	1
TemplateScratchId	string	No	The scenario ID. For more information about how to query the scenario ID, see ListTemplateScratches . Note You must and can specify only one of the following parameters: TemplateBody, TemplateURL, TemplateId, and TemplateScratchId.	ts-aa9c62feab844a6b****
TemplateScratchRegionId	string	No	The region ID of the scenario. The default value is the same as the value of RegionId. You can call the DescribeRegions operation to query the most recent region list.	cn-hangzhou
StackId	string	No	The stack ID. You can use this parameter to preview a stack that you want to update. Note You must and can specify only one of StackName and StackId. In the scenario in which you preview a stack that you want to create or update, you cannot preview the resources in its nested stacks.	4a6c9851-3b0f-4f5f-b4ca-a14bf691****
EnablePreConfig	boolean	No	Specifies whether to query the parameters that you want to use in compliance precheck. Valid values: true false (default)	false

For more information about common request parameters, see Common parameters.

Response parameters

Parameter	Type	Description	Example
	object
RequestId	string	The request ID.	B288A0BE-D927-4888-B0F7-B35EF84B6E6F
Stack	object	The information about the stack that is previewed.
TemplateDescription	string	The description of the template.	One ECS instance.
Parameters	array<object>	The parameters of the stack.
	object
ParameterKey	string	The name of the parameter.	ALIYUN::AccountId
ParameterValue	string	The value of the parameter.	151266687691****
Description	string	The description of the stack.	One ECS instance.
DisableRollback	boolean	Indicates whether rollback is disabled for the resources when the stack fails to be created.	false
StackName	string	The stack name.	MyStack
TimeoutInMinutes	integer	The timeout period for creating the stack. Unit: minutes.	60
StackPolicyBody	object	The structure that contains the stack policy body.	{ "Statement": [ { "Action": "Update:", "Resource": "", "Effect": "Allow", "Principal": "" }, { "Action": "Update:", "Resource": "LogicalResourceId/apple1", "Effect": "Deny", "Principal": "*" } ] }
Resources	array<object>	The resources in the stack.
	object
LogicalResourceId	string	The logical ID of the resource.	WebServer
AcsResourceType	string	The resource type of an Alibaba Cloud service.	ACS::ECS::Instance
ResourceType	string	The resource type.	ALIYUN::ECS::Instance
Description	string	The description of the resource.	ECS instance.
Stack	object	The information about the nested stack. The data structure of the value is the same as the data structure of the entire response.	{}
RequiredBy	array	The resources on which the stack depends.
	string	The resource on which the stack depends.	["Resource1", "Resource2"]
Properties	object	The resource properties.	{ "DiskMappings": [ { "Category": "cloud_ssd", "Size": "20" } ], "SystemDisk_Category": "cloud_ssd", "InstanceChargeType": "PostPaid", "AutoRenew": "False", "WillReplace": true, "ImageId": "centos_7", "InstanceType": "ecs.g6.large", "AllocatePublicIP": true, "AutoRenewPeriod": 1, "IoOptimized": "optimized", "ZoneId": "cn-beijing-g", "VSwitchId": "", "SecurityGroupId": "", "Period": 1, "InternetChargeType": "PayByTraffic", "SystemDiskCategory": "cloud_efficiency", "InternetMaxBandwidthOut": 1, "VpcId": "", "InternetMaxBandwidthIn": 200, "PeriodUnit": "Month" }
Action	string	The action that is performed on the resource. Valid values: Add Modify Remove None	Add
Replacement	string	Indicates whether a replacement update is performed on the template. Valid values: True: A replacement update is performed on the template. False: A change is made on the template. Conditional: A replacement update may be performed on the template. You can check whether a replacement update is performed when the template is in use. Note This parameter is returned only if Action is set to Modify.	False
PhysicalResourceId	string	The physical ID of the resource. This parameter is returned only if Action is set to Modify or Remove.	i-a1b2c3***
RegionId	string	The region where the stack resides.	cn-hangzhou
Log	object	The log that is generated when the stack is run.
TerraformLogs	array<object>	The Terraform logs. This parameter is returned only if the stack is a Terraform stack. Note This parameter contains the logs of previewing the stack.
	object
Command	string	The name of the Terraform command that is run. Valid values: apply plan destroy version For more information about Terraform commands, see Basic CLI Features.	apply
Stream	string	The output stream. Valid values: stdout: standard output stream stderr: standard error stream	stdout
Content	string	The content of the output stream that is returned after the command is run.	Apply complete! Resources: 42 added, 0 changed, 0 destroyed.

Examples

Sample success responses

JSONformat

{
  "RequestId": "B288A0BE-D927-4888-B0F7-B35EF84B6E6F",
  "Stack": {
    "TemplateDescription": "One ECS instance.",
    "Parameters": [
      {
        "ParameterKey": "ALIYUN::AccountId",
        "ParameterValue": "151266687691****"
      }
    ],
    "Description": "One ECS instance.",
    "DisableRollback": false,
    "StackName": "MyStack",
    "TimeoutInMinutes": 60,
    "StackPolicyBody": {
      "Statement": [
        {
          "Action": "Update:*",
          "Resource": "*",
          "Effect": "Allow",
          "Principal": "*"
        },
        {
          "Action": "Update:*",
          "Resource": "LogicalResourceId/apple1",
          "Effect": "Deny",
          "Principal": "*"
        }
      ]
    },
    "Resources": [
      {
        "LogicalResourceId": "WebServer",
        "AcsResourceType": "ACS::ECS::Instance",
        "ResourceType": "ALIYUN::ECS::Instance",
        "Description": "ECS instance.",
        "Stack": {},
        "RequiredBy": [
          "[\"Resource1\", \"Resource2\"]"
        ],
        "Properties": {
          "DiskMappings": [
            {
              "Category": "cloud_ssd",
              "Size": "20"
            }
          ],
          "SystemDisk_Category": "cloud_ssd",
          "InstanceChargeType": "PostPaid",
          "AutoRenew": "False",
          "WillReplace": true,
          "ImageId": "centos_7",
          "InstanceType": "ecs.g6.large",
          "AllocatePublicIP": true,
          "AutoRenewPeriod": 1,
          "IoOptimized": "optimized",
          "ZoneId": "cn-beijing-g",
          "VSwitchId": "",
          "SecurityGroupId": "",
          "Period": 1,
          "InternetChargeType": "PayByTraffic",
          "SystemDiskCategory": "cloud_efficiency",
          "InternetMaxBandwidthOut": 1,
          "VpcId": "",
          "InternetMaxBandwidthIn": 200,
          "PeriodUnit": "Month"
        },
        "Action": "Add",
        "Replacement": "False",
        "PhysicalResourceId": "i-a1b2c3***"
      }
    ],
    "RegionId": "cn-hangzhou",
    "Log": {
      "TerraformLogs": [
        {
          "Command": "apply",
          "Stream": "stdout",
          "Content": "Apply complete! Resources: 42 added, 0 changed, 0 destroyed."
        }
      ]
    }
  }
}

Error codes

For a list of error codes, visit the Service error codes.

Change history

Change time	Summary of changes	Operation
2024-01-11	The internal configuration of the API is changed, but the call is not affected	View Change Details