Obtaining Metadata of a Stack Set Operation

Function

ShowStackSetOperationMetadata

This API obtains the metadata of a specified stack set operation, including the stack set operation ID, stack set ID, stack set name, stack set operation status, creation time, update time, and deployment target.

For details, refer to ShowStackSetOperationMetadataResponseBody.

URI

GET /v1/stack-sets/{stack_set_name}/operations/{stack_set_operation_id}/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. Minimum: 1 Maximum: 128
stack_set_operation_id	Yes	String	Unique ID of the stack set operation (stack_set_operation). It is a UUID generated by RFS when a stack set operation is created. Minimum: 36 Maximum: 36

**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. Minimum: 36 Maximum: 36

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. Minimum: 36 Maximum: 128

Response Parameters

Status code: 200

**Table 4** 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
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. Minimum: 36 Maximum: 36
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. Minimum: 1 Maximum: 128
status	String	The stack set operation status can be: QUEUE_IN_PROGRESS: The operation is in queue. OPERATION_IN_PROGRESS: The operation is in progress. OPERATION_COMPLETE: The operation is complete. OPERATION_FAILED: The operation failed. STOP_IN_PROGRESS: The operation is being stopped. STOP_COMPLETE - The operation stopped. STOP_FAILED: Failed to stop the operation. Enumeration values: QUEUE_IN_PROGRESS OPERATION_IN_PROGRESS OPERATION_COMPLETE OPERATION_FAILED STOP_IN_PROGRESS STOP_COMPLETE STOP_FAILED
status_message	String	If a stack set operation fails, the causes are displayed. For example, the number of stack instances to be deployed or deleted has exceeded the upper limit or the stack set operation times out. To view failure details, use the ListStackInstances API to obtain status_message of the stack instance.
action	String	Current operation of the user can be: CREATE_STACK_INSTANCES: Create a stack instance. DELETE_STACK_INSTANCES: Delete a stack instance. DEPLOY_STACK_SET: Deploy a stack set. DEPLOY_STACK_INSTANCES: Deploy a stack instance. Enumeration values: CREATE_STACK_INSTANCES DELETE_STACK_INSTANCES DEPLOY_STACK_SET DEPLOY_STACK_INSTANCES UPDATE_STACK_INSTANCES
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. Minimum: 0 Maximum: 64
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_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. Minimum: 0 Maximum: 64
deployment_targets	deployment_targets object	Deployment target information.
create_time	String	Time when a stack set operation 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 operation is updated. It uses a UTC (YYYY-MM-DDTHH:mm:ss.SSSZ) format, for example, 1970-01-01T00:00:00.000Z.
operation_preferences	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.

**Table 5** deployment_targets
Parameter	Type	Description
regions	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	Array of strings	When SELF_MANAGED permissions are used, the information about the tenant 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. * You can specify either domain_ids or domain_ids_uri, but not both. Minimum: 1 Maximum: 64
domain_ids_uri	String	When SELF_MANAGED permissions are used, the OBS address of the tenant 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. * You can specify either domain_ids or domain_ids_uri, but not both. Minimum: 0 Maximum: 2048

**Table 6** operation_preferences
Parameter	Type	Description
region_concurrency_type	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 Enumeration values: SEQUENTIAL PARALLEL
region_order	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	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	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	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	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	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 Enumeration values: STRICT_FAILURE_TOLERANCE SOFT_FAILURE_TOLERANCE

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.

Status code: 401

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

Status code: 403

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

Status code: 404

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

Status code: 429

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

Status code: 500

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

Example Requests

Obtain metadata of a stack set operation.

GET https://{endpoint}/v1/stack-sets/{stack_set_name}/operations/{stack_set_operation_id}/metadata

Example Responses

Status code: 200

Stack set operation metadata obtained.

{
  "stack_set_operation_id" : "daa46d87-045b-4a50-a0d5-c167fc34b632",
  "stack_set_id" : "10f29827-939f-4a11-8bcc-65b051257860",
  "stack_set_name" : "my_hello_world_stack_set",
  "status" : "OPERATION_COMPLETE",
  "administration_agency_name" : "test_administration_agency_name",
  "managed_agency_name" : "test_managed_agency_name",
  "action" : "CREATE_STACK_INSTANCES",
  "deployment_targets" : {
    "domain_ids" : [ "dfda721e8ecd46088662f2dc9e97b1c6", "dfda721e8ecd46088662f2dc9e97b1c7" ],
    "regions" : "region_id"
  },
  "create_time" : "2023-05-15T15:39:25.210Z",
  "update_time" : "2023-05-15T16:39:25.210Z",
  "operation_preferences" : {
    "failure_tolerance_count" : 4,
    "max_concurrent_count" : 3,
    "region_order" : [ "region_id" ],
    "region_concurrency_type" : "SEQUENTIAL",
    "failure_tolerance_mode" : "STRICT_FAILURE_TOLERANCE"
  }
}

Status Codes

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