Help Center/ Resource Formation Service/ API Reference/ API/ Resource Formation - Stack Sets/ Deploying a Stack Set
Updated on 2026-07-14 GMT+08:00
View PDF

Deploying a Stack Set

Function

DeployStackSet

This API deploys an existing stack set and returns the stack set operation ID (stack_set_operation_id).

  • You can use this API to update the template and variables of a stack set and deploy it.

  • This API directly triggers deployment of stack instances. You can deploy all stack instances in a stack set or a specified stack instance.

  • This API needs you providing full templates and vars for each deployment.

  • When the triggered deployment fails, the stack set does not automatically roll back the template and variables. However, the stack that fails to be deployed determines whether to roll back based on its rollback configuration. Stacks that have been deployed do not trigger rollback.

  • You can obtain the stack set operation status by calling the ShowStackSetOperationMetadata API based on the stack set operation ID (stack_set_operation_id).

URI

POST /v1/stack-sets/{stack_set_name}/deployments

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

stack_set_name

Yes

String

Stack set name. The name is unique within its domain (domain_id) and region. Only letters, digits, underscores (_), and hyphens (-) are allowed. The name is case-sensitive and must start with a letter.

Minimum: 1

Maximum: 128

Request Parameters

Table 2 Request header parameters

Parameter

Mandatory

Type

Description

Client-Request-Id

Yes

String

Unique request ID. It is specified by a user and is used to locate a request. UUID is recommended.

Minimum: 36

Maximum: 128
Table 3 Request body parameters

Parameter

Mandatory

Type

Description

stack_set_id

No

String

Unique ID of a stack set.

It is a UUID generated by RFS when a stack is created.

Stack set names are unique only at one specific time, so you can create a stack set named HelloWorld and another stack set with the same name after deleting the first one.

For parallel development in a team, users may want to ensure that the stack set they operate is the one created by themselves, not the one with the same name created by other teammates after deleting the previous one. Therefore, they can use this ID for strong matching.

RFS ensures that the ID of each stack set is different and does not change with updates. If the stack_set_id value is different from the current stack set ID, 400 is returned.

Minimum: 36

Maximum: 36

deployment_targets

Yes

deployment_targets object

Deployment target information.

template_body

No

String

HCL template, which describes the target status of a resource. RFS compares the difference between the statuses of this template and the current remote resource.

You can specify either template_body or template_uri, not both.

Note:

  • Stack sets do not encrypt sensitive data. RFS uses, logs, displays, and stores template_body as plaintext.

Minimum: 0

Maximum: 51200

template_uri

No

String

OBS address of an HCL template. The template describes the target status of a resource. RFS compares the difference between the statuses of this template and the current remote resource.

Ensure that the OBS address is located in the same region as the RFS.

The corresponding file must be a tf file or a zip package.

A .tf file must be named with a .tf or .tf.json suffix, compatible with HCL, and UTF-8 encoded.

Currently, only the .zip package is supported. The file name extension must be .zip. The decompressed files cannot contain .tfvars files. The maximum size of the file is 1 MB before decompression and 1 MB after decompression. A maximum of 100 files can be archived to one .zip package.

You can specify either template_body or template_uri, not both.

Note:

  • Stack sets do not encrypt sensitive data. RFS uses, logs, displays, and stores the template file content corresponding to template_uri as plaintext.

    • If the template file specified by the template_uri is in .zip format, the names of the files or folders within the package contain a maximum of 255 bytes, the length of the longest directory cannot exceed 2048 bytes, and the size of the .zip package cannot exceed 1 MB.

Minimum: 0

Maximum: 2048

vars_uri

No

String

OBS address of the HCL parameter file. Transferring parameters is supported by the HCL template. The same template can use different parameters for different purposes.

Ensure that the OBS address is located in the same region as the RFS.

  • vars_uri directs to a pre-signed URL of OBS. Currently, other addresses are not supported.

  • RFS supports vars_structure, vars_body, and vars_uri. If they declare the same variable, error 400 will be reported.

