资源栈配置说明

format_version

format_version字段指定配置文件格式版本，格式为：

<POP Code>/<POP Version>

当前使用以下版本：

format_version: IaCService/2021-08-06

description

description字段用于描述当前Component配置的用途。

description: 创建VPC和VSwitch

variable

variable字段声明Component使用的输入变量。变量值可以通过以下方式提供：

• 在variable.default中配置默认值。

• 在tfdeploy.yaml的deployment.inputs中配置。

• 在deployment.inputs中引用局部变量、参数集或上游资源栈输出。

示例：

variable:
  - name: region
    type: string
    description: 资源所属地域

  - name: tags
    type: map(string)
    description: 资源标签
    default:
      managed_by: terraform

  - name: token
    type: string
    description: 外部服务访问Token
    sensitive: true

required_providers

required_providers字段声明资源栈依赖的Provider及其版本约束。

示例：

required_providers:
  - name: alicloud
    source: hashicorp/alicloud
    version: "~> 1.251.0"

provider

provider字段定义组件使用的Provider实例。

通过以下格式引用Provider实例：

provider.<type>.<name>

示例：

provider:
  - type: alicloud
    name: this
    config:
      region: var.region

对应引用为：

provider.alicloud.this

component

component字段声明资源栈中的基础设施组件。每个组件引用一个Terraform模块。

组件输出通过以下格式引用：

component.<组件名称>.<输出名称>

示例：

component:
  - name: vpc
    source: "../modules/vpc"
    inputs:
      vpc_name: var.vpc_name
      cidr_block: var.vpc_cidr
    providers:
      alicloud: provider.alicloud.this

inputs字段支持普通值、复杂数据结构和Terraform表达式：

• 普通字符串必须使用双引号，例如"created by terraform"。

• var.*、component.*、each.value和Terraform函数等表达式不添加引号。

• 包含Terraform字符串插值的值使用双引号，例如"${var.name}-suffix"。

引用 Registry 模块

引用Registry模块时，可以同时指定source和version：

component:
  - name: vpc
    source: "alibaba/vpc/alicloud"
    version: "1.11.0"
    inputs:
      cidr_block: var.vpc_cidr
    providers:
      alicloud: provider.alicloud.this

显式声明组件依赖

当组件输入中已经引用其他组件的输出时，系统会根据引用关系建立依赖。对于无法通过输入引用表达的依赖，使用depends_on字段：

component:
  - name: application
    source: "../modules/application"
    depends_on:
      - component.vpc
    providers:
      alicloud: provider.alicloud.this

如果inputs已引用另一个组件的输出，例如：

vpc_id: component.vpc.vpc_id

Terraform会自动建立依赖，通常不需要再配置depends_on。

使用 for_each 创建多个组件实例

通过for_each字段，可以根据集合循环创建组件实例。

variable:
  - name: bucket_names
    type: set(string)

component:
  - name: bucket
    source: "../modules/oss_bucket"
    for_each: var.bucket_names
    inputs:
      bucket_name: each.value
    providers:
      alicloud: provider.alicloud.this

当bucket_names包含以下值时：

bucket_names:
  - data-bucket
  - log-bucket

系统会创建两个组件实例。

使用for_each字段后，组件输出通常为按实例键组织的集合。引用输出时，根据Terraform模块实际生成的数据结构选择实例或遍历结果。

output

output字段声明Component对外提供的输出值。tfdeploy.yaml可以通过publish_output字段发布这些值，供其他资源栈使用。

示例：

output:
  - name: vpc_id
    type: string
    description: VPC ID
    value: component.vpc.vpc_id

被引用的输出必须在对应Terraform模块的outputs.tf中真实存在。例如，使用component.vpc.vpc_id前，需要确保VPC模块已经声明名为vpc_id的Terraform Output。

format_version

与Component配置相同，当前使用：

format_version: IaCService/2021-08-06

description

description字段用于描述当前Deployment配置的用途：

description: 创建开发和生产环境

store

store字段用于引用自动化服务台中的参数集。配置后，可以在deployment.inputs字段中引用参数集中的参数，避免将密码、Token等敏感值直接写入配置文件或代码仓库。

使用store字段前，先在自动化服务台创建参数集，并将参数集关联到当前资源栈。

如果同时配置id和name，系统优先使用id查找参数集。

参数集引用格式为：

store.<type>.<store_name>.<参数名>

示例：

store:
  - type: varset
    store_name: tokens
    id: pts-xxxx
    category: terraform

deployment:
  - name: production
    inputs:
      token: store.varset.tokens.example_token

上述配置引用参数集pts-xxxx中名为example_token的参数，并将其传入Component变量token。

