Hang Zhengyang
English ↗

统一入口说明（Terraform + K8s + Helm）

本文档解释当前项目的“统一入口”方案：为什么这样设计、如何配置、如何执行、底层原理是什么。

1. 什么是统一入口

统一入口指：用一套主流程管理整套部署，避免 Docker/K8s/Terraform 三套并行命令互相打架。

当前项目的统一入口是：

  • 应用镜像准备（docker build + kind load）
  • 基础设施与平台部署（terraform-k8s）

核心命令链路：

docker build -t serving-lab-app-service:latest ./serving-lab/app-service
kind load docker-image serving-lab-app-service:latest --name serving-lab

cd terraform-k8s
terraform init
terraform plan -var-file=dev.tfvars -out tfplan
terraform apply tfplan

2. 统一入口的目标

  • 单一真相来源：部署状态以 Terraform state 为准
  • 标准化：同一套命令可重复执行
  • 可回收：terraform destroy 即可清理主要资源
  • 可演进：后续可接 CI/CD，实现自动化发布

3. 当前统一方案包含什么

由 terraform-k8s 管理：

  • Kubernetes 原生资源（通过 kubernetes provider）
    • ConfigMap（Nginx 配置）
    • Deployment（app-service, edge-proxy）
    • Service（app-service, edge-proxy）
    • Ingress
  • Helm 组件（通过 helm provider）
    • ingress-nginx
    • kube-prometheus-stack（Prometheus + Grafana）
  • Grafana 观测资产
    • Dashboard（ConfigMap + sidecar）
    • Alert rules（ConfigMap + sidecar）

4. 关键配置文件说明

terraform-k8s/providers.tf

  • 定义 Terraform provider：
    • kubernetes
    • helm
  • 通过 kubeconfig_path 与 kube_context 指向目标集群

terraform-k8s/variables.tf

  • 定义统一可配置参数：
    • app_image
    • namespace
    • ingress_host
    • grafana_admin_password
    • 等

terraform-k8s/dev.tfvars

  • 本地环境参数实例
  • 运行时通过 -var-file 注入

terraform-k8s/main.tf

  • 声明 app/nginx 的 K8s 资源
  • 含 probes、resources 等运行参数

terraform-k8s/helm.tf

  • 声明 Helm release（ingress-nginx、kube-prometheus-stack）

terraform-k8s/observability.tf

  • 声明 Grafana dashboard 与告警规则 ConfigMap

5. 统一流程（推荐日常执行）

Step 1：准备集群（仅首次）

kind create cluster --name serving-lab

Step 2：构建并导入应用镜像

docker build -t serving-lab-app-service:latest ./serving-lab/app-service
kind load docker-image serving-lab-app-service:latest --name serving-lab

Step 3：Terraform 统一部署

cd terraform-k8s
terraform init
terraform fmt
terraform validate
terraform plan -var-file=dev.tfvars -out tfplan
terraform apply tfplan

Step 4：验证

kubectl get pods -A
kubectl get svc -A
kubectl get ingress -A

Step 5：统一回收

cd terraform-k8s
terraform destroy -var-file=dev.tfvars -auto-approve

6. 原理解释（简版）

6.1 为什么还需要 docker build + kind load

Terraform 可以管理“部署声明”，但不会替你构建本地源码镜像。
在 kind 本地集群里，节点容器默认看不到你宿主机刚 build 的镜像，所以需要 kind load docker-image 注入节点。

6.2 为什么用 Terraform 管 K8s + Helm

  • K8s 原生资源适合精细控制（Deployment/Service/Ingress）
  • Helm 适合安装大型第三方组件（Prometheus/Grafana）
  • Terraform 把两者统一在一个 state 里，便于 plan/apply/destroy

6.3 为什么比手动 kubectl apply 更稳定

  • plan 先看变更，再执行
  • 配置可参数化（dev.tfvars, 后续可 stage/prod.tfvars）
  • 资源关系可通过依赖声明
  • 回滚和回收路径更清晰

7. 边界与注意事项

  • 统一入口管理“集群内资源”，不直接替代 CI 构建流程
  • 生产环境建议镜像来自仓库（ECR/GHCR），不依赖 kind load
  • 敏感参数（如 Grafana 密码）应改为安全注入方式（secret manager / CI secret）
  • terraform destroy 会删除该栈管理的资源，执行前先确认目标环境

8. 后续建议

  • 增加 stage/prod tfvars（镜像 tag、域名、资源规格）
  • 将镜像构建/推送接入 CI，再由 Terraform 做部署
  • 增加策略检查（fmt/validate/plan in CI）
  • 补充告警通知渠道（webhook/Slack/Email）