KubeKey 安装和配置指南

概述

KubeKey 是一个开源轻量级工具，用于快速部署 Kubernetes 集群。它提供了灵活、快速且便捷的方式来安装 Kubernetes/K3s、KubeSphere 以及相关的云原生附加组件。本文将为您提供完整的 KubeKey 安装和配置指南，涵盖从环境准备到高级配置的各个方面。

环境要求

系统要求

组件	最低要求	推荐配置
CPU	2 vCPUs	4+ vCPUs
内存	4 GB RAM	8+ GB RAM
存储	20 GB	50+ GB

支持的 Linux 发行版

mindmap
  root(KubeKey 支持的系统)
    Ubuntu
      16.04
      18.04
      20.04
      22.04
    Debian
      Bookworm
      Bullseye
      Buster
      Stretch
    CentOS/RHEL
      7.x
    AlmaLinux
      9.0
    SUSE Linux Enterprise Server
      15.x

网络要求

确保以下端口在防火墙中开放：

服务	协议	端口范围	说明
SSH	TCP	22	远程连接
etcd	TCP	2379-2380	分布式存储
API Server	TCP	6443	Kubernetes API
NodePort	TCP	30000-32767	服务暴露
kubelet	TCP	10250-10258	节点通信
DNS	TCP/UDP	53	域名解析

安装 KubeKey

快速安装方式

# 使用官方脚本安装
curl -sfL https://get-kk.kubesphere.io | sh -

# 或者手动下载二进制文件
wget https://github.com/kubesphere/kubekey/releases/download/v3.0.7/kubekey-v3.0.7-linux-amd64.tar.gz
tar -zxvf kubekey-v3.0.7-linux-amd64.tar.gz
mv kk /usr/local/bin/

从源码编译

git clone https://gitcode.com/gh_mirrors/ku/kubekey
cd kubekey
make kk

集群配置详解

基础配置示例

apiVersion: kubekey.kubesphere.io/v1alpha2
kind: Cluster
metadata:
  name: production-cluster
spec:
  hosts:
  - {name: master1, address: 192.168.1.10, internalAddress: 192.168.1.10, user: root, password: "SecurePass123!"}
  - {name: worker1, address: 192.168.1.11, internalAddress: 192.168.1.11, user: root, password: "SecurePass123!"}
  - {name: worker2, address: 192.168.1.12, internalAddress: 192.168.1.12, user: root, password: "SecurePass123!"}
  
  roleGroups:
    etcd:
    - master1
    master:
    - master1
    worker:
    - worker1
    - worker2

  kubernetes:
    version: v1.24.7
    containerManager: containerd
    clusterName: cluster.local

网络配置

network:
  plugin: calico
  calico:
    ipipMode: Always
    vxlanMode: Never
    vethMTU: 0
  kubePodsCIDR: 10.233.64.0/18
  kubeServiceCIDR: 10.233.0.0/18

存储配置

storage:
  openebs:
    basePath: /var/openebs/local
  # 或者使用外部存储
  # externalStorage:
  #   enabled: true
  #   type: nfs
  #   server: 192.168.1.100
  #   path: /data/nfs

部署集群

快速部署（All-in-One）

# 部署纯 Kubernetes 集群
./kk create cluster

# 部署 Kubernetes + KubeSphere
./kk create cluster --with-kubesphere v3.3.1

# 指定容器运行时
./kk create cluster --container-manager containerd

高级部署（配置文件方式）

# 生成配置文件
./kk create config -f cluster-config.yaml

# 编辑配置文件
vim cluster-config.yaml

# 使用配置文件部署集群
./kk create cluster -f cluster-config.yaml

部署流程

sequenceDiagram
    participant User
    participant KubeKey
    participant Nodes
    
    User->>KubeKey: 执行部署命令
    KubeKey->>Nodes: SSH 连接验证
    KubeKey->>Nodes: 系统环境检查
    KubeKey->>Nodes: 安装依赖包
    KubeKey->>Nodes: 部署容器运行时
    KubeKey->>Nodes: 部署 Kubernetes 组件
    KubeKey->>Nodes: 配置网络插件
    KubeKey->>Nodes: 部署存储组件
    KubeKey->>User: 部署完成，输出 kubeconfig

高级配置选项

容器镜像仓库配置

registry:
  registryMirrors:
    - "https://dockerhub.kubesphere.local"
  insecureRegistries:
    - "192.168.1.200:5000"
  privateRegistry: "dockerhub.kubesphere.local"
  auths:
    "dockerhub.kubesphere.local":
      username: "admin"
      password: "password123"

系统调优配置

system:
  ntpServers:
    - time1.aliyun.com
    - time2.aliyun.com
  timezone: "Asia/Shanghai"
  rpms:
    - nfs-utils
    - telnet
  debs:
    - nfs-common
    - curl

Kubernetes 高级配置

kubernetes:
  kubeletArgs:
    - --root-dir=/var/lib/kubelet
    - --max-pods=250
  featureGates:
    CSIStorageCapacity: true
    ExpandCSIVolumes: true
    RotateKubeletServerCertificate: true
  kubeProxyConfiguration:
    ipvs:
      excludeCIDRs:
        - 192.168.1.0/24

集群管理操作

节点管理

# 添加节点
./kk add nodes -f cluster-config.yaml

# 删除节点
./kk delete node worker3 -f cluster-config.yaml

# 查看节点状态
kubectl get nodes

集群升级

# 升级 Kubernetes 版本
./kk upgrade --with-kubernetes v1.25.3 -f cluster-config.yaml

# 升级 KubeSphere 版本
./kk upgrade --with-kubesphere v3.3.2 -f cluster-config.yaml

集群删除

# 删除集群
./kk delete cluster -f cluster-config.yaml

# 强制删除（忽略错误）
./kk delete cluster -f cluster-config.yaml --ignore-err

故障排除和最佳实践

常见问题解决

问题	解决方案
SSH 连接失败	检查防火墙设置和 SSH 密钥配置
镜像拉取失败	配置镜像仓库或离线仓库
端口冲突	检查端口占用情况，调整服务端口
资源不足	增加节点资源或调整 Pod 资源限制

性能优化建议

1. 网络优化：使用高性能网络插件如 Cilium
2. 存储优化：使用 SSD 存储并配置合适的 IO 调度器
3. 内核参数调优：调整 net.core.somaxconn 等参数
4. 容器运行时优化：根据负载特性选择合适的容器运行时

监控和日志

# 部署监控组件
kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml

# 查看集群状态
kubectl get all --all-namespaces
kubectl top nodes
kubectl top pods

安全配置

证书管理

kubernetes:
  autoRenewCerts: true
  apiserverCertExtraSans:
    - 192.168.1.100
    - k8s-api.example.com

网络安全策略

network:
  # 启用网络策略
  networkPolicy: true
  # 配置 Pod 安全策略
  podSecurity:
    enabled: true
    defaultPolicy: restricted

总结

KubeKey 提供了一个强大而灵活的工具来部署和管理 Kubernetes 集群。通过本文的指南，您应该能够：

1. ✅ 理解 KubeKey 的基本概念和架构
2. ✅ 准备符合要求的部署环境
3. ✅ 创建适合您需求的集群配置
4. ✅ 成功部署和管理 Kubernetes 集群
5. ✅ 配置高级功能和进行故障排除

记住，在生产环境中部署前，务必在测试环境中充分验证配置。定期备份集群配置和状态，并建立完善的监控和告警机制。

---

提示：本文基于 KubeKey v3.0.7 编写，具体功能可能随版本更新而变化。建议查阅官方文档获取最新信息。