The content in vars_uri uses the tfvars format of HCL. You can save the content in .tfvars to a file, upload the file to OBS, and transfer the pre-signed URL of OBS to vars_uri.

  • Stack sets do not encrypt sensitive data. RFS uses, logs, displays, and stores the variable file content corresponding to vars_uri as plaintext.

Minimum: 0

Maximum: 2048

vars_body

No

String

Content of the HCL variable file. Transferring parameters is supported by the HCL template. The same template can use different parameters for different purposes.

  • The vars_body uses the tfvars format of HCL. You can submit the content in the .tfvars file to the vars_body.

  • RFS supports vars_structure, vars_body, and vars_uri. If they declare the same variable, error 400 will be reported.

  • If vars_body is too large, you can use vars_uri.

  • Stack sets do not encrypt sensitive data. RFS uses, logs, displays, and stores vars_body as plaintext.

Minimum: 0

Maximum: 51200

operation_preferences

No

operation_preferences object

The user-specified preferences for how to perform a stack set operation. This parameter takes effect only in a specified single operation.

If this parameter is not specified, the default operation preferences is that only one stack is deployed at a time and after all stack instances in a region are deployed completely, the next region will be selected randomly for deployment. The default value of failure tolerance count in a region is 0.

This parameter can be specified in the following APIs:

CreateStackInstance, DeployStackSet, UpdateStackInstance, DeleteStackInstance.

call_identity

No

String

This parameter is only supported when the stack set permission model is SERVICE_MANAGED. Specify whether you are acting as an account administrator in the organization's management account or as a delegated administrator in a member account. By default, SELF is specified.

Use SELF for stack sets with self-managed permissions.

No matter what call identity is specified, the stack set involved in request is always belonging to management account.

  • SELF - Invoked as to the management account.

  • DELEGATED_ADMIN - Invoked as a delegated administrator. The Huawei Cloud account must be registered as a delegated administrator of the Resource Formation Stack Set service in the organization.
Table 4 deployment_targets

Parameter

Mandatory

Type

Description

regions

Yes

Array of strings

Regions involved in the stack set operations are specified by the user.

  • If this parameter is specified in the DeployStackSet API, stack instances in the stack set are selected for deployment. This operation applies to the Cartesian product of the regions and domain_ids input by the user. If a region that is not managed by the stack set is specified, an error is reported. *

domain_ids

No

Array of strings

When the stack set permission model is SELF_MANAGED, the domain IDs involved in this operation is specified by the user.

  • If this parameter is specified in the DeployStackSet API, stack instances in the stack set are selected for deployment. This operation applies to the Cartesian product of the regions and domain_ids input by the user. If a domain_id that is not managed by the stack set is specified, an error is reported. *

When the stack set permission model is SERVICE_MANAGED, this parameter needs to be used with domain_id_filter_type. It's used to specify, exclude or additionally deploy the domain IDS of member accounts from the organizational units in deployment target.

You can specify either domain_ids or domain_ids_uri, but not both.

Minimum: 1

Maximum: 64

Array Length: 1 - 100

domain_ids_uri

No

String

When the stack set permission model is SELF_MANAGED, the OBS address of the domain IDs involved in this operation is specified by the user.

Tenant IDs are separated by commas (,) and line breaks are supported. Currently, only CSV files are supported, and the files should be encoded in UTF-8. The file size cannot exceed 100 KB.

Do not use Excel for operations on the CSV file to be uploaded. Otherwise, inconsistencies may occur in results read from the CSV file. You are advised to use Notepad to open the file and check whether the content complies with your expectation.

  • If this parameter is specified in the DeployStackSet API, stack instances in the stack set are selected for deployment. This operation applies to the Cartesian product of the domain_ids_uri file and regions input by the user. If a domain_id that is not managed by the stack set is specified, an error is reported. *

When the stack set permission model is SERVICE_MANAGED, this parameter needs to be used with domain_id_filter_type. Used to specify, exclude or additionally deploy the domain IDS of member accounts from the organizational units in deployment target.

You can specify either domain_ids or domain_ids_uri, but not both.

Minimum: 0

Maximum: 2048

organizational_unit_ids

No

Array of strings

Organizational Unit (OU) IDs list. This parameter is only allowed to be specified when the stack set permission model is SERVICE_MANAGED.

