企业官网建设流程全解析

• 云原生
• DevOps
• 运维
• 微服务

KubeVela 通过内置的alibaba-ack云服务组件，让开发者可以用一份声明式的Application配置直接申请阿里云容器服务 ACK（Kubernetes）集群。本文以仓库中的示例文档 alibaba-ack.eg.md 为主体，结合其背后的 TerraformComponentDefinition定义、e2e 测试用例与云资源数据传递设计文档，讲解组件配置、writeConnectionSecretToRef连接信息机制以及完整的落地流程，读完即可在自己的 KubeVela 环境中复用该组件。

一、这份示例文档是什么：def-doc 的定位与用途

在 KubeVela 仓库中，references/docgen/def-doc目录存放的是"内置定义的用法示例"（example），它与真正的定义文件相互印证。根据 def-doc README 的说明，这些示例承担两个职责：

1. 生成官方参考文档：作为 kubevela.io 上组件参考文档的素材来源；
2. 支持用户自助生成：帮助用户通过vela show命令查看任意内置定义的参数与用法。

因此，alibaba-ack.eg.md 是一份"可直接复制运行的完整 Application 示例"，它演示了 KubeVela 中如何声明式地创建一个阿里云 ACK 集群组件，是理解"Terraform 类型云服务组件如何接入 KubeVela"的最佳入口。该目录下还有alibaba-eip.eg.md、alibaba-oss.eg.md、alibaba-rds.eg.md、alibaba-redis.eg.md等同族示例，模式完全一致，alibaba-ack是其中面向容器服务（ACK）的代表。

二、示例文档的完整内容：alibaba-ack 组件的最小 Application

示例文档全文即下面这份 YAML，它定义了一个名为ack-cloud-source的Application，其中包含一个类型为alibaba-ack、名为ack-cluster的组件：

apiVersion: core.oam.dev/v1beta1 kind: Application metadata: name: ack-cloud-source spec: components: - name: ack-cluster type: alibaba-ack properties: writeConnectionSecretToRef: name: ack-conn namespace: vela-system

逐字段解读如下：

这份配置的核心动作只有一件：声明"我要一个 ACK 集群，并把它的连接凭证写到vela-system/ack-conn这个 Secret 里"。集群的具体规格（实例规格、节点数、可用区等）由组件定义提供默认值，示例文档未显式覆盖，表明这些参数全部可选、由定义侧兜底。

三、组件定义背后：Terraform 类型的 ComponentDefinition

alibaba-ack不是硬编码在控制器里的特殊组件，而是一个标准的、由 Terraform 驱动的ComponentDefinition。仓库的 e2e 测试数据中保留了它的完整定义（terraform-alibaba-ack.yaml）：

apiVersion: core.oam.dev/v1beta1 kind: ComponentDefinition metadata: name: alibaba-ack namespace: vela-system annotations: definition.oam.dev/description: Terraform configuration for Alibaba Cloud ACK cluster labels: type: terraform spec: workload: definition: apiVersion: terraform.core.oam.dev/v1beta1 kind: Configuration schematic: terraform: configuration: https://github.com/kubevela-contrib/terraform-modules.git type: remote path: alibaba/cs/dedicated-kubernetes

从这份定义可以确认以下实现事实：

• 声明式描述：definition.oam.dev/description明确指出这是"Terraform configuration for Alibaba Cloud ACK cluster"；
• 类型标签：labels.type: terraform，这是vela comp --label type=terraform能过滤出它的依据；
• 工作负载类型：spec.workload.definition指向terraform.core.oam.dev/v1beta1的Configuration，即该组件最终会实例化为一个 Terraform Controller 管理的Configuration资源；
• Terraform 模板来源：spec.schematic.terraform声明模板为remote（远端）类型，从kubevela-contrib/terraform-modules仓库拉取，具体模块路径为alibaba/cs/dedicated-kubernetes（阿里云容器服务"专有 Kubernetes 集群"模块）。

也就是说，alibaba-ack组件本质上是把一份阿里云 Terraform 模块包装成了 OAM 组件：KubeVela 负责接收Application声明、渲染出ConfigurationCR，再由 Terraform Controller 实际执行云端资源的申请与销毁。

配套 Addon：terraform-alibaba

与组件定义配套的是terraform-alibaba插件（addon），其元数据位于 metadata.yaml：

• 名称/版本：terraform-alibaba、1.0.0；
• 描述：Kubernetes Terraform Controller for Alibaba Cloud；
• 依赖：dependencies中声明依赖terraform（即 Terraform Controller 本体）；
• 部署目标：deployTo.control_plane: true，即部署到控制面集群。

这解释了使用alibaba-ack组件的前提：集群中必须先安装 Terraform Controller（terraformaddon）与阿里云 Provider 相关的terraform-alibabaaddon，alibaba-ack组件定义才会存在、Configuration才能被正确执行。

