All Products
Search

This Product

    Resource Orchestration Service:CreateStackGroup

    Document Center

    Resource Orchestration Service:CreateStackGroup

    Last Updated:Sep 12, 2024

    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.

    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:CreateStackGroupcreate
    • StackGroup
      acs:ros:{#regionId}:{#accountId}:stackgroup/{#StackGroupName}
      none
    		none

    Request parameters

    ParameterTypeRequiredDescriptionExample
    RegionIdstringYes

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

    		cn-hangzhou
    StackGroupNamestringYes

    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
    DescriptionstringNo

    The description of the stack group.
    The description must be 1 to 256 characters in length.

    		StackGroup Description
    TemplateBodystringNo

    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"}
    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 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
    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 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****
    AdministrationRoleNamestringNo

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

    		AliyunROSStackGroupAdministrationRole
    ExecutionRoleNamestringNo

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

    		AliyunROSStackGroupExecutionRole
    TemplateIdstringNo

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

    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
    Parametersarray<object>No

    The parameters of the stack group.

    objectNo

    The parameters.

    ParameterKeystringYes

    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
    ParameterValuestringYes

    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
    ResourceGroupIdstringNo

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

    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
    Tagsarray<object>No

    The tags of the stack group.

    objectNo

    The tag of the stack group.

    KeystringYes

    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
    ValuestringNo

    The tag value of the stack group.

    		test
    AutoDeploymentobjectNo

    The information about automatic deployment settings.

    Note You must specify this parameter if PermissionModel is set to SERVICE_MANAGED.
    EnabledbooleanYes

    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
    RetainStacksOnAccountRemovalbooleanNo

    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
    CapabilitiesarrayNo

    The options for the stack group. You can specify up to one option.

    stringNo

    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

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

    Response parameters

    ParameterTypeDescriptionExample
    object
    RequestIdstring

    The ID of the request.

    		14A07460-EBE7-47CA-9757-12CC4761D47A
    StackGroupIdstring

    The ID of the stack group.

    		2c036e78-9e82-428e-afd6-177f5d04****

    Examples

    Sample success responses

    JSONformat

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

    Error codes

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

    Change history

    Change timeSummary of changesOperation
    2024-09-12The request parameters of the API has changedView Change Details
    2024-01-11The internal configuration of the API is changed, but the call is not affectedView Change Details
    2023-05-10The request parameters of the API has changedView Change Details
    2022-10-27The request parameters of the API has changedView Change Details