Previews the information about a stack that you want to create based on a specified template. This helps validate the validity of resources in the template.

This topic provides an example on how to create a stack named MyStack in the China (Hangzhou) region and preview the information about the stack. In this example, the template body of the stack 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. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes PreviewStack

The operation that you want to perform. Set the value to PreviewStack.

DisableRollback Boolean No false

Specifies whether to disable rollback for the resources when the stack fails to be created. Default value: false. Valid values:

  • true
  • false
TimeoutInMinutes Long No 60

The timeout period that is allowed to create the stack.

Unit: minutes.

Default value: 60.

TemplateBody String No {"ROSTemplateFormatVersion":"2015-09-01"}

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 specify only one of the following parameters: TemplateBody, TemplateURL, TemplateId, and TemplateScratchId.
StackPolicyURL String No oss://ros-stack-policy/demo

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 Alibaba Cloud 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 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 in length.

RegionId String Yes cn-hangzhou

The region ID of the stack. You can call the DescribeRegions operation to query the most recent region list.

StackPolicyBody String No {"Statement": [{"Action": "Update:*", "Resource": "*", "Effect": "Allow", "Principal": "*"}]}

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 the StackPolicyBody and StackPolicyURL parameters.
StackName String No MyStack

The name of the stack. 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 (_). The name must start with a digit or letter.

Note You must specify only one of the StackName and StackId parameters.
ClientToken String No 123e4567-e89b-12d3-a456-42665544****

The client token that is used to ensure the idempotence of the request. You can use the client to generate the value, but you must make sure that the value is unique among different requests.

The token can be up to 64 characters in length, and can contain letters, digits, hyphens (-), and underscores (_).

For more information, see Ensure idempotence.

TemplateURL String No oss://ros-template/demo

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 Alibaba Cloud OSS bucket, such as oss://ros/stack-policy/demo or oss://ros/stack-policy/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 the RegionId parameter is used.

Note You must specify only one of the following parameters: TemplateBody, TemplateURL, TemplateId, and TemplateScratchId.
TemplateId String No 5ecd1e10-b0e9-4389-a565-e4c15efc****

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, TemplateId, and TemplateScratchId.
TemplateVersion String No v1

The version of the template. This parameter takes effect only when the TemplateId parameter is specified.

Parameters.N.ParameterKey String Yes ALIYUN::AccountId

The name of 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 the Parameters parameter, you must specify the Parameters.N.ParameterKey parameter.
Parameters.N.ParameterValue String Yes 151266687691****

The value of parameter N. Maximum value of N: 200.

Note If you specify the Parameters parameter, you must specify the Parameters.N.ParameterValue parameter.
Parallelism Long No 1

The maximum number of concurrent operations that can be performed on resources. This parameter takes effect only for Terraform stacks.

This parameter is empty by default. You can set this parameter to an integer 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 it empty, the default value of Terraform is used. In most cases, the default value of Terraform is 10.
TemplateScratchId String No ts-aa9c62feab844a6b****

The ID of the scenario.

For more information about how to query the IDs of scenarios, see ListTemplateScratches.

Note You must specify only one of the following parameters: TemplateBody, TemplateURL, TemplateId, and TemplateScratchId.
TemplateScratchRegionId String No cn-hangzhou

The region ID of the scenario. The default value is the same as the value of the RegionId parameter.

You can call the DescribeRegions operation to query the most recent region list.

StackId String No 4a6c9851-3b0f-4f5f-b4ca-a14bf691****

The ID of the stack. You can use this parameter to preview a stack that you want to update.

Note
  • You must specify only one of the StackName and StackId parameters.
  • 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.
EnablePreConfig Boolean No false

Specifies whether to query the parameters that are used for the compliance precheck feature.

Default value: false. Valid values:

  • true
  • false

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

Response parameters

Parameter Type Example Description
RequestId String B288A0BE-D927-4888-B0F7-B35EF84B6E6F

The ID of the request.

Stack Object

The information about the stack that is previewed.

TemplateDescription String One ECS instance.

The description of the template.

Parameters Array of Parameter

The parameters of the stack.

ParameterKey String ALIYUN::AccountId

The name of the parameter.

ParameterValue String 151266687691****

The value of the parameter.

Description String One ECS instance.

The description of the stack.

DisableRollback Boolean false

Indicates whether rollback is disabled.

StackName String MyStack

The name of the stack.

TimeoutInMinutes Integer 60

The timeout period that is allowed to create the stack.

Unit: minutes.

StackPolicyBody Map

The structure that contains the stack policy body.

Resources Array of Resource

The list of resources in the stack.

LogicalResourceId String WebServer

The logical ID of the resource.

AcsResourceType String ACS::ECS::Instance

The type of the resource that belongs to an Alibaba Cloud service.

ResourceType String ALIYUN::ECS::Instance

The type of the resource.

Description String ECS instance.

The description of the resource.

Stack Map

The information about the nested stack. The data structure of this parameter is the same as that of the entire response.

RequiredBy Array of String ["Resource1", "Resource2"]

The resources on which the stack depends.

Properties Map

The properties of the resource.

Action String Add

