📚 课程目录第4章 Kubernetes集群环境搭建

4. Kubernetes 集群环境搭建：Minikube/K3s 部署、命名空间规划、资源配额设置

在构建倒排索引与文档嵌套结构系统之前，必须搭建一个稳定、可复现的 Kubernetes 实验环境。本章聚焦于两种主流轻量级集群方案——Minikube（本地开发）与 K3s（边缘/生产模拟），并围绕搜索引擎场景进行命名空间与资源配额的精细化设计。

4.1 集群方案选型对比

根据课程实验规模（单机多节点、资源受限、需快速重建），推荐以下两种方案：

特性	Minikube	K3s
安装复杂度	低（单二进制 + 驱动）	极低（单文件安装）
资源占用	中等（约 2GB RAM）	低（约 512MB RAM）
多节点支持	需额外配置（multi-node 驱动）	原生支持（server + agent）
持久化存储	默认 hostPath / 需 CSI	内置 Local Path Provisioner
适用场景	本地开发、单机调试	边缘集群、CI/CD 模拟

选型建议： 本课程后续章节均兼容两种集群。若宿主机内存 ≥ 8GB，推荐 Minikube（体验更接近生产）；若资源紧张或需模拟多节点，优先 K3s。

4.2 Minikube 部署步骤

安装 Minikube 二进制（Linux/macOS）：

curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
sudo install minikube-linux-amd64 /usr/local/bin/minikube

启动集群（指定驱动与资源）：

minikube start --driver=docker --cpus=4 --memory=8192 --disk-size=20g

验证集群状态：
```
kubectl cluster-info
kubectl get nodes
```

启用必要插件（用于倒排索引存储）：

minikube addons enable ingress
minikube addons enable storage-provisioner

  关键参数说明： --cpus=4 与 --memory=8192 确保后续 Elasticsearch / 倒排索引 Pod 有足够资源；--disk-size=20g 避免索引数据撑爆临时存储。

4.3 K3s 部署步骤

安装 K3s Server（控制平面 + 工作节点）：

curl -sfL https://get.k3s.io | sh -s - --write-kubeconfig-mode 644

获取 kubeconfig：

export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
kubectl get nodes

添加 Agent 节点（可选，模拟多节点）：

curl -sfL https://get.k3s.io | K3S_URL=https://server-ip:6443 K3S_TOKEN=mynodetoken sh -

验证内置存储：

kubectl get storageclass
# 应看到 local-path (default)

注意： K3s 默认使用 containerd 而非 Docker。若后续需构建自定义镜像，请确保在集群外完成构建并推送到镜像仓库，或配置 K3s 使用 Docker 运行时。

4.4 命名空间规划

针对倒排索引与文档嵌套结构系统，建议按功能域划分命名空间，实现逻辑隔离与资源管控：

命名空间	用途	包含组件
`index-core`	倒排索引核心服务	索引构建器、倒排表 Pod、词典缓存
`doc-store`	文档嵌套结构存储	文档数据库、嵌套字段解析器
`search-api`	搜索查询入口	API Gateway、查询重写、结果排序
`monitoring`	可观测性	Prometheus、Grafana、日志采集
`data-pipeline`	数据摄入与预处理	Kafka Connect、ETL 任务

规划原则： 每个命名空间对应一个独立的资源配额与网络策略域。例如 index-core 需要更多 CPU 和内存，而 monitoring 需要持久化存储。

4.5 资源配额设置

为每个命名空间设置 ResourceQuota 与 LimitRange，防止单个组件耗尽集群资源：

4.5.1 核心索引命名空间配额示例

apiVersion: v1
kind: ResourceQuota
metadata:
  name: index-core-quota
  namespace: index-core
spec:
  hard:
    requests.cpu: "4"
    requests.memory: "8Gi"
    limits.cpu: "8"
    limits.memory: "16Gi"
    persistentvolumeclaims: "3"
    pods: "10"
---
apiVersion: v1
kind: LimitRange
metadata:
  name: index-core-limits
  namespace: index-core
spec:
  limits:
  - default:
      cpu: "1"
      memory: "2Gi"
    defaultRequest:
      cpu: "500m"
      memory: "1Gi"
    type: Container

4.5.2 各命名空间配额分配表

命名空间	CPU 请求	内存请求	CPU 上限	内存上限	最大 Pod 数
`index-core`	4	8Gi	8	16Gi	10
`doc-store`	2	4Gi	4	8Gi	8
`search-api`	2	4Gi	4	8Gi	6
`monitoring`	1	2Gi	2	4Gi	5
`data-pipeline`	2	4Gi	4	8Gi	8

  验证配额生效： 使用 kubectl describe quota -n index-core 查看当前使用量；若 Pod 创建失败，检查 kubectl describe pod <pod-name> -n index-core 中的资源不足事件。

4.6 集群环境架构总览

下图展示了 Minikube/K3s 集群中命名空间、资源配额与倒排索引组件之间的逻辑关系：

4.7 环境验证清单

完成部署后，执行以下命令确认集群就绪：

# 1. 节点状态
kubectl get nodes -o wide

# 2. 命名空间创建
kubectl create ns index-core
kubectl create ns doc-store
kubectl create ns search-api
kubectl create ns monitoring
kubectl create ns data-pipeline

# 3. 应用资源配额
kubectl apply -f quota-index-core.yaml
kubectl apply -f quota-doc-store.yaml
kubectl apply -f quota-search-api.yaml

# 4. 验证配额
kubectl describe quota -n index-core

# 5. 测试调度（部署一个测试 Pod）
kubectl run test-pod --image=nginx -n index-core --requests='cpu=500m,memory=1Gi'
kubectl delete pod test-pod -n index-core

  预期输出： 所有节点处于 Ready 状态；命名空间列表包含上述 5 个；配额描述显示 Used: 0 且 Hard 值与配置一致；测试 Pod 成功运行后删除无报错。

4.8 常见问题与避坑

Minikube 驱动冲突： 若已安装 VirtualBox，Minikube 默认使用 virtualbox 驱动；建议统一使用 --driver=docker 避免网络模式不一致。
K3s 权限问题： 默认 kubeconfig 文件权限为 644，但 /etc/rancher/k3s/k3s.yaml 可能被普通用户读取；使用 export KUBECONFIG=~/.kube/config 并复制内容。
资源配额超出后 Pod 卡在 Pending： 使用 kubectl describe pod <pod-name> -n <ns> 查看事件，若显示 Failed quota 则需调整配额或减少 Pod 资源请求。
存储类缺失： Minikube 默认不安装 CSI 驱动；使用 minikube addons enable storage-provisioner 或手动创建 hostPath PV。

生产环境提示： 本课程使用 Minikube/K3s 仅用于学习验证。生产环境建议使用托管集群（EKS/GKE/ACK）或自建高可用集群，并配合 Velero 进行备份。