CreateStackGroup - Resource Orchestration Service - Alibaba Cloud Documentation Center

Creates stack groups based on Resource Orchestration Service (ROS) templates. Stack groups allow you to create stacks within multiple Alibaba Cloud accounts across regions.

Operation description

A stack group is a collection of ROS stacks that you can manage as a unit. You can use an ROS template of a stack group to create stacks within Alibaba Cloud accounts across regions.

You can create a stack group that is granted self-managed or service-managed permissions:

If you use an Alibaba Cloud account to create a self-managed stack group, the administrator account and the execution account are Alibaba Cloud accounts.
If you enable a resource directory and use the management account or a delegated administrator account of the resource directory to create a service-managed stack group, the administrator account is the management account or delegated administrator account, and the execution account is a member account of the resource directory.

For more information about stack groups, see Overview.

In this topic, a stack group named MyStackGroup is created in the China (Hangzhou) region and granted the self-managed permissions. In this example, the template whose ID is 5ecd1e10-b0e9-4389-a565-e4c15efc**** is used.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

ros:CreateStackGroup

create

*StackGroup

acs:ros:{#regionId}:{#accountId}:stackgroup/{#StackGroupName}

Template

acs:ros:{#regionId}:{#accountId}:template/{#TemplateId}

None

Request parameters

Parameter	Type	Required	Description	Example
RegionId	string	Yes	The region ID of the stack group. You can call the DescribeRegions operation to query the most recent region list.	cn-hangzhou
StackGroupName	string	Yes	The name of the stack group. The name must be unique within a region. 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 a letter.	MyStackGroup
Description	string	No	The description of the stack group. The description must be 1 to 256 characters in length.	StackGroup Description
TemplateBody	string	No	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, and TemplateId.	{"ROSTemplateFormatVersion":"2015-09-01"}
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 Alibaba Cloud Object Storage Service (OSS) bucket. The template body must be 1 to 524,288 bytes in length. Examples: oss://ros/template/demo and oss://ros/template/demo?RegionId=cn-hangzhou. 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, and TemplateId.	oss://ros-template/demo
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 contain letters, digits, underscores (_), and hyphens (-) and cannot exceed 64 characters in length. For more information, see How to ensure idempotence.	123e4567-e89b-12d3-a456-42665544****
AdministrationRoleName	string	No	The name of the RAM role that you specify for the administrator account when you create a self-managed stack group. ROS assumes the administrator role to perform operations. If you do not specify this parameter, AliyunROSStackGroupAdministrationRole is used as the default value. ROS uses the administrator role to assume the execution role AliyunROSStackGroupExecutionRole to perform operations on the stacks in the stack group. The name must be 1 to 64 characters in length and can contain letters, digits, and hyphens (-). Note This parameter is required when the value of PermissionModel is set to SELF_MANAGED.	AliyunROSStackGroupAdministrationRole
ExecutionRoleName	string	No	The name of the RAM role that you specify for the execution account when you create a self-managed stack group. The administrator role AliyunROSStackGroupAdministrationRole assumes the execution role to perform operations. If you do not specify this parameter, AliyunROSStackGroupExecutionRole is used as the default value. ROS assumes the execution role to perform operations on the stacks in the stack group. The name must be 1 to 64 characters in length and can contain letters, digits, and hyphens (-). Note This parameter is required when the value of PermissionModel is set to SELF_MANAGED.	AliyunROSStackGroupExecutionRole
TemplateId	string	No	The ID of the template. This parameter applies to shared and private templates. Note You must and can specify only one of the following parameters: TemplateBody, TemplateURL, and TemplateId.	5ecd1e10-b0e9-4389-a565-e4c15efc****
TemplateVersion	string	No	The version of the template. If you do not specify this parameter, the latest version is used. Note TemplateVersion takes effect only if you specify TemplateId.	v1
Parameters	array<object>	No	The parameters of the stack group.
	object	No
ParameterKey	string	Yes	The key of parameter N. If you do not specify the key and value of a parameter, ROS uses the default name and value that are defined in the template. Maximum value of N: 200. Note Parameters is optional. If you specify Parameters, you must also specify Parameters.N.ParameterKey.	Amount
ParameterValue	string	Yes	The value of parameter N. Maximum value of N: 200. Note Parameters is optional. If you specify Parameters, you must also specify Parameters.N.ParameterValue.	12
ResourceGroupId	string	No	The ID of the resource group. If you do not specify this parameter, the stack group is added to the default resource group. For more information about resource groups, see Resource groups.	rg-acfmxazb4ph6aiy****
PermissionModel	string	No	The permission model of the stack group. Valid values: SELF_MANAGED (default): the self-managed permission model. If you create a self-managed stack group, you must create RAM roles within the administrator and execution accounts and establish a trust relationship between the accounts. Then, you can deploy stacks within the execution account. SERVICE_MANAGED: the service-managed permission model. If you create a service-managed stack group, ROS creates service-linked roles for the administrator and execution accounts, and the administrator account uses its role to deploy stacks within the execution account. Note If you want to use the service-managed permission model to deploy stacks, your account must be the management account or a delegated administrator account of your resource directory and the trusted access feature is enabled for the account. For more information, see Manage a delegated administrator account and Enable trusted access.	SELF_MANAGED
Tags	array<object>	No	The tags of the stack group.
	object	No	The tag of the stack group.
Key	string	Yes	The tag key of the stack group. Note Tags is optional. If you want to specify Tags, you must also specify Tags.N.Key.	usage
Value	string	No	The tag value of the stack group.	test
AutoDeployment	object	No	The information about automatic deployment settings. Note You must specify this parameter if PermissionModel is set to SERVICE_MANAGED.	{"Enabled": true, "RetainStacksOnAccountRemoval": true}
Enabled	boolean	Yes	Indicates whether automatic deployment is enabled. Valid values: true: Automatic deployment is enabled. If you add a member account to the folder to which the stack group belongs after you enable automatic deployment, ROS automatically adds the stacks in the stack group to the member account. If you remove a member account from the folder, ROS automatically deletes the stacks from the member account. false: Automatic deployment is disabled. After you disable automatic deployment, the stacks remain unchanged when you add member accounts to or remove member accounts from the folder.	true
RetainStacksOnAccountRemoval	boolean	No	Indicates whether the stacks within a member account are retained when you remove the member account from the folder. Valid values: true false Note You must specify RetainStacksOnAccountRemoval if Enabled is set to true.	true
Capabilities	array	No	The options for the stack group. You can specify up to one option.
	string	No	The option for the stack group. Valid value: ExpandModules. A value of ExpandModules specifies to expand modules within the current account. Note This parameter takes effect only when modules are used in the template. By default, modules are not expanded within the current account. This requires that the modules exist in all execution accounts within which you want to deploy the stack group. If you want to expand modules within the current account, the modules must exist in the current account.	ExpandModules
StackArn	string	No	The ARN of the stack, in the format of acs:ros:${RegionId}:${AccountId}:stack/${StackId}. The stack group will be created based on the template and parameters of this stack. Note Only supported in self-managed permission mode. If StackArn is specified, Parameters must not be specified. You must specify only one of the following parameters: TemplateBody, TemplateURL, TemplateId, or StackArn.	acs:ros:cn-hangzhou:175458000000**:stack/4a65f506-c3cc-43b6-af06-3f000000**

For more information about common request parameters, refer to Common parameters.

Response elements

Element	Type	Description	Example
	object
RequestId	string	The ID of the request.	14A07460-EBE7-47CA-9757-12CC4761D47A
StackGroupId	string	The ID of the stack group.	2c036e78-9e82-428e-afd6-177f5d04****

Examples

Success response

JSON format

{
  "RequestId": "14A07460-EBE7-47CA-9757-12CC4761D47A",
  "StackGroupId": "2c036e78-9e82-428e-afd6-177f5d04****"
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.