# 集群 API (CAPI) ## 概述 Cluster API (CAPI) 将 Kubernetes 集群作为 Kubernetes 资源进行管理。您无需通过 SSH 连接到节点并运行命令式命令，而是使用自定义资源以声明方式定义集群，并且 CAPI 控制器将所需状态与现实相协调。 **核心原则：** CAPI 将集群生命周期管理转变为 Kubernetes 原生工作流程——定义集群 CR、应用它，控制器自动处理配置、扩展和升级。 ## 何时使用 * 从管理集群以声明方式配置 Kubernetes 集群 * 大规模管理集群队列（数十到数百） * 通过修补版本字段来执行滚动升级 * 使用 ClusterClass 蓝图标准化集群模板 * 与 Docker 基础设施提供商一起设置开发/测试环境 **不适用于：** 具有安全强化功能的单集群安装（使用 rke2-deployment 或 kubespray-deployment）、没有 CAPI 控制器映像的气隙环境、没有基础设施提供商的裸机配置 ## 关键概念概念|描述 ---|--- 管理集群|运行 CAPI 控制器、存储集群定义——“大脑” 工作负载集群|由CAPI配置，运行实际应用程序集群CR |定义所需的集群状态（版本、拓扑、网络）机器|代表单个节点（VM或容器）机器部署|管理一组机器（就像 Deployment 管理 Pod）机器组 | MachineDeployment 和 Machine 之间的中间资源集群类 |用于创建具有一致拓扑的集群的可重用蓝图 ## CAPI 与 Kubespray/RKE2 方面| Kubespray / RKE2 |集群API ---|---|--- 型号|命令式（Ansible 剧本/CLI）|声明式（Kubernetes CR）范围 |单集群安装|多个集群的车队管理升级|手动按节点运行手册 |补丁版本字段，控制器处理规模|一次一个集群 |从一个地方管理数百个集群安全焦点| RKE2：FIPS、SELinux、CIS 强化 |取决于基础设施提供商气隙支持|强（Kubespray离线，RKE2嵌入）|需要可用的 CAPI 控制器映像 ## 提供商架构 CAPI 使用模块化提供商架构。四种提供商类型协同工作来配置和管理集群。管理集群 +--------------------------------------------------------------------------------+ | | | +--------------------------------+ +--------------------------------+ | | |核心提供商 | |引导程序提供商 | | | | （capi 系统）| | (capi-kubeadm-bootstrap-system)| | | | | | | | | |管理： | |生成：| | | | - 集群| | - 云初始化/用户数据| | | | - 机器| | - kubeadm 初始化配置 | | | | - 机器组| | - kubeadm 加入配置 | | | | - 机器部署| +--------------------------------+ | | +--------------------+ | | | | +----------------------------+ +----------------------------+ | | |控制平面提供商| |基础设施提供商| | | | （capi-kubeadm-control- | | （例如，capd-system for | | | | 平面系统） | | Docker、用于 vSphere 的 capv、| | | | | | AWS 等的 capa）| | | |管理： | | | | | | - KubeadmControlPlane | |创建： | | | | - CP 扩展/升级 | | - 实际虚拟机/容器| | | | - etcd 会员 | | - 负载平衡器| | | +----------------------------------------+ | - 网络/磁盘| | | +----------------------------------------+ | +--------------------------------------------------------------------------------+ ### 提供商类型供应商|命名空间|责任 ---|---|--- 核心| `capi 系统` |管理集群、机器、MachineSet、MachineDeployment CRD 引导程序| `capi-kubeadm-bootstrap-system` |为 kubeadm init/join 生成 cloud-init/user-data 控制平面| `capi-kubeadm-控制平面系统` |管理 KubeadmControlPlane，处理 CP 扩展/升级/etcd 基础设施|特定于提供商（例如“capd-system”）|创建实际的虚拟机/容器、LB、网络 ### 基础设施提供商示例供应商|前缀 |创造 ---|---|--- Docker（CAPD）| `capd 系统` | Docker 容器模拟节点（开发/测试） vSphere (CAPV) | `capv 系统` | vSphere 虚拟机 AWS（CAPA）| `capa 系统` | EC2 实例、ELB、VPC 天蓝色 (CAPZ) | `capz 系统` | Azure VM、LB、VNet 金属3 (CAPM3) | `capm3 系统` |通过 Ironic 的裸机服务器 ## 管理集群与工作负载集群 +--------------------------------------------------------+ | 管理集群（KinD）| | | | CAPI 控制器： | | - 核心提供商| | - 引导程序提供商| | - 控制平面提供商| | - 基础设施提供商| | - 证书经理 | | | | 存储 CR： | | - 集群/capi-快速入门 | | - KubeadmControlPlane/... | | - 机器部署/... | | - 机器/...（每个节点一个）| +--------------------------------------------------------+ | | | |调和|调和|调和维维维 +--------------------------------------------------------+ | 工作负载集群（capi-快速入门）| | | | +----------+ +---------+ +---------+ | | | CP-1 | | CP-2 | | CP-3 | | | | （节点）| | （节点）| | （节点）| | | +----------+ +---------+ +---------+ | | | | +----------+ +---------+ +---------+ | | |工人1 | |工人2| |工人-3| | | | （节点）| | （节点）| | （节点）| | | +----------+ +---------+ +---------+ | | | | HAProxy LB（用于 API 服务器访问）| | | | 运行实际应用程序工作负载 | +--------------------------------------------------------+ **主要区别：** * 管理集群是“大脑”——它运行 CAPI 控制器并存储集群定义 * 工作负载集群是“肌肉”——它们运行实际的应用程序工作负载 * 管理集群不运行应用程序 Pod * 一个管理集群可以管理多个工作负载集群 ## 动手设置（Docker 提供商） Docker 提供者 (CAPD) 将节点模拟为 Docker 容器。非常适合学习、开发和 CI/CD 测试。 ### 第 1 步：使用 KindD 创建管理集群 kind create cluster --name myk8s --image kindest/node:v1.35.0 --config - < capi-quickstart.yaml **什么`--flavordevelopment`的作用：** 选择专为本地基于 Docker 的开发而设计的预构建模板。该模板包括 ClusterClass 定义、DockerCluster/DockerMachine 模板和 kubeadm 配置。 ### 应用集群清单 kubectl apply -f capi-quickstart.yaml ### 监控配置 # 观察集群配置状态 clusterctl 描述集群 capi-快速启动 # 实时观看 clusterctl 描述集群 capi-quickstart --show-conditions all **配置期间会发生什么（Docker 提供商）：** 1. CAPI使用`kindest/node`镜像创建Docker容器来模拟集群节点 2. 创建HAProxy容器作为工作负载集群API服务器的负载均衡器 3. Bootstrap提供程序生成kubeadm init/join配置 4. 控制平面提供程序在第一个 CP 节点上运行 kubeadm init，然后加入其余 CP 节点 5. Worker 机器通过 kubeadm join 进行引导配置流程（Docker 提供商） +--------------------------------------------------------------------+ | | | kubectl apply -f capi-quickstart.yaml | kubectl apply -f capi-quickstart.yaml | | | | | v | | 核心提供者：创建 Cluster 对象 | | | | | v | | 基础设施提供商 (CAPD)： | | - 创建 DockerCluster（网络设置）| | - 创建 HAProxy 容器（API 服务器的 LB）| | | | | v | | 控制平面提供商： | | - 创建第一台机器（Docker 容器）| | - Bootstrap Provider 生成 kubeadm init 配置 | | - 在容器内运行 kubeadm init | | - 对 CP 节点 2 和 3 重复 (kubeadm join --control-plane) | | | | | v | | MachineDeployment 控制器： | | - 创建 MachineSet -> 为工人提供的机器 | | - Bootstrap Provider 生成 kubeadm join 配置 | | - 在每个工作容器内运行 kubeadm join | | | | | v | | 集群状态：已配置 | | （在安装 CNI 之前，节点尚未就绪）| +--------------------------------------------------------------------+ ### 访问工作负载集群 # 获取工作负载集群的 kubeconfig clusterctl get kubeconfig capi-quickstart > capi-quickstart.kubeconfig **修复本地访问的 kubeconfig（仅限 Docker 提供商）：** 生成的 kubeconfig 包含 API 服务器的内部 Docker 网络 IP。要从您的主机进行访问，您必须将其替换为“127.0.0.1”和映射的端口。 # 找到HAProxy容器的映射端口码头工人 PS | grep capi-快速启动-lb # 输出示例： # ... 0.0.0.0:43210->6443/tcp ... capi-quickstart-lb # 映射的端口为43210 # 更新 kubeconfig 以使用 localhost 和映射端口 sed -i 's|服务器：https://.*:6443|服务器：https://127.0.0.1:43210|' capi-快速启动.kubeconfig # macOS: sed -i '' 's|服务器：https://.*:6443|服务器：https://127.0.0.1:43210|' capi-快速启动.kubeconfig ### 安装 CNI（必需）在安装 CNI 插件之前，节点将保持“NotReady”状态。 CAPI 不会自动安装 CNI——这是设计使然，让您可以灵活地选择 CNI。 # 安装 Calico CNI kubectl --kubeconfig=capi-quickstart.kubeconfig \ 应用-f https://raw.githubusercontent.com/projectcalico/calico/v3.27.0/manifests/calico.yaml **验证节点转换为就绪状态：** # 观察节点从NotReady -> Ready kubectl --kubeconfig=capi-quickstart.kubeconfig 获取节点 -w CNI 安装后 1-2 分钟内所有节点应显示“就绪”状态。 ### 完整验证 # 所有节点就绪 kubectl --kubeconfig=capi-quickstart.kubeconfig 获取节点 -o Wide # 系统 Pod 正在运行 kubectl --kubeconfig=capi-quickstart.kubeconfig 获取 pods -A # 来自管理集群：集群状态 clusterctl 描述集群 capi-快速启动 # 检查机器对象 kubectl 获取机器 -o Wide # 检查机器部署 kubectl get machinedeployments -o Wide ## ClusterClass（拓扑） ClusterClass 是用于创建集群的可重用蓝图。定义一次集群形状（基础设施、控制平面、工作人员的模板），然后在创建集群时引用它。 ### 启用 ClusterClass # 必须在 clusterctl init 之前设置导出 CLUSTER_TOPOLOGY=true clusterctl init --基础设施泊坞窗 ### ClusterClass资源层次结构 ClusterClass（蓝图） +------------------------------------------------------------------------+ | 名称：我的集群类 | | | | 基础设施： | | 参考：DockerClusterTemplate/my-cluster-class | | | | 控制平面： | | 参考：KubeadmControlPlaneTemplate/my-cluster-class | | 基础设施： | | 参考：DockerMachineTemplate/my-cluster-class-cp | | | | 工人： | | 机器部署： | | - 类：默认工作者 | | 模板：| | 引导程序： | | 参考：KubeadmConfigTemplate/my-cluster-class | | 基础设施： | | 参考：DockerMachineTemplate/my-cluster-class-wkr | +------------------------------------------------------------------------+ 集群（使用 ClusterClass 的实例） +------------------------------------------------------------------------+ | 名称： capi-快速入门 | | 规格: | | 拓扑： | | 类： my-cluster-class <-- 引用 ClusterClass| | 版本：v1.34.3 | | 控制平面： | | 副本：3 | | 工人: | | 机器部署： | | - 类：默认工作者 | | 名称：md-0 | | 副本：3 | +------------------------------------------------------------------------+ ### ClusterClass 中的资源类型资源 |目的 ---|--- `集群类` |将所有模板捆绑在一起的顶级蓝图 `DockerClusterTemplate` |基础设施级集群配置模板（网络、LB） `KubeadmControlPlaneTemplate` |控制平面行为的模板（kubeadm 配置、部署） `DockerMachineTemplate` |单个机器规格的模板（CPU、内存、图像） `KubeadmConfigTemplate` |工作节点引导配置模板 `集群` |通过“spec.topology.class”引用 ClusterClass 的实例 ### ClusterClass 的好处 * **一致性：** 同一类的所有集群共享相同的基础设施和引导配置 * **简单性：** 创建一个新的集群只需要一个小的 Cluster CR 引用该类 * **升级：** 更新 ClusterClass 并且使用它的所有集群都可以前滚 * **治理：** 平台团队定义 ClusterClass，应用程序团队使用它们 ## 声明式集群升级 CAPI 最强大的功能之一：通过修补单个字段来升级整个集群。 ### 从 v1.34 升级到 v1.35 kubectl 补丁集群 capi-quickstart --type merge \ -p '{"规格":{"拓扑":{"版本":"v1.35.0"}}}' **这是整个升级命令。** 一行。没有 SSH，没有手动 kubeadm 命令，没有逐节点 playbook 运行。 ### 升级过程中会发生什么声明式升级流程 +--------------------------------------------------------------------+ | | | kubectl 补丁集群...版本：“v1.35.0”| | | | | v | | 控制平面提供程序检测版本漂移 | | | | | v | | 第一阶段：控制平面滚动升级| | 对于每个 CP 节点（一次一个）： | | 1.使用v1.35.0镜像创建新机器| | 2.等待新节点加入并变为Ready | | 3.警戒老节点| | 4. 排空旧节点（驱逐工作负载）| | 5.删除旧机器（删除容器/VM）| | 6.更新etcd会员资格 | | 重复此操作，直到所有 CP 节点均位于 v1.35.0 | | | | | v | | 第 2 阶段：Worker 滚动升级 | | MachineDeployment 控制器： | | 1. 使用 v1.35.0 创建新的 MachineSet | | 2. 扩展新的MachineSet（新工人加入）| | 3. 封锁老工人| | 4. 流失老工人| | 5. 缩小旧的MachineSet（删除旧的worker）| | 根据推出策略进行收益（默认：滚动） | | | | | v | | 升级完成：所有节点运行v1.35.0 | +--------------------------------------------------------------------+ ### 监控升级进度 # 实时观看升级情况 clusterctl 描述集群 capi-quickstart --show-conditions all # 手表机器更换 kubectl 获取机器 -w # 检查 MachineDeployments 的部署状态 kubectl get machinedeployments -o Wide # 验证工作负载集群上的版本 kubectl --kubeconfig=capi-quickstart.kubeconfig 获取节点 -o Wide ### 升级行为详细信息方面|行为 ---|--- CP升级令|一次一个节点（串行），在旧节点删除之前创建新节点工人升级订单|通过 MachineDeployment 进行滚动更新（可配置激增/不可用） etcd 处理 |自动——随着 CP 节点的更换而更新成员资格工作负载中断 |在节点删除之前 Pod 会正常排空回滚|不是自动的——如果需要的话将补丁版本恢复到以前的版本故障处理|如果新节点未能就绪，升级将暂停 ## 清理 ### 删除工作负载集群 # 删除工作负载集群（从管理集群上下文中） kubectl 删除集群 capi-quickstart 此单个命令将删除与工作负载集群关联的所有资源： * 所有机器对象（Docker 容器或虚拟机） * 负载均衡器容器 * 机器部署、机器集 * Bootstrap 配置、kubeadm 配置 * 基础设施资源（DockerCluster、DockerMachines） **CAPI 使用所有者引用** \--删除 Cluster 对象会自动级联到所有子资源。 ### 删除管理集群 # 删除KinD管理集群 kind 删除集群 --name myk8s ## 自定义资源快速参考资源 | API组|管理人 |目的 ---|---|---|--- `集群` | `cluster.x-k8s.io` |核心提供商 |顶级集群定义 `机器` | `cluster.x-k8s.io` |核心提供商 |单节点表示 `机器集` | `cluster.x-k8s.io` |核心提供商 |管理一组相同的机器 `机器部署` | `cluster.x-k8s.io` |核心提供商| MachineSet 的声明性更新 `KubeadmControlPlane` | `controlplane.cluster.x-k8s.io` | CP提供商|控制平面扩展和升级 `KubeadmConfig` | `bootstrap.cluster.x-k8s.io` |引导程序提供商 | kubeadm 引导配置 `KubeadmConfigTemplate` | `bootstrap.cluster.x-k8s.io` |引导程序提供商 |工作线程引导配置模板 `Docker 集群` | `infrastruction.cluster.x-k8s.io` |基础设施提供商 | Docker 特定的集群基础设施 `DockerMachine` | `infrastruction.cluster.x-k8s.io` |基础设施提供商 | Docker专用机器（容器） `DockerMachineTemplate` | `infrastruction.cluster.x-k8s.io` |基础设施提供商 | DockerMachine 规格模板 `集群类` | `cluster.x-k8s.io` |核心提供商|可重用的集群蓝图 ## 有用的命令命令 |目的 ---|--- `clusterctl init --基础设施 docker` |使用 Docker 提供商初始化管理集群 `clusterctl 生成集群 <名称> ...` |从模板生成集群清单 `clusterctl 描述集群 <名称>` |显示集群拓扑和状态 `clusterctl get kubeconfig <名称>` |检索工作负载集群 kubeconfig `clusterctl move --to-kubeconfig <路径>` |将 CAPI 对象移动到不同的管理集群 `kubectl 获取集群` |列出所有 CAPI 管理的集群 `kubectl 获取机器 -o Wide` |列出所有机器的状态和版本 `kubectl 获取机器部署` |列出所有 MachineDeployment `kubectl 获取 kubeadmcontrolplane` |列出具有副本计数的控制平面对象 ## 常见错误（可搜索）错误：无法连接到管理集群 **原因：** kubectl 上下文未指向管理集群。 **修复：** 运行 `kubectl config use-context kind-myk8s` 以切换到管理集群上下文。错误：X 次尝试后操作失败：无法获取“docker”提供程序的提供程序组件 **原因：** clusterctl 无法下载提供程序组件（网络问题或版本错误）。 **修复：** 检查互联网连接。对于气隙设置，请使用“clusterctl init”以及“~/.cluster-api/clusterctl.yaml”中的本地提供程序存储库配置。集群“capi-quickstart”未准备好：WaitForControlPlaneAvailable **原因：** 控制平面计算机仍在配置或无法引导。 **修复：** 检查机器对象（`kubectl getmachines`），检查机器状况，检查 Docker 容器日志（`dockerlog`）。无法连接到服务器：x509：由未知颁发机构签名的证书 **原因：** 工作负载集群的 Kubeconfig 的 CA 或服务器地址不正确。 **修复：** 使用 clusterctl get kubeconfig 重新检索 kubeconfig 并修复本地 Docker 访问的服务器地址。节点未就绪：节点“capi-quickstart-xxxx”未就绪 **原因：** CNI 未安装在工作负载集群上。 **修复：** 使用工作负载集群的 kubeconfig 安装 CNI 插件（Calico、Cilium、Flannel）。在部署 CNI 之前，节点将保持 NotReady 状态。来自服务器的错误：创建“capi-quickstart.yaml”时出错：准入 webhook“validation.cluster.cluster.x-k8s.io”拒绝了请求：找不到 Cluster.spec.topology.class“quick-start” **原因：** 清单中引用的 ClusterClass 不存在。 **修复：** 确保在“clusterctl init”之前设置“CLUSTER_TOPOLOGY=true”。 “--flavordevelopment”标志包括生成的清单中的 ClusterClass 定义 - 确保应用完整文件。 docker：守护程序的错误响应：冲突。容器名称“/capi-quickstart-lb”已被使用 **原因：** 来自先前 CAPI 集群的同名剩余 Docker 容器。 **修复：** 首先删除旧集群（`kubectl delete cluster capi-quickstart`），或手动删除孤立容器（`docker rm -f capi-quickstart-lb`）。错误：等待机器上的条件超时 **原因：** 机器配置被卡住——可能是 Docker 资源限制、镜像拉取失败或 kubeadm init/join 失败。 **修复：** 检查 Docker 守护进程资源（`docker system df`），检查机器的引导数据，并检查容器日志中是否有 kubeadm 错误。无法创建种类集群：无法初始化节点：kubeadm init 失败 **原因：** KinD 管理集群创建失败，通常是由于 Docker 资源不足或端口映射冲突。 **修复：** 确保 Docker 有足够的内存（至少 4 GB 用于管理 + 工作负载集群），检查 extraPortMappings 的端口可用性。 ## 常见错误错误|后果 ---|--- 在 `clusterctl init` 之前忘记 `CLUSTER_TOPOLOGY=true` | ClusterClass CRD 未安装；使用环境变量集重新运行 `clusterctl init` 未在 KinD 配置中安装 Docker 套接字 | CAPD无法创建工作负载集群容器；使用“extraMounts”为“/var/run/docker.sock”重新创建 KinD 跳过工作负载集群上的 CNI 安装 |所有节点都陷入“NotReady”状态，无法调度 Pod 直接使用生成的 kubeconfig（Docker 提供商）|连接被拒绝;将 API 服务器地址替换为 `127.0.0.1:` 手动删除 Docker 容器而不是 `kubectl delete cluster` | CAPI 状态变得不一致，管理集群中的孤立资源直接运行`kubectl delete machine` | CAPI 将协调并重新创建机器；使用 MachineDeployment 副本或“kubectl 删除集群” 尝试通过 SSH 连接到 CAPD Docker 容器 |容器不是虚拟机；使用 `docker exec -it bash` 代替不检查 CAPI 提供程序版本是否匹配 |版本不匹配导致协调失败；使用`clusterctl升级计划`来检查用于管理+工作负载集群的Docker资源不足|容器 OOM 被杀死；至少分配4GB内存，3+3集群建议8GB 在配置期间忽略“clusterctl描述”输出|缺少早期错误信号；始终使用“clusterctl描述集群<名称> --show-conditions all”进行监控

集群API

包含技能