🔧 kubeadm 参数全解

关于本文档

kubeadm 所有核心命令的参数手册。本文档是使用 kubeadm 创建集群 的配套参考。

#k8s #kubeadm #reference

📋 目录

1. #kubeadm init — 初始化控制平面
2. #kubeadm join — 加入节点
3. #kubeadm token — 令牌管理
4. #kubeadm certs — 证书管理
5. #kubeadm config — 配置管理
6. #kubeadm reset — 重置集群
7. #kubeadm upgrade — 升级集群
8. #kubeadm alpha — Alpha 功能
9. #kubeadm 配置文件 YAML — YAML 配置方式
10. #kubeadm 常用参数速查表

kubeadm init

初始化 Kubernetes 控制平面节点。

kubeadm init [flags]

核心参数

实战示例

## 📖 最简方式
sudo kubeadm init

## ⚡ 单控制平面（完整参数）
sudo kubeadm init \
  --apiserver-advertise-address=192.168.1.100 \
  --apiserver-cert-extra-sans="k8s.example.com,10.0.0.1" \
  --pod-network-cidr=10.244.0.0/16 \
  --service-cidr=10.96.0.0/12 \
  --kubernetes-version=v1.36.0 \
  --node-name=master-1 \
  --v=5

## 🔧 高可用控制平面首节点
sudo kubeadm init \
  --control-plane-endpoint=192.168.1.20:6443 \
  --apiserver-advertise-address=192.168.1.101 \
  --pod-network-cidr=10.244.0.0/16 \
  --upload-certs

## ⚙️ 离线部署（指定私有镜像仓库）
sudo kubeadm init \
  --image-repository=registry.internal.company.com/k8s \
  --kubernetes-version=v1.36.0 \
  --pod-network-cidr=10.244.0.0/16

## 5. 忽略预检错误（踩坑时用）
sudo kubeadm init \
  --ignore-preflight-errors=Swap,NumCPU,FileAvailable--etc-kubernetes-manifests-etcd.yaml \
  --pod-network-cidr=10.244.0.0/16

## 6. 试运行验证配置
sudo kubeadm init --config=kubeadm-config.yaml --dry-run

参数组合速记

面试口诀

单控制平面记 3 个：--apiserver-advertise-address + --pod-network-cidr + --kubernetes-version

高可用多加 2 个：--control-plane-endpoint + --upload-certs

排错用 3 个：--v=5 + --ignore-preflight-errors + --dry-run

kubeadm join

将节点加入已有集群。

kubeadm join [endpoint:port] [flags]

核心参数

实战示例

## 📖 Worker 节点加入（最常用）
sudo kubeadm join 192.168.1.100:6443 \
  --token <token> \
  --discovery-token-ca-cert-hash sha256:<hash>

## ⚡ 控制平面节点加入（HA）
sudo kubeadm join 192.168.1.20:6443 \
  --token <token> \
  --discovery-token-ca-cert-hash sha256:<hash> \
  --control-plane \
  --certificate-key <key>

## 🔧 指定节点名加入
sudo kubeadm join 192.168.1.100:6443 \
  --token <token> \
  --discovery-token-ca-cert-hash sha256:<hash> \
  --node-name=worker-production-01

## ⚙️ 跳过证书验证（仅开发环境！）
sudo kubeadm join 192.168.1.100:6443 \
  --token <token> \
  --discovery-token-unsafe-skip-ca-verification

## 5. 使用配置文件加入
sudo kubeadm join --config=join-config.yaml

## 6. 忽略预检错误
sudo kubeadm join 192.168.1.100:6443 \
  --token <token> \
  --discovery-token-ca-cert-hash sha256:<hash> \
  --ignore-preflight-errors=Swap

安全警告

--discovery-token-unsafe-skip-ca-verification 严禁在生产环境使用！ 跳过 CA 验证意味着无法确认连接的是否是真正的集群，可能被中间人攻击。

kubeadm token

管理 bootstrap token。

kubeadm token [subcommand] [flags]

子命令

create 参数

kubeadm token create [flags]

实战示例

## 📖 创建 token 并直接打印 join 命令（最常用）
kubeadm token create --print-join-command

## ⚡ 创建永不过期的 token（生产不推荐）
kubeadm token create --ttl=0

## 🔧 创建 2 小时有效期的 token（适合临时使用）
kubeadm token create --ttl=2h --description="临时扩容"

## ⚙️ 列出所有 token
kubeadm token list

## 5. 删除指定 token
kubeadm token delete <token-id>

## 6. 只生成 token 但不保存到集群
kubeadm token generate

实用技巧

最常用的就是 kubeadm token create --print-join-command，一步搞定！ 这个命令会自动生成 token 并拼好完整的 kubeadm join 命令，直接复制粘贴即可。

kubeadm certs

管理集群证书。