The list of organizational_unit_ids, it can be the root organization (Root) ID or the ID of organizational units.

This parameter must be specified in the CreateStackInstances API. This API will asynchronously verify the OU IDs. Valid OU IDs and all non-empty sub-OU IDs will be managed by the stack set. This API allows specifying OU IDs that are not or already managed by the stack set.

  • If the stack set is not automatically deployed, it will not manage the empty sub-OUs (specifically, there are no member accounts under the sub-OU or the deployment excludes all member accounts). *

  • [Not supported] If the stack set is automatically deployed, it will also manage the empty sub-OUs (specifically, there are no member accounts under the sub-OU or the deployment excludes all member accounts). Automatic deployment only responds to changes in member accounts, not for organizational units changes, such as adding new OUs. Adding new OUs will not be automatically managed by the stack set. *

To deploy or delete resource stack instances (including DeployStackSet, UpdateStackInstances, DeleteStackInstances API) , only OU IDs that have been managed by the resource stack set are allowed to be specified. If you specify OU IDs that are not managed by the resource stack set records, an error will be reported.

This parameter must be specified in the DeleteStackInstances API.

You can call ShowStackSetMetadata API to get the OU IDs specified by CreateStackInstances API request.

Stack set will be deployed not only to users in the deployment target OUs, but also to users in all sub-OUs. Stack set assembly selects stack instances to create or deploy in the form of a Cartesian product based on all users under the OUs (including under sub-OUs) and the region list.

Stack sets will not choose administrator in organization as deployment target for stack instance creation or deployment, even if the organization administrator is in the given organization or the organization's OU.

Array Length: 1 - 100

domain_id_filter_type

No

String

Domain IDs filter type. This parameter is only supported when stack set permission model is SERVICE_MANAGED. By default, NONE is specified.

You can specify different filter types to include or exclude deployment target users by providing either domain_ids or domain_ids_uri, thus increasing or limiting the scope of deployment target and implement different deployment strategies.

  • INTERSECTION - Select specified accounts from the OUs in deployment target for deployment. You can specify either domain_ids or domain_ids_uri, but not both.

  • DIFFERENCE - Exclude specified accounts from the OUs in deployment target for deployment. You can specify either domain_ids or domain_ids_uri, but not both.

  • UNION - In addition to deploy all accounts from the OUs in deployment target, it will also deploy to the specified account. Users can deploy the OU and specific individual accounts in stack set operation by specifying both organizational_unit_ids and domain_ids/domain_ids_uri. You can specify either domain_ids or domain_ids_uri, but not both. CreateStackInstances does not allow using this type.

  • NONE - Only deploy to all accounts from the OUs in deployment target. You can not specify domain_ids or domain_ids_uri.
Table 5 operation_preferences

Parameter

Mandatory

Type

Description

region_concurrency_type

No

String

The concurrency type of deploying stack instances in regions. The value can be SEQUENTIAL (default) or PARALLEL. The value is case-sensitive.

Detailed introduction:

  • SEQUENTIAL: Stack instances are deployed in sequence among regions, that is, after all stack instances in a region are deployed completely, the next region will be selected for deployment.

  • PARALLEL: Stack instances are deployed in all specified regions concurrently.

Default: SEQUENTIAL

region_order

No

Array of strings

Region deployment order. This parameter can be specified only when region_concurrency_type is set to SEQUENTIAL. The region_order must only contain all regions in this deployment target.

If this parameter is not specified, the region deployment order is random. The region_order takes effect only during a specified single operation.

failure_tolerance_count

No

Long

The maximum number of failed stack instances in a region. The value must be 0 or a positive integer. The default value is 0.

If the value of region_concurrency_type is SEQUENTIAL, when the number of stack instances that deploy failed in a region exceeds the failure_tolerance_count, all other instances that are still in WAIT_IN_PROGRESS status will be canceled. The status of the canceled instance changes to CANCEL_COMPLETE;

If the value of region_concurrency_type is PARALLEL, when the number of stack instances that deploy failed in a region exceeds the failure_tolerance_count, the stack set only cancels all instances that are still in WAIT_IN_PROGRESS status in this region. The status of the canceled instance changes to CANCEL_COMPLETE.

