文档首页/ 资源编排服务 RFS/ API参考（吉隆坡区域）/ API/ 资源栈/ 创建资源栈
更新时间：2024-12-12 GMT+08:00
在线调试
CLI示例
查看PDF
分享

创建资源栈

功能介绍

CreateStack用于生成一个资源栈

  • 当请求中不含有模板（template）、参数（vars）等信息，将生成一个无任何资源的空资源栈，返回资源栈ID（stack_id）
  • 当请求中携带了模板（template）、参数（vars）等信息，则会同时创建并部署资源栈，返回资源栈ID（stack_id）和部署ID（deployment_id）

URI

POST /v1/{project_id}/stacks

表1 路径参数

参数

是否必选

参数类型

描述

project_id

是

String

项目ID，可以从调用API处获取，也可以从控制台获取。

项目ID获取方式

最小长度：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对资源的操作中。如果委托中提供的权限不足，有可能导致相关资源操作失败。

创建委托及授权方式

数组长度：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 必须有且只有一个存在

在CreateStack API中，template_body和template_uri可以都不给予

注意：

  • template_body中默认不应该含有任何敏感信息，资源编排服务会直接明文使用、log、展示、存储对应的template_body。如为敏感信息，建议将敏感信息通过vars_structure参数化，并设置encryption字段开启加密

最小长度：0

最大长度：51200

template_uri

否

String

HCL模板的OBS地址，该模板描述了资源的目标状态。资源编排服务将比较此模板与当前远程资源的状态之间的区别。

OBS地址支持同类型Region之间进行互相访问（Region分为通用Region和专属Region，通用Region指面向公共租户提供通用云服务的Region；专属Region指只承载同一类业务或只面向特定租户提供业务服务的专用Region）

对应的文件应该是纯tf文件或zip压缩包

纯tf文件需要以.tf或者.tf.json结尾，并遵守HCL语法

压缩包目前只支持zip格式，文件需要以.zip结尾。解压后的文件不得包含".tfvars"文件且必须是UTF8编码（其中.tf.json不能包含BOM头），zip压缩包当前支持的子文件数量最大为100

template_body和template_uri 必须有且只有一个存在

在CreateStack API中，template_body和template_uri可以都不给予

注意：

  • template_uri对应的模板文件中默认不应该含有任何敏感信息，资源编排服务会直接明文使用、log、展示、存储对应的模板文件内容。如为敏感信息，建议将敏感信息通过vars_structure参数化，并设置encryption字段开启加密
  • template_uri对应的模板文件如果为zip类型，则内部的文件或文件夹名称长度不得超过255个字节，最深路径长度不得超过2048字节，zip包大小不得超过1MB

最小长度：0

最大长度：2048

vars_body

否

String

HCL参数文件的内容。HCL模板支持参数传入，即，同一个模板可以给予不同的参数而达到不同的效果。

  • vars_body使用HCL的tfvars格式，用户可以将“.tfvars”中的内容提交到vars_body中。
  • 资源编排服务支持vars_structure，vars_body和vars_uri，如果以上三种方式中声名了同一个变量，将报错400
  • 如果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_uri、vars_body，vars_uri和vars_body中支持HCL支持的各种类型以及复杂结构
  • 如果vars_structure过大，可以使用vars_uri
  • 注意：vars_structure中默认不应该含有任何敏感信息，资源编排服务会直接明文使用、log、展示、存储对应的vars。如为敏感信息，建议设置encryption字段开启加密

数组长度：0 - 100

vars_uri

否

String

HCL参数文件的OBS地址。HCL模板支持参数传入，即，同一个模板可以给予不同的参数而达到不同的效果。

OBS地址支持同类型Region之间进行互相访问（Region分为通用Region和专属Region，通用Region指面向公共租户提供通用云服务的Region；专属Region指只承载同一类业务或只面向特定租户提供业务服务的专用Region）

  • 资源编排服务支持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
