All Products
Search
Document Center

:Stack operations

Last Updated:Apr 10, 2024

This topic describes how to use Alibaba Cloud CLI to call API operations that are related to stacks.

CreateStack

You can call this operation to create a stack.

Parameter

Type

Required

Example

Description

--RegionId

String

Yes

cn-hangzhou

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

--StackName

String

Yes

MyStack

The stack name.

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.

--TimeoutInMinutes

Long

Yes

10

The timeout period for creating the stack.

  • Default value: 60.

  • Unit: minutes.

--Parameters.N.ParameterKey

String

No

InstanceId

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.

--Parameters.N.ParameterValue

String

No

i-xxxxxx

The value of parameter N.

Maximum value of N: 200.

--DisableRollback

Boolean

No

false

Specifies whether to disable rollback when the stack fails to be created.

  • true

  • false (default)

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

You can specify one of TemplateBody and TemplateURL, but you cannot specify both of them.

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

Note

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

You can specify one of StackPolicyBody and StackPolicyURL, but you cannot specify both of them.

The URL can be up to 1,350 bytes in length.

--StackPolicyBody

String

No

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

The structure that contains the stack policy body. The policy body must be 1 to 16,384 bytes in length.

You can specify one of StackPolicyBody and StackPolicyURL, but you cannot specify both of them.

--NotificationURLs.N

RepeatList

No

http://example.com/ros-event

The callback URL for receiving stack event N. Only HTTP POST is supported.

  • Maximum value of N: 5.

  • Each URL can be up to 1,024 bytes in length.

When the status of a stack changes, ROS sends a notification to the specified URL. When rollback is enabled for the stack, notifications are sent if the stack is in the CREATE_ROLLBACK or ROLLBACK state, but are not sent if the stack is in the CREATE_FAILED, UPDATE_FAILED, or IN_PROGRESS state.

Note

ROS sends notifications regardless of whether you configure the Outputs section. The following sample code provides an example on the content of a notification:

{
    "Outputs": [
        {
            "Description": "No description given",
            "OutputKey": "InstanceId",
            "OutputValue": "i-xxx"
        }
    ],
    "StackId": "80bd6b6c-e888-4573-ae3b-93d29113****",
    "StackName": "test-notification-url",
    "Status": "CREATE_COMPLETE"
}

--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 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 you cannot specify both of them.

--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 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 only letters, digits, hyphens (-), and underscores (_).

For more information, see Ensure idempotence.

Sample request

 aliyun ros CreateStack --RegionId cn-hangzhou --StackName MyStack --TimeoutInMinutes 10 --TemplateURL oss://ros-template/demo

Sample success response

{
        "StackId": "c18d62d8-51ce-4e8e-b8f6-e00be431****",
        "RequestId": "53C2DB3A-8374-4464-9466-952614EEC159"
}

ListStacks

You can call this operation to query a list of stacks.

Parameter

Type

Required

Example

Description

--RegionId

String

Yes

cn-hangzhou

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

--StackName.N

RepeatList

No

MyStack

The name of stack N.

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. Fuzzy search with the wildcard character (*) is supported.

Valid values of N: 1 to 5.

--Status.N

RepeatList

No

CREATE_COMPLETE

The stack state N.

Valid values:

  • CREATE_IN_PROGRESS

  • CREATE_FAILED

  • CREATE_COMPLETE

  • UPDATE_IN_PROGRESS

  • UPDATE_FAILED

  • UPDATE_COMPLETE

  • DELETE_IN_PROGRESS

  • DELETE_FAILED

  • DELETE_COMPLETE

  • ROLLBACK_IN_PROGRESS

  • ROLLBACK_FAILED

  • ROLLBACK_COMPLETE

  • CHECK_IN_PROGRESS

  • CHECK_FAILED

  • CHECK_COMPLETE

  • REVIEW_IN_PROGRESS

--ParentStackId

String

No

fgce558a-bdd6-d52j-555b-63755971****

The ID of the parent stack.

--ShowNestedStack

Boolean

No

true

Specifies whether to return nested stacks.

--PageNumber

Long

No

1

The page number.

  • Pages start from page 1.

  • Default value: 1.

--PageSize

Long

No

10

The number of entries per page.

  • Maximum value: 100.

  • Default value: 10.

Sample request

aliyun ros ListStacks --RegionId cn-hangzhou

Sample success response