Stack instances that are in OPERATION_IN_PROGRESS status or have been deployed (that is, in OPERATION_COMPLETE or OPERATION_FAILED status) are not affected.

Only one of failure_tolerance_count and failure_tolerance_percentage can exist.

Minimum: 0

Maximum: 100

failure_tolerance_percentage

No

Long

The maximum percentage of failed stack instances in a region. The value must be 0 or a positive integer. The default value is 0.

By multiplying the failure_tolerance_percentage by the number of stack instances in the region and rounding it down, the actual number of failure tolerance count can be obtained.

Only one of failure_tolerance_count and failure_tolerance_percentage can exist.

Minimum: 0

Maximum: 100

max_concurrent_count

No

Long

The maximum number of concurrent accounts can be deployed in a region. The value must be a positive integer. The default value is 1.

max_concurrent_count is at most one more than the failure tolerance count. If failure_tolerance_percentage is specified, max_concurrent_count is at most one more than the result of failure_tolerance_percentage multiplied by the number of stack instances in a region to guarantee that the deployment stops at the required level of failure tolerance.

Only one of max_concurrent_count and max_concurrent_percentage can exist.

Minimum: 1

Maximum: 5

max_concurrent_percentage

No

Long

The maximum percentage of concurrent accounts can be deployed in a region. The value must be a positive integer. The default value is 1.

The RFS calculates the actual maximum number of concurrent accounts by rounding down the value obtained by multiplying the percentage by the number of stack instances in each region.

This actual maximum number of concurrent accounts is at most one more than the failure tolerance count. If failure_tolerance_percentage is specified, this actual maximum number of concurrent accounts is at most one more than the result of failure_tolerance_percentage multiplied by the number of stack instances in a region to guarantee that the deployment stops at the required level of failure tolerance.

Only one of max_concurrent_count and max_concurrent_percentage can exist.

Minimum: 1

Maximum: 100

failure_tolerance_mode

No

String

The failure tolerance mode of deploying stack instances in regions. The value can be STRICT_FAILURE_TOLERANCE or SOFT_FAILURE_TOLERANCE. The default value is STRICT_FAILURE_TOLERANCE. The value is case-sensitive.

Detailed introduction:

  • STRICT_FAILURE_TOLERANCE: This option dynamically lowers the concurrency level to ensure the number of failed stack instances never exceeds the value of failure_tolerance_count + 1. If failure_tolerance_percentage is specified, this option ensures the number of failed stack instances never exceeds the result of failure_tolerance_percentage multiplied by the number of stack instances in a region.

  • The initial actual maximum number of concurrent accounts is max_concurrent_count. If max_concurrent_percentage is specified, the initial actual maximum number of concurrent accounts is the result of max_concurrent_percentage multiplied by the number of stack instances. The actual maximum number of concurrent accounts is then reduced proportionally by the number of failed stack instances.

  • SOFT_FAILURE_TOLERANCE: This option separates failure_tolerance_count (failure_tolerance_percentage) from the actual maximum number of concurrent accounts. This option allows actual maximum number of concurrent accounts to keep at the concurrency level set by the max_concurrent_count, or max_concurrent_percentage.

  • This option does not ensure the number of failed stack instances is less than failure_tolerance_count + 1. If failure_tolerance_percentage is specified, this option does not ensure the number of failed stack instances is less than the result of max_concurrent_percentage multiplied by the number of stack instances.

Default: STRICT_FAILURE_TOLERANCE

Response Parameters

Status code: 202

Table 6 Response body parameters

Parameter

Type

Description

stack_set_operation_id

String

Unique ID of a stack set operation.

It is a UUID generated by RFS when a stack set operation is created.

Minimum: 36

Maximum: 36

Status code: 400

Table 7 Response body parameters

Parameter

Type

Description

error_code

String

Response code.

Minimum: 11

Maximum: 11

error_msg

String

Response message.

encoded_authorization_message

String

The message contains information about unauthorized requests.

details

Array of Detail objects

Detailed error messages returned by service when permission is denied.
Table 8 Detail