The action that is performed on resources. Valid values:

  • Add
  • Modify
  • Remove
  • None
Replacement String False

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 the Action parameter is set to Modify.
RegionId String cn-hangzhou

The region ID of the stack.

Log Object

The log that is generated when the stack is run.

TerraformLogs Array of TerraformLog

The log that is generated when a Terraform stack is run. This parameter is returned only if the stack is a Terraform stack.

Note You can use this parameter to preview the logs of a Terraform stack.
Command String apply

The name of the Terraform command. Valid values:

  • apply
  • plan
  • destroy
  • version

For more information about Terraform commands, see Basic CLI Features.

Stream String stdout

The output stream. Valid values:

  • stdout: the standard output stream
  • stderr: the standard error stream
Content String Apply complete! Resources: 42 added, 0 changed, 0 destroyed.

The content of the output stream that is returned after the command is run.

Examples

Sample requests

http(s)://ros.aliyuncs.com/?Action=PreviewStack
&TemplateBody={"ROSTemplateFormatVersion":"2015-09-01"}
&StackName=MyStack
&RegionId=cn-hangzhou
&<Common request parameters>

Sample success responses

XML format

HTTP/1.1 200 OK
Content-Type:application/xml

<PreviewStackResponse>
    <RequestId>B288A0BE-D927-4888-B0F7-B35EF84B6E6F</RequestId>
    <Stack>
        <TemplateDescription>One ECS instance.</TemplateDescription>
        <Parameters>
            <ParameterKey>ALIYUN::AccountId</ParameterKey>
            <ParameterValue>151266687691****</ParameterValue>
        </Parameters>
        <Description>One ECS instance.</Description>
        <DisableRollback>false</DisableRollback>
        <StackName>MyStack</StackName>
        <TimeoutInMinutes>60</TimeoutInMinutes>
        <Resources>
            <LogicalResourceId>WebServer</LogicalResourceId>
            <AcsResourceType>ACS::ECS::Instance</AcsResourceType>
            <ResourceType>ALIYUN::ECS::Instance</ResourceType>
            <Description>ECS instance.</Description>
            <RequiredBy>["Resource1", "Resource2"]</RequiredBy>
            <Action>Add</Action>
            <Replacement>False</Replacement>
        </Resources>
        <RegionId>cn-hangzhou</RegionId>
        <Log>
            <TerraformLogs>
                <Command>apply</Command>
                <Stream>stdout</Stream>
                <Content>Apply complete! Resources: 42 added, 0 changed, 0 destroyed.</Content>
            </TerraformLogs>
        </Log>
    </Stack>
</PreviewStackResponse>

JSON format

HTTP/1.1 200 OK
Content-Type:application/json

{
  "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,
    "Resources" : {
      "LogicalResourceId" : "WebServer",
      "AcsResourceType" : "ACS::ECS::Instance",
      "ResourceType" : "ALIYUN::ECS::Instance",
      "Description" : "ECS instance.",
      "RequiredBy" : "[\"Resource1\", \"Resource2\"]",
      "Action" : "Add",
      "Replacement" : "False"
    },
    "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, see Service error codes.

For more information about errors common to all operations, see Common errors.

HTTP status code

Error code

Error message

Description

400

CircularDependency

Circular Dependency Found: {reason}.

The error message returned because the template contains circular dependencies. reason indicates the cause of the error.

400

InvalidSchema

{reason}.

The error message returned because the template format is invalid. reason indicates the cause of the error.

400

InvalidTemplateAttribute

The Referenced Attribute ({resource} {name}) is incorrect.

The error message returned because the template contains an invalid reference of the resource property in the Outputs section. resource indicates the resource name. name indicates the property name.

400

InvalidTemplatePropertyType

The specified value type of ({resource} {section}) is incorrect.

The error message returned because the type of the resource property that is defined in a section of the template is invalid. resource indicates the resource name. section indicates the section name.

400

InvalidTemplateReference

The specified reference "{name}" (in {referencer}) is incorrect.

The error message returned because the template contains an invalid reference. name indicates the reference name. referencer indicates the referencer name.

400

InvalidTemplateSection

The template section is invalid: {section}.

The error message returned because the template contains an invalid section. section indicates the section name.

400

InvalidTemplateVersion

The template version is invalid: {reason}.

The error message returned because the template version is invalid. reason indicates the cause of the error.

400

StackValidationFailed

{reason}.

The error message returned because the stack failed to be validated. reason indicates the cause of the error.

400

UnknownUserParameter

The Parameter ({name}) was not defined in template.

The error message returned because the specified parameter is not defined in the template. name indicates the parameter name.

400

UserParameterMissing

The Parameter {name} was not provided.

The error message returned because no value is specified for the parameter defined in the template. name indicates the parameter name.

409

StackExists

The Stack ({name}) already exists.

The error message returned because a stack that has the same name already exists. name indicates the stack name.

404

TemplateNotFound

The Template ({ ID }) could not be found.

The error message returned because the template does not exist. ID indicates the template ID.

404

TemplateNotFound

The Template { ID } with version { version } could not be found.

The error message returned because the specified template or template version does not exist. ID indicates the template ID. version indicates the template version.