声明store字段只会建立参数集引用，不会将参数集中的全部参数自动传入Terraform。只有在deployment.inputs字段中显式引用的参数才会传入对应的Deployment。

如果引用参数集中的敏感参数，tfcomponent.yaml中接收该参数的变量必须配置sensitive: true：

variable:
  - name: token
    type: string
    sensitive: true

如果敏感参数对应的变量未配置sensitive: true，资源栈配置校验或执行将失败。

使用store字段时存在以下限制：

• 参数集必须已经关联到当前资源栈。

• 当前仅支持varset类型。

• category当前仅支持terraform。

• name和id至少配置一项。

• 参数集不存在、未关联或敏感属性配置不一致时，资源栈执行将失败。

deployment

deployment字段声明部署实例。每条Deployment配置对应一组独立的部署参数，例如开发环境和生产环境。

示例：

deployment:
  - name: development
    inputs:
      region: "cn-hangzhou"
      vpc_name: "vpc-dev"

  - name: production
    inputs:
      region: "cn-beijing"
      vpc_name: "vpc-prod"

同一个资源栈中的不同Deployment会分别创建和维护Terraform任务及状态。根据实际隔离需求划分Deployment。

orchestrate

orchestrate字段用于控制Terraform Plan完成后是否自动执行Apply。

未配置orchestrate时，资源栈只执行Terraform Plan，并在Plan完成后等待人工确认，不会自动执行Apply。

当前仅支持auto_approve类型。

check对象包含以下字段：

系统会检查auto_approve下的全部条件：

• 所有条件均成立：Plan完成后自动执行Apply。

• 任一条件不成立：Plan完成后等待人工确认。

• 未配置orchestrate：Plan完成后等待人工确认。

示例：当VPC组件没有变更时自动执行Apply；如果VPC组件存在变更，则等待人工确认。

orchestrate:
  - type: auto_approve
    name: safe_changes_only
    check:
      - condition: 'context.plan.component_changes["component.vpc"].total == 0'
        reason: "VPC组件存在变更，需要人工确认。"

自动执行规则不会绕过资源保护策略和其他安全检查。如果变更触发资源保护策略，即使条件成立，任务也可能被拒绝执行。

locals

locals字段用于定义tfdeploy.yaml中重复使用的值。

locals:
  common_region: "cn-hangzhou"
  default_tags:
    managed_by: "terraform"

在deployment.inputs中通过local.<name>引用：

deployment:
  - name: development
    inputs:
      region: local.common_region
      tags: local.default_tags

当前局部变量主要用于值传递。不要在locals字段中嵌套复杂引用或Terraform函数。

发布资源栈输出

publish_output字段声明当前资源栈向下游资源栈发布的输出。

示例：

publish_output:
  - name: vpc_id
    description: 生产环境VPC ID
    value: deployment.production.vpc_id

其中：

• production是deployment.name。

• vpc_id是tfcomponent.yaml中声明的output.name。

引用上游资源栈输出

upstream_input字段声明需要引用的上游资源栈。

source格式为：

{IaCEndpoint}/{AccountId}/{StackName}

在deployment.inputs中通过以下格式引用输出：

upstream_input.<name>.<output>

跨资源栈示例

上游网络资源栈发布生产环境VPC ID：

publish_output:
  - name: vpc_id
    description: 生产环境VPC ID
    value: deployment.production.vpc_id

下游应用资源栈声明并引用该输出：

upstream_input:
  - name: network_stack
    type: stack
    source: "{IaCEndpoint}/{AccountId}/{NetworkStackName}"

deployment:
  - name: production
    inputs:
      region: "cn-hangzhou"
      vpc_id: upstream_input.network_stack.vpc_id

执行下游资源栈时，系统会读取上游资源栈当前已经发布的输出值，无需在配置中硬编码资源ID。

使用跨资源栈输出时需注意：

• 上游资源栈必须存在，并且已经成功部署。

• 上游资源栈必须已经通过publish_output发布对应名称的输出。

• 跨账号引用前，上游资源栈所属账号必须在资源栈详情页的账户授权中，将下游阿里云账号 UID 添加为授权账号。具体操作请参见《创建和管理资源栈》中的“授权其他账号引用资源栈输出”。

• upstream_input只有在deployment.inputs中被实际引用时，才会建立对应的消费关系。

• 上游发布输出发生变化后，系统会触发存在消费关系的下游资源栈执行Plan。

• 自动触发下游Plan不代表一定自动执行Apply。是否自动Apply仍由下游资源栈的orchestrate配置决定。

• 当前自动触发以资源栈为粒度，可能执行下游资源栈中的全部Deployment，而不仅是引用该输出的单个Deployment。