k8s-cluster-api

Kubernetes 集群 API

Kubernetes Cluster API（CAPI）是 Kubernetes 的一个子项目，旨在提供声明式 API 和工具，简化多个 Kubernetes 集群的预配、升级和运维。

概览

Cluster API 由 SIG Cluster Lifecycle 发起，使用 Kubernetes 风格的 API 和模式来自动化集群生命周期管理。基础设施（VM、网络、负载均衡器、VPC）和 Kubernetes 配置以声明式方式定义，从而能够在不同环境中一致且可重复地部署集群。

为什么选择 Cluster API？

虽然 kubeadm 降低了安装复杂度，但它无法解决集群的日常管理问题：

• 如何在不同供应商和位置间以一致的方式预配基础设施？
• 如何自动化集群生命周期（升级、删除）？
• 如何扩展流程以管理任意数量的集群？

Cluster API 通过声明式的 Kubernetes 风格 API 自动化集群的创建、配置和管理，弥补了这些不足。

目标

• 通过声明式 API 管理符合 Kubernetes 标准的集群生命周期（创建、扩缩、升级、销毁）
• 适用于不同环境（本地部署和云端）
• 通过可替换的实现来定义常见操作
• 重用现有生态系统组件（cluster-autoscaler、node-problem-detector）
• 为现有工具提供渐进式采用的迁移路径

非目标

• 向 Kubernetes 核心添加 API
• 管理与 Kubernetes 集群无关的基础设施
• 强制所有生命周期产品使用这些 API
• 管理非通过 CAPI 预配的集群
• 管理跨多个供应商的单个集群
• 在创建或升级后配置机器

快速导航

主题	参考资料
入门	getting-started.md
概念与架构	concepts.md
证书	certificates.md
引导（Kubeadm/MicroK8s）	bootstrap.md
集群操作	cluster-operations.md
实验性功能	experimental.md
clusterctl CLI	clusterctl.md
开发者指南	developer.md
故障排查	troubleshooting.md
API 参考与供应商	api-reference.md
安全与 PSS	security.md
控制器	controllers.md
版本迁移	migrations.md
常见问题	faq.md
最佳实践	best-practices.md

适用场景

• 跨多个基础设施供应商预配 Kubernetes 集群
• 管理集群生命周期（创建、扩缩、升级、销毁）
• 使用声明式 API 自动化集群操作
• 为集群管理实现 GitOps 工作流
• 构建自定义基础设施供应商

核心概念

架构

┌─────────────────────────────────────────┐
│         Management Cluster              │
│  ┌─────────────┐  ┌─────────────────┐   │
│  │ CAPI Core   │  │ Infrastructure  │   │
│  │ Controllers │  │ Provider        │   │
│  └─────────────┘  └─────────────────┘   │
│  ┌─────────────┐  ┌─────────────────┐   │
│  │  Bootstrap  │  │  Control Plane  │   │
│  │  Provider   │  │  Provider       │   │
│  └─────────────┘  └─────────────────┘   │
└─────────────────────┬───────────────────┘
                      │ manages
          ┌───────────┴───────────┐
          ▼                       ▼
┌─────────────────┐     ┌─────────────────┐
│ Workload        │     │ Workload        │
│ Cluster 1       │     │ Cluster N       │
└─────────────────┘     └─────────────────┘

关键组件

组件	用途
管理集群	运行 CAPI 控制器，管理工作负载
工作负载集群	由 CAPI 管理的用户集群
基础设施提供商	配置虚拟机、网络、负载均衡器
引导提供商	生成 cloud-init/ignition 配置
控制平面提供商	管理控制平面节点的生命周期

核心资源

资源	描述
Cluster	表示一个 Kubernetes 集群
Machine	表示单个节点/虚拟机
MachineSet	管理 Machine 副本
MachineDeployment	以声明式方式更新 MachineSet
MachineHealthCheck	自动修复不健康的节点

快速入门

# Install clusterctl
curl -L https://github.com/kubernetes-sigs/cluster-api/releases/download/v1.12.0/clusterctl-linux-amd64 -o clusterctl
chmod +x clusterctl
sudo mv clusterctl /usr/local/bin/

# Initialize management cluster
clusterctl init --infrastructure docker

# Create workload cluster
clusterctl generate cluster my-cluster --kubernetes-version v1.32.0 --control-plane-machine-count 1 --worker-machine-count 3 | kubectl apply -f -

# Get cluster kubeconfig
clusterctl get kubeconfig my-cluster > my-cluster.kubeconfig

# Delete cluster
kubectl delete cluster my-cluster

常见工作流

集群生命周期

# Create cluster from template
clusterctl generate cluster prod-cluster \
  --infrastructure aws \
  --kubernetes-version v1.32.0 \
  --control-plane-machine-count 3 \
  --worker-machine-count 5 \
  | kubectl apply -f -

# Scale workers
kubectl scale machinedeployment prod-cluster-md-0 --replicas=10

# Upgrade Kubernetes version
kubectl patch cluster prod-cluster --type merge -p '{"spec":{"topology":{"version":"v1.33.0"}}}'

# Move cluster to new management cluster
clusterctl move --to-kubeconfig target-mgmt.kubeconfig

健康监控

apiVersion: cluster.x-k8s.io/v1beta1
kind: MachineHealthCheck
metadata:
  name: my-cluster-mhc
spec:
  clusterName: my-cluster
  maxUnhealthy: 40%
  nodeStartupTimeout: 10m
  selector:
    matchLabels:
      cluster.x-k8s.io/cluster-name: my-cluster
  unhealthyConditions:
    - type: Ready
      status: "False"
      timeout: 5m
    - type: Ready
      status: Unknown
      timeout: 5m

严禁事项

• 未进行适当备份时，切勿直接修改管理集群
• 切勿直接删除 Machine 对象（请使用 MachineDeployment scale）
• 未检查兼容性时，切勿混用不同版本的提供商
• 切勿跳过集群升级步骤（先升级控制平面，再升级工作节点）
• 切勿忽略 MachineHealthCheck 警报

版本亮点（1.14.x）

• 到 1.14.1 版本线时，Kubernetes 兼容性将提升至管理集群 v1.33.x -> v1.37.x，以及工作负载集群 v1.31.x -> v1.37.x。
• API 类型移入专用的 Golang 模块：提供更强的兼容性保证，以及规模大幅缩小且严格受控的依赖树，从而减少传递依赖带来的 CVE 暴露风险。
• Kubeadm 控制平面稳健性：支持在较旧的 Kubernetes 版本上安全加入工作节点；改进控制平面 Machine 删除时 etcd 领导权的平稳转移；并在连续升级的中间步骤中修复不健康的 Machine。
• 可观测性：升级计划会显示在集群状态中；状态中会公开聚合后的 Machine 版本；运行时扩展错误会显示在集群条件中。
• 扩展性/性能：ClusterCache 客户端提供缓存调优选项，以减少内存占用；managedFields 内部化可减少存储的状态。
• 弃用警告：v1beta1 API 计划在 CAPI v1.16 中停止提供（请迁移到 v1beta2）；Docker* 资源将在 v1.15 中移除（请迁移到 Dev* 资源）。目前提供实验性的 clusterctl convert 命令。

版本亮点（1.13.x）

• 到 1.13.2 版本线时，Kubernetes 兼容性将提升至管理集群 v1.32.x -> v1.36.x，以及工作负载集群 v1.30.x -> v1.36.x。
• v1alpha3 和 v1alpha4 API 版本现已移除；提供商应继续迁移至 v1beta2 契约，因为 v1beta1 仍计划在后续版本中停止提供。
• 集群拓扑现在可以为控制平面和 MachineDeployment 资源设置 rolloutAfter。
• KubeadmControlPlane 提升了对多处故障的修复容忍度，并能更好地显示常见的加入/修复问题。
• PriorityQueue 和 ReconcilerRateLimiting 现已成为 1.13 版本线中的 Beta 默认功能，这可能会改变高负载下的协调行为。

脚本

基于 Go 的工具位于 scripts/ 中。在 scripts 目录下运行 go run ./tool-name。

工具	用途
validate-manifests	根据 CRD 架构验证 YAML 清单
run-clusterctl-diagnose	运行 clusterctl describe 并保存诊断报告
migration-checker	检查 v1beta1→v1beta2 迁移准备情况
check-cluster-health	分析所有集群对象的状态
analyze-conditions	解析并报告 False/Unknown 状态
scaffold-provider	生成新的提供程序目录结构
generate-cluster-template	根据 ClusterClass 生成模板
export-cluster-state	导出集群状态以用于备份/迁移
audit-security	检查 PSS 合规性和安全状况
timeline-events	构建置备事件时间线
compare-versions	比较 CAPI 版本规范和 API 变更
check-provider-contract	验证提供程序 CRD 是否符合契约
lint-cluster-templates	检查并验证 CAPI 清单

资源

assets/ 中的可复用模板：

• 集群模板：cluster-minimal.yaml、cluster-production.yaml、cluster-clusterclass.yaml、clusterclass-example.yaml
• 提供程序配置：docker-quickstart.yaml、aws-credentials.yaml、azure-credentials.yaml、provider-matrix.md
• 运维：upgrade-checklist.md、migration-v1beta2.md、troubleshooting-flow.md、security-audit-report.md、dr-backup-restore.md、etcd-backup.yaml
• GitOps：argocd-cluster-app.yaml、flux-kustomization.yaml、gitops-rbac.yaml
• 监控：prometheus-alerts.yaml

链接

• 文档
• GitHub
• 版本发布