部署资源栈集
功能介绍
部署资源栈集(DeployStackSet)
此API用于部署一个已有的资源栈集,并返回资源栈集操作ID(stack_set_operation_id)
- 用户可以使用此API更新资源栈集的模板、参数并进行部署。
- 此API会直接触发资源栈实例部署。用户既可以部署资源栈集下所有的资源栈实例,也可以部署指定资源栈实例。
- 此API为全量API,即用户每次部署都需要给予所想要使用的template、vars的全量
- 当触发的部署失败时,资源栈集不会自动回滚模板和参数,但部署失败的资源栈会根据资源栈的回滚配置决定是否进行回滚,已经部署成功的资源栈不会触发回滚。
- 用户可以根据资源栈集操作ID(stack_set_operation_id),通过ShowStackSetOperationMetadata API获取资源栈集操作状态
URI
POST /v1/stack-sets/{stack_set_name}/deployments
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
stack_set_name |
是 |
String |
资源栈集的名称。此名字在domain_id+region下应唯一,可以使用中文、大小写英文、数字、下划线、中划线。首字符需为中文或者英文,区分大小写。 最小长度:1 最大长度:128 |
请求参数
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
Client-Request-Id |
是 |
String |
用户指定的,对于此请求的唯一ID,用于定位某个请求,推荐使用UUID 最小长度:36 最大长度:128 |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
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 必须有且只有一个存在 注意:
最小长度:0 最大长度:51200 |
template_uri |
否 |
String |
HCL模板的OBS地址,该模板描述了资源的目标状态。资源编排服务将比较此模板与当前远程资源的状态之间的区别 OBS地址支持同类型Region之间进行互相访问(Region分为通用Region和专属Region,通用Region指面向公共租户提供通用云服务的Region;专属Region指只承载同一类业务或只面向特定租户提供业务服务的专用Region) 对应的文件应该是纯tf文件或zip压缩包 纯tf文件需要以“.tf”或者“.tf.json”结尾,并遵守HCL语法,且文件的编码格式须为UTF-8 压缩包目前只支持zip格式,文件需要以".zip"结尾。解压后的文件不得包含".tfvars"文件。解压前最大支持1MB,解压后最大支持1MB。zip压缩包文件数量不能超过100个 template_body和template_uri 必须有且只有一个存在 注意:
最小长度:0 最大长度:2048 |
vars_uri |
否 |
String |
HCL参数文件的OBS地址。HCL模板支持参数传入,即,同一个模板可以给予不同的参数而达到不同的效果。 OBS地址支持同类型Region之间进行互相访问(Region分为通用Region和专属Region,通用Region指面向公共租户提供通用云服务的Region;专属Region指只承载同一类业务或只面向特定租户提供业务服务的专用Region)
最小长度:0 最大长度:2048 |
vars_body |
否 |
String |
HCL参数文件的内容。HCL模板支持参数传入,即,同一个模板可以给予不同的参数而达到不同的效果。
最小长度:0 最大长度:51200 |
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。 注:
|
operation_preferences |
否 |
operation_preferences object |
资源栈集操作(stack_set_operation)的部署策略。该参数只在指定的单次操作中生效。 当用户不指定该参数时,默认的操作部署策略为区域(region)内资源栈实例串行部署,即每次只执行一个资源栈实例,区域(region)间随机且串行部署,执行完一个region下的全部资源栈实例后,才会选择另一个region部署,容错次数默认为0。 该参数可以在生成资源栈集操作的四个API中指定: 创建资源栈实例(CreateStackInstance),部署资源栈集(DeployStackSet),更新资源栈实例(UpdateStackInstance),删除资源栈实例(DeleteStackInstance) |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
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,则会报错。 domain_ids和domain_ids_uri 有且仅有一个存在。 最小长度:1 最大长度:64 |
domain_ids_uri |
否 |
String |
权限模型是SELF_MANAGED时,用户指定包含本次操作涉及到的租户ID内容文件的OBS地址。 内容格式要求每个租户ID以逗号(,)分割,支持换行。当前仅支持csv文件,且文件的编码格式须为UTF-8。文件内容大小不超过100KB。 上传的csv文件应尽量避免Excel操作,以防出现读取内容不一致的问题。推荐使用记事本打开确认内容是否符合预期。 在DeployStackSet API中,如果指定该参数,根据用户输入的domain_ids_uri文件内容和regions列表,以笛卡尔积的形式选择资源栈集中存在的资源栈实例进行部署。如果内容包含了没有被资源栈集所管理的domain_id,则会报错。 domain_ids和domain_ids_uri有且仅有一个存在。 最小长度:0 最大长度:2048 |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
vars_uri |
否 |
String |
HCL参数文件的OBS地址。HCL模板支持参数传入,即,同一个模板可以给予不同的参数而达到不同的效果。 OBS地址支持同类型Region之间进行互相访问(Region分为通用Region和专属Region,通用Region指面向公共租户提供通用云服务的Region;专属Region指只承载同一类业务或只面向特定租户提供业务服务的专用Region)
最小长度:0 最大长度:2048 |
vars_body |
否 |
String |
HCL参数文件的内容。HCL模板支持参数传入,即,同一个模板可以给予不同的参数而达到不同的效果。
最小长度:0 最大长度:51200 |
use_stack_set_vars |
否 |
Array of strings |
用户期望使用资源栈集中记录的参数值进行部署的参数名称列表。 用户只能选择已经在资源栈集中被记录的参数,如果指定了未被记录的参数会报错400。 如果use_stack_set_vars中包含资源栈实例中已经被覆盖的参数名称,则会将该参数回退至资源栈集中记录的参数值。 |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
region_concurrency_type |
否 |
String |
部署资源栈实例时区域(region)的执行策略,分为两种,SEQUENTIAL和PARALLEL,区分大小写,默认值为SEQUENTIAL 详细介绍:
缺省值: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 枚举值:
|
响应参数
状态码: 202
参数 |
参数类型 |
描述 |
---|---|---|
stack_set_operation_id |
String |
资源栈集操作(stack_set_operation)的唯一Id。 此ID由资源编排服务在生成资源栈集操作的时候生成,为UUID。 最小长度:36 最大长度:36 |
状态码: 400
参数 |
参数类型 |
描述 |
---|---|---|
error_code |
String |
响应码 最小长度:11 最大长度:11 |
error_msg |
String |
响应消息 |
encoded_authorization_message |
String |
包含有关未经授权请求的信息。 |
状态码: 401
参数 |
参数类型 |
描述 |
---|---|---|
error_code |
String |
响应码 最小长度:11 最大长度:11 |
error_msg |
String |
响应消息 |
encoded_authorization_message |
String |
包含有关未经授权请求的信息。 |
状态码: 403
参数 |
参数类型 |
描述 |
---|---|---|
error_code |
String |
响应码 最小长度:11 最大长度:11 |
error_msg |
String |
响应消息 |
encoded_authorization_message |
String |
包含有关未经授权请求的信息。 |
状态码: 404
参数 |
参数类型 |
描述 |
---|---|---|
error_code |
String |
响应码 最小长度:11 最大长度:11 |
error_msg |
String |
响应消息 |
encoded_authorization_message |
String |
包含有关未经授权请求的信息。 |
状态码: 409
参数 |
参数类型 |
描述 |
---|---|---|
error_code |
String |
响应码 最小长度:11 最大长度:11 |
error_msg |
String |
响应消息 |
encoded_authorization_message |
String |
包含有关未经授权请求的信息。 |
状态码: 429
参数 |
参数类型 |
描述 |
---|---|---|
error_code |
String |
响应码 最小长度:11 最大长度:11 |
error_msg |
String |
响应消息 |
encoded_authorization_message |
String |
包含有关未经授权请求的信息。 |
状态码: 500
参数 |
参数类型 |
描述 |
---|---|---|
error_code |
String |
响应码 最小长度:11 最大长度:11 |
error_msg |
String |
响应消息 |
encoded_authorization_message |
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" : [ "region_id" ], "domain_ids" : [ "0e0bc7572c0dfb74efa6c60ecd7b1dbf" ] }, "operation_preferences" : { "region_concurrency_type" : "SEQUENTIAL" } }
响应示例
状态码: 202
请求接受,异步处理
{ "stack_set_operation_id" : "1b15e005-bdbb-4bd7-8f9a-a09b6774b4b3" }
状态码
状态码 |
描述 |
---|---|
202 |
请求接受,异步处理 |
400 |
用户请求非法 |
401 |
用户身份认证失败 |
403 |
|
404 |
资源栈集不存在 |
409 |
部署冲突,另一个请求正在操作此资源栈集 |
429 |
请求数量过多 |
500 |
服务器内部错误 |