Obtaining a Stack Instance

Function

ShowStackInstance

This API obtains details about a stack instance, including the name and ID of its associated stack, creation time, and information about variable overriding.

URI

GET /v1/stack-sets/{stack_set_name}/stack-instances/{stack_instance_addr}

**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.
stack_instance_addr	Yes	String	Unique address of a stack instance. The address combines region and stack_domain_id using slashes (/, whose escape codes are %2f or %2F). The address is unique within its domain (domain_id), region, and stack set (stack_set_name).

**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.
status	String	Stack instance status can be: WAIT_IN_PROGRESS: The stack instance is waiting for operation. CANCEL_COMPLETE - The stack instance operation is canceled. OPERATION_IN_PROGRESS: The stack instance operation is in progress. OPERATION_FAILED: The stack instance operation failed. INOPERABLE - The stack instance cannot be operated. OPERATION_COMPLETE: The stack instance operation is complete.
status_message	String	When the stack instance is in an INOPERABLE or OPERATION_FAILED state, brief error information is displayed for debugging.
stack_id	String	Unique stack ID. It is a UUID generated by RFS when a stack is created. Stack names are unique at one specific time, so you can create a stack named HelloWorld and another stack with the same name after deleting the first one. For parallel development in a team, users may want to ensure that the stack 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 is different and does not change with updates. If the stack_id value is different from the current stack ID, 400 is returned.
stack_name	String	Stack name. The name is unique within its domain (domain_id), region, and project (project_id). Only letters, digits, underscores (_), and hyphens (-) are allowed. The name is case-sensitive and must start with a letter.
stack_domain_id	String	Tenant ID of the stack associated with the stack instance.
latest_stack_set_operation_id	String	Stack set operation ID for the latest deployment of the stack instance. It is a UUID generated by RFS when a stack set operation is created.
region	String	Region of the stack associated with the stack instance.
create_time	String	Time when a stack instance 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 instance is updated. It uses a UTC (YYYY-MM-DDTHH:mm:ss.SSSZ) format, for example, 1970-01-01T00:00:00.000Z.
var_overrides	var_overrides object	Overridden variables of the stack instance. If you use the CreateStackInstances or UpdateStackInstances APIs to override variables on the stack instance, this field returns the latest overridden variables recorded by the stack instance. If this field is not returned, use the variables recorded in the stack set to deploy the instance.

**Table 5** var_overrides
Parameter	Type	Description
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.

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 details about the stack instance whose region is cn-north-7 and domain_id is my-domain-id.

GET https://{endpoint}/v1/stack-sets/my_stack_set/stack-instances/cn-north-7%2fmy-domain-id

Example Responses

Status code: 200

Stack instance obtained.

{
  "stack_set_id" : "f689e9fd-97e7-4185-bd8a-7d5f708d45d7",
  "stack_set_name" : "my_hello_world_stack_set",
  "latest_stack_set_operation_id" : "3fef5d3e-27b6-44e8-9769-1d7262bd9430",
  "status" : "OPERATION_COMPLETE",
  "stack_id" : "ea6a4f0e-ee8a-494e-b12a-8be4a1e65af2",
  "stack_name" : "my_hello_world_stack",
  "stack_domain_id" : "6cbcca2a2f114a63841bdbc7a19b7b09",
  "region" : "cn-north-7",
  "create_time" : "2023-05-15T15:39:25.210Z",
  "update_time" : "2023-05-15T16:39:25.210Z",
  "var_overrides" : {
    "vars_body" : "var_key1=\"var_value1\"",
    "vars_uri_content" : "var_key2=\"var_value2\""
  }
}

Status Codes

Status Code	Description
200	Stack instance 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 instance does not exist.
429	Too frequent requests.
500	Internal server error.