本文导读

展开导读

文档首页/ 资源编排服务 RFS/ API参考/ API/ 资源栈/ 创建资源栈

创建资源栈

更新时间：2024-12-13 GMT+08:00

查看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获取方式

请求参数

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

表3 请求Body参数
参数	是否必选	参数类型	描述
stack_name	是	String	资源栈的名称。此名字在domain_id+区域+project_id下应唯一，可以使用中文、大小写英文、数字、下划线、中划线。首字符需为中文或者英文，区分大小写。
agencies	否	Array of Agency objects	委托授权的信息。 RFS仅在创建资源栈（触发部署）、创建执行计划、部署资源栈、删除资源栈等涉及资源操作的请求中使用委托，且该委托仅作用于与之绑定的Provider对资源的操作中。如果委托中提供的权限不足，有可能导致相关资源操作失败。创建委托及授权方式
description	否	String	资源栈的描述。可用于客户识别自己的资源栈。
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字段开启加密
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 必须有且只有一个存在在CreateStack API中，template_body和template_uri可以都不给予注意： template_uri对应的模板文件中默认不应该含有任何敏感信息，资源编排服务会直接明文使用、log、展示、存储对应的模板文件内容。如为敏感信息，建议将敏感信息通过vars_structure参数化，并设置encryption字段开启加密 template_uri对应的模板文件如果为zip类型，则内部的文件或文件夹名称长度不得超过255个字节，最深路径长度不得超过2048字节，zip包大小不得超过1MB
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字段传递
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字段开启加密
vars_uri	否	String	HCL参数文件的OBS地址。HCL模板支持参数传入，即，同一个模板可以给予不同的参数而达到不同的效果。请确保OBS地址所在局点与使用RFS服务局点一致。资源编排服务支持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字段传递

表4 Agency
参数	是否必选	参数类型	描述
provider_name	是	String	用户使用的provider的名字。如果用户给予的provider_name含有重复的值，则返回400
agency_name	否	String	对应provider所使用的IAM委托名称，资源编排服务会使用此委托的权限去访问、创建对应provider的资源。agency_name和agency_urn必须有且只有一个存在
agency_urn	否	String	委托URN 当用户定义Agency时，agency_name和agency_urn 必须有且只有一个存在。推荐用户在使用信任委托时给予agency_urn，agency_name只支持接收普通委托名称，如果给予了信任委托名称，则会在部署模板时失败。

表5 VarsStructure
参数	是否必选	参数类型	描述
var_key	是	String	参数的名字
var_value	是	String	参数的值。注意，参数需要以字符串形式存在，如果是数字，也需要以字符串形式存在，如'10'。如果需要支持不同类型，或者复杂结构，请使用vars_uri或vars_body
encryption	否	EncryptionStructure object	如果用户传递的var_value是已经加密过的，可以通过声明此项以要求资源编排服务在使用前进行解密，目前暂时只支持KMS加解密

表6 EncryptionStructure
参数	是否必选	参数类型	描述
kms	是	KmsStructure object	如果用户给予的var_value是经过KMS加密的，可以通过传递相关加密信息，资源编排服务在使用的时候会帮助用户进行KMS解密更多关于KMS加密以及KMS加密的样例代码请见：KMS加密使用场景介绍注意：请确保用户给予资源编排服务的委托中包含对指定密钥ID的操作权限 KMS每个月有免费试用的额度，如果超过，则KMS需要收费，此费用不是资源编排服务收取，具体标准见：https://www.huaweicloud.com/intl/zh-cn/pricing/index.html#/kms KMS加密只代表资源编排服务在存储和传输的时候传递的是密文，但是在stack-events中依然是明文，如果希望在log中以密文形式对待，请在模板中声明sensitive，更多关于sensitive的介绍见：https://learn.hashicorp.com/tutorials/terraform/sensitive-variables

表7 KmsStructure
参数	是否必选	参数类型	描述
id	是	String	解密时，资源编排服务应该使用的KMS密钥的ID，通常是加密时所使用的密钥ID
cipher_text	是	String	数据加密密钥所对应的密文

响应参数

状态码： 201

表8 响应Body参数
参数	参数类型	描述
stack_id	String	资源栈（stack）的唯一Id。此Id由资源编排服务在生成资源栈的时候生成，为UUID。由于资源栈名仅仅在同一时间下唯一，即用户允许先生成一个叫HelloWorld的资源栈，删除，再重新创建一个同名资源栈。对于团队并行开发，用户可能希望确保，当前我操作的资源栈就是我认为的那个，而不是其他队友删除后创建的同名资源栈。因此，使用ID就可以做到强匹配。资源编排服务保证每次创建的资源栈所对应的ID都不相同，更新不会影响ID。如果给予的stack_id和当前资源栈的ID不一致，则返回400
deployment_id	String	部署ID 接受请求，进行异步处理。可以调用GetStackMetadata来获取异步请求的部署状态注意：部署资源栈后，资源编排服务持久化请求并立即返回，客户端不等待请求最终处理完成，用户无法实时感知请求处理结果资源编排服务最终会将异步部署请求排队，在服务端空闲的情况下逐个处理。用户最大等待时长为6小时

状态码： 400

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

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

状态码： 401

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

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

状态码： 403

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

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

状态码： 409

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

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

状态码： 429

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

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

状态码： 500

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

**表20** Detail
参数	参数类型	描述
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"
}

使用模板内容创建并部署资源栈

{
  "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	用户无权限调用此API 资源栈数量达到上限
409	创建冲突，同名的资源栈已经存在
429	请求数量过多
500	服务器内部错误

父主题： 资源栈

上一篇：列举资源栈

下一篇：获取资源栈模板

意见反馈

文档内容是否对您有帮助？

有帮助没帮助

提供反馈

提交成功！非常感谢您的反馈，我们会继续努力做到更好！

系统繁忙，请稍后重试

在使用文档中是否遇到以下问题

内容与产品页面不一致

内容不易理解

缺失示例代码

步骤不可操作

搜不到想要的内容

缺少最佳实践

意见反馈（选填）

0/500

请至少选择一项反馈信息并填写问题反馈

字符长度不能超过500

直接提交取消

创建资源栈

功能介绍

URI

请求参数

响应参数

请求示例

响应示例

状态码

意见反馈

文档内容是否对您有帮助？

文档反馈