yldmdocs

kube-vip · 控制面 API 高可用 VIP

kube-vip 为 K3s 控制平面提供一个浮动虚拟 IP（VIP）。它以 DaemonSet 形式只跑在 control-plane 节点上，通过 leader election 选出一个持有者，用 ARP（L2 模式）在局域网应答 VIP 192.168.88.99，端口 6443。kubectl 和集群组件都连这个固定地址而非某个具体 master 的 IP，当持有者节点故障时 VIP 会自动漂移到另一个 master，从而避免单点。

本服务的 manifest 在 applications/networking/kube-vip/，但实际部署在 kube-system namespace。该目录是裸 YAML 集合，没有 kustomization.yaml、没有 namePrefix，资源名直接是 kube-vip。

部署形态

  • Name
    namespace
    Description
    kube-system
  • Name
    工作负载类型
    Description
    DaemonSet（kube-vip），hostNetwork: true
  • Name
    镜像与版本
    Description
    ghcr.io/kube-vip/kube-vip:v1.2.0（2026-06-14 起，PR #1008 由 v0.8.10 升级；据部署指南，该升级 env 配置全兼容，仅改 image tag）
  • Name
    调度
    Description
    nodeSelector: node-role.kubernetes.io/control-plane: "true" —— 仅 control-plane 节点；tolerations 容忍所有 NoSchedule / NoExecute，保证在打了污点的 master 上也能跑
  • Name
    VIP / 端口
    Description
    192.168.88.99/32，端口 6443（K3s API Server）
  • Name
    资源
    Description
    requests cpu: 50m / memory: 50Mi；limits cpu: 100m / memory: 100Mi
  • Name
    能力
    Description
    securityContext.capabilities 添加 NET_ADMIN、NET_RAW（绑定 VIP、发 ARP 所需）

容器以 manager 参数启动，无独立存储（不挂 PVC），状态全在 Kubernetes 的 lease 对象里。

配置与依赖

配置全部经容器 env 注入，没有 ConfigMap，也没有 ExternalSecret —— kube-vip 用集群内 ServiceAccount token 直接读写 API 资源。关键 env：

env值含义
cp_enabletrue启用 control-plane VIP 功能
cp_namespacekube-systemleader lease 所在 namespace
svc_enablefalse不接管 LoadBalancer Service（那是 MetalLB 的活）
vip_arptrueARP（L2）模式
address192.168.88.99VIP 地址
vip_cidr32VIP 以 /32 绑定
port6443API Server 端口
vip_ddnsfalse不启用 DDNS
vip_leaderelectiontrue启用 leader election
vip_leaseduration5租约时长（秒）
vip_renewdeadline3续约截止（秒）
vip_retryperiod1重试周期（秒）
prometheus_server:2112Prometheus 指标监听地址

注意 DaemonSet 没有 vip_interface env —— 网卡名由 kube-vip 按节点默认路由自动探测（PR #894），不再写死。

RBAC 自带一套：ServiceAccount kube-vip 绑定到 ClusterRole kube-vip，授予对 services/nodes/endpoints 的 list/get/watch/update、对 configmaps 的 list/get/watch/create/update，以及对 coordination.k8s.io 的 leases 的 list/get/watch/create/update（leader election 用）。

同目录还有一个独立的 k3s-api ExternalName Service：它本身不属于 kube-vip 的 VIP 机制，而是借 External-DNS 注解（external-dns.alpha.kubernetes.io/hostname: k3s-api.yldm.tech、target: 2b822c22-...cfargotunnel.com、cloudflare-proxied: "true"、ttl: 300）把 k3s-api.yldm.tech 指向 Cloudflare Tunnel 的目标，供从公网经隧道访问 API 用。

访问与监控

VIP 192.168.88.99:6443 不经 Service 暴露，而是直接由持有者节点在 hostNetwork 上绑定并做 ARP 应答，所以集群内外只要在同一 L2 网段都能连到它。

kube-vip 在 :2112 暴露 Prometheus 指标（prometheus_server env）。但本目录没有 ServiceMonitor、PrometheusRule、HPA、VPA 或 PDB —— 这些抓取/告警配置（若有）不在 kube-vip 自己的 manifest 里。

查看 leader 与排障：

# 当前 leader
kubectl get lease -n kube-system plndr-cp-lock -o yaml | grep holderIdentity

# pod 日志
kubectl logs -n kube-system daemonset/kube-vip -f

# 验证 VIP 已绑定（以默认路由接口为准，不一定是 enp6s18）
kubectl --server=https://192.168.88.99:6443 get nodes

注意事项

网卡名不再写死：ISO 安装的旧节点网卡是 enp6s18，cloud-image 新节点（如 k8s-worker4）是 eth0。曾经写死 vip_interface: enp6s18 导致新节点上 kube-vip 崩溃循环；DaemonSet 已删除该 env，由 kube-vip 按 ip route show default 的接口自行探测（PR #894）。验证 VIP 绑定时以默认路由接口为准。

频繁重启先查 master CPU，不是改 kube-vip：kube-vip 曾长期高频重启（单 pod 累计 190+ 次），根因是 master CPU 饥饿导致 leader 租约（leaseduration 5s / renewdeadline 3s）超时，而非配置问题。若再次出现频繁重启，先排查 master 节点 CPU。

API Server 证书需含 VIP：通过 VIP 访问要求 K3s 的 tls-san 包含 192.168.88.99，否则会报 x509: certificate is valid for ... not 192.168.88.99。这属于节点侧 K3s 配置，不在本仓库。完整 VIP 配置、TLS-SAN 更新与故障转移验证见 docs/kube-vip-deployment-guide.md。

返回 networking 总览

评论