Obtaining Metadata of a Stack Set

Function

ShowStackSetMetadata

You can use this API to obtain the stack set metadata.

URI

GET /v1/stack-sets/{stack_set_name}/metadata

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

**Table 2** Query 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 set 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.
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 the management account. DELEGATED_ADMIN - Invoked as a delegated administrator account. User account must be registered as a delegated administrator in the management account.

Request Parameters

**Table 3** 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.

Response Parameters

Status code: 200

**Table 4** Response body parameters
Parameter	Type	Description
stack_set_id	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.
stack_set_name	String	Name of a stack set. 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.
stack_set_description	String	Description of a stack set. It can be used by customers to identify their own stack sets.
initial_stack_description	String	Description of stacks that is being initialized. It can be used to identify stacks managed by a stack set. This description is used for stacks in the stack set only when they are created. To update the description of stacks that is being initialized, call the UpdateStackSet API. If the stack set description is updated later, the managed stack description will not be updated synchronously.
permission_model	String	Permission model. It defines the creation mode of the agency required for RFS to operate stack sets, default is SELF_MANAGED. You can use the CreateStackSet API to specify this parameter. This parameter does not support updating yet. If you want to update the permission model, you can delete and then create a stack set with the same name. * SERVICE_MANAGED: Based on the Organization service, RFS will automatically create all IAM agency required when deploying organization member accounts. You can use this model to create stack sets only after setting "Resource Formation Stack Set service" as a trusted service in your organization. Only an organization administrator or a delegated administrator can create stack sets using SERVICE_MANAGED permissions. * SELF_MANAGED: For deployment, you need to manually create agencies in advance, including the agency created by the management account for RFS and the agency created by the member account for the management account. The stack set creation will not fail if the agency does not exist or is incorrect. An error is reported only when the stack set or stack instance is deployed.
administration_agency_name	String	Administration agency names. RFS uses this agency to obtain permissions that a member account grants to a management account. This agency must contain the iam:tokens:assume permission to subsequently obtain the managed agency credentials. If it is not included, adding or deploying instances will fail. When you define SELF_MANAGED permissions, you must specify either administration_agency_name or administration_agency_urn, but not both. You are advised to specify administration_agency_urn when using a trust agency. administration_agency_name only receives agency names. If trust agency names are assigned to administration_agency_name, template fails to be deployed. Do not specify this parameter when SERVICE_MANAGED permissions are used. Otherwise, error code 400 is returned.
managed_agency_name	String	Name of the managed agency. RFS uses this agency to obtain the permissions required for deploying resources. The names of the agencies that different member accounts grants to the management account must be the same. Currently, different agency permissions cannot be defined based on different providers. This parameter must be specified when SELF_MANAGED permissions are defined. Do not specify this parameter when SERVICE_MANAGED permissions are used. Otherwise, error code 400 is returned.
status	String	The stack set status can be: IDLE: The stack set is idle. OPERATION_IN_PROGRESS: The stack set operation is in progress. DEACTIVATED: The stack set is disabled.
vars_uri_content	String	File content corresponding to vars_uri.
vars_body	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.
create_time	String	Time when a stack set is created. It uses a UTC (YYYY-MM-DDTHH:mm:ss.SSSZ) format, for example, 1970-01-01T00:00:00.000Z.
update_time	String	Time when a stack set is updated. It uses a UTC (YYYY-MM-DDTHH:mm:ss.SSSZ) format, for example, 1970-01-01T00:00:00.000Z.
administration_agency_urn	String	Administration agency URNs. RFS uses this agency to obtain permissions that a member account grants to a management account. This agency must contain the sts:tokens:assume permission to subsequently obtain the managed agency credentials. If it is not included, adding or deploying instances will fail. When you define SELF_MANAGED permissions, you must specify either administration_agency_name or administration_agency_urn, but not both. You are advised to specify administration_agency_urn when using a trust agency. administration_agency_name only receives agency names. If trust agency names are assigned to administration_agency_name, template fails to be deployed. Do not specify this parameter when SERVICE_MANAGED permissions are used. Otherwise, error code 400 is returned.
managed_operation	managed_operation object	A set of properties used to manage the stack set operation.
organizational_unit_ids	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.

