# 创建资源栈 #### 功能介绍 CreateStack用于生成一个资源栈 - 当请求中不含有模板（template）、参数（vars）等信息，将生成一个无任何资源的空资源栈，返回资源栈ID（stack_id） - 当请求中携带了模板（template）、参数（vars）等信息，则会同时创建并部署资源栈，返回资源栈ID（stack_id）和部署ID（deployment_id） - 若指定 encrypt_kms_key_id 启用模板加密功能，请确保资源栈委托角色（如已配置）或当前账号身份拥有该主密钥的 kms:dek:create（创建数据密钥） 和 kms:dek:decrypt（解密数据密钥） 访问权限。 #### 调试 您可以在[API Explorer](https://console.huaweicloud.com/apiexplorer/#/openapi/AOS/doc?api=CreateStack)中调试该接口，支持自动认证鉴权。API Explorer可以自动生成SDK代码示例，并提供SDK代码示例调试功能。 #### URI POST /v1/{project_id}/stacks 表1路径参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | project_id | 是 | String | 项目ID，可以从调用API处获取，也可以从控制台获取。 [项目ID获取方式](https://support.huaweicloud.com/api-ticket/ticket_api_20002.html) 最小长度：**3** 最大长度：**64** | #### 请求参数 表2请求Header参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | Client-Request-Id | 是 | String | 用户指定的，对于此请求的唯一ID，用于定位某个请求，推荐使用UUID 最小长度：**36** 最大长度：**128** | 表3请求Body参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | stack_name | 是 | String | 资源栈的名称。此名字在domain_id+区域+project_id下应唯一，可以使用中文、大小写英文、数字、下划线、中划线。首字符需为中文或者英文，区分大小写。 最小长度：**1** 最大长度：**128** | | agencies | 否 | Array of [Agency] objects | 委托授权的信息。 RFS仅在创建资源栈（触发部署）、创建执行计划、部署资源栈、删除资源栈等涉及资源操作的请求中使用委托，且该委托仅作用于与之绑定的Provider对资源的操作中。如果委托中提供的权限不足，有可能导致相关资源操作失败。 [创建委托及授权方式](https://support.huaweicloud.com/usermanual-iam/iam_06_0002.html) 数组长度：**0 - 10** | | description | 否 | String | 资源栈的描述。可用于客户识别自己的资源栈。 最小长度：**0** 最大长度：**1024** | | enable_deletion_protection | 否 | Boolean | 删除保护的标识位，如果不传默认为false，即默认不开启资源栈删除保护（删除保护开启后资源栈不允许被删除） 在UpdateStack API中，如果该参数未在RequestBody中给予，则不会对资源栈的删除保护属性进行更新 | | enable_auto_rollback | 否 | Boolean | 自动回滚的标识位，如果不传默认为false，即默认不开启资源栈自动回滚（自动回滚开启后，如果部署失败，则会自动回滚，并返回上一个稳定状态） 在UpdateStack API中，如果该参数未在RequestBody中给予，则不会对资源栈的自动回滚属性进行更新 该属性与使用模板导入资源功能互斥，如果资源栈的自动回滚设置为true，则不允许部署包含导入资源的模板 | | template_body | 否 | String | HCL模板，描述了资源的目标状态。资源编排服务将比较此模板与当前远程资源的状态之间的区别。 template_body，template_uri和private_template必须有且只有一个存在 在CreateStack API中，template_body，template_uri和private_template可以都不给予 **注意：** - template_body中默认不应该含有任何敏感信息，资源编排服务会直接明文使用、log、展示和存储对应的template_body。如为敏感信息，建议在模板中抽取变量并声明为sensitive，将敏感信息通过vars_structure参数化，并设置encryption字段开启加密 （如果变量variable在模板中被标记为sensitive，则在 GetStackMetadata 和 GetExecutionPlanMetadata 接口返回的 vars_structure、vars_uri_content、vars_body 中，该变量的值将被脱敏） 最小长度：**0** 最大长度：**51200** | | template_uri | 否 | String | HCL模板的OBS地址，该模板描述了资源的目标状态。资源编排服务将比较此模板与当前远程资源的状态之间的区别。 请确保OBS地址所在局点与使用RFS服务局点一致。 对应的文件应该是纯tf文件或zip压缩包 纯tf文件需要以.tf或者.tf.json结尾，并遵守HCL语法 压缩包目前只支持zip格式，文件需要以.zip结尾。解压后的文件不得包含.tfvars文件且必须是UTF8编码（其中.tf.json不能包含BOM头），zip压缩包当前支持的子文件数量最大为100 template_body，template_uri和private_template必须有且只有一个存在 在CreateStack API中，template_body，template_uri和private_template可以都不给予 **注意：** - template_uri对应的模板文件中默认不应该含有任何敏感信息，资源编排服务会直接明文使用、log、展示和存储对应的模板文件内容。如为敏感信息，建议在模板中抽取变量并声明为sensitive，将敏感信息通过vars_structure参数化，并设置encryption字段开启加密 - template_uri对应的模板文件如果为zip类型，则内部的文件或文件夹名称长度不得超过255个字节，最深路径长度不得超过2048字节，zip包大小不得超过1MB （如果变量variable在模板中被标记为sensitive，则在 GetStackMetadata 和 GetExecutionPlanMetadata 接口返回的 vars_structure、vars_uri_content、vars_body 中，该变量的值将被脱敏） 最小长度：**0** 最大长度：**2048** | | vars_body | 否 | String | HCL参数文件的内容。HCL模板支持参数传入，即，同一个模板可以给予不同的参数而达到不同的效果。 - vars_body使用HCL的tfvars格式，用户可以将".tfvars"中的内容提交到vars_body中。 - 资源编排服务支持vars_structure，vars_body和vars_uri，如果以上三种方式中声明了同一个变量，将报错400 - vars_body最大长度为51200字节，如果vars_body过大，可以使用vars_uri - 如果vars中都是简单的字符串格式，可以使用var_structure - 注意：vars_body中不应该含有任何敏感信息，资源编排服务会直接明文使用、log、展示和存储对应的vars。如为敏感信息，建议通过vars_structure并设置encryption字段传递 最小长度：**0** 最大长度：**51200** | | vars_structure | 否 | Array of [VarsStructure] objects | HCL参数结构。HCL模板支持参数传入，即，同一个模板可以给予不同的参数而达到不同的效果。 - var_structure可以允许客户提交最简单的字符串类型的参数 - 资源编排服务支持vars_structure，vars_body和vars_uri，如果以上三种方式中声明了同一个变量，将报错400 - vars_structure中的值只支持简单的字符串类型，如果需要使用其他类型，需要用户自己在HCL引用时转换， - vars_structure最多允许100项，如果vars_structure过大，可以使用vars_uri - 注意：vars_structure中默认不应该含有任何敏感信息，资源编排服务会直接明文使用、log、展示和存储对应的vars。如为敏感信息，建议设置encryption字段开启加密 或者用户可以使用vars_uri、vars_body，vars_uri和vars_body中支持HCL支持的各种类型以及复杂结构 数组长度：**0 - 100** | | vars_uri | 否 | String | HCL参数文件的OBS地址。HCL模板支持参数传入，即，同一个模板可以给予不同的参数而达到不同的效果。 请确保OBS地址所在局点与使用RFS服务局点一致。 - vars_uri最大长度为2048字节，vars_uri所指向的HCL参数文件大小最大长度为1MB。 - 资源编排服务支持vars_structure，vars_body和vars_uri，如果以上三种方式中声明了同一个变量，将报错400 - vars_uri中的内容使用HCL的tfvars格式，用户可以将".tfvars"中的内容保存到文件并上传到OBS中，并将OBS pre-signed URL传递给vars_uri。 - 注意：vars_uri的内容不应该含有任何敏感信息，资源编排服务会直接明文使用、log、展示和存储对应的vars。如为敏感信息，建议通过vars_structure并设置encryption字段传递 最小长度：**0** 最大长度：**2048** | | encrypt_kms_key_id | 否 | String | 用于加密模板的KMS主密钥ID，当前仅支持 AES_256 算法的密钥。设置后，RFS将使用该密钥对Terraform模板进行加密存储。请注意，使用此密钥会产生相应的KMS服务费用。重要：该密钥一旦被用于加密，请谨慎删除。若密钥被删除，将导致相关堆栈无法访问，操作风险由您自行承担。 最小长度：**36** 最大长度：**36** | | private_template | 否 | [PrivateTemplate] object | | | tags | 否 | Array of [Tag] objects | 标签列表 | 表4Agency | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | provider_name | 是 | String | 用户使用的provider的名字。 如果用户给予的provider_name含有重复的值，则返回400 取值范围： - huaweicloud 最小长度：**1** 最大长度：**128** | | agency_name | 否 | String | 对应provider所使用的IAM委托名称，资源编排服务会使用此委托的权限去访问、创建对应provider的资源。agency_name和agency_urn必须有且只有一个存在 最小长度：**1** 最大长度：**64** | | agency_urn | 否 | String | 委托URN 当用户定义Agency时，agency_name和agency_urn 必须有且只有一个存在。 推荐用户在使用信任委托时给予agency_urn。 | 表5VarsStructure | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | var_key | 是 | String | 参数的名字 最小长度：**1** 最大长度：**32** | | var_value | 是 | String | 参数的值。 注意，参数需要以字符串形式存在，如果是数字，也需要以字符串形式存在，如'10'。 如果需要支持不同类型，或者复杂结构，请使用vars_uri或vars_body 最小长度：**0** 最大长度：**2048** | | encryption | 否 | [EncryptionStructure] object | 如果用户传递的var_value是已经加密过的，可以通过声明此项以要求资源编排服务在使用前进行解密，目前暂时只支持KMS加解密 | 表6EncryptionStructure | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | kms | 是 | [KmsStructure] object | 如果用户给予的var_value是经过KMS加密的，可以通过传递相关加密信息，资源编排服务在使用的时候会帮助用户进行KMS解密 更多关于KMS加密以及KMS加密的样例代码请见：[KMS加密使用场景介绍](https://support.huaweicloud.com/productdesc-dew/dew_01_0006.html) **注意：** - 请确保用户给予资源编排服务的委托中包含对指定密钥ID的操作权限 - KMS每个月有免费试用的额度，如果超过，则KMS需要收费，此费用不是资源编排服务收取，具体标准见： - KMS加密只代表资源编排服务在存储和传输的时候传递的是密文，但是在stack-events中依然是明文，如果希望在log中以密文形式对待，请在模板中声明sensitive，更多关于sensitive的介绍见： | 表7KmsStructure | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | id | 是 | String | 解密时，资源编排服务应该使用的KMS密钥的ID，通常是加密时所使用的密钥ID 最小长度：**36** 最大长度：**36** | | cipher_text | 是 | String | 数据加密密钥所对应的密文 最小长度：**2** 最大长度：**2048** | 表8PrivateTemplate | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | template_id | 是 | String | 私有模板（PrivateTemplate）的Id。 最小长度：**36** 最大长度：**36** | | template_version | 是 | String | 模板版本Id，以大写V开头。 最小长度：**2** 最大长度：**11** | 表9Tag | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | key | 是 | String | 标签键 最小长度：**1** 最大长度：**128** | | value | 是 | String | 标签值 最小长度：**0** 最大长度：**255** | #### 响应参数 **状态码：201** 表10响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | stack_id | String | 资源栈（stack）的唯一ID。 此Id由资源编排服务在生成资源栈的时候生成，为UUID。 由于资源栈名仅仅在同一时间下唯一，即用户允许先生成一个叫HelloWorld的资源栈，删除，再重新创建一个同名资源栈。 对于团队并行开发，用户可能希望确保，当前我操作的资源栈就是我认为的那个，而不是其他队友删除后创建的同名资源栈。因此，使用ID就可以做到强匹配。 资源编排服务保证每次创建的资源栈所对应的ID都不相同，更新不会影响ID。如果给予的stack_id和当前资源栈的ID不一致，则返回400 最小长度：**36** 最大长度：**36** | | deployment_id | String | 部署ID 接受请求，进行异步处理。可以调用GetStackMetadata来获取异步请求的部署状态 **注意：** - 部署资源栈后，资源编排服务持久化请求并立即返回，客户端不等待请求最终处理完成，用户无法实时感知请求处理结果 - 资源编排服务最终会将异步部署请求排队，在服务端空闲的情况下逐个处理。用户最大等待时长为6小时 | **状态码：400** 表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 | 响应消息 | **状态码：401** 表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 | 响应消息 | **状态码：403** 表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 | 响应消息 | **状态码：409** 表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 | 响应消息 | **状态码：429** 表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 | 响应消息 | **状态码：500** 表21响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | 响应码 最小长度：**11** 最大长度：**11** | | error_msg | String | 响应消息 | | encoded_authorization_message | String | 包含有关未经授权请求的信息。 | | details | Array of [Detail] objects | 权限拒绝时服务返回的详细错误信息。 | 表22Detail | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | 响应码 | | error_msg | String | 响应消息 | #### 请求示例 - 创建资源栈 ``` POST https://{endpoint}/v1/ba2b9930c977f71edaeaa3a5e96a8ff1/stacks { "stack_name" : "my_first_stack", "description" : "my first stack" } ``` - 使用委托创建资源栈 ``` POST https://{endpoint}/v1/ba2b9930c977f71edaeaa3a5e96a8ff1/stacks { "stack_name" : "my_second_stack", "description" : "my second stack", "agencies" : [ { "provider_name" : "huaweicloud", "agency_name" : "my_agency" } ] } ``` - 使用模板的uri创建并部署资源栈 ``` POST https://{endpoint}/v1/ba2b9930c977f71edaeaa3a5e96a8ff1/stacks { "stack_name" : "my_third_stack", "template_uri" : "https://my_hello_world_bucket.{region}.myhuaweicloud.com/my-hello-world-template.tf", "description" : "my third stack" } ``` - 使用模板内容创建并部署资源栈。RFS模板支持HCL语法，同时规定required_providers模块下用于声明provider路径的source字段，需按照huawei.com/provider/{provider_name}的形式拼接，例如huawei.com/provider/huaweicloud ``` POST https://{endpoint}/v1/ba2b9930c977f71edaeaa3a5e96a8ff1/stacks { "stack_name" : "my_fourth_stack", "template_body" : "terraform {\n required_providers {\n huaweicloud = {\n source = \"huawei.com/provider/huaweicloud\"\n version = \"1.41.0\"\n }\n }\n}\nprovider \"huaweicloud\"{\n insecure = true\n cloud = \"{cloud_name}\"\n region = \"{region}\"\n endpoints = {\n iam = \"{iam_endpoint}\"\n }\n}\n\nresource \"huaweicloud_vpc\" \"vpc\" {\n cidr = \"172.16.0.0/16\"\n name = \"my_vpc\"\n}", "description" : "my fourth stack" } ``` - 使用私有模板创建并部署资源栈 ``` POST https://{endpoint}/v1/ba2b9930c977f71edaeaa3a5e96a8ff1/stacks { "stack_name" : "my_fifth_stack", "private_template" : { "template_id" : "69f8d5ea-eaa4-4a3b-a96d-bae9230e97c9", "template_version" : "V1" } } ``` #### 响应示例 **状态码：201** 创建成功 - 创建资源栈 ``` { "stack_id" : "ea6a4f0e-ee8a-494e-b12a-8be4a1e65af2" } ``` - 使用委托创建资源栈 ``` { "stack_id" : "ea6a4f0e-ee8a-494e-b12a-8be4a1e65af2" } ``` - 使用模板的uri创建并部署资源栈 ``` { "stack_id" : "ea6a4f0e-ee8a-494e-b12a-8be4a1e65af2", "deployment_id" : "d102dda3-10af-48db-75bb-16c2661c79d6" } ``` - 使用模板内容创建并部署资源栈。RFS模板支持HCL语法，同时规定required_providers模块下用于声明provider路径的source字段，需按照huawei.com/provider/{provider_name}的形式拼接，例如huawei.com/provider/huaweicloud ``` { "stack_id" : "ea6a4f0e-ee8a-494e-b12a-8be4a1e65af2", "deployment_id" : "d102dda3-10af-48db-75bb-16c2661c79d6" } ``` - 使用私有模板创建并部署资源栈 ``` { "stack_id" : "ea6a4f0e-ee8a-494e-b12a-8be4a1e65af2", "deployment_id" : "d102dda3-10af-48db-75bb-16c2661c79d6" } ``` #### 状态码 | 状态码 | 描述 | |:---|:---| | 201 | 创建成功 | | 400 | 用户请求非法 | | 401 | 用户身份认证失败 | | 403 | 1. 用户无权限调用此API 2. 资源栈数量达到上限 | | 409 | 创建冲突，同名的资源栈已经存在 | | 429 | 请求数量过多 | | 500 | 服务器内部错误 |