# 部署资源栈集 #### 功能介绍 部署资源栈集（DeployStackSet） 此API用于部署一个已有的资源栈集，并返回资源栈集操作ID（stack_set_operation_id） - 用户可以使用此API更新资源栈集的模板、参数并进行部署。 - 此API会直接触发资源栈实例部署。用户既可以部署资源栈集下所有的资源栈实例，也可以部署指定资源栈实例。 - 此API为全量API，即用户每次部署都需要给予所想要使用的template、vars的全量 - 当触发的部署失败时，资源栈集不会自动回滚模板和参数，但部署失败的资源栈会根据资源栈的回滚配置决定是否进行回滚，已经部署成功的资源栈不会触发回滚。 - 用户可以根据资源栈集操作ID（stack_set_operation_id），通过ShowStackSetOperationMetadata API获取资源栈集操作状态 #### 调试 您可以在[API Explorer](https://console.huaweicloud.com/apiexplorer/#/openapi/AOS/doc?api=DeployStackSet)中调试该接口，支持自动认证鉴权。API Explorer可以自动生成SDK代码示例，并提供SDK代码示例调试功能。 #### URI POST /v1/stack-sets/{stack_set_name}/deployments 表1路径参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | stack_set_name | 是 | String | 资源栈集的名称。此名字在domain_id+region下应唯一，可以使用中文、大小写英文、数字、下划线、中划线。首字符需为中文或者英文，区分大小写。 最小长度：**1** 最大长度：**128** | #### 请求参数 表2请求Header参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | Client-Request-Id | 是 | String | 用户指定的，对于此请求的唯一ID，用于定位某个请求，推荐使用UUID 最小长度：**36** 最大长度：**128** | 表3请求Body参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | stack_set_id | 否 | String | 资源栈集（stack_set）的唯一ID。 此ID由资源编排服务在生成资源栈集的时候生成，为UUID。 由于资源栈集名仅仅在同一时间下唯一，即用户允许先生成一个叫HelloWorld的资源栈集，删除，再重新创建一个同名资源栈集。 对于团队并行开发，用户可能希望确保，当前我操作的资源栈集就是我以为的那个，而不是被其他队友删除后创建的同名资源栈集。因此，使用ID就可以做到强匹配。 资源编排服务保证每次创建的资源栈集所对应的ID都不相同，更新不会影响ID。如果给予的stack_set_id和当前资源栈集的ID不一致，则返回400 最小长度：**36** 最大长度：**36** | | deployment_targets | 是 | [deployment_targets] object | 部署目标信息。 | | template_body | 否 | String | HCL模板，描述了资源的目标状态。资源编排服务将比较此模板与当前远程资源的状态之间的区别。 template_body和template_uri 必须有且只有一个存在 **注意：** - 资源栈集不支持敏感数据加密，资源编排服务会直接明文使用、log、展示、存储对应的template_body 最小长度：**0** 最大长度：**51200** | | template_uri | 否 | String | HCL模板的OBS地址，该模板描述了资源的目标状态。资源编排服务将比较此模板与当前远程资源的状态之间的区别 请确保OBS地址所在局点与使用RFS服务局点一致。 对应的文件应该是纯tf文件或zip压缩包 纯tf文件需要以".tf"或者".tf.json"结尾，并遵守HCL语法，且文件的编码格式须为UTF-8 压缩包目前只支持zip格式，文件需要以".zip"结尾。解压后的文件不得包含".tfvars"文件。解压前最大支持1MB，解压后最大支持1MB。zip压缩包文件数量不能超过100个 template_body和template_uri 必须有且只有一个存在 **注意：** - 资源栈集不支持敏感数据加密，资源编排服务会直接明文使用、log、展示、存储template_uri对应的模板文件内容。 - template_uri对应的模板文件如果为zip类型，则内部的文件或文件夹名称长度不得超过255个字节，最深路径长度不得超过2048字节，zip包大小不得超过1MB 最小长度：**0** 最大长度：**2048** | | vars_uri | 否 | String | HCL参数文件的OBS地址。HCL模板支持参数传入，即，同一个模板可以给予不同的参数而达到不同的效果。 请确保OBS地址所在局点与使用RFS服务局点一致。 - vars_uri需要指向一个OBS的pre-signed URL地址，其他地址暂不支持 - 资源编排服务支持vars_body和vars_uri，如果以上两种方式中声明了同一个变量，将报错400 - vars_uri中的内容使用HCL的tfvars格式，用户可以将".tfvars"中的内容保存到文件并上传到OBS中，并将OBS pre-signed URL传递给vars_uri - 资源栈集不支持敏感数据加密，资源编排服务会直接明文使用、log、展示、存储vars_uri对应的参数文件内容 最小长度：**0** 最大长度：**2048** | | vars_body | 否 | String | HCL参数文件的内容。HCL模板支持参数传入，即，同一个模板可以给予不同的参数而达到不同的效果。 - vars_body使用HCL的tfvars格式，用户可以将".tfvars"中的内容提交到vars_body中 - 资源编排服务支持vars_body和vars_uri，如果以上两种方式中声明了同一个变量，将报错400 - 如果vars_body过大，可以使用vars_uri - 资源栈集不支持敏感数据加密，资源编排服务会直接明文使用、log、展示、存储对应的vars_body。 最小长度：**0** 最大长度：**51200** | | operation_preferences | 否 | [operation_preferences] object | 资源栈集操作（stack_set_operation）的部署策略。该参数只在指定的单次操作中生效。 当用户不指定该参数时，默认的操作部署策略为区域（region）内资源栈实例串行部署，即每次只执行一个资源栈实例，区域（region）间随机且串行部署，执行完一个region下的全部资源栈实例后，才会选择另一个region部署，容错次数默认为0。 该参数可以在生成资源栈集操作的四个API中指定： 创建资源栈实例（CreateStackInstance），部署资源栈集（DeployStackSet），更新资源栈实例（UpdateStackInstance），删除资源栈实例（DeleteStackInstance） | | call_identity | 否 | String | 仅支持资源栈集权限模式为SERVICE_MANAGED时指定该参数。用于指定用户是以组织管理账号还是成员账号中的服务委托管理员身份调用资源栈集。默认为SELF。 当资源栈集权限模式为SELF_MANAGED时，默认为SELF。 无论指定何种用户身份，涉及操作的资源栈集始终在组织管理账号名下。 - *SELF* - 以组织管理账号身份调用。 - *DELEGATED_ADMIN* - 以服务委托管理员身份调用。用户的华为云账号必须在组织中已经被注册为"资源编排资源栈集服务"的委托管理员。 | 表4deployment_targets | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | regions | 是 | Array of strings | 用户指定资源栈集操作所涉及的区域。 *在DeployStackSet API中，根据用户输入regions和domain_ids列表，以笛卡尔积的形式选择资源栈集中存在的资源栈实例进行部署。如果指定了没有被资源栈集所管理的region，则会报错。* | | domain_ids | 否 | Array of strings | 当资源栈集权限模型是SELF_MANAGED时，用户指定包含本次操作涉及到的租户ID内容。 *在DeployStackSet API中，如果指定该参数，根据用户输入的domain_ids列表和regions列表，以笛卡尔积的形式选择资源栈集中存在的资源栈实例进行部署。如果指定了没有被资源栈集所管理的domain_id，则会报错。* 当资源栈集权限模型是SERVICE_MANAGED时，该参数需结合domain_id_filter_type使用。用于指定资源栈集操作涉及到的，从所提供的OU中指定或排除部署的租户ID信息，或除提供的OU外，还进行额外部署的租户ID信息。 domain_ids和domain_ids_uri 有且仅有一个存在。 最小长度：**1** 最大长度：**64** 数组长度：**1 - 100** | | domain_ids_uri | 否 | String | 当资源栈集权限模型是SELF_MANAGED时，用户指定包含本次操作涉及到的租户ID内容文件的OBS地址。 内容格式要求每个租户ID以逗号（,）分隔，支持换行。当前仅支持csv文件，且文件的编码格式须为UTF-8。文件内容大小不超过100KB。 上传的csv文件应尽量避免Excel操作，以防出现读取内容不一致的问题。推荐使用记事本打开确认内容是否符合预期。 *在DeployStackSet API中，如果指定该参数，根据用户输入的domain_ids_uri文件内容和regions列表，以笛卡尔积的形式选择资源栈集中存在的资源栈实例进行部署。如果内容包含了没有被资源栈集所管理的domain_id，则会报错。* 当资源栈集权限模型是SERVICE_MANAGED时，该参数需结合domain_id_filter_type使用。链接文件内容用于指定资源栈集操作涉及到的，从所提供的OU中指定或排除部署的租户ID信息，或除提供的OU外，还进行额外部署的租户ID信息。 domain_ids和domain_ids_uri有且仅有一个存在。 最小长度：**0** 最大长度：**2048** | | organizational_unit_ids | 否 | Array of strings | 组织单元（Organizational Unit，缩写OU）ID列表，仅在资源栈集权限模型是SERVICE_MANAGED时，才允许指定该参数。 用户指定的Organization组织部署的ID列表，可以是根组织（Root）ID，也可以是某些组织单元的ID。 创建资源栈实例 （CreateStackInstances）API 必须指定该参数，该API 会异步校验OU IDs 的合法性，校验有效的OU IDs 及其所有非空子OU ID 都会被资源栈集记录管理。该API允许指定没有或者已经被资源栈集管理的OU IDs。 - 若资源栈集不自动部署，空子OU不会被资源栈集记录管理（特指子OU下无成员账号或部署排除其下所有成员账号）。\* - 【暂不支持】若资源栈集开启自动部署，空子OU也会被资源栈集记录管理（特指子OU下无成员账号或部署排除其下所有成员账号），自动部署仅针对成员账号变动，不针对其他组织结构变化，例如新增OU等，新增OU不会自动被资源栈集管理。\* 部署或删除资源栈实例（DeployStackSet、UpdateStackInstances、DeleteStackInstances） API，只允许指定已经被资源栈集管理的OU IDs。若指定了没有被资源栈集记录管理的OU IDs，则会报错。 删除资源栈实例 （DeleteStackInstances）API 必须指定该参数。 用户可以通过获取资源栈集元数据（ShowStackSetMetadata）API ，获取通过创建资源栈实例（CreateStackInstances）API 请求指定过的OU IDs。 资源栈集不仅会部署到目标 OU 中的用户，同时还会部署所有子 OU 下的用户。指定该参数后，资源栈集会根据用户输入的 OU 列表下所有的用户信息（包含子 OU 下的用户）和region列表，以笛卡尔积的形式，选择资源栈实例进行创建或部署。 *资源栈集不会选择组织管理员作为部署目标，进行资源栈实例的创建或部署，即使组织管理员位于给与的组织或组织的 OU 中。* 数组长度：**1 - 100** | | domain_id_filter_type | 否 | String | 租户ID筛选类型，仅支持资源栈集权限模型是SERVICE_MANAGED时指定该参数。默认为NONE 用户可以指定不同的筛选类型，通过domain_ids或domain_ids_uri 指定或排除部署的用户信息，以增加或限制部署目标用户范围，实现不同的部署策略。 - *INTERSECTION* - 从所提供的 OUs 中选择指定用户进行部署。指定该类型时，domain_ids和domain_ids_uri 有且仅能有一个存在。 - *DIFFERENCE* - 从所提供的 OUs 中排除指定用户部署。指定该类型时，domain_ids和domain_ids_uri 有且仅能有一个存在。 - *UNION* - 除了部署到提供的 OUs 外，还将部署到指定的账号中。用户可以通过同时指定organizational_unit_ids 和 domain_ids/domain_ids_uri 以实现在同一请求中部署整个OU和来自不同OU的特定个人账号。指定该类型时，domain_ids和domain_ids_uri 有且仅能有一个存在。创建资源栈实例（CreateStackInstances）除外，该API 不允许指定使用该类型。 - *NONE* - 只部署在指定 OUs 中的所有账号。该类型下domain_ids和domain_ids_uri字段必须为空。 | 表5operation_preferences | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | region_concurrency_type | 否 | String | 部署资源栈实例时区域（region）的执行策略，分为两种，SEQUENTIAL和PARALLEL，区分大小写，默认值为SEQUENTIAL 详细介绍： - *SEQUENTIAL*：顺序执行，执行完一个region下的全部资源栈实例后再去执行另一个region。默认顺序执行。 - *PARALLEL*：并发执行，并发部署所有指定区域的资源栈实例。 缺省值：**SEQUENTIAL** | | region_order | 否 | Array of strings | 区域（region）部署顺序。只有当用户指定region_concurrency_type为SEQUENTIAL时才会允许指定该参数。用户指定部署region的顺序，不允许出现资源栈集管理之外的region。 如果不指定，实际部署region顺序随机。部署顺序仅在当次部署时生效，应该包含且仅包含本次部署的所有region。 | | failure_tolerance_count | 否 | Long | 容错次数。用户定义在每个区域（region）下，允许部署失败的资源栈实例数量。该参数取值默认为0，限定0和正整数。 如果定义region顺序执行（region_concurrency_type值为SEQUENTIAL），在某个region超过容错次数时，资源栈集会取消所有状态仍处于WAIT_IN_PROGRESS状态的实例。被取消的实例状态最终变为CANCEL_COMPLETE； 如果是region并行执行（region_concurrency_type值为PARALLEL），在某个region超过容错次数时，资源栈集只会取消该region下所有处于WAIT_IN_PROGRESS状态的实例。被取消的实例状态最终变为CANCEL_COMPLETE。 对处于OPERATION_IN_PROGRESS，或已经部署完成，即处于OPERATION_COMPLETE或者OPERATION_FAILED状态的资源栈实例，不受影响，状态不变。 failure_tolerance_count 和 failure_tolerance_percentage 仅能有一个存在。 最小值：**0** 最大值：**100** | | failure_tolerance_percentage | 否 | Long | 容错百分比。定义每个区域（region）下，允许部署失败的资源栈实例数占该region下所有资源栈实例数的百分比。该参数取值默认为0，限定0和正整数。 通过容错百分比\*资源栈实例数，并向下取整，得到实际容错次数。 failure_tolerance_count 和 failure_tolerance_percentage 仅能有一个存在。 最小值：**0** 最大值：**100** | | max_concurrent_count | 否 | Long | 每个区域（region）下可同时部署资源栈实例的最大账号数。该参数取值默认为1，限定为正整数。 最大并发账号数最多比容错次数多1。如果用户指定failure_tolerance_percentage，最大并发账号数最多比 failure_tolerance_percentage \* 资源栈实例数多1。保证部署在所需的容错级别停止。 max_concurrent_count 和 max_concurrent_percentage 仅能有一个存在。 最小值：**1** 最大值：**5** | | max_concurrent_percentage | 否 | Long | 最大并发账号百分比，每个区域（region）中可同时部署的资源栈实例的最大账号百分比。该参数取值默认为1，限定正整数。 RFS根据百分比 \*（每个region下资源栈实例数）得到的值，再向下取整，得到实际最大并发账号数。如果实际最大并发账号数向下取整值为0时，则默认选择最大并发账号数为1。 通过百分比计算得到的实际最大并发账号数最多比容错次数多1。如果用户指定failure_tolerance_percentage，实际最大并发账号数最多比 failure_tolerance_percentage \* 资源栈实例数多1。保证部署在所需的容错级别停止。 max_concurrent_count 和 max_concurrent_percentage 仅能有一个存在。 最小值：**1** 最大值：**100** | | failure_tolerance_mode | 否 | String | 资源栈集操作部署的失败容忍模式，分为两种，STRICT_FAILURE_TOLERANCE和SOFT_FAILURE_TOLERANCE，区分大小写，默认值为STRICT_FAILURE_TOLERANCE。 详细介绍： - *STRICT_FAILURE_TOLERANCE*：此选项会动态降低并发级别，以确保同region下部署失败的账号数量永远不超过 failure_tolerance_count + 1。当用户指定failure_tolerance_percentage时，确保同region下部署失败的账号数量不超过 failure_tolerance_percentage \* 资源栈实例数 + 1。 - 初始实际最大并发数为max_concurrent_count，如果用户指定的是max_concurrent_percentage，则初始实际最大并发数为 max_concurrent_percentage \* 资源栈实例数，随后，实际最大并发数会根据失败次数增加而减少。 - *SOFT_FAILURE_TOLERANCE*：此选项将failure_tolerance_count (failure_tolerance_percentage) 与实际并发数分离开。该参数允许资源栈集操作始终以指定的 max_concurrent_count 或 max_concurrent_percentage 操作资源栈实例。 - 此时不保证资源栈实例失败总数小于 failure_tolerance_count + 1，如果用户指定的是failure_tolerance_percentage的值，则不保证资源栈实例失败总数小于 failure_tolerance_percentage \* 资源栈实例数 + 1。 缺省值：**STRICT_FAILURE_TOLERANCE** | #### 响应参数 **状态码：202** 表6响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | stack_set_operation_id | String | 资源栈集操作（stack_set_operation）的唯一Id。 此ID由资源编排服务在生成资源栈集操作的时候生成，为UUID。 最小长度：**36** 最大长度：**36** | **状态码：400** 表7响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | 响应码 最小长度：**11** 最大长度：**11** | | error_msg | String | 响应消息 | | encoded_authorization_message | String | 包含有关未经授权请求的信息。 | | details | Array of [Detail] objects | 权限拒绝时服务返回的详细错误信息。 | 表8Detail | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | 响应码 | | error_msg | String | 响应消息 | **状态码：401** 表9响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | 响应码 最小长度：**11** 最大长度：**11** | | error_msg | String | 响应消息 | | encoded_authorization_message | String | 包含有关未经授权请求的信息。 | | details | Array of [Detail] objects | 权限拒绝时服务返回的详细错误信息。 | 表10Detail | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | 响应码 | | error_msg | String | 响应消息 | **状态码：403** 表11响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | 响应码 最小长度：**11** 最大长度：**11** | | error_msg | String | 响应消息 | | encoded_authorization_message | String | 包含有关未经授权请求的信息。 | | details | Array of [Detail] objects | 权限拒绝时服务返回的详细错误信息。 | 表12Detail | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | 响应码 | | error_msg | String | 响应消息 | **状态码：404** 表13响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | 响应码 最小长度：**11** 最大长度：**11** | | error_msg | String | 响应消息 | | encoded_authorization_message | String | 包含有关未经授权请求的信息。 | | details | Array of [Detail] objects | 权限拒绝时服务返回的详细错误信息。 | 表14Detail | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | 响应码 | | error_msg | String | 响应消息 | **状态码：409** 表15响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | 响应码 最小长度：**11** 最大长度：**11** | | error_msg | String | 响应消息 | | encoded_authorization_message | String | 包含有关未经授权请求的信息。 | | details | Array of [Detail] objects | 权限拒绝时服务返回的详细错误信息。 | 表16Detail | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | 响应码 | | error_msg | String | 响应消息 | **状态码：429** 表17响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | 响应码 最小长度：**11** 最大长度：**11** | | error_msg | String | 响应消息 | | encoded_authorization_message | String | 包含有关未经授权请求的信息。 | | details | Array of [Detail] objects | 权限拒绝时服务返回的详细错误信息。 | 表18Detail | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | 响应码 | | error_msg | String | 响应消息 | **状态码：500** 表19响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | 响应码 最小长度：**11** 最大长度：**11** | | error_msg | String | 响应消息 | | encoded_authorization_message | String | 包含有关未经授权请求的信息。 | | details | Array of [Detail] objects | 权限拒绝时服务返回的详细错误信息。 | 表20Detail | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | 响应码 | | error_msg | String | 响应消息 | #### 请求示例 通过OBS Signed URL传递模板和参数信息，且指定部署资源栈集在region间串行进行 ``` 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" } } ``` #### 响应示例 **状态码：202** 请求接受，异步处理 ``` { "stack_set_operation_id" : "1b15e005-bdbb-4bd7-8f9a-a09b6774b4b3" } ``` #### 状态码 | 状态码 | 描述 | |:---|:---| | 202 | 请求接受，异步处理 | | 400 | 用户请求非法 | | 401 | 用户身份认证失败 | | 403 | 1. 用户无权限调用此API 2. 资源栈集状态非法，不允许创建并行操作 | | 404 | 资源栈集不存在 | | 409 | 部署冲突，另一个请求正在操作此资源栈集 | | 429 | 请求数量过多 | | 500 | 服务器内部错误 |