All Products
Search
Document Center

Resource Orchestration Service:PreviewStack

Last Updated:Feb 22, 2024

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.

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.
OperationAccess levelResource typeCondition keyAssociated operation
ros:PreviewStackREAD
  • stack
    acs:ros:{#regionId}:{#accountId}:stack/*
    none
none

Request parameters

ParameterTypeRequiredDescriptionExample
DisableRollbackbooleanNo

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

  • true
  • false (default)
false
TimeoutInMinuteslongNo

The timeout period for creating the stack.

Unit: minutes.

Default value: 60.

60
TemplateBodystringNo

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"}
StackPolicyURLstringNo

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
RegionIdstringYes

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

cn-hangzhou
StackPolicyBodystringNo

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": "*"}]}
StackNamestringNo

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
ClientTokenstringNo

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****
TemplateURLstringNo

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
TemplateIdstringNo

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****
TemplateVersionstringNo

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

v1
Parametersobject []No

The parameters of the stack.

ParameterKeystringYes

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
ParameterValuestringYes

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

Note If you specify Parameters, you must specify Parameters.N.ParameterValue.
151266687691****
ParallelismlongNo

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
TemplateScratchIdstringNo

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****
TemplateScratchRegionIdstringNo

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
StackIdstringNo

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****
    EnablePreConfigbooleanNo

    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

    ParameterTypeDescriptionExample
    object
    RequestIdstring

    The request ID.

    B288A0BE-D927-4888-B0F7-B35EF84B6E6F
    Stackobject

    The information about the stack that is previewed.

    TemplateDescriptionstring

    The description of the template.

    One ECS instance.
    Parametersobject []

    The parameters of the stack.

    ParameterKeystring

    The name of the parameter.

    ALIYUN::AccountId
    ParameterValuestring

    The value of the parameter.

    151266687691****
    Descriptionstring

    The description of the stack.

    One ECS instance.
    DisableRollbackboolean

    Indicates whether rollback is disabled for the resources when the stack fails to be created.

    false
    StackNamestring

    The stack name.

    MyStack
    TimeoutInMinutesinteger

    The timeout period for creating the stack.

    Unit: minutes.

    60
    StackPolicyBodyobject

    The structure that contains the stack policy body.

    { "Statement": [ { "Action": "Update:*", "Resource": "*", "Effect": "Allow", "Principal": "*" }, { "Action": "Update:*", "Resource": "LogicalResourceId/apple1", "Effect": "Deny", "Principal": "*" } ] }
    Resourcesobject []

    The resources in the stack.

    LogicalResourceIdstring

    The logical ID of the resource.

    WebServer
    AcsResourceTypestring

    The resource type of an Alibaba Cloud service.

    ACS::ECS::Instance
    ResourceTypestring

    The resource type.

    ALIYUN::ECS::Instance
    Descriptionstring

    The description of the resource.

    ECS instance.
    Stackobject

    The information about the nested stack. The data structure of the value is the same as the data structure of the entire response.

    {}
    RequiredByarray

    The resources on which the stack depends.

    string

    The resource on which the stack depends.

    ["Resource1", "Resource2"]
    Propertiesobject

    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" }
    Actionstring

    The action that is performed on the resource. Valid values:

    • Add
    • Modify
    • Remove
    • None
    Add
    Replacementstring

    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
    PhysicalResourceIdstring

    The physical ID of the resource.

    This parameter is returned only if Action is set to Modify or Remove.

    i-a1b2c3***
    RegionIdstring

    The region where the stack resides.

    cn-hangzhou
    Logobject

    The log that is generated when the stack is run.

    TerraformLogsobject []

    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.
    Commandstring

    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
    Streamstring

    The output stream. Valid values:

    • stdout: standard output stream
    • stderr: standard error stream
    stdout
    Contentstring

    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 timeSummary of changesOperation
    2024-01-11The internal configuration of the API is changed, but the call is not affectedsee changesets
    Change itemChange content
    The internal configuration of the API is changed, but the call is not affected.