KubeKey 环境准备与安装 k8s

本篇覆盖 KubeKey 部署前每台机器的系统初始化，以及在线安装 k8s 的两种方式。容器运行时（docker/containerd）由 KubeKey 自动安装，节点无需手工预装。

一、初始化机器环境（每台机器）

容器运行时无需手工安装，KubeKey 会自动处理。如需了解运行时配置可参考《节点安装 Containerd 容器运行时》。

修改主机名

主机名不要有大写，保持小写：

hostnamectl set-hostname [新主机名]

修改后重新进入终端，主机名才会生效。

初始化安装基础组件

# 安装时间同步，启动 chronyd 服务
# yum -y install chrony    # CentOS
apt install -y chrony      # Ubuntu

systemctl start chronyd
systemctl enable chronyd

# 手动同步一下
timedatectl set-ntp true
chronyc -a makestep
date

# ubuntu 安装基础依赖
apt install -y socat conntrack ebtables ipset ipvsadm
# centos 安装基础依赖
yum install -y socat conntrack ebtables ipset ipvsadm tar

# 关闭 firewalld 服务
systemctl stop firewalld
systemctl disable firewalld
# 禁用 iptables
systemctl stop iptables
systemctl disable iptables
# 禁用 selinux
echo "SELINUX=disabled" > /etc/selinux/config

# 临时关闭 swap 分区
swapoff -a
# 永久关闭 swap 分区：编辑 /etc/fstab 注释掉 swap 一行（修改后需重启）
vim /etc/fstab
# 注释掉 /dev/mapper/centos-swap swap

# 检查：如果 swap 全部是 0，则代表配置完成
free -m

二、下载 KubeKey

机器最低规格：16C32G；之前安装过 KubeSphere(KS) 要提前清理环境。下载不成功可多执行几次。

# 在线安装
export KKZONE=cn
curl -sfL https://get-kk.kubesphere.io | VERSION=v3.1.10 sh -
chmod +x kk
cp kk /usr/bin/

# 离线安装（提前下好二进制）
# arm64 版本
# wget https://cube-studio.oss-cn-hangzhou.aliyuncs.com/install/kubekey-v3.1.10-linux-arm64 -O /usr/bin/kk
# amd64 版本
# wget https://cube-studio.oss-cn-hangzhou.aliyuncs.com/install/kubekey-v3.1.10-linux-amd64 -O /usr/bin/kk
# chmod +x /usr/bin/kk

清理已有 kubeconfig，否则会导致其他 node 节点无法使用 kubectl：

rm -rf /root/.kube/config

三、在线安装 k8s

KubeKey 安装 k8s 时会自动安装 containerd/docker、kubeadm、kubelet、kubectl、CNI、helm 等。自定义部署最好不要启用 servicemesh 和 monitoring。

方式 A：命令行直接建集群（单机快速，k8s v1.28.15）

# 使用 docker 作为运行时
export KKZONE=cn
./kk create cluster -y --with-kubernetes v1.28.15 --container-manager docker

# 使用 containerd 作为运行时
export KKZONE=cn
./kk create cluster -y --with-kubernetes v1.28.15 --container-manager containerd

方式 B：配置文件方式（多机，k8s v1.25.16）

适合多节点。name 写内网 IP，KubeKey 会用配置里的账号密码登录远程机器执行安装命令（需提前配好免密或填密码）。

# 生成配置文件
kk create config --with-kubernetes v1.25.16

编辑 config-cluster.yaml（示例，name 写内网 IP 地址）：

spec:
  hosts:
  - {name: 172.16.0.2, address: 172.16.0.2, internalAddress: 172.16.0.2, user: ubuntu, password: "Qcloud@123"}
  - {name: 172.16.0.3, address: 172.16.0.3, internalAddress: 172.16.0.3, user: ubuntu, password: "Qcloud@123"}
  roleGroups:
    etcd:
    - 172.16.0.2
    control-plane:
    - 172.16.0.2
    worker:
    - 172.16.0.2
    - 172.16.0.3

创建集群：

export KKZONE=cn
kk create cluster -f config-cluster.yaml
# 会自动安装 containerd、kubectl、kubeadm、kubecni、helm 等

仓库内置示例配置 install/kubernetes/rancher/kubekey/config-cluster.yaml：k8s 版本 v1.25.16、containerManager: docker、controlPlaneEndpoint.domain: lb.kubesphere.local、registryMirrors 预置了多个国内镜像加速地址。多机/高可用部署可在此基础上改。

四、常见报错

sftp packet too long

报错 new sftp client failed: packet too long，修复方式：

vim /etc/ssh/sshd_config
# 注释掉 Subsystem 开头的行，并新增一行使用内部 sftp：
#   Subsystem sftp internal-sftp
# 重启 sshd 服务
systemctl restart sshd

装好 k8s 后，进入《在 k8s 上部署 CubeStudio》。离线场景见《离线部署》。