1. KubeKey配置文件基础解析

第一次接触KubeKey的config-sample.yaml文件时，我盯着那密密麻麻的YAML结构看了足足十分钟。这个看似复杂的配置文件，其实就像乐高说明书——只要掌握关键模块的组装逻辑，就能搭建出稳定的K8s和KubeSphere集群。

配置文件的核心结构分为两大部分：Cluster配置和ClusterConfiguration配置。前者定义Kubernetes集群的基础架构，后者控制KubeSphere组件的安装选项。我习惯用树状结构来理解：

config-sample.yaml
├── Cluster (K8s集群骨架)
│   ├── hosts (节点信息)
│   ├── roleGroups (角色分组)
│   ├── kubernetes (K8s版本参数)
│   └── addons (扩展插件)
└── ClusterConfiguration (KubeSphere血肉)
    ├── etcd (监控配置)
    └── devops (可选组件)

生产环境中最常见的配置失误往往发生在hosts段。比如有次我给某企业部署时，internalAddress误填了公网IP，导致节点间通信始终走公网带宽。正确的配置应该像这样：

hosts:
  - name: master
    address: 203.0.113.10  # 公网SSH地址
    internalAddress: 10.0.0.10  # 内网通信地址
    user: root
    password: "SecurePass123!"

2. etcd集群配置实战技巧

etcd作为Kubernetes的大脑，配置不当会导致整个集群不稳定。经过多次生产环境验证，我总结出三个黄金法则：

1. 奇数节点原则：生产环境至少部署3个etcd节点，且必须为奇数。我曾测试过2节点集群，当网络分区时直接导致脑裂。

2. 隔离部署策略：不要将etcd与worker节点混部。最佳实践是单独配置etcd节点组：

roleGroups:
  etcd:
    - etcd01
    - etcd02
    - etcd03
  worker:
    - worker01
    - worker02

3. 性能调优参数：高负载环境下需要调整这些关键参数：

etcd:
  type: kubekey
  heartbeatInterval: 250  # 心跳间隔(ms)
  electionTimeout: 5000   # 选举超时(ms)
  dataDir: "/data/etcd"   # 建议单独挂盘

去年有个客户集群频繁出现leader选举，就是因为默认的electionTimeout(1000ms)在跨机房部署时网络延迟导致。调整为5000ms后立即稳定。

3. Worker节点高级配置

worker配置看似简单，但隐藏着不少玄机。最常见的误区是资源分配：

kubernetes:
  maxPods: 250  # 单节点Pod数量上限
  podPidsLimit: 4096  # Pod的PID数量限制
  nodeCidrMaskSize: 24  # 节点CIDR掩码

关键经验：

• 物理机建议maxPods设置100-250
• 虚拟机建议50-100
• 超过限制会导致Pod创建失败

对于混合工作负载场景，可以通过标签实现精细化调度：

hosts:
  - name: gpu-worker01
    address: 10.0.0.20
    labels:
      accelerator: nvidia-t4
      storage: ssd

然后在K8s部署时使用nodeSelector匹配：

spec:
  nodeSelector:
    accelerator: nvidia-t4

4. Addons插件配置详解

addons模块是KubeKey最强大的功能之一。以部署NFS客户端为例：

addons:
- name: nfs-client
  namespace: kube-system
  sources:
    chart:
      name: nfs-client-provisioner
      repo: https://charts.kubesphere.io/main
      values: |
        nfs.server: 10.0.0.100
        nfs.path: /data/nfs
        storageClass.defaultClass: true

避坑指南：

1. 先确保NFS服务端已就绪再部署集群
2. values内容必须用|保持多行格式
3. 国内环境建议替换repo为阿里云镜像

我曾遇到一个经典案例：客户在集群部署完才搭建NFS，导致PV无法自动创建。解决方法是在KubeKey配置中预先定义addons，或者后续手动执行：

helm install nfs-client --set nfs.server=10.0.0.100 \
  --set nfs.path=/data/nfs \
  -n kube-system

5. 网络插件选型与配置

Calico是KubeKey的默认网络插件，生产环境推荐以下配置：

network:
  plugin: calico
  kubePodsCIDR: 10.233.64.0/18  # Pod网段
  kubeServiceCIDR: 10.233.0.0/18 # Service网段
  multusCNI:
    enabled: true  # 启用多网卡支持

性能优化参数：

# 在主机上执行
echo "net.ipv4.ip_forward = 1" >> /etc/sysctl.conf
echo "net.ipv4.conf.all.rp_filter = 0" >> /etc/sysctl.conf
sysctl -p

遇到网络问题时，可以检查Calico日志：

kubectl logs -n kube-system $(kubectl get pod -n kube-system -l k8s-app=calico-node -o name) -c calico-node

6. 存储方案配置实践

生产环境存储配置需要特别注意：

storage:
  openebs:
    basePath: /data/openebs  # 本地存储路径
  ceph:
    monitors:
      - 10.0.0.101:6789
      - 10.0.0.102:6789
    pool: kube
    adminID: admin
    adminSecret: "AQD...=="

经验之谈：

• 开发环境可用OpenEBS LocalPV
• 生产环境推荐Ceph RBD或商业存储
• 提前规划StorageClass：

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: ceph-rbd
provisioner: rbd.csi.ceph.com
parameters:
  clusterID: ceph-cluster
  pool: kube
  imageFeatures: layering
  csi.storage.k8s.io/provisioner-secret-name: ceph-secret

7. 高可用控制平面配置

对于生产级集群，控制平面高可用必不可少：

controlPlaneEndpoint:
  internalLoadbalancer: haproxy  # 内置负载均衡
  domain: cluster.example.com
  address: "" 
  port: 6443

部署建议：

1. 至少3个master节点
2. 使用独立负载均衡器时，address填写VIP
3. 测试环境可以用nginx替代haproxy

检查apiserver健康状况：

curl -k https://localhost:6443/healthz

8. 镜像仓库配置技巧

国内用户必须配置镜像加速：

registry:
  registryMirrors:
    - https://registry.cn-hangzhou.aliyuncs.com
  insecureRegistries:
    - 10.0.0.100:5000  # 私有仓库

离线环境需要预先导入镜像：

./kk artifact export -m manifest.yaml -o kubesphere.tar.gz
./kk artifact import -o kubesphere.tar.gz

9. 集群部署与验证

执行部署命令前建议先做预检查：

./kk create cluster -f config-sample.yaml --skip-install

正式部署：

export KKZONE=cn  # 国内环境必须设置
./kk create cluster -f config-sample.yaml

部署完成后验证：

kubectl get nodes -o wide
kubectl get pod -A

10. 生产环境调优建议

根据负载特性调整kubelet参数：

kubernetes:
  kubeletArgs:
    - --max-pods=150
    - --kube-reserved=cpu=500m,memory=1Gi
    - --system-reserved=cpu=1000m,memory=2Gi

关键监控指标：

• etcd存储大小（超过2GB需告警）
• apiserver请求延迟
• 节点内存/磁盘压力

记得定期备份etcd：

ETCDCTL_API=3 etcdctl --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/server.crt \
  --key=/etc/kubernetes/pki/etcd/server.key \
  snapshot save snapshot.db

配置KubeKey的过程就像在精心调校一台精密仪器，每个参数都可能影响最终性能。建议首次部署时保持最小配置，稳定后再逐步添加功能组件。遇到问题多查看/var/log/messages和journalctl -u kubelet日志，往往能找到线索。