{
        "PageNumber": 3,
        "TotalCount": 4,
        "PageSize": 1,
        "RequestId": "B2B3B873-25AE-4A86-B320-8C7298628393",
        "Stacks": [
                {
                        "StatusReason": "Stack CREATE completed successfully",
                        "Status": "CREATE_COMPLETE",
                        "TimeoutInMinutes": 60,
                        "StackId": "aace595a-a00d-4631-858b-61134991****",
                        "RegionId": "cn-beijing",
                        "CreateTime": "2019-08-26T09:52:06",
                        "DisableRollback": false,
                        "StackName": "Test"
                }
        ]
}

GetStack

You can call this operation to query the information about a stack.

Parameter

Type

Required

Example

Description

--RegionId

String

Yes

cn-hangzhou

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

--StackId

String

Yes

4a6c9851-3b0f-4f5f-b4ca-a14bf691****

The stack ID.

--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 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 only letters, digits, hyphens (-), and underscores (_).

For more information, see Ensure idempotence.

Sample request

aliyun ros GetStack --RegionId cn-hangzhou --StackId 628e9ed4-899b-4e64-8a8c-2a2b00e4****

Sample success response

{        
"Parameters": [
                {
                        "ParameterValue": "22536460730754****",
                        "ParameterKey": "ALIYUN::AccountId"
                },
                {
                        "ParameterValue": "cn-beijing",
                        "ParameterKey": "ALIYUN::Region"
                },
                {
                        "ParameterValue": "628e9ed4-899b-4e64-8a8c-2a2b00e4****",
                        "ParameterKey": "ALIYUN::StackId"
                },
                {
                        "ParameterValue": "MyStack",
                        "ParameterKey": "ALIYUN::StackName"
                }
        ],
        "TimeoutInMinutes": 60,
        "Description": "No description",
        "StackId": "628e9ed4-899b-4e64-8a8c-2a2b00e4****",
        "UpdateTime": "2019-08-26T08:27:23",
        "DisableRollback": false,
        "StackName": "MyStack",
        "StatusReason": "Stack successfully updated",
        "Status": "UPDATE_COMPLETE",
        "TemplateDescription": "No description",
        "CreateTime": "2019-08-26T08:26:05",
        "RegionId": "cn-hangzhou",
        "RequestId": "754AEAE5-C800-41EC-A64D-A08C1A4A718F"
}

UpdateStack

You can call this operation to update a stack.

Parameter

Type

Required

Example

Description

--RegionId

String

Yes

cn-beijing

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

--StackId

String

Yes

4a6c9851-3b0f-4f5f-b4ca-a14bf691****

The stack ID.

--Parameters.N.ParameterKey

String

No

InstanceId

The name of parameter N. If you do not specify the name and value of a parameter, ROS uses the default name and value that are specified in the template.

Maximum value of N: 200.

--Parameters.N.ParameterValue

String

No

i-xxxxxx

The value of parameter N.

Maximum value of N: 200.

--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 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 only letters, digits, hyphens (-), and underscores (_).

For more information, see Ensure idempotence.

--StackPolicyDuringUpdateBody

String

No

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

The structure that contains the body of the temporary overriding stack policy. The policy body must be 1 to 16,384 bytes in length.

If you want to update protected resources, you must specify a temporary overriding stack policy during the update. If you do not specify a temporary overriding stack policy, the existing policy that is associated with the stack is used.

This parameter takes effect only when the change set is of the UPDATE type. You can specify only one of the following parameters:

  • StackPolicyBody

  • StackPolicyURL

  • StackPolicyDuringUpdateBody

  • StackPolicyDuringUpdateURL

--TimeoutInMinutes

Long

No

10

The timeout period for updating the stack.

  • Default value: 60.

  • Unit: minutes.

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

You can specify one of TemplateBody and TemplateURL, but you cannot specify both of them.

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

Note

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

You can specify one of StackPolicyBody and StackPolicyURL, but you cannot specify both of them.

The URL can be up to 1,350 bytes in length.

--StackPolicyDuringUpdateURL

String

No

oss://ros-stack-policy/demo

The URL of the file that contains the stack update policy. The URL must point to a policy that is located on an HTTP or HTTPS web server or in an 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.

Note

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

The URL can be up to 1,350 bytes in length.

If you want to update protected resources, you must specify a temporary overriding stack policy during the update. If you do not specify a temporary overriding stack policy, the existing policy that is associated with the stack is used. This parameter takes effect only when the change set is of the UPDATE type. You can specify only one of the following parameters:

  • StackPolicyBody

  • StackPolicyURL

  • StackPolicyDuringUpdateBody

  • StackPolicyDuringUpdateURL

