KubeKey（kk）是当前部署Kubernetes+KubeSphere最可靠、最省事的工具，自动处理Docker、内核参数、SELinux、swap、ipvs、时钟同步等前置项，支持一键部署all-in-one环境，适配单节点验证及小规模生产。
kk 是当前部署 Kubernetes + KubeSphere 最可靠、最省事的工具，比手动 kubeadm 初始化再套 ks-installer 稳定得多，尤其适合单节点验证或小规模生产环境。别折腾 kubectl apply -f 那套离线 YAML，镜像版本错一个就卡在 Pending 或 ImagePullBackOff。
用 kk 一键部署 all-in-one 环境
kk 会自动处理 Docker、内核参数、SELinux、swap、ipvs、时钟同步等前置项，只要 OS 是 CentOS 7.6+/Ubuntu 20.04+、有 root 权限、能联网（或提前下载好离线包），一条命令就能跑通。
-
下载最新版
kk（以 v3.1.1 为例）：wget https://github.com/kubesphere/kubekey/releases/download/v3.1.1/kubekey-v3.1.1-linux-amd64.tar.gz tar -zxvf kubekey-v3.1.1-linux-amd64.tar.gz chmod +x kk sudo mv kk /usr/local/bin/
-
直接创建单节点集群并集成 KubeSphere（v3.4.1 + k8s v1.28.8）：
kk create cluster --with-kubernetes v1.28.8 --with-kubesphere v3.4.1
安装完成后，访问
<a href="https://www.php.cn/link/6327377ea57c84da73765f4b2b95c5e7">https://www.php.cn/link/6327377ea57c84da73765f4b2b95c5e7</a>（注意是 HTTPS），默认账号admin，密码在终端最后输出的admin行里，类似：admin password: NxxxQxxx
kk 配置文件里必须改的几项
不写配置文件也能跑，但一旦要调资源、换存储、开 DevOps 或指定镜像仓库，就必须生成并编辑 config-sample.yaml：
kk create config --with-kubernetes v1.28.8 --with-kubesphere v3.4.1 -f config.yaml
关键修改点（只列真正影响启动的）：
-
hosts下确认role：单节点必须同时含control-plane和worker，否则 KubeSphere 组件调度失败 -
kubernetes.network.plugin默认calico，别动；若内网已有flannel，得同步改 CNI 插件路径，否则 Pod 网络不通 -
registry块：如果走私有 Harbor，必须填domain和privateRegistry，且所有节点/etc/docker/daemon.json要加该域名到insecure-registries -
storage下的defaultStorageClass：不配的话，KubeSphere 的日志、审计、DevOps 流水线都会因 PVC 无法绑定而失败
常见 Pod 卡在 ContainerCreating 的原因
这不是 KubeSphere 特有，但新手常在这里卡住半天：
-
Failed to run kubelet：大概率是swap没关干净，检查free -h输出里Swap:行是否全为0B，不是就再跑一次swapoff -a并注释/etc/fstab里的 swap 行 -
MountVolume.SetUp failed for volume "ks-installer-secret"：说明ks-installer的 Secret 没生成，通常是kk执行中途被 Ctrl+C 中断，删掉/etc/kubernetes和/var/lib/kubelet后重来 -
context deadline exceeded在etcdPod 日志里：单节点不用管 etcd 集群健康，但得确认dataDir路径磁盘空间 ≥20GB，且目录可写（chown -R root:root /var/lib/etcd） -
no such host报在openpitrix或notification-manager：说明 DNS 解析失败，检查corednsPod 是否 Running，以及node上/etc/resolv.conf是否被覆盖成错误 nameserver
访问控制台前必须确认的端口和证书
KubeSphere 不走 443 或 80，它强制用30880（NodePort），且默认启用 TLS：
- 确保防火墙放行
30880（firewall-cmd --add-port=30880/tcp --permanent && firewall-cmd --reload） - 如果用自签名证书，浏览器会提示不安全 —— 这正常，直接点「高级」→「继续前往」就行
- 若想换域名 + 正式证书，别碰
ks-console的 Ingress，应该在前置 Nginx 或 LB 层做 TLS 终止，然后把流量转到<a href="https://www.php.cn/link/bd177a0139bb56a47fe733d1957034bf">https://www.php.cn/link/bd177a0139bb56a47fe733d1957034bf</a>
真正容易被忽略的是：KubeSphere 的组件（比如 ks-controller-manager）依赖 hostNetwork: true，这意味着它会直接使用宿主机网络栈。一旦你之前装过旧版 Flannel 或修改过 /proc/sys/net/ipv4/ip_forward，哪怕只是临时设成 0，都可能导致组件反复 CrashLoopBackOff —— 查 kubectl logs -n kubesphere-system ks-controller-manager-xxx，第一眼就看有没有 failed to get node IP。