**Table 5** managed_operation
Parameter	Type	Description
enable_parallel_operation	Boolean	This parameter indicates whether the stack set can create multiple stack set operations concurrently. As an attribute of the stack set, this parameter can be specified by using CreateStackSet API and updated by using UpdateStackSet API. When false (default), the stack set performs one operation at a time in request order. To be specific, at a time, only one stack set operation in QUEUE_IN_PROGRESS or OPERATION_IN_PROGRESS status can be processed. When true, the stack set can create operations concurrently, handle non-conflicting operations, and queue conflicting operations. When the conflicting operation is completed, the stack set continues to perform queuing operations in the order of requests. Currently, a maximum of 10 concurrent stack set operations are allowed to be created under the same stack set. Note: When the stack set allows multiple operations to be created at the same time, if more than one operation deploys same stack instances, these operations are called conflicting operations. When the stack set is in OPERATION_IN_PROGRESS status, this parameter is not allowed to be modified by UpdateStackSet API. Currently, a maximum of 10 stack set operations in QUEUE_IN_PROGRESS or OPERATION_IN_PROGRESS status can exist in one stack set.

Status code: 400

**Table 6** Response body parameters
Parameter	Type	Description
error_code	String	Response code.
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 7** Detail
Parameter	Type	Description
error_code	String	Response code.
error_msg	String	Response message.

Status code: 401

**Table 8** Response body parameters
Parameter	Type	Description
error_code	String	Response code.
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 9** Detail
Parameter	Type	Description
error_code	String	Response code.
error_msg	String	Response message.

Status code: 403

**Table 10** Response body parameters
Parameter	Type	Description
error_code	String	Response code.
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 11** Detail
Parameter	Type	Description
error_code	String	Response code.
error_msg	String	Response message.

Status code: 404

**Table 12** Response body parameters
Parameter	Type	Description
error_code	String	Response code.
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 13** Detail
Parameter	Type	Description
error_code	String	Response code.
error_msg	String	Response message.

Status code: 429

**Table 14** Response body parameters
Parameter	Type	Description
error_code	String	Response code.
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 15** Detail
Parameter	Type	Description
error_code	String	Response code.
error_msg	String	Response message.

Status code: 500

**Table 16** Response body parameters
Parameter	Type	Description
error_code	String	Response code.
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 17** Detail
Parameter	Type	Description
error_code	String	Response code.
error_msg	String	Response message.

Example Requests

Obtain metadata of a specified stack set.

GET https://{endpoint}/v1/stack_sets/my_hello_world_stack_set/metadata

Obtain the stack set metadata and check whether the stack set ID matches the current stack set.

GET https://{endpoint}/v1/stack_sets/my_hello_world_stack_set/metadata?stack_set_id=ea6a4f0e-ee8a-494e-b12a-8be4a1e65af2

Example Responses

Status code: 200

Stack set metadata obtained.

{
  "stack_set_id" : "f689e9fd-97e7-4185-bd8a-7d5f708d45d7",
  "stack_set_name" : "my_hello_world_stack_set",
  "stack_set_description" : "my first stack set",
  "initial_stack_description" : "my stack created by stack set",
  "permission_model" : "SELF_MANAGED",
  "managed_agency_name" : "my_managed_agency_name",
  "administration_agency_name" : "my_administration_agency_name",
  "status" : "OPERATION_IN_PROGRESS",
  "create_time" : "2023-03-16T03:28:20.210Z",
  "update_time" : "2023-05-24T08:56:10.210Z",
  "managed_operation" : {
    "enable_parallel_operation" : false
  }
}

Status Codes

Status Code	Description
200	Stack set metadata obtained.
400	Invalid request.
401	Authentication failed.
403	The user does not have the permission to call this API.
404	The stack set does not exist.
429	Too frequent requests.
500	Internal server error.