kubeadm certs [subcommand] [flags]

子命令

renew 子参数

kubeadm certs renew [subcommand] [flags]

实战示例

## 📖 查看所有证书到期时间（日常巡检）
kubeadm certs check-expiration

## 输出示例：
## [CERTIFICATE]                EXPIRES                  RESIDUAL TIME   CERTIFICATE AUTHORITY
## admin.conf                   May 30, 2027 00:00 UTC   364d            ca
## apiserver                    May 30, 2027 00:00 UTC   364d            ca
## ...

## ⚡ 续期所有证书
kubeadm certs renew all

## 🔧 只续期 API Server 证书
kubeadm certs renew apiserver

## ⚙️ 续期后需要重启控制平面组件
## 修改 Static Pod Manifest 的 annotation 触发滚动更新
## 或直接重启 kubelet
sudo systemctl restart kubelet

## 5. 生成 HA 用的 certificate-key
kubeadm certs certificate-key

## ⚙️  kubectl（续期后需要）
## 如果 admin.conf 更新了，需要重新复制
sudo cp /etc/kubernetes/admin.conf $HOME/.kube/config

重要

kubeadm certs renew all 只续期证书，不会重启组件！

续期后需要：

1. 重启 kubelet：sudo systemctl restart kubelet
2. 或者修改 Static Pod Manifest（加个 annotation 触发重建）
3. 更新用户的 kubeconfig：重新 cp admin.conf ~/.kube/config

kubeadm config

查看和管理 kubeadm 配置。

kubeadm config [subcommand] [flags]

子命令

images 子命令

kubeadm config images [subcommand] [flags]

实战示例

## 📖 查看当前集群的 kubeadm 配置
kubeadm config view

## ⚡ 打印 kubeadm init 的默认配置模板
kubeadm config print init-defaults

## 🔧 打印 kubeadm join 的默认配置模板
kubeadm config print join-defaults

## ⚙️ 列出指定版本所需的镜像
kubeadm config images list --kubernetes-version=v1.36.0

## 5. 拉取 kubeadm 所需镜像（离线部署准备）
kubeadm config images pull --kubernetes-version=v1.36.0

## 6. 使用自定义仓库拉取镜像
kubeadm config images pull \
  --image-repository=registry.internal.company.com/k8s \
  --kubernetes-version=v1.36.0

## 7. 将旧版配置迁移到新版
kubeadm config migrate --old-config old.yaml --new-config new.yaml

离线部署批量拉取镜像

# 先拉取全部镜像
kubeadm config images pull --kubernetes-version=v1.36.0

# 然后导出并传到离线环境
docker save -o k8s-images.tar $(kubeadm config images list --kubernetes-version=v1.36.0 | tr '\n' ' ')

kubeadm reset

重置节点，清除所有 kubeadm 安装的数据。

kubeadm reset [flags]

实战示例

## 📖 标准重置
sudo kubeadm reset

## ⚡ 强制重置（不提示确认）
sudo kubeadm reset --force

## 🔧 重置后清理 kubeconfig
rm -rf $HOME/.kube

## ⚙️ 完整重置脚本
sudo kubeadm reset --force
sudo rm -rf /etc/kubernetes/
sudo rm -rf /var/lib/etcd/
sudo rm -rf $HOME/.kube/
sudo iptables -F && sudo iptables -t nat -F && sudo iptables -t mangle -F
sudo systemctl restart containerd

注意

kubeadm reset 不会自动清理 kubelet 配置、容器运行时数据、iptables 规则等。

尤其在控制平面节点上，etcd 数据目录 /var/lib/etcd/ 需要手动删除，否则重新 init 时会报错。

kubeadm upgrade

升级 Kubernetes 集群版本。

kubeadm upgrade [subcommand] [flags]

子命令

参数

HA 集群升级流程

## ----- 重要：HA 集群必须逐个节点升级！-----

## Step 1：在每个节点上依次执行

## 先 drain 节点（迁移 Pod）
kubectl drain master-1 --ignore-daemonsets --delete-emptydir-data

## 升级 kubeadm
sudo apt-mark unhold kubeadm
sudo apt-get update && sudo apt-get install -y kubeadm=1.36.0-1.1
sudo apt-mark hold kubeadm

## 查看升级计划
sudo kubeadm upgrade plan

## 执行升级
sudo kubeadm upgrade apply v1.36.0

## 升级 kubelet 和 kubectl
sudo apt-mark unhold kubelet kubectl
sudo apt-get update && sudo apt-get install -y kubelet=1.36.0-1.1 kubectl=1.36.0-1.1
sudo apt-mark hold kubelet kubectl
sudo systemctl daemon-reload && sudo systemctl restart kubelet

## 恢复节点调度
kubectl uncordon master-1

## 然后到下一个控制平面节点重复以上步骤

kubeadm alpha