--StackPolicyBody

String

No

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

The structure that contains the stack policy body. The policy body must be 1 to 16,384 bytes in length.

You can specify one of StackPolicyBody and StackPolicyURL, but you cannot specify both of them.

--UsePreviousParameters

Boolean

No

true

Specifies whether to use the values specified in the previous request for the parameters that you do not specify in the current request.

--DisableRollback

Boolean

No

false

Specifies whether to disable rollback when the stack fails to be updated. Valid values:

  • true

  • false (default)

--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 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 you cannot specify both of them.

The URL can be up to 1,024 bytes in length.

Sample request

aliyun ros UpdateStack --RegionId cn-hangzhou --StackId c18d62d8-51ce-4e8e-b8f6-e00be431****

Sample success response

{
        "StackId": "c18d62d8-51ce-4e8e-b8f6-e00be431****",
        "RequestId": "53C2DB3A-8374-4464-9466-952614EEC467"
}

PreviewStack

You can call this operation to preview the information about a stack that you want to create based on a template.

Parameter

Type

Required

Example

Description

--RegionId

String

Yes

cn-beijing

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

--StackName

String

Yes

MyStack

The stack name.

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. Fuzzy search with the wildcard character (*) is supported.

--TimeoutInMinutes

Long

Yes

10

The timeout period for creating the stack.

  • Default value: 60.

  • Unit: minutes.

--Parameters.N.ParameterValue

String

No

ecs.cm4.6xlarge

The value of parameter N.

Maximum value of N: 200.

--Parameters.N.ParameterKey

String

No

InstanceType

The name of parameter N. If you do not specify the name and value of a parameter, ROS uses the default name and value that are specified in the template.

Maximum value of N: 200.

--DisableRollback

Boolean

No

false

Specifies whether to disable rollback when the stack fails to be created.

  • true

  • false (default)

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

You can specify one of TemplateBody and TemplateURL, but you cannot specify both of them.

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

Note

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

You can specify one of StackPolicyBody and StackPolicyURL, but you cannot specify both of them.

The URL can be up to 1,350 bytes in length.

--StackPolicyBody

String

No

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

The structure that contains the stack policy body. The policy body must be 1 to 16,384 bytes in length.

You can specify one of StackPolicyBody and StackPolicyURL, but you cannot specify both of them.

--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 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 you cannot specify both of them.

--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 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 only letters, digits, hyphens (-), and underscores (_).

For more information, see Ensure idempotence.

Sample request

aliyun ros PreviewStack --RegionId cn-beijing --StackName PreStack --TimeoutInMinutes 10

Sample success response

{
        "Stack": {
                "Parameters": [
                        {
                                "ParameterValue": "26492326756309****",
                                "ParameterKey": "ALIYUN::AccountId"
                        },
                        {
                                "ParameterValue": "None",
                                "ParameterKey": "ALIYUN::NoValue"
                        },
                        {
                                "ParameterValue": "cn-hangzou",
                                "ParameterKey": "ALIYUN::Region"
                        },
                        {
                                "ParameterValue": "None",
                                "ParameterKey": "ALIYUN::StackId"
                        },
                        {
                                "ParameterValue": "PreStack",
                                "ParameterKey": "ALIYUN::StackName"
                        }
                ],
                "TemplateDescription": "No description",
                "Description": "No description",
                "TimeoutInMinutes": 10,
                "RegionId": "cn-hangzou",
                "DisableRollback": false,
                "Resources": [],
                "StackName": "PreStack"
        },
        "RequestId": "0400B1C6-0CD5-4E6B-A674-9A2507ED07B5"
}

DeleteStack

You can call this operation to delete a stack and all of its resources.

Parameter

Type

Required

Example

Description

--RegionId

String

Yes

cn-hangzhou

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

--StackId

String

Yes

4a6c9851-3b0f-4f5f-b4ca-a14bf691f2ff

The stack ID.

--RetainAllResources

Boolean

No

false

Specifies whether to retain the resources in the stack.

Sample request

aliyun ros DeleteStack --RegionId cn-hangzhou --StackId 3763bb21-5aa2-4a46-86ec-4b149b2f****

Sample success response

{
        "RequestId": "DC2C269B-C29C-4F07-9A6F-6CE47A267A2F"
}