四、writeConnectionSecretToRef 原理：云资源连接信息如何传递

示例中唯一显式配置的属性就是writeConnectionSecretToRef，这是 KubeVela 云服务组件（Terraform 类型）的关键约定。仓库设计文档 cloud-resource-data-passing.md 对这一机制有完整阐述：

KubeVela 通过 Terraform Controller 在 Kubernetes 环境内供给云资源。对于云数据库等场景，需要把连接信息传递给相关的工作负载，这些连接信息由 Terraform Controller 创建并保存在 Kubernetes Secret 中。

其核心机制为：

1. 当Configuration（云资源）就绪后，Terraform Controller 会按照writeConnectionSecretToRef指定的name与namespace，把资源输出的连接字段（如数据库地址、账号、密码、集群 kubeconfig 等）写入一个 Kubernetes Secret；
2. 应用侧工作负载再通过引用该 Secret 的名称与键来消费这些信息。

针对"数据如何到达工作负载"，设计文档归纳了两种方法、两种位置的四种组合：

Pass Secret（示例文档采用的方式）：Secret 对象在目标集群创建，工作负载在 Application 中直接引用 Secret 名与键。以alibaba-rds为例（参见 application-rds.yaml 与设计文档中的完整示例），配合service-binding运维特征即可把数据库连接信息映射为业务容器的环境变量：

traits: - type: service-binding properties: envMappings: DATABASE_HOST: secret: db-conn key: DB_PUBLIC_HOST DATABASE_NAME: secret: db-conn key: DATABASE_NAME DATABASE_USER: secret: db-conn key: DB_USER DATABASE_PASSWORD: secret: db-conn key: DB_PASSWORD

回到alibaba-ack场景：writeConnectionSecretToRef.name: ack-conn意味着 ACK 集群创建完成后，其 kubeconfig / 集群凭证会被写入名为ack-conn的 Secret，后续任何需要访问该集群的工作负载都可以基于这个 Secret 完成认证与接入。

Pass Value：不在目标集群创建 Secret，而是在 workflow 中读取 Secret 值，通过组件级 input/output 机制把连接信息直接注入工作负载 spec。设计文档特别指出，apply-component步骤可以把 workflow 级 output 传给组件级 input，但它只对本地集群生效，因此该方式无法用于托管集群场景。

五、实战落地：从安装到消费的完整路径

1. 安装 Terraform 相关 addon

使用alibaba-ack组件前，先确保terraform与terraform-alibaba两个 addon 已安装（后者声明依赖前者），并配置好阿里云账号的访问凭证（AK/SK）。插件部署到控制面集群后，alibaba-ack组件定义即被注册到vela-system命名空间。

2. 确认组件可用

alibaba-ack组件定义带有type: terraform标签，因此可用 CLI 过滤确认其存在。仓库 e2e 测试 registry_test.go 中就有对应断言：

vela comp --label type=terraform

测试期望该命令输出中包含alibaba-ack（且不包含非 Terraform 的raw组件），这验证了"标签过滤 → 列出已安装组件"这一可复现的排查路径。

3. 提交 Application

将示例文档中的 YAML 保存后提交到集群即可：

kubectl apply -f ack-cloud-source.yaml

KubeVela 应用控制器会完成"渲染组件定义 → 生成terraform.core.oam.dev/v1beta1的Configuration→ 交给 Terraform Controller 申请 ACK 集群"的完整链路；集群就绪后，连接信息自动落入vela-system/ack-connSecret。

4. 用 vela show 生成可复用的参数参考

按 def-doc README 的说明，这类示例不仅用于生成官方参考文档，也可通过vela show alibaba-ack查看组件定义的完整参数（包括实例规格、节点配置等未在示例中显式给出的可选字段），从而按需扩展properties。

六、小结与进一步阅读

alibaba-ack示例虽短，却浓缩了 KubeVela 云服务组件的完整模式：一个type背后是一个 Terraform 驱动的ComponentDefinition，一份properties.writeConnectionSecretToRef声明了一段可被其他组件消费的连接信息。从组件定义（terraform-alibaba-ack.yaml）到数据传递机制（cloud-resource-data-passing.md），再到 CLI 验证（registry_test.go），仓库内证据链完整，读者可据此照搬使用。

想进一步深入，可继续阅读：

• 同族组件示例：alibaba-rds.eg.md、alibaba-oss.eg.md；
• 真实场景样例：cloud-resource-provision-and-consume 目录下多份"供给 + 消费"组合示例（如 application-aws-s3.yaml、application-vpc.yaml）；
• 数据传递设计文档：cloud-resource-data-passing.md（含 Pass Secret / Pass Value 的完整组合矩阵与示例）。

• 云原生
• DevOps
• 运维
• 微服务