Creating Stack Instances

Function

CreateStackInstance

This API creates multiple stack instances in a specified stack set and returns the stack set operation ID (stack_set_operation_id).

This API uses var_overrides to specify the variable values for creating a stack instance to override variables. If var_overrides are not assigned, the variables recorded in the current stack are used for deployment by default. For details, see the description of the var_overrides.

After the stack set variables are updated through the DeployStackSet API, the overridden variables in the stack instance are not updated and the overridden values are retained.

You can override only the variables recorded in the stack set. If you want to add variables that can be overridden, use the DeployStackSet API to update the variable set recorded in the stack set.

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}/stack-instances

**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.
var_overrides	No	var_overrides object	Variables that the user expects to update in the stack instance. Related variables will be overridden in all stack instances specified in this request, and the stack instances will be deployed based on the updated variables. The overwritten variables are permanently recorded in the stack instances and continue to be used in subsequent deployment until they are overridden in the next update. Only the variable set (vars) recorded in the stack set can be overridden. If a variable that does not exist in vars is specified, error code 400 is returned. If you want to add variables that can be overridden, use the DeployStackSet API to update the variable set (vars) recorded in the stack set. After the stack set variable set (vars) is updated through the DeployStackSet API, the overridden variables in the stack instance are not updated and the overridden values are retained. Variable overriding applies only to the variables specified by vars in the stack set, excluding the variables that use default values as defined in the template. If you want to override the variables that use the default values, use the DeployStackSet API to update the vars recorded in the stack set and explicitly define related variables in the vars. Each time a user use the DeployStackSet API to update the vars of the stack set, error code 400 is returned for loss of the overridden variables recorded in the stack instance deployed to any targets. (The current overridden variables are not a subset of the vars of the updated stack set.) In a new update, existing variables cannot be retained. Instead, all existing variables should be overridden. The total length of the overridden vars_body of the stack instance does not exceed 51,200. After variable overriding, the size of the vars_uri file of the stack instance does not exceed 1 MB. For example, the vars_body recorded in the stack set is "key1=value1, key2=value2...", and the new vars_body in the stack instance is "key1=another_value1". The length of the overridden vars_body "key1=another_value1, key2=value2...." cannot exceed 51,200. For example, the file content specified by the vars_uri recorded in the stack set is "key1=value1, key2=value2...", and that of the new vars_uri in the stack instance is "key1=another_value1". The size of the file specified by the overridden vars_body "key1=another_value1, key2=value2...." cannot exceed 1 MB. If var_overrides is not assigned, the variables recorded in the overridden stack instance are not updated. If you have assigned at least one of vars_uri, vars_body, and use_stack_set_vars, the variables will be updated through replacement. The new variables assigned by you override related variables in the specified stack instance. All variable sets declared in vars_body, vars_uri, and use_stack_set_vars must be consistent with those recorded in the stack set. Error code 400 is returned for the following scenarios: variables that do not exist in the stack set are declared, variables that have been recorded in the stack set are not declared, and duplicate variables are declared. Note: To override a specified variable value, specify the name and value of the variable to be overridden in vars_uri or vars_body. To roll back an overridden variable to the value recorded in the stack set, specify the name of the variable to be rolled back to in use_stack_set_vars. To roll back all overridden variables to the values recorded in the stack set, specify the names of all variables recorded in the stack set in use_stack_set_vars. To use the variable values recorded in the current stack instance for deployment, var_overrides are not required.

**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 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	No	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 5** var_overrides
Parameter	Mandatory	Type	Description
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. The OBS address allows mutual access to regions of the same type. Regions are classified into universal regions and dedicated regions. A universal region provides universal cloud services for common tenants. A dedicated region provides specific services for specific tenants. 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
use_stack_set_vars	No	Array of strings	Names of the variables whose values are recorded in the stack set and expected to be used for deployment. You can select only the variables that have been recorded in the stack set. Otherwise, error code 400 is returned. If the use_stack_set_vars contains name of a variable that has been overridden in the stack instance, the value of the variable is rolled back to that recorded in the stack set.

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.

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

Assign member account information through the array of domain IDs.

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

{
  "deployment_targets" : {
    "regions" : [ "cn-north-7" ],
    "domain_ids" : [ "6cbcca2a2f114a63841bdbc7a19b7b12", "1e03325ba3cc47b1fdb03f3771bbb4f3" ]
  }
}

Assign member account information through the URL signed by domain IDs.

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

{
  "deployment_targets" : {
    "regions" : [ "cn-north-7" ],
    "domain_ids_uri" : "https://my-obs.obs.cn-north-7.ulanqab.huawei.com/domain_ids.csv"
  }
}

Example Responses

Status code: 202

The request is accepted and processed asynchronously.

{
  "stack_set_operation_id" : "fb5e781e-a27d-46e2-9954-242753857a9f"
}

Status Codes

Status Code	Description
202	The request is accepted and processed asynchronously.
400	Invalid request.
401	Authentication failed.
403	The user does not have the permission to call this API. The stack set status is invalid. Parallel operations are not allowed.
404	The stack set does not exist.
429	Too frequent requests.
500	Internal server error.