表4 Agency

参数

是否必选

参数类型

描述

provider_name

是

String

用户使用的provider的名字。如果用户给予的provider_name含有重复的值，则返回400

最小长度：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，agency_name只支持接收普通委托名称，如果给予了信任委托名称，则会在部署模板时失败。
表5 VarsStructure

参数

是否必选

参数类型

描述

var_key

是

String

参数的名字

最小长度：1

最大长度：32

var_value

是

String

参数的值。

注意，参数需要以字符串形式存在，如果是数字，也需要以字符串形式存在，如'10'。

如果需要支持不同类型，或者复杂结构，请使用vars_uri或vars_body

最小长度：0

最大长度：2048

encryption

否

EncryptionStructure object

如果用户传递的var_value是已经加密过的，可以通过声名此项以要求资源编排服务在使用前进行解密，目前暂时只支持KMS加解密
表6 EncryptionStructure

参数

是否必选

参数类型

描述

kms

是

KmsStructure object

如果用户给予的var_value是经过KMS加密的，可以通过传递相关加密信息，资源编排服务在使用的时候会帮助用户进行KMS解密

更多关于KMS加密以及KMS加密的样例代码请见：KMS加密使用场景介绍

注意：

  • 请确保用户给予资源编排服务的委托中包含对指定密钥ID的操作权限
  • KMS每个月有免费试用的额度，如果超过，则KMS需要收费。
  • KMS加密只代表资源编排服务在存储和传输的时候传递的是密文，但是在stack-events中依然是明文，如果希望在log中以密文形式对待，请在模板中声明sensitive，更多关于sensitive的介绍见：https://learn.hashicorp.com/tutorials/terraform/sensitive-variables
表7 KmsStructure

参数

是否必选

参数类型

描述

id

是

String

解密时，资源编排服务应该使用的KMS密钥的ID，通常是加密时所使用的密钥ID

最小长度：36

最大长度：36

cipher_text

是

String

数据加密密钥所对应的密文

最小长度：2

最大长度：2048

响应参数

状态码： 201

表8 响应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

表9 响应Body参数

参数

参数类型

描述

error_code

String

响应码

最小长度：11

最大长度：11

error_msg

String

响应消息

encoded_authorization_message

String

包含有关未经授权请求的信息。

状态码： 401

表10 响应Body参数

参数

参数类型

描述

error_code

String

响应码

最小长度：11

最大长度：11

error_msg

String

响应消息

encoded_authorization_message

String

包含有关未经授权请求的信息。

状态码： 403

表11 响应Body参数

参数

参数类型

描述

error_code

String

响应码

最小长度：11

最大长度：11

error_msg

String

响应消息

encoded_authorization_message

String

包含有关未经授权请求的信息。

状态码： 409

表12 响应Body参数

参数

参数类型

描述

error_code

String

响应码

最小长度：11

最大长度：11

error_msg

String

响应消息

encoded_authorization_message

String

包含有关未经授权请求的信息。

状态码： 429

表13 响应Body参数

参数

参数类型

描述

error_code

String

响应码

最小长度：11

最大长度：11

error_msg

String

响应消息

encoded_authorization_message

String

包含有关未经授权请求的信息。

状态码： 500

表14 响应Body参数

参数

参数类型

描述

error_code

String

响应码

最小长度：11

最大长度：11

error_msg

String

响应消息

encoded_authorization_message

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"
}
  • 使用模板内容创建并部署资源栈 
    {
  "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"
}

响应示例

状态码： 201

创建成功

{
  "stack_id" : "ea6a4f0e-ee8a-494e-b12a-8be4a1e65af2"
}

状态码

状态码

描述

201

创建成功

400

用户请求非法

401

用户身份认证失败

403
  1. 用户无权限调用此API
  2. 资源栈数量达到上限

409

创建冲突，同名的资源栈已经存在

429

请求数量过多

500

服务器内部错误
父主题： 资源栈