📚 课程目录第4章 CAPI安装与配置

4. CAPI 安装与配置：安装 clusterctl CLI、初始化管理集群、配置 Docker Provider

本章是 CAPI 实践的核心起点。完成本章操作后，你将拥有一个可用的 CAPI 管理集群，并配置好 Docker Provider 作为基础设施目标。后续所有多租户集群的创建与发布都将基于此环境展开。

4.1 安装 clusterctl CLI

clusterctl 是 CAPI 的命令行管理工具，负责管理集群生命周期、Provider 安装与升级。安装方式支持二进制下载、包管理器或容器化运行。

4.1.1 下载与安装

推荐使用官方脚本安装最新稳定版：

curl -L https://github.com/kubernetes-sigs/cluster-api/releases/download/v1.7.3/clusterctl-linux-amd64 -o clusterctl
sudo install -o root -g root -m 0755 clusterctl /usr/local/bin/clusterctl
clusterctl version

macOS 用户可使用 Homebrew：

brew install clusterctl

4.1.2 验证安装

执行以下命令确认版本与可用性：

clusterctl version
# 输出示例: clusterctl version: &version.Info{Major:"1", Minor:"7", GitVersion:"v1.7.3", ...}

版本兼容性提示： clusterctl 版本应与目标 Kubernetes 版本及 Provider 版本匹配。建议使用 v1.7.x 系列，支持 Kubernetes v1.28–v1.30。

4.2 初始化管理集群

管理集群是运行 CAPI Controller 的 Kubernetes 集群。你可以使用现有集群，也可以新建一个。本章使用 kind 快速创建本地管理集群。

4.2.1 创建 Kind 集群

cat <<EOF | kind create cluster --name capi-management --config=-
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
  extraPortMappings:
  - containerPort: 6443
    hostPort: 6443
    protocol: TCP
EOF

4.2.2 初始化 CAPI 核心组件

使用 clusterctl init 安装核心 Provider（Cluster、ControlPlane、Bootstrap）：

clusterctl init --infrastructure docker

该命令会自动完成以下工作：

组件	Provider 名称	作用
Core Provider	cluster-api	核心 CRD 与 Controller
Bootstrap Provider	kubeadm	生成集群引导配置
Control Plane Provider	kubeadm	管理控制平面节点
Infrastructure Provider	docker	管理 Docker 基础设施资源

4.2.3 验证初始化状态

kubectl get pods -n capi-system
kubectl get pods -n capi-kubeadm-bootstrap-system
kubectl get pods -n capi-kubeadm-control-plane-system
kubectl get pods -n capi-docker-system

所有 Pod 应处于 Running 状态。

  初始化参数说明： 使用 --infrastructure docker 时，clusterctl 会自动安装 Docker Infrastructure Provider。如需指定版本，可追加 --infrastructure docker:v1.7.3。

4.3 配置 Docker Provider

Docker Provider 允许 CAPI 在本地 Docker 环境中创建和管理集群节点（容器）。它主要用于开发、测试与演示场景。

4.3.1 Provider 架构概览

下图展示了 Docker Provider 在 CAPI 管理集群中的位置与交互关系：

4.3.2 配置 Docker Provider 参数

Docker Provider 安装后，可通过 ConfigMap 调整默认行为。常用配置项如下：

配置项	默认值	说明
`controllerManagerConfigurationMap`	无	Controller Manager 参数
`DockerProviderOptions`	无	Provider 特定选项
`machineContainerImage`	`kindest/node:v1.29.2`	节点容器镜像
`machineContainerPort`	`6443`	API Server 映射端口

查看当前配置：

kubectl get configmap -n capi-docker-system docker-provider-config -o yaml

4.3.3 验证 Provider 就绪

执行以下命令确认 Provider 已正确注册：

clusterctl describe provider docker
# 输出应显示 Provider 版本、状态、部署信息

同时检查 CRD 是否可用：

kubectl get crd | grep docker
# 应包含 dockermachines.infrastructure.cluster.x-k8s.io
# 应包含 dockermachinetemplates.infrastructure.cluster.x-k8s.io

常见问题： 如果 clusterctl init 失败，请检查：1) 管理集群 kubeconfig 是否正确；2) 网络能否访问 GitHub 与 Docker Hub；3) 是否已安装 kind 或 minikube 等本地集群工具。

4.4 环境验证清单

完成本章配置后，请逐项确认：

clusterctl CLI：clusterctl version 返回正确版本号
管理集群：kubectl cluster-info 正常返回
CAPI 核心 Pod：四个命名空间下的 Controller Pod 均为 Running
Docker Provider CRD：kubectl get crd | grep docker 返回至少两个 CRD
Provider 状态：clusterctl describe provider docker 显示 Ready: True

至此，CAPI 管理集群已初始化完成，Docker Provider 配置就绪。下一阶段将进入多租户集群的模板定义与快速创建环节。