CancelUpdateStack

You can call this operation to cancel the update of a stack.

Parameter

Type

Required

Example

Description

--RegionId

String

Yes

cn-hangzhou

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

--StackId

String

Yes

4a6c9851-3b0f-4f5f-b4ca-a14bf691****

The stack ID.

--CancelType

String

No

Safe

The method to cancel the update of the stack. We recommend that you set DisableRollback to true. Valid values:

  • Quick: cancels the update of the stack as soon as possible.

  • Safe: cancels the update of the stack as safely as possible.

Sample request

aliyun ros CancelUpdateStack --RegionId cn-hangzhou --StackId c18d62d8-51ce-4e8e-b8f6-e00be431****

Sample success response

{
        "RequestId":"F5DFBC9B-1604-4281-B52C-BB35B96018C5"
}

ContinueCreateStack

You can call this operation to continue to create a stack after the stack fails to be created.

Parameter

Type

Required

Example

Description

--RegionId

String

Yes

cn-hangzhou

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

--StackId

String

Yes

4a6c9851-3b0f-4f5f-b4ca-a14bf691****

The stack ID.

--RecreatingResources.N

RepeatList

No

WebServer

The resource N that ROS continues to create after the resource fails to be created.

You can add new resources to the resources that ROS continues to create. ROS continues to create all dependencies of the new resources.

Sample request

aliyun ros ContinueCreateStack --RegionId cn-hangzhou --StackId c18d62d8-51ce-4e8e-b8f6-e00be43****

Sample success response

{
        "StackId":"c18d62d8-51ce-4e8e-b8f6-e00be431****",
        "RequestId":"E7C8199F-2DC4-4D1B-BA5E-7860BF3A530C"
}

ListStackEvents

You can call this operation to query a stack and the events of resources in the stack.

Parameter

Type

Required

Example

Description

--RegionId

String

Yes

cn-hangzhou

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

--StackId

String

Yes

4a6c9851-3b0f-4f5f-b4ca-a14bf691****

The stack ID.

--Status.N

RepeatList

No

CREATE_IN_PROGRESS

The resource state N. Valid values:

  • CREATE_COMPLETE

  • CREATE_FAILED

  • CREATE_IN_PROGRESS

  • DELETE_FAILED

  • DELETE_IN_PROGRESS

  • ROLLBACK_COMPLETE

  • ROLLBACK_FAILED

  • ROLLBACK_IN_PROGRESS

--ResourceType.N

RepeatList

No

ALIYUN::ECS::Instance

The resource type N.

Maximum value of N: 200.

--PageNumber

Long

No

1

The page number.

  • Pages start from page 1.

  • Default value: 1.

--PageSize

Long

No

10

The number of entries per page.

  • Maximum value: 100.

  • Default value: 10.

Sample request

aliyun ros ListStackEvents --RegionId cn-hangzhou --StackId c18d62d8-51ce-4e8e-b8f6-e00be431****

Sample success response

{
        "PageNumber": 1,
        "TotalCount": 2,
        "PageSize": 10,
        "RequestId": "2AE74AAF-F467-4476-AC0E-208C5AE66666",
        "Events": [
                {
                        "StatusReason": "Stack CREATE completed successfully",
                        "Status": "CREATE_COMPLETE",
                        "PhysicalResourceId": "c18d62d8-51ce-4e8e-b8f6-e00be431****",
                        "LogicalResourceId": "test_stack",
                        "ResourceType": "ALIYUN::ROS::Stack",
                        "StackId": "c18d62d8-51ce-4e8e-b8f6-e00be431****",
                        "CreateTime": "2019-09-05T01:27:58",
                        "EventId": "51cc568c-4112-4507-aa8b-d432af5b****",
                        "StackName": "MyStack"
                },
                {
                        "StatusReason": "Stack CREATE started",
                        "Status": "CREATE_IN_PROGRESS",
                        "PhysicalResourceId": "c18d62d8-51ce-4e8e-b8f6-e00be431****",
                        "LogicalResourceId": "test_stack",
                        "ResourceType": "ALIYUN::ROS::Stack",
                        "StackId": "c18d62d8-51ce-4e8e-b8f6-e00be431****",
                        "CreateTime": "2019-09-05T01:27:58",
                        "EventId": "5b9161fc-d4a1-46ef-bbde-a06cceeb****",
                        "StackName": "MyStack"
                }
        ]
}