Linux 知识库

Appearance

kubeadm-管理工具 ​

基础语法 ​

命令简介 ​

kubeadm 是 Kubernetes 官方提供的集群引导工具，用于快速搭建符合最佳实践的生产级 Kubernetes 集群。它自动化了证书生成、控制平面组件部署、etcd 配置等复杂流程，支持集群初始化、节点加入、升级和降级等全生命周期操作。

语法格式 ​

bash
kubeadm <command> [flags]

主要子命令 ​

命令描述示例
init初始化控制平面节点kubeadm init --apiserver-advertise-address=192.168.1.100
join将节点加入集群kubeadm join 192.168.1.100:6443 --token <token>
upgrade升级集群版本kubeadm upgrade apply v1.28.0
reset重置节点状态kubeadm reset --force
token管理引导令牌kubeadm token create --ttl 2h
config管理集群配置kubeadm config print init-defaults

kubeadm init - 初始化 Kubernetes 控制平面节点 ​

命令简介 ​

kubeadm init 是 Kubernetes 集群初始化的核心命令，负责在第一个控制平面节点上部署所有必要的控制组件（API Server、Controller Manager、Scheduler、etcd 等），生成集群 CA 证书和引导令牌，并输出加入其他节点所需的命令。

语法格式 ​

kubeadm init [flags]

核心选项 ​

选项描述示例
--apiserver-advertise-addressAPI Server 通告地址--apiserver-advertise-address=192.168.1.100
--pod-network-cidr指定 Pod 网络 CIDR（需与 CNI 插件匹配）--pod-network-cidr=10.244.0.0/16（Flannel 默认）
--control-plane-endpoint高可用集群负载均衡地址--control-plane-endpoint=k8s-api.example.com:6443
--upload-certs自动上传控制平面证书（高可用场景）--upload-certs
--kubernetes-version指定 Kubernetes 版本--kubernetes-version=v1.28.0
--cri-socket指定容器运行时套接字路径--cri-socket=unix:///var/run/containerd/containerd.sock
--dry-run试运行模式--dry-run=client
--ignore-preflight-errors忽略特定预检错误--ignore-preflight-errors=Swap

经典案例 ​

bash
# 单节点集群初始化（使用 containerd 运行时）
kubeadm init \
  --apiserver-advertise-address=192.168.1.100 \
  --pod-network-cidr=10.244.0.0/16 \
  --cri-socket=unix:///var/run/containerd/containerd.sock \
  --kubernetes-version=v1.28.0

# 高可用集群初始化（3个控制平面节点）
kubeadm init \
  --control-plane-endpoint=k8s-api.example.com:6443 \
  --upload-certs \
  --pod-network-cidr=192.168.0.0/16

# 生产环境推荐配置（带证书自动续期）
kubeadm init \
  --apiserver-advertise-address=10.0.0.1 \
  --service-cidr=10.96.0.0/12 \
  --pod-network-cidr=10.244.0.0/16 \
  --feature-gates=RotateKubeletServerCertificate=true \
  --certificate-renewal=true

初始化后操作 ​

bash
# 配置 kubectl（普通用户）
mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config

# 安装网络插件（示例使用 Calico）
kubectl apply -f https://raw.githubusercontent.com/projectcalico/calico/v3.26.1/manifests/calico.yaml

# 获取加入命令（工作节点）
kubeadm token create --print-join-command

注意事项 ​

  1. 系统要求：
    • 2GB+ 内存
    • 禁用 swap（或通过 --ignore-preflight-errors=Swap 忽略）
    • 唯一的主机名、MAC 地址和 product_uuid
  2. 网络冲突：
    • --pod-network-cidr 不能与主机网络重叠
    • --service-cidr 默认 10.96.0.0/12 需确保不冲突
  3. 证书管理：
    • 默认证书有效期 1 年
    • 通过 kubeadm certs check-expiration 检查
    • 生产环境建议启用 RotateKubeletServerCertificate 特性
  4. 重置风险：
    • kubeadm reset 会彻底清除节点状态
    • 重置前需手动清理 /etc/cni/net.d 和 /var/lib/cni/
  5. 版本兼容：
    • kubeadm 与 kubelet 版本差不得超过 ±1 个小版本
    • 使用 --kubernetes-version 确保版本一致性