提供 Alpha 级别的功能，可能在未来版本中变更或移除。

kubeadm alpha [subcommand] [flags]

实用示例

## 生成一个指定用户名的 kubeconfig
kubeadm alpha kubeconfig user --client-name=deploy-bot

注意

kubeadm 1.36 中大部分 alpha 功能已迁移到正式子命令（如 certs）。 不再建议使用 alpha 子命令，直接使用对应的正式子命令即可。

kubeadm 配置文件 YAML

面试重点：为什么要用配置文件而不是命令行参数？

1. 可重复 — 配置文件可以版本化管理（Git）
2. 可审计 — 清晰记录集群的初始化配置
3. 完整 — 命令行参数有限，配置文件的选项更全面
4. 可迁移 — 配置文件可用于 init、join、upgrade

kubeadm init 配置示例

## kubeadm-config.yaml
apiVersion: kubeadm.k8s.io/v1beta4
kind: InitConfiguration
bootstrapTokens:
  - token: "abcdef.0123456789abcdef"
    description: "kubeadm bootstrap token"
    ttl: "24h"
nodeRegistration:
  name: "master-1"
  criSocket: "unix:///run/containerd/containerd.sock"
  kubeletExtraArgs:
    node-ip: "192.168.1.100"
localAPIEndpoint:
  advertiseAddress: "192.168.1.100"
  bindPort: 6443
---
apiVersion: kubeadm.k8s.io/v1beta4
kind: ClusterConfiguration
kubernetesVersion: "v1.36.0"
controlPlaneEndpoint: "192.168.1.20:6443"   # HA 专用
networking:
  podSubnet: "10.244.0.0/16"
  serviceSubnet: "10.96.0.0/12"
  dnsDomain: "cluster.local"
apiServer:
  certSANs:
    - "k8s.example.com"
    - "10.0.0.1"
  extraArgs:
    authorization-mode: "Node,RBAC"
controllerManager:
  extraArgs:
    bind-address: "0.0.0.0"
scheduler:
  extraArgs:
    bind-address: "0.0.0.0"
imageRepository: "registry.k8s.io"
---
apiVersion: kubelet.config.k8s.io/v1beta1
kind: KubeletConfiguration
cgroupDriver: "systemd"
maxPods: 110

## 使用配置文件初始化
sudo kubeadm init --config=kubeadm-config.yaml --upload-certs

kubeadm join 配置示例

## kubeadm-join-config.yaml
apiVersion: kubeadm.k8s.io/v1beta4
kind: JoinConfiguration
nodeRegistration:
  name: "worker-1"
  criSocket: "unix:///run/containerd/containerd.sock"
  kubeletExtraArgs:
    node-ip: "192.168.1.201"
discovery:
  bootstrapToken:
    token: "abcdef.0123456789abcdef"
    apiServerEndpoint: "192.168.1.20:6443"
    caCertHashes:
      - "sha256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  tlsBootstrapToken: "abcdef.0123456789abcdef"
---
## 如果是控制平面节点加入，追加以下部分
apiVersion: kubeadm.k8s.io/v1beta4
kind: InitConfiguration
localAPIEndpoint:
  advertiseAddress: "192.168.1.102"
  bindPort: 6443
nodeRegistration:
  name: "master-2"

## 使用配置文件加入
sudo kubeadm join --config=kubeadm-join-config.yaml

配置文件对比：命令行 vs YAML

如何从现有集群导出配置？

# 查看当前集群的 InitConfiguration
kubectl -n kube-system get configmap kubeadm-config -o yaml

# 或使用 kubeadm 命令
kubeadm config view

kubeadm 常用参数速查表

按场景分类

flowchart TD
    subgraph "场景与参数速查"
        A1[单控制平面] --> B1["--pod-network-cidr<br/>--apiserver-advertise-address"]
        A2[高可用 HA] --> B2["--control-plane-endpoint<br/>--upload-certs<br/>--certificate-key"]
        A3[离线部署] --> B3["--image-repository<br/>kubeadm config images pull"]
        A4[问题排查] --> B4["--v=5<br/>--ignore-preflight-errors<br/>--dry-run"]
        A5[版本升级] --> B5["kubeadm upgrade plan<br/>kubeadm upgrade apply"]
        A6[证书管理] --> B6["kubeadm certs check-expiration<br/>kubeadm certs renew all"]
        A7[节点加入] --> B7["--token<br/>--discovery-token-ca-cert-hash"]
    end

全部命令一览

关联文档

• 完整集群搭建流程 →使用 kubeadm 创建集群
• K8s 核心概念 → ../core/K8s 核心概念

• ../../network/网络 — 集群网络配置（CNI/flannel/Calico）
• ../../network/tools/firewalld 与 iptables 对比 — 节点防火墙配置
• ../service/K8s Service DNS 实现原理 — CoreDNS 域名解析