All Products
Search
Document Center

Resource Orchestration Service:ValidateTemplate

Last Updated:Feb 22, 2024

Validates a template by using a template URL or template body. The template is used to create a stack.

Operation description

In this example, a template that you want to use to create a stack is validated. TemplateURL is set to oss://ros/template/demo.

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:ValidateTemplateREAD
  • All Resources
    *
    none
none

Request parameters

ParameterTypeRequiredDescriptionExample
TemplateURLstringNo

The URL of the file that contains the template body. The URL must point to a template that is located on an HTTP web server or in an Object Storage Service (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.

Note If you do not specify the region ID of the OSS bucket, the value of RegionId is used.

You can specify one of TemplateBody and TemplateURL, but not both of them. The URL can be up to 1,024 bytes in length.\

oss://ros/template/demo
RegionIdstringNo

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

cn-hangzhou
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.
You can specify the TemplateBody or TemplateURL parameter, but not both parameters.

{"ROSTemplateFormatVersion":"2015-09-01"}
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, hyphens (-), and underscores (_).

For more information, see Ensure idempotence.

123e4567-e89b-12d3-a456-42665544****
ValidationOptionstringNo

Specifies whether to enable additional validation for the template. Valid values:

  • None (default): does not enable additional validation.
  • EnableTerraformValidation: runs the terraform validate command in the Terraform CLI to enable additional validation for a Terraform template.
  • EnableFastTerraformValidation: runs a command that is similar to the terraform validate command in the Terraform CLI to enable additional validation for a Terraform template.
Note Compared with the EnableTerraformValidation method, the EnableFastTerraformValidation method validates a template at a faster speed but a lower integrity level.
None
UpdateInfoOptionsarrayNo

The options that are used to control the generation of information about the stack update. You can specify up to two options.

stringNo

The option that is used to control the generation of information about the stack update. Valid values:

  • Disabled: does not generate information about the stack update.
  • ConsiderCondition: generates information about the stack update with conditions considered. We recommend that you use this option. Otherwise, the conditions are calculated, and the default parameter values or a value of null is used for the parameters involved in the calculation.
  • EnableReplacement: generates information about the stack update with replacement updates considered.
ConsiderCondition

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

Response parameters

ParameterTypeDescriptionExample
object
Descriptionstring

The description of the template.

No description
Parametersobject []

The parameters that are defined in the Parameters section of the template.

object

The parameter that is defined in the Parameters section of the template.
The Parameters section contains the parameters that you must specify when you use the template to create a stack. You can use the parameters to specify the stack details, such as the username, password, and environment-related Elastic Compute Service (ECS) instance type.

[{"Description": "", "Label": "param_integer", "NoEcho": "false", "ParameterKey": "param_integer", "Type": "Number"},{ "Description": "", "Label": "param_float", "NoEcho": "false", "ParameterKey": "param_float", "Type": "Number"}]
RequestIdstring

The request ID.

B288A0BE-D927-4888-B0F7-B35EF84B6E6F
Outputsobject []

The outputs of the template.

OutputKeystring

The name of the template output.

instance_id
Descriptionstring

The description of the template output.

The instance ID of my ECS.
Labelstring

The alias of the template output.

Instance ID
ResourceTypesobject

The resource types that are used in the template.

Resourcesarray

The regular resource types that are used in the template. The value is deduplicated.

string

The regular resource type that is used in the template.

ALIYUN::ECS::InstanceGroup
DataSourcesarray

The DataSource resource types that are used in the template. The value is deduplicated.

string

The DataSource resource type that is used in the template.

DATASOURCE::VPC::Vpcs
Resourcesobject []

The regular resources that are defined in the template.

Note
  • For a Resource Orchestration Service (ROS) template, the resource whose definition contains Count is not displayed as a list.
  • For a Terraform template, the resource whose definition contains count or for_each is not displayed as a list.
  • ResourceTypestring

    The regular resource type.

    ALIYUN::ECS::InstanceGroup
    ResourcePathstring

    The path of the regular resource. In most cases, the path of a regular resource is the same as the resource name.

    server
    LogicalResourceIdPatternstring

    The pattern in which the logical IDs of regular resources are formed.

    If resources are defined in a ROS template, the following rules apply:

    • Resource whose definition does not contain Count: If the resource name defined in the template is server, the values of LogicalResourceIdPattern and ResourcePath are both server.``
    • Resource whose definition contains Count: If the resource name defined in the template is server, the value of LogicalResourceIdPattern is server[*], and the value of ResourcePath is server.

    If resources and modules are defined in a Terraform template, the following rules apply:

    • Resource and module whose definitions do not contain count or for_each: If the resource name defined in the template is server, the values of LogicalResourceIdPattern and ResourcePath are both server.``
    • Resource and module whose definitions contain count or for_each: If the resource name defined in the template is server, the value of LogicalResourceIdPattern is server[*], and the value of ResourcePath is server.

    Examples of LogicalResourceIdPattern for resources in a Terraform template:

    • Valid values of LogicalResourceIdPattern if a resource belongs to the root module:

      • server: In this case, count and for_each are not contained in the resource. The value of ResourcePath is server.
      • server[*]: In this case, count or for_each is contained in the resource. The value of ResourcePath is server.
    • Valid values of LogicalResourceIdPattern if a resource belongs to a child module:

      • app.server: In this case, count and for_each are not contained in the app module and the server resource. The value of ResourcePath is app.server.````
      • app.server[*]: In this case, count or for_each is contained in the server resource, but count and for_each are not contained in the app module. The value of ResourcePath is app.server.
      • app[*].server: In this case, count or for_each is contained in the app module, but count and for_each are not contained in the server resource. The value of ResourcePath is app.server.
      • app[*].server[*]: In this case, count or for_each is contained in the app module and the server resource. The value of ResourcePath is app.server.````
      • app.app_group[*].server: In this case, count or for_each is contained in the app_group module, but count and for_each are not contained in the app module and the server resource. The value of ResourcePath is app.app_group.server. The app_group module is a child module of the app module.````
    server
    UpdateInfoobject

    The information about the stack update. This parameter cannot be returned if the value of UpdateInfoOptions contains Disabled.

    ParametersAllowedToBeModifiedarray

    The parameters that can be modified.

    string

    The parameter that can be modified. If you change only values of the parameters in a stack template and use the template to update the stack, no validation errors are caused.

    param1
    ParametersCauseInterruptionIfModifiedarray

    The parameters whose changes cause service interruptions.

    Note
  • This parameter is supported only for a small number of resource types.
  • This parameter is valid only for updates on ROS stacks.
  • string

    The parameter whose change causes a service interruption. If you change only values of the parameters in a stack template and use the template to update the stack, service interruptions are caused.

    param1
    ParametersConditionallyAllowedToBeModifiedarray

    The parameters that can be modified under specific conditions.

    string

    The parameter that can be modified under specific conditions. If you change only values of the parameters in a stack template and use the template to update the stack, the new values of the parameters determine whether validation errors are caused.

    param2
    ParametersConditionallyCauseInterruptionIfModifiedarray

    The parameters whose changes cause service interruptions under specific conditions.

    Note
  • This parameter is supported only for a small number of resource types.
  • This parameter is valid only for updates on ROS stacks.
  • string

    The parameter whose change causes a service interruption under specific conditions. If you change only values of the parameters in a stack template and use the template to update the stack, the new values and the update type determine whether service interruptions are caused.

    param2
    ParametersNotAllowedToBeModifiedarray

    The parameters that cannot be modified.

    string

    The parameter that cannot be modified. If you change only values of the parameters in a stack template and use the template to update the stack, validation errors are caused.

    param3
    ParametersUncertainlyAllowedToBeModifiedarray

    The parameters that can be modified under uncertain conditions.

    string

    The parameter that can be modified under uncertain conditions. If you change only values of the parameters in a stack template and use the template to update the stack, the actual running environment determines whether validation errors are caused.

    param4
    ParametersUncertainlyCauseInterruptionIfModifiedarray

    The parameters whose changes cause service interruptions under uncertain conditions.

    Note
  • This parameter is supported only for a small number of resource types.
  • This parameter is valid only for updates on ROS stacks.
  • string

    The parameter whose change causes a service interruption under uncertain conditions. If you change only values of the parameters in a stack template and use the template to update the stack, the actual running environment determines whether service interruptions are caused.

    param4
    ParametersCauseReplacementIfModifiedarray

    The parameters whose changes trigger replacement updates for resources.

    Note
  • This parameter can be returned only if the value of UpdateInfoOptions contains EnableReplacement.
  • This parameter is valid only for updates on ROS stacks.
  • string

    The parameter whose change triggers a replacement update for resources. If you change only values of the parameters in a stack template and use the template to update the stack, replacement updates are triggered for resources.

    param5
    ParametersConditionallyCauseReplacementIfModifiedarray

    The parameters whose changes trigger replacement updates for resources under specific conditions.

    Note
  • This parameter can be returned only if the value of UpdateInfoOptions contains EnableReplacement.
  • This parameter is valid only for updates on ROS stacks.
  • string

    The parameter whose change triggers a replacement update for resources under specific conditions. If you change only values of the parameters in a stack template and use the template to update the stack, the new values determine whether replacement updates are triggered for resources.

    param6
    ParametersUncertainlyCauseReplacementIfModifiedarray

    The parameters whose changes trigger replacement updates for resources under uncertain conditions.

    Note
  • This parameter can be returned only if the value of UpdateInfoOptions contains EnableReplacement.
  • This parameter is valid only for updates on ROS stacks.
  • string

    The parameter whose change triggers a replacement update for resources under uncertain conditions. If you change only values of the parameters in a stack template and use the template to update the stack, the actual running environment determines whether replacement updates are triggered for resources.

    param7

    Examples

    Sample success responses

    JSONformat

    {
      "Description": "No description",
      "Parameters": [
        [
          {
            "Description": "",
            "Label": "param_integer",
            "NoEcho": "false",
            "ParameterKey": "param_integer",
            "Type": "Number"
          },
          {
            "Description": "",
            "Label": "param_float",
            "NoEcho": "false",
            "ParameterKey": "param_float",
            "Type": "Number"
          }
        ]
      ],
      "RequestId": "B288A0BE-D927-4888-B0F7-B35EF84B6E6F",
      "Outputs": [
        {
          "OutputKey": "instance_id",
          "Description": "The instance ID of my ECS.",
          "Label": "Instance ID"
        }
      ],
      "ResourceTypes": {
        "Resources": [
          "ALIYUN::ECS::InstanceGroup"
        ],
        "DataSources": [
          "DATASOURCE::VPC::Vpcs"
        ]
      },
      "Resources": [
        {
          "ResourceType": "ALIYUN::ECS::InstanceGroup",
          "ResourcePath": "server",
          "LogicalResourceIdPattern": "server"
        }
      ],
      "UpdateInfo": {
        "ParametersAllowedToBeModified": [
          "param1"
        ],
        "ParametersCauseInterruptionIfModified": [
          "param1"
        ],
        "ParametersConditionallyAllowedToBeModified": [
          "param2"
        ],
        "ParametersConditionallyCauseInterruptionIfModified": [
          "param2"
        ],
        "ParametersNotAllowedToBeModified": [
          "param3"
        ],
        "ParametersUncertainlyAllowedToBeModified": [
          "param4"
        ],
        "ParametersUncertainlyCauseInterruptionIfModified": [
          "param4"
        ],
        "ParametersCauseReplacementIfModified": [
          "param5"
        ],
        "ParametersConditionallyCauseReplacementIfModified": [
          "param6"
        ],
        "ParametersUncertainlyCauseReplacementIfModified": [
          "param7"
        ]
      }
    }

    Error codes

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

    Change history

    Change timeSummary of changesOperation
    2023-07-27The request parameters of the API has changed. The response structure of the API has changedsee changesets
    Change itemChange content
    Input ParametersThe request parameters of the API has changed.
      Added Input Parameters: UpdateInfoOptions
    Output ParametersThe response structure of the API has changed.
    2023-03-28The 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.