kubeadm join - 将节点加入 Kubernetes 集群 ​

命令简介 ​

kubeadm join 是将工作节点或额外控制平面节点加入现有 Kubernetes 集群的关键命令。它通过引导令牌（bootstrap token）或发现令牌（discovery token）完成节点认证，自动配置 kubelet 并建立与 API Server 的安全连接。

语法格式 ​

bash
kubeadm join <control-plane-host>:<control-plane-port> --token <token> \
  --discovery-token-ca-cert-hash sha256:<hash> [flags]

核心选项 ​

选项描述示例
--token引导令牌（24小时有效）--token abcdef.0123456789abcdef
--discovery-token-ca-cert-hashCA证书的SHA256哈希--discovery-token-ca-cert-hash sha256:xxxxxx
--control-plane加入为控制平面节点--control-plane
--certificate-key解密控制平面证书的密钥--certificate-key xxxxxx
--node-name指定节点名称--node-name worker-01
--ignore-preflight-errors忽略预检错误--ignore-preflight-errors=NumCPU
--cri-socket指定容器运行时路径--cri-socket=unix:///var/run/containerd/containerd.sock

经典案例 ​

bash
# 加入工作节点（标准方式）
kubeadm join 192.168.1.100:6443 \
  --token abcdef.0123456789abcdef \
  --discovery-token-ca-cert-hash sha256:xxxxxx

# 加入控制平面节点（高可用集群）
kubeadm join k8s-api.example.com:6443 \
  --token abcdef.0123456789abcdef \
  --discovery-token-ca-cert-hash sha256:xxxxxx \
  --control-plane \
  --certificate-key xxxxxx

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

# 生成长期有效的加入命令（需先安装kubeadm）
kubeadm token create --ttl 0 --print-join-command

令牌管理 ​

bash
# 查看现有令牌
kubectl get secrets -n kube-system | grep bootstrap-token

# 创建新令牌（默认24小时有效）
kubeadm token create --ttl 2h

# 获取CA证书哈希（当忘记保存时）
openssl x509 -pubkey -in /etc/kubernetes/pki/ca.crt | \
  openssl rsa -pubin -outform der 2>/dev/null | \
  openssl dgst -sha256 -hex | sed 's/^.* //'

注意事项 ​

  1. 令牌有效期：

    • 默认令牌24小时后失效
    • 可通过 kubeadm token create --ttl 0 创建永久令牌

  2. 网络要求：

    • 节点必须能访问API Server的6443端口
    • 控制平面节点间需开放2379/2380（etcd）、10250（kubelet）等端口

  3. 证书同步：

    • 控制平面节点会自动同步证书
    • 工作节点仅需kubelet证书

  4. 常见错误处理：

    bash
    # 重置错误状态
kubeadm reset
systemctl restart kubelet

  5. 生产建议：

    • 使用 --control-plane-endpoint 而非直接IP

    • 为不同角色节点打标签：

      bash
      kubectl label node worker-01 node-role.kubernetes.io/worker=

提示：加入节点后需等待若干分钟，kubectl get nodes 才会显示 READY 状态，期间可通过 journalctl -xu kubelet 查看进度。

kubeadm upgrade - Kubernetes 集群升级工具 ​

命令简介 ​

kubeadm upgrade 是 Kubernetes 官方提供的集群升级工具，用于安全地将集群从一个版本升级到另一个版本。它采用分阶段升级策略，确保控制平面组件（API Server、Controller Manager、Scheduler、etcd）和工作节点可以逐步升级，最小化对工作负载的影响。

升级流程 ​

  1. 升级控制平面：先升级第一个控制平面节点，再升级其他控制平面节点
  2. 升级工作节点：逐个升级工作节点（可并行）
  3. 升级插件：最后升级 CoreDNS 和 kube-proxy

核心子命令 ​

命令描述示例
plan检查可升级版本和前置条件kubeadm upgrade plan
apply执行控制平面升级kubeadm upgrade apply v1.28.0
node升级工作节点kubeadm upgrade node
diff显示升级前后的配置差异kubeadm upgrade diff v1.28.0

关键选项 ​

选项描述示例
--config使用配置文件升级--config=kubeadm-config.yaml
--etcd-upgrade自动升级 etcd--etcd-upgrade=true
--certificate-renewal自动续期证书--certificate-renewal=true
--allow-experimental-upgrades允许升级到测试版--allow-experimental-upgrades
--force强制跳过版本验证--force
--dry-run试运行模式--dry-run=client

经典案例 ​

bash
# 1. 检查可升级版本（在所有控制平面节点执行）
kubeadm upgrade plan

# 2. 升级第一个控制平面节点
kubeadm upgrade apply v1.28.0 \
  --etcd-upgrade=true \
  --certificate-renewal=true

# 3. 升级其他控制平面节点（依次执行）
kubeadm upgrade node

# 4. 升级工作节点（逐个执行）
kubeadm upgrade node \
  --kubelet-version=v1.28.0

# 5. 验证升级结果
kubectl get nodes -o wide

升级前准备 ​

bash
# 备份关键数据
mkdir k8s-backup
cp -i /etc/kubernetes/admin.conf k8s-backup/
cp -R /etc/kubernetes/manifests/ k8s-backup/
cp -R /etc/kubernetes/pki/ k8s-backup/

# 检查版本兼容性
kubeadm version
kubectl version
kubelet --version

# 排空节点（优雅驱逐Pod）
kubectl drain <node> --ignore-daemonsets --delete-emptydir-data

升级后操作 ​

bash
# 解除节点保护
kubectl uncordon <node>

# 验证组件版本
kubectl get pods -n kube-system -o wide

# 升级网络插件（如需要）
kubectl apply -f https://docs.projectcalico.org/manifests/calico.yaml

注意事项 ​

  1. 版本跳跃限制：

    • 仅支持升级到下一个次要版本（如 1.26 → 1.27）
    • 大版本升级需逐步进行（1.25 → 1.26 → 1.27）

  2. 证书管理：

    • 升级默认会续期即将过期的证书
    • 通过 kubeadm certs check-expiration 检查有效期

  3. 工作负载影响：

    • 控制平面升级期间API Server会有短暂不可用
    • 建议在维护窗口期执行升级

  4. 回滚方案：

    bash
    # 从备份恢复（极端情况）
cp -R k8s-backup/pki/ /etc/kubernetes/
systemctl restart kubelet

  5. 特殊场景：

    • 使用外部 etcd 时需手动升级 etcd 集群

    • 离线环境需预先下载镜像：

      bash
      kubeadm config images pull --kubernetes-version=v1.28.0

最佳实践：生产环境建议先在测试集群验证升级过程，使用 --dry-run 检查潜在问题，并通过 Prometheus 监控升级过程中的关键指标。

kubeadm reset - Kubernetes 节点重置工具 ​

命令简介 ​

kubeadm reset 是用于将节点恢复为未加入集群状态的清理工具，它会删除所有由 kubeadm init 或 kubeadm join 创建的 Kubernetes 组件和配置，但不会移除容器运行时管理的容器或用户数据。

语法格式 ​

bash
kubeadm reset [flags]

核心选项 ​

选项描述示例
--force跳过交互式确认kubeadm reset --force
--ignore-preflight-errors忽略特定预检错误--ignore-preflight-errors=all
--cri-socket指定容器运行时套接字路径--cri-socket=unix:///var/run/containerd/containerd.sock
--cleanup-tmp-dir清理临时目录--cleanup-tmp-dir=true
--cert-dir指定证书目录--cert-dir=/etc/kubernetes/pki
--dry-run试运行模式--dry-run=client

执行流程 ​

  1. 停止 kubelet 服务

删除 Kubernetes 管理组件

：

  • 移除 /etc/kubernetes/ 下的配置文件
  • 清理 /var/lib/kubelet/ 数据
  • 删除 /var/lib/etcd/（控制平面节点）

清理 CNI 网络配置

（需手动）：

bash
rm -rf /etc/cni/net.d/*

保留内容

：

  • 容器运行时管理的容器（需手动清理）
  • 用户创建的证书和密钥（非默认路径）

经典案例 ​

bash
# 安全重置节点（交互式）
kubeadm reset

# 强制重置（非交互式）
kubeadm reset --force

# 彻底清理容器运行时
containerd rm -f $(containerd ps -aq)
docker rm -f $(docker ps -aq)

# 完整清理流程（生产环境推荐）
systemctl stop kubelet
kubeadm reset --force
rm -rf /etc/cni/net.d/ /var/lib/kubelet/
iptables -F && iptables -t nat -F
ipvsadm --clear
systemctl restart containerd

注意事项 ​

  1. 数据风险：

    • 不会自动清理持久卷数据（需手动备份）
    • 控制平面节点的 etcd 数据会被完全删除

  2. 网络残留：

    • 建议手动清理 iptables 规则和 IPVS 表
    bash
    iptables -F && iptables -t nat -F
ipvsadm --clear

  3. 容器清理：

    • 重置后需手动删除残留容器：
    bash
    # Docker
docker rm -f $(docker ps -aq)

# Containerd
crictl rm -f $(crictl ps -aq)

  4. 高可用集群：

    • 重置控制平面节点前需从 etcd 集群移除该节点
    bash
    # 在其他正常节点执行
etcdctl member list
etcdctl member remove <ID>

  5. 证书处理：

    • 重置不会删除用户手动创建的证书
    • 生产环境建议备份 /etc/kubernetes/pki/

重置后检查清单 ​

  1. 验证服务状态：

    bash
    systemctl status kubelet

  2. 检查目录清理：

    bash
    ls /etc/kubernetes/
ls /var/lib/kubelet/

  3. 确认网络清理：

    bash
    iptables -L -n
ip link show

重要提示：生产环境执行 reset 前，务必确保已备份关键数据（如 etcd 快照），并优先在测试环境验证操作流程。对于加入集群的工作节点，建议先执行 kubectl drain 优雅驱逐工作负载。

kubeadm token - Kubernetes 集群节点加入令牌管理 ​

命令简介 ​

kubeadm token 是管理 Kubernetes 集群节点加入令牌的核心命令，用于创建、列出和删除引导令牌（bootstrap tokens）。这些令牌是工作节点或额外控制平面节点加入集群时的临时身份凭证，默认24小时有效。

核心子命令 ​

命令描述示例
create创建新令牌kubeadm token create --ttl 2h
list列出有效令牌kubeadm token list
delete删除指定令牌kubeadm delete abcdef.0123456789abcdef
generate生成令牌（不创建）kubeadm token generate

关键选项 ​

选项描述示例
--ttl设置令牌有效期--ttl 4h30m
--description添加令牌描述--description "For temporary nodes"
--usages指定令牌用途--usages signing,authentication
--groups设置认证组--groups system:bootstrappers:kubeadm:default-node-token
--print-join-command输出完整加入命令--print-join-command
--config使用配置文件--config token-config.yaml

经典案例 ​

bash
# 创建24小时有效的标准令牌
kubeadm token create

# 创建长期有效的令牌（生产环境慎用）
kubeadm token create --ttl 0

# 获取完整节点加入命令（含CA证书哈希）
kubeadm token create --print-join-command

# 创建带描述的限时令牌
kubeadm token create \
  --ttl 2h \
  --description "For temporary worker nodes"

# 列出所有有效令牌
kubeadm token list -o json

# 立即撤销令牌
kubeadm token delete abcdef.0123456789abcdef

令牌结构解析 ​

典型令牌格式：abcdef.0123456789abcdef

  • 前6位：Token ID（随机字符串）
  • 后16位：Token Secret（随机字符串）

安全实践 ​

  1. 最小化有效期：

    bash
    # 创建仅2小时有效的令牌
kubeadm token create --ttl 2h

  2. 按需创建令牌：

    bash
    # 在需要加入节点时临时生成
JOIN_CMD=$(kubeadm token create --print-join-command)

  3. 令牌轮换：

    bash
    # 定期删除旧令牌
kubeadm token list | grep expired | awk '{print $1}' | xargs kubeadm token delete

高级配置 ​

通过配置文件创建定制令牌：

bash
# token-config.yaml
apiVersion: bootstrap.k8s.io/v1
kind: Token
metadata:
  name: custom-token
spec:
  token-id: abcdef
  token-secret: 0123456789abcdef
  ttl: 24h
  usages:
    - authentication
    - signing
  groups:
    - system:bootstrappers:kubeadm:default-node-token

应用配置：

bash
kubeadm token create --config token-config.yaml

注意事项 ​

  1. 令牌存储位置：

    • 实际存储在 kube-system 命名空间的 Secret 中
    bash
    kubectl get secrets -n kube-system | grep bootstrap-token

  2. CA证书哈希：

    • 令牌必须配合CA证书哈希使用

    • 获取哈希的替代方法：

      bash
      openssl x509 -pubkey -in /etc/kubernetes/pki/ca.crt | \
  openssl rsa -pubin -outform der 2>/dev/null | \
  openssl dgst -sha256 -hex | sed 's/^.* //'

  3. 控制平面加入：

    • 加入控制平面节点需要额外 --certificate-key
    bash
    kubeadm init phase upload-certs --upload-certs

  4. 故障排查：

    • 令牌失效时检查：

      bash
      kubectl get secrets -n kube-system bootstrap-token-abcdef -o yaml

  5. 审计日志：

    • 所有令牌使用记录可在 API Server 审计日志中查看

kubeadm token - Kubernetes 集群节点加入令牌管理 ​

命令简介 ​

kubeadm token 是管理 Kubernetes 集群节点加入令牌的核心命令，用于创建、列出和删除引导令牌（bootstrap tokens）。这些令牌是工作节点或额外控制平面节点加入集群时的临时身份凭证，默认24小时有效。

核心子命令 ​

命令描述示例
create创建新令牌kubeadm token create --ttl 2h
list列出有效令牌kubeadm token list
delete删除指定令牌kubeadm delete abcdef.0123456789abcdef
generate生成令牌（不创建）kubeadm token generate

关键选项 ​

选项描述示例
--ttl设置令牌有效期--ttl 4h30m
--description添加令牌描述--description "For temporary nodes"
--usages指定令牌用途--usages signing,authentication
--groups设置认证组--groups system:bootstrappers:kubeadm:default-node-token
--print-join-command输出完整加入命令--print-join-command
--config使用配置文件--config token-config.yaml

经典案例 ​

bash
# 创建24小时有效的标准令牌
kubeadm token create

# 创建长期有效的令牌（生产环境慎用）
kubeadm token create --ttl 0

# 获取完整节点加入命令（含CA证书哈希）
kubeadm token create --print-join-command

# 创建带描述的限时令牌
kubeadm token create \
  --ttl 2h \
  --description "For temporary worker nodes"

# 列出所有有效令牌
kubeadm token list -o json

# 立即撤销令牌
kubeadm token delete abcdef.0123456789abcdef

令牌结构解析 ​

典型令牌格式：abcdef.0123456789abcdef

  • 前6位：Token ID（随机字符串）
  • 后16位：Token Secret（随机字符串）

安全实践 ​

  1. 最小化有效期：

    bash
    # 创建仅2小时有效的令牌
kubeadm token create --ttl 2h

  2. 按需创建令牌：

    bash
    # 在需要加入节点时临时生成
JOIN_CMD=$(kubeadm token create --print-join-command)

  3. 令牌轮换：

    bash
    # 定期删除旧令牌
kubeadm token list | grep expired | awk '{print $1}' | xargs kubeadm token delete

高级配置 ​

通过配置文件创建定制令牌：

bash
# token-config.yaml
apiVersion: bootstrap.k8s.io/v1
kind: Token
metadata:
  name: custom-token
spec:
  token-id: abcdef
  token-secret: 0123456789abcdef
  ttl: 24h
  usages:
    - authentication
    - signing
  groups:
    - system:bootstrappers:kubeadm:default-node-token

应用配置：

bash
kubeadm token create --config token-config.yaml

注意事项 ​

  1. 令牌存储位置：

    • 实际存储在 kube-system 命名空间的 Secret 中
    bash
    kubectl get secrets -n kube-system | grep bootstrap-token

  2. CA证书哈希：

    • 令牌必须配合CA证书哈希使用

    • 获取哈希的替代方法：

      bash
      openssl x509 -pubkey -in /etc/kubernetes/pki/ca.crt | \
  openssl rsa -pubin -outform der 2>/dev/null | \
  openssl dgst -sha256 -hex | sed 's/^.* //'

  3. 控制平面加入：

    • 加入控制平面节点需要额外 --certificate-key
    bash
    kubeadm init phase upload-certs --upload-certs

  4. 故障排查：

    • 令牌失效时检查：

      bash
      kubectl get secrets -n kube-system bootstrap-token-abcdef -o yaml

  5. 审计日志：

    • 所有令牌使用记录可在 API Server 审计日志中查看