跳到主要内容

从零实现过程

这一页按项目生成顺序组织。读完后应该能理解每个目录为什么存在、先写什么、后写什么，以及每一步如何验证。

1. 创建仓库骨架​

mkdir -p iac-gitops-hybrid-k8s-ha
cd iac-gitops-hybrid-k8s-ha
git init
mkdir -p aliyun tencent modules scripts website/docs
ln -s website/docs docs

创建忽略规则：

touch .gitignore

.gitignore 至少包含：

**/terraform.tfvars
**/terraform.tfstate
**/terraform.tfstate.*
**/*.tfplan
**/tfplan
**/.terraform/
generated/
generated/**/*.json
generated/**/kubeconfig
generated/**/*token*
generated/**/*certificate*
*.log

2. 建立 Terraform root module​

先为两云创建相同结构：

touch aliyun/main.tf aliyun/variables.tf aliyun/outputs.tf aliyun/versions.tf aliyun/terraform.tfvars.example
touch tencent/main.tf tencent/variables.tf tencent/outputs.tf tencent/versions.tf tencent/terraform.tfvars.example

versions.tf 负责 Terraform 和 provider 版本：

terraform {
  required_version = ">= 1.5.0"

  required_providers {
    alicloud = {
      source  = "aliyun/alicloud"
      version = "~> 1.279"
    }
  }
}

腾讯云侧使用：

terraform {
  required_version = ">= 1.5.0"

  required_providers {
    tencentcloud = {
      source  = "tencentcloudstack/tencentcloud"
      version = "~> 1.82"
    }
  }
}

3. 拆分模块​

创建模块目录：

mkdir -p modules/aliyun-vpc modules/aliyun-ecs modules/aliyun-security-group modules/aliyun-lb modules/aliyun-vpn
mkdir -p modules/tencent-vpc modules/tencent-cvm modules/tencent-security-group modules/tencent-lb modules/tencent-vpn

每个模块使用同样文件结构：

touch modules/aliyun-vpc/main.tf modules/aliyun-vpc/variables.tf modules/aliyun-vpc/outputs.tf modules/aliyun-vpc/versions.tf

模块拆分原则：

  • VPC 模块只管 VPC、子网、路由表。
  • 节点模块只管 ECS/CVM、SSH key、实例输出。
  • 安全组模块只管端口规则。
  • LB 模块只管 API 和 Cluster Mesh 入口。
  • VPN 模块只管可选 IPsec 路线。

4. 编写 root module 编排​

root module 先整理公共输入，再调用模块：

module "vpc" {
  source = "../modules/aliyun-vpc"

  name_prefix  = var.name_prefix
  vpc_cidr     = var.vpc_cidr
  vswitch_cidr = var.vswitch_cidr
  zone_id      = var.zone_id
  tags         = local.common_tags
}

模块之间通过输出连接：

module "ecs" {
  source = "../modules/aliyun-ecs"

  vswitch_id        = module.vpc.vswitch_id
  security_group_id = module.security_group.security_group_id
  node_groups       = local.node_groups
}

5. 编写 Makefile​

Makefile 把常用命令固定下来：

aliyun-plan:
	cd aliyun && terraform fmt -recursive && terraform validate && terraform plan -out=tfplan

aliyun-output:
	mkdir -p generated/aliyun
	cd aliyun && terraform output -json > ../generated/aliyun/terraform-output.json

所有人都执行同一组 target，避免手写命令不一致。

6. 编写脚本​

脚本放在 scripts/：

bootstrap-common.sh
setup-wireguard-underlay.sh
render-kubeadm-config.sh
render-cilium-values.sh
init-first-master.sh
join-worker.sh
install-cilium.sh
enable-clustermesh.sh
check-underlay.sh
check-cluster.sh

脚本共同约束：

  • set -euo pipefail。
  • 输入来自参数、环境变量或 generated/*/terraform-output.json。
  • 不把密钥、token、kubeconfig 写进 Git。
  • 每个脚本只做一类事。

7. 接上 kubeadm​

先渲染 kubeadm config：

scripts/render-kubeadm-config.sh aliyun
scripts/render-kubeadm-config.sh tencent

配置里写入：

apiVersion: kubeadm.k8s.io/v1beta4
kind: ClusterConfiguration
clusterName: "aliyun-guangzhou"
controlPlaneEndpoint: "<k8s-api-lb-host>:6443"
networking:
  podSubnet: "172.16.0.0/16"
  serviceSubnet: "10.96.0.0/16"

再执行节点初始化、master 初始化和 worker 加入。

8. 接上 Cilium​

渲染 Helm values：

cluster:
  name: aliyun-guangzhou
  id: 1
routingMode: tunnel
tunnelProtocol: vxlan
ipam:
  mode: kubernetes

安装：

helm upgrade --install cilium cilium/cilium \
  --namespace kube-system \
  --version "<cilium-version>" \
  --values generated/aliyun/cilium-values.yaml \
  --kube-context aliyun-guangzhou

9. 接上 Cluster Mesh​

cilium clustermesh enable --context aliyun-guangzhou --service-type NodePort --enable-kvstoremesh=false
cilium clustermesh enable --context tencent-guangzhou --service-type NodePort --enable-kvstoremesh=false

固定 NodePort：

kubectl --context aliyun-guangzhou -n kube-system patch service clustermesh-apiserver \
  --type='json' \
  -p='[{"op":"replace","path":"/spec/ports/0/nodePort","value":32379}]'

连接集群：

cilium clustermesh connect \
  --context aliyun-guangzhou \
  --destination-context tencent-guangzhou \
  --destination-endpoint "<tencent-node-or-lb>:32379" \
  --allow-mismatching-ca

10. 建立文档站​

cd website
npm install
npm run start
npm run build

文档站需要覆盖：

  • 项目介绍。
  • 架构设计。
  • 快速开始。
  • 代码走读。
  • 排障记录。
  • 后续路线。

11. 每个阶段的提交检查​

terraform fmt -check -recursive
npm run build
git status --short

如果修改脚本，至少手工检查：

bash -n scripts/bootstrap-common.sh
bash -n scripts/setup-wireguard-underlay.sh
bash -n scripts/render-kubeadm-config.sh
bash -n scripts/render-cilium-values.sh
bash -n scripts/install-cilium.sh
bash -n scripts/enable-clustermesh.sh