Parameter

Type

Description

error_code

String

Response code.

error_msg

String

Response message.

Status code: 401

Table 9 Response body parameters

Parameter

Type

Description

error_code

String

Response code.

Minimum: 11

Maximum: 11

error_msg

String

Response message.

encoded_authorization_message

String

The message contains information about unauthorized requests.

details

Array of Detail objects

Detailed error messages returned by service when permission is denied.
Table 10 Detail

Parameter

Type

Description

error_code

String

Response code.

error_msg

String

Response message.

Status code: 403

Table 11 Response body parameters

Parameter

Type

Description

error_code

String

Response code.

Minimum: 11

Maximum: 11

error_msg

String

Response message.

encoded_authorization_message

String

The message contains information about unauthorized requests.

details

Array of Detail objects

Detailed error messages returned by service when permission is denied.
Table 12 Detail

Parameter

Type

Description

error_code

String

Response code.

error_msg

String

Response message.

Status code: 404

Table 13 Response body parameters

Parameter

Type

Description

error_code

String

Response code.

Minimum: 11

Maximum: 11

error_msg

String

Response message.

encoded_authorization_message

String

The message contains information about unauthorized requests.

details

Array of Detail objects

Detailed error messages returned by service when permission is denied.
Table 14 Detail

Parameter

Type

Description

error_code

String

Response code.

error_msg

String

Response message.

Status code: 409

Table 15 Response body parameters

Parameter

Type

Description

error_code

String

Response code.

Minimum: 11

Maximum: 11

error_msg

String

Response message.

encoded_authorization_message

String

The message contains information about unauthorized requests.

details

Array of Detail objects

Detailed error messages returned by service when permission is denied.
Table 16 Detail

Parameter

Type

Description

error_code

String

Response code.

error_msg

String

Response message.

Status code: 429

Table 17 Response body parameters

Parameter

Type

Description

error_code

String

Response code.

Minimum: 11

Maximum: 11

error_msg

String

Response message.

encoded_authorization_message

String

The message contains information about unauthorized requests.

details

Array of Detail objects

Detailed error messages returned by service when permission is denied.
Table 18 Detail

Parameter

Type

Description

error_code

String

Response code.

error_msg

String

Response message.

Status code: 500

Table 19 Response body parameters

Parameter

Type

Description

error_code

String

Response code.

Minimum: 11

Maximum: 11

error_msg

String

Response message.

encoded_authorization_message

String

The message contains information about unauthorized requests.

details

Array of Detail objects

Detailed error messages returned by service when permission is denied.
Table 20 Detail

Parameter

Type

Description

error_code

String

Response code.

error_msg

String

Response message.

Example Requests

The following example shows how to pass template and parameter information using OBS Signed URL. Stack instances are deployed in sequential mode among regions.

POST https://{endpoint}/v1/stack-sets/my_hello_world_stack_set/deployments

{
  "template_uri" : "https://{bucket_name}.{region}.myhuaweicloud.com/my-hello-world-template.tf",
  "vars_uri" : "https://{bucket_name}.{region}.myhuaweicloud.com/my-hello-world-vars.tfvars",
  "stack_set_id" : "1b15e005-bdbb-4bd7-8f9a-a09b6774b4b4",
  "deployment_targets" : {
    "regions" : [ "cn-north-7" ],
    "domain_ids" : [ "0e0bc7572c0dfb74efa6c60ecd7b1dbf" ]
  },
  "operation_preferences" : {
    "region_concurrency_type" : "SEQUENTIAL"
  }
}

Example Responses

Status code: 202

The request is accepted and processed asynchronously.

{
  "stack_set_operation_id" : "1b15e005-bdbb-4bd7-8f9a-a09b6774b4b3"
}

Status Codes

Status Code

Description

202

The request is accepted and processed asynchronously.

400

Invalid request.

401

Authentication failed.

403

  1. The user does not have the permission to call this API.

  2. The stack set status is invalid. Parallel operations are not allowed.

404

The stack set does not exist.

409

Request conflict. Another request is being processed on the current stack set.

429

Too frequent requests.

500

Internal server error.