更新资源栈实例

功能介绍

更新资源栈实例（UpdateStackInstances）

此API用于更新并部署指定资源栈实例集合，并返回资源栈集操作ID（stack_set_operation_id）

此API可以通过var_overrides参数，更新指定资源栈实例的参数值，进行参数覆盖。如果var_overrides参数未给予，则默认使用当前资源栈集中记录的参数进行部署，详见：var_overrides参数描述。用户只可以更新已经存在的资源栈实例，如果用户想要增加额外的资源栈实例，请使用CreateStackInstances API。

通过DeployStackSet API更新资源栈集参数后，资源栈实例中已经被覆盖的参数不会被更新，仍然保留覆盖值。

用户只能覆盖已经在资源栈集中记录的参数，如果用户想要增加可以覆盖的参数，需要先通过DeployStackSet API更新资源栈集记录的参数集合。

当触发的部署失败时，资源栈实例不会自动回滚参数覆盖，但部署失败的资源栈会默认自动回滚，已经部署成功的资源栈不会触发回滚。
用户可以根据资源栈集操作ID（stack_set_operation_id），通过ShowStackSetOperationMetadata API获取资源栈集操作状态。

URI

PATCH /v1/stack-sets/{stack_set_name}/stack-instances

表1 路径参数
参数	是否必选	参数类型	描述
stack_set_name	是	String	资源栈集的名称。此名字在domain_id+region下应唯一，可以使用中文、大小写英文、数字、下划线、中划线。首字符需为中文或者英文，区分大小写。

请求参数

表2 请求Header参数
参数	是否必选	参数类型	描述
Client-Request-Id	是	String	用户指定的，对于此请求的唯一ID，用于定位某个请求，推荐使用UUID

表3 请求Body参数
参数	是否必选	参数类型	描述
stack_set_id	否	String	资源栈集（stack_set）的唯一ID。此ID由资源编排服务在生成资源栈集的时候生成，为UUID。由于资源栈集名仅仅在同一时间下唯一，即用户允许先生成一个叫HelloWorld的资源栈集，删除，再重新创建一个同名资源栈集。对于团队并行开发，用户可能希望确保，当前我操作的资源栈集就是我以为的那个，而不是被其他队友删除后创建的同名资源栈集。因此，使用ID就可以做到强匹配。资源编排服务保证每次创建的资源栈集所对应的ID都不相同，更新不会影响ID。如果给予的stack_set_id和当前资源栈集的ID不一致，则返回400
deployment_targets	是	deployment_targets object	部署目标信息。
var_overrides	否	var_overrides object	用户期望在资源栈实例中更新的参数内容，参数将覆盖到本次请求中指定的所有资源栈实例中，并根据更新后的参数部署资源栈实例。覆盖后的参数将永久被记录在资源栈实例中，并在之后的部署中继续使用被覆盖参数，直到下一次被更新覆盖。用户只能覆盖在资源栈集中记录的参数集合vars，如果指定了vars中不存在的参数会报错400。如果用户想要增加可以覆盖的参数，需要先通过DeployStackSet API 更新资源栈集记录的参数集合vars。通过DeployStackSet API更新vars后，资源栈实例中已经被覆盖的参数不会被更新，仍然保留覆盖值。参数覆盖只针对用户在资源栈集中通过vars指定的参数，不包括在模板中定义使用默认值的参数。如果用户期望对使用默认值的参数进行覆盖，则需要按上述要求先通过DeployStackSet API 更新资源栈集记录的vars，显式地向vars中增加相关参数定义。用户每次通过DeployStackSet API 更新资源栈集vars时，如果缺少了任一部署目标的资源栈实例中所记录的被覆盖参数时（即当前被覆盖参数已不是更新后资源栈集参数vars的子集)，会报错400 当前用户在更新参数覆盖时不能指定保留已有的参数覆盖，必须在更新的时候给予全部的覆盖信息。参数覆盖后的资源栈实例应用的vars_body总长不超过51200。参数覆盖后的资源栈实例应用的vars_uri文件内容不超过1M。例如：资源栈集中记录的vars_body内容为”key1=value1,key2=value2,....“，资源栈实例参数覆盖的vars_body为“key1=another_value1”，则要求应用参数覆盖后的vars_body“key1=another_value1,key2=value2,....”总长不超过51200。例如：资源栈集中记录的vars_uri文件内容为”key1=value1,key2=value2,....“，资源栈实例参数覆盖的vars_body为“key1=another_value1”，则要求应用参数覆盖后的vars_uri文件内容“key1=another_value1,key2=value2,....”总长不超过1M。如果var_overrides未给予，则不会更新覆盖资源栈实例中记录的参数。如果vars_uri或vars_body或use_stack_set_vars至少给予了一个，则会对参数覆盖进行替换式更新，即所给予的参数将被完全覆盖至指定资源栈实例中。 vars_body、vars_uri和use_stack_set_vars中声明的全部参数集合必须和资源栈集中记录的参数集合保持一致，如果声明了资源栈集中不存在的参数会报错400，如果没有声明已经在资源栈集中记录的参数会报错400，如果声明了同一个参数会报错400。注：期望覆盖指定参数值，需要在vars_uri或者vars_body中指定期望覆盖的参数名称及参数值。期望将某个已覆盖参数回退至资源栈集中记录的参数值，需要在use_stack_set_vars中指定期望回退的参数名称。期望将所有已覆盖参数回退至资源栈集中记录的参数值，需要在use_stack_set_vars中指定资源栈集中记录的全部参数名称。期望使用当前资源栈实例中记录的参数值进行部署，则不需要指定var_overrides。
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 - 以服务委托管理员身份调用。用户的华为云账号必须在组织中已经被注册为”资源编排资源栈集服务“的委托管理员。

表4 deployment_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 有且仅有一个存在。
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有且仅有一个存在。
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 中。
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字段必须为空。

表5 var_overrides
参数	是否必选	参数类型	描述
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对应的参数文件内容
vars_body	否	String	HCL参数文件的内容。HCL模板支持参数传入，即，同一个模板可以给予不同的参数而达到不同的效果。 vars_body使用HCL的tfvars格式，用户可以将“.tfvars”中的内容提交到vars_body中资源编排服务支持vars_body和vars_uri，如果以上两种方式中声明了同一个变量，将报错400 如果vars_body过大，可以使用vars_uri 资源栈集不支持敏感数据加密，资源编排服务会直接明文使用、log、展示、存储对应的vars_body。
use_stack_set_vars	否	Array of strings	用户期望使用资源栈集中记录的参数值进行部署的参数名称列表。用户只能选择已经在资源栈集中被记录的参数，如果指定了未被记录的参数会报错400。如果use_stack_set_vars中包含资源栈实例中已经被覆盖的参数名称，则会将该参数回退至资源栈集中记录的参数值。

表6 operation_preferences
参数	是否必选	参数类型	描述
region_concurrency_type	否	String	部署资源栈实例时区域（region）的执行策略，分为两种，SEQUENTIAL和PARALLEL，区分大小写，默认值为SEQUENTIAL 详细介绍： SEQUENTIAL：顺序执行，执行完一个region下的全部资源栈实例后再去执行另一个region。默认顺序执行。 PARALLEL：并发执行，并发部署所有指定区域的资源栈实例。
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 仅能有一个存在。
failure_tolerance_percentage	否	Long	容错百分比。定义每个区域（region）下，允许部署失败的资源栈实例数占该region下所有资源栈实例数的百分比。该参数取值默认为0，限定0和正整数。通过容错百分比*资源栈实例数，并向下取整，得到实际容错次数。 failure_tolerance_count 和 failure_tolerance_percentage 仅能有一个存在。
max_concurrent_count	否	Long	每个区域（region）下可同时部署资源栈实例的最大账号数。该参数取值默认为1，限定为正整数。最大并发账号数最多比容错次数多1。如果用户指定failure_tolerance_percentage，最大并发账号数最多比 failure_tolerance_percentage * 资源栈实例数多1。保证部署在所需的容错级别停止。 max_concurrent_count 和 max_concurrent_percentage 仅能有一个存在。
max_concurrent_percentage	否	Long	最大并发账号百分比，每个区域（region）中可同时部署的资源栈实例的最大账号百分比。该参数取值默认为1，限定正整数。 RFS根据百分比（每个region下资源栈实例数）得到的值，再向下取整，得到实际最大并发账号数。如果实际最大并发账号数向下取整值为0时，则默认选择最大并发账号数为1。通过百分比计算得到的实际最大并发账号数最多比容错次数多1。如果用户指定failure_tolerance_percentage，实际最大并发账号数最多比 failure_tolerance_percentage 资源栈实例数多1。保证部署在所需的容错级别停止。 max_concurrent_count 和 max_concurrent_percentage 仅能有一个存在。
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。

响应参数

状态码： 202

表7 响应Body参数
参数	参数类型	描述
stack_set_operation_id	String	资源栈集操作（stack_set_operation）的唯一Id。此ID由资源编排服务在生成资源栈集操作的时候生成，为UUID。

状态码： 400

表8 响应Body参数
参数	参数类型	描述
error_code	String	响应码
error_msg	String	响应消息
encoded_authorization_message	String	包含有关未经授权请求的信息。
details	Array of Detail objects	权限拒绝时服务返回的详细错误信息。

表9 Detail
参数	参数类型	描述
error_code	String	响应码
error_msg	String	响应消息

状态码： 401

**表10** 响应Body参数
参数	参数类型	描述
error_code	String	响应码
error_msg	String	响应消息
encoded_authorization_message	String	包含有关未经授权请求的信息。
details	Array of Detail objects	权限拒绝时服务返回的详细错误信息。

**表11** Detail
参数	参数类型	描述
error_code	String	响应码
error_msg	String	响应消息

状态码： 403

**表12** 响应Body参数
参数	参数类型	描述
error_code	String	响应码
error_msg	String	响应消息
encoded_authorization_message	String	包含有关未经授权请求的信息。
details	Array of Detail objects	权限拒绝时服务返回的详细错误信息。

**表13** Detail
参数	参数类型	描述
error_code	String	响应码
error_msg	String	响应消息

状态码： 404

**表14** 响应Body参数
参数	参数类型	描述
error_code	String	响应码
error_msg	String	响应消息
encoded_authorization_message	String	包含有关未经授权请求的信息。
details	Array of Detail objects	权限拒绝时服务返回的详细错误信息。

**表15** Detail
参数	参数类型	描述
error_code	String	响应码
error_msg	String	响应消息

状态码： 429

**表16** 响应Body参数
参数	参数类型	描述
error_code	String	响应码
error_msg	String	响应消息
encoded_authorization_message	String	包含有关未经授权请求的信息。
details	Array of Detail objects	权限拒绝时服务返回的详细错误信息。

**表17** Detail
参数	参数类型	描述
error_code	String	响应码
error_msg	String	响应消息

状态码： 500

**表18** 响应Body参数
参数	参数类型	描述
error_code	String	响应码
error_msg	String	响应消息
encoded_authorization_message	String	包含有关未经授权请求的信息。
details	Array of Detail objects	权限拒绝时服务返回的详细错误信息。

**表19** Detail
参数	参数类型	描述
error_code	String	响应码
error_msg	String	响应消息

请求示例

通过vars uri 传递期望更新的覆盖参数，保留资源栈实例中已被覆盖的参数var_key_1，并触发部署，且指定更新资源栈实例在region间串行进行

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

{
  "deployment_targets" : {
    "regions" : [ "cn-north-7" ],
    "domain_ids_uri" : "https://your-bucket.cn-north-7.myhuaweicloud.com/my-domain-ids.csv"
  },
  "var_overrides" : {
    "vars_uri" : "https://{bucket_name}.{region}.myhuaweicloud.com/my-hello-world-vars.tfvars",
    "use_stack_set_vars" : [ "var_key_1" ]
  },
  "stack_set_id" : "1b15e005-bdbb-4bd7-8f9a-a09b6774b4b4",
  "operation_preferences" : {
    "region_concurrency_type" : "SEQUENTIAL"
  }
}

部署在cn-north-7下租户ID为my-domain-id的资源栈实例，不更新参数覆盖，且指定更新资源栈实例在region间并行进行

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

{
  "deployment_targets" : {
    "regions" : [ "cn-north-7" ],
    "domain_ids" : [ "my-domain-id" ]
  },
  "stack_set_id" : "1b15e005-bdbb-4bd7-8f9a-a09b6774b4b4",
  "operation_preferences" : {
    "region_concurrency_type" : "PARALLEL"
  }
}

响应示例

状态码： 202

请求接受，异步处理

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

状态码

状态码	描述
202	请求接受，异步处理
400	用户请求非法
401	用户身份认证失败
403	用户无权限调用此API 资源栈集状态非法，不允许创建并行操作
404	资源栈集不存在
429	请求数量过多
500	服务器内部错误