4. 环境准备：安装 K8s 集群与 kubectl 配置

在开始构建 GitOps 流水线之前，必须准备一个可用的 Kubernetes 集群环境。本章将指导你完成以下核心任务：安装轻量级 K8s 集群（Minikube 或 K3s）、安装命令行工具 kubectl，以及配置 kubeconfig 文件以建立集群连接。这些是后续所有 GitOps 实践的基础设施前提。

选择建议： 本地开发与学习推荐使用 Minikube；资源受限环境或边缘场景推荐使用 K3s。两者均支持完整的 Kubernetes API，且与 GitOps 工具（ArgoCD / Flux）兼容。

4.1 环境概览与工具矩阵

下表列出了本课程所需的核心组件及其版本要求。请确保你的操作系统满足最低配置。

组件 版本要求 用途 安装方式
Minikube ≥ v1.30 本地单节点 K8s 集群 二进制 / 包管理器
K3s ≥ v1.27 轻量级生产级 K8s 集群 官方安装脚本
kubectl ≥ v1.28 K8s 命令行控制工具 二进制 / 包管理器
Docker ≥ 24.0 容器运行时（Minikube 驱动） 官方仓库
kubeconfig — 集群访问凭证与上下文 自动生成 / 手动配置

4.2 安装 Minikube（推荐用于本地开发）

Minikube 是运行单节点 K8s 集群的最快方式，特别适合 GitOps 流水线的本地验证。以下步骤基于 Linux/macOS 环境。

  1. 安装 Docker（作为 Minikube 驱动）：
# Ubuntu / Debian
sudo apt-get update && sudo apt-get install -y docker.io
sudo systemctl enable --now docker

# macOS (Homebrew)
brew install docker
  1. 安装 Minikube 二进制文件：
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
sudo install minikube-linux-amd64 /usr/local/bin/minikube
  1. 启动集群：
minikube start --driver=docker --cpus=2 --memory=4096
验证： 执行 minikube status 应显示 host: Running、kubelet: Running、apiserver: Running。

4.3 安装 K3s（轻量级备选方案）

如果你的环境资源有限，或希望模拟更接近生产的多节点场景，K3s 是更优选择。K3s 将 K8s 组件打包为单个二进制，内存占用极低。

# 安装 K3s 服务端（单节点集群）
curl -sfL https://get.k3s.io | sh -

# 检查节点状态
sudo k3s kubectl get nodes

K3s 安装完成后会自动生成 /etc/rancher/k3s/k3s.yaml 配置文件，该文件可直接用作 kubeconfig。

注意： K3s 默认使用 containerd 作为容器运行时，而非 Docker。如果你的 GitOps 流水线依赖 Docker-in-Docker 或特定镜像构建工具，请提前验证兼容性。

4.4 安装 kubectl

kubectl 是与 K8s 集群交互的核心 CLI。无论选择 Minikube 还是 K3s，都需要独立安装 kubectl。

# 下载最新稳定版 kubectl
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"

# 赋予执行权限并移动到 PATH
chmod +x kubectl
sudo mv kubectl /usr/local/bin/

# 验证版本
kubectl version --client

4.5 配置 kubeconfig

kubeconfig 文件定义了集群、用户和上下文的映射关系。kubectl 默认读取 ~/.kube/config。以下是两种典型场景的配置方法。

4.5.1 Minikube 自动配置

Minikube 启动后会自动生成 kubeconfig 并合并到默认路径：

# 查看当前上下文
kubectl config current-context

# 输出应为：minikube

4.5.2 K3s 手动配置

K3s 生成的配置文件默认位于 /etc/rancher/k3s/k3s.yaml，需要复制到用户目录并修改权限：

mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown $(id -u):$(id -g) ~/.kube/config
export KUBECONFIG=~/.kube/config

# 验证集群连接
kubectl cluster-info

4.5.3 多集群上下文管理

当同时管理多个集群时，可以使用 kubectl config 命令切换上下文：

命令 说明
kubectl config get-contexts 列出所有上下文
kubectl config use-context <name> 切换当前上下文
kubectl config set-context <name> --namespace=<ns> 设置默认命名空间

4.6 环境验证清单

完成上述安装后，请执行以下命令确认环境就绪：

# 1. 检查 kubectl 版本
kubectl version --client --short

# 2. 检查集群节点
kubectl get nodes -o wide

# 3. 检查核心组件状态
kubectl get pods -n kube-system

# 4. 测试部署一个简单应用
kubectl create deployment nginx-test --image=nginx:alpine
kubectl get deployments
kubectl delete deployment nginx-test
GitOps 准备提示： 确保集群网络能够访问 Git 仓库（如 GitHub / GitLab），并且集群具备拉取公共容器镜像的能力。如果使用私有仓库，请提前配置 ImagePullSecret。

4.7 环境架构示意

下图展示了本课程所使用的本地开发环境整体架构，包括 Minikube 集群、kubectl 客户端、kubeconfig 配置以及后续将集成的 GitOps 组件。

GitOps 流水线本地环境架构 开发者工作站 kubectl CLI kubeconfig (~/.kube/config) Minikube 集群 Control Plane Worker Node K3s 集群（备选） 单二进制 / 低内存 containerd 运行时 Git 仓库 GitHub / GitLab 应用清单 + 配置 kubectl apply kubectl apply 拉取清单 拉取清单 核心配置要点 • kubeconfig 文件决定了 kubectl 连接哪个集群，支持多上下文切换。 • Minikube 与 K3s 可共存，通过 kubectl config use-context 切换。

4.8 常见问题与排错

  • kubectl 无法连接集群： 检查 kubectl config view 输出的 server 地址是否正确。Minikube 使用 minikube ip 获取地址；K3s 默认监听 6443 端口。
  • Minikube 启动失败： 确保 Docker 服务运行中，且当前用户具有 Docker 组权限（sudo usermod -aG docker $USER 后重新登录）。
  • K3s 权限错误： kubeconfig 文件权限必须为 600，且属主为当前用户。使用 chmod 600 ~/.kube/config 修复。
  • 上下文冲突： 如果同时安装 Minikube 和 K3s，kubeconfig 可能包含多个上下文。使用 kubectl config rename-context 重命名以避免混淆。
← 上一章 📖 返回目录 下一章 →