在 Kubernetes 集群中启用 IPv6 双栈支持的完整实践
作者：钝刀张三
时间：2025年11月
分类：Kubernetes、网络、IPv6
标签：Kubernetes IPv6 DualStack、Calico、kubelet、容器网络
前言
随着 IPv6 在数据中心和云原生环境中的逐步普及，Kubernetes 已经原生支持 IPv6 双栈网络模式（DualStack）。本文记录了我在生产环境中为 Kubernetes 集群开启 IPv6 双栈支持的完整实践过程，涵盖从主机系统配置到 kube 组件、Calico 网络插件以及验证步骤。
主机启用 IPv6 网络支持
启用 IPv6 网络
编辑全局网络配置文件：
vim /etc/sysconfig/network
NETWORKING_IPV6=yes
修改网卡配置（示例以 ens192 为例）：
vi /etc/sysconfig/network-scripts/ifcfg-ens192
添加或修改以下参数：
IPV6INIT=yes
IPV6_AUTOCONF=no
IPV6_DEFROUTE=yes
IPV6_PEERDNS=yes
IPV6ADDR=10:1:21::71/64
IPV6_DEFAULTGW=10:1:21::FFFF
DNS1=192.168.30.2
⚠️ 注意：请确保每台主机的 IPv6 地址不重复。
禁用 IPv6 的行需注释掉：
# IPV6_DISABLED=yes
配置系统 IPv6 参数
编辑内核参数：
vim /etc/sysctl.conf
增加以下内容：
net.ipv6.conf.all.disable_ipv6=0
net.ipv6.conf.default.disable_ipv6=0
net.ipv6.conf.lo.disable_ipv6=0
net.ipv6.conf.all.forwarding=1
同时检查 rp_filter 参数（出口网关中必须为 0）：
sysctl -a | grep rp_filter
若不为 0，请修改为：
net.ipv4.conf.all.rp_filter=0
使配置立即生效：
sysctl -p
systemctl restart network
等待 2-3 分钟后执行：
ip a
若未自动分配 IPv6，可手动添加。
Kubernetes 核心组件配置
1️⃣ kube-apiserver
编辑：
sudo vim /etc/kubernetes/manifests/kube-apiserver.yaml
添加参数：
- --feature-gates=IPv6DualStack=true
- --service-cluster-ip-range=10.68.0.0/16,fd00::/108
确保镜像使用私有仓库：
image: harbor地址:haror端口/paas_public/kube-system/kube-apiserver:v1.24.2
若修改后 API Server 无法启动：
-
检查镜像是否能正常拉取；
-
查看日志：
journalctl -u kubelet | grep kube-apiserver -
必要时重启：
sudo systemctl restart kubelet
2️⃣ kube-controller-manager
修改配置：
sudo vim /etc/kubernetes/manifests/kube-controller-manager.yaml
添加：
- --feature-gates=TTLAfterFinished=true,EphemeralContainers=true,IPv6DualStack=true
- --cluster-cidr=192.168.0.0/16,fc00::/48
- --service-cluster-ip-range=10.68.0.0/16,fd00::/108
- --node-cidr-mask-size-ipv4=16
- --node-cidr-mask-size-ipv6=64
同时更新镜像地址：
image: harbor地址:haror端口/paas_public/kube-system/kube-controller-manager:v1.24.2
3️⃣ kubelet
编辑节点配置：
vi /var/lib/kubelet/kubeadm-flags.env
添加 IPv6 地址：
KUBELET_KUBEADM_ARGS="--node-ip=10.1.12.175,10:1:12::175"
重启服务：
sudo systemctl daemon-reload
sudo systemctl restart kubelet
验证：
kubectl get nodes -o wide
节点应显示双栈 IP。
4️⃣ kube-proxy
启用 DualStack：
kubectl edit configmap kube-proxy -n kube-system
修改：
featureGates:
IPv6DualStack: true
clusterCIDR: 172.20.0.0/16,fc00::/48
重启：
kubectl rollout restart daemonset kube-proxy -n kube-system
确保镜像来自私有仓库：
image: harbor地址:haror端口/paas_public/kube-system/kube-proxy:v1.27.2
Calico 网络插件启用双栈
双栈模式配置
修改 ConfigMap：
kubectl edit configmap cni-config -n calico-system
设置：
"assign_ipv6": "true"
关闭 operator：
kubectl scale deployment tigera-operator -n calico --replicas=0
编辑 calico-node：
kubectl edit daemonsets calico-node -n calico-system
添加环境变量：
- name: CALICO_IPV6POOL_CIDR
value: fc00::/48
- name: FELIX_IPV6SUPPORT
value: "true"
- name: IP6_AUTODETECTION_METHOD
value: interface=eth.*|en.*|em.*
更新镜像：
image: harbor地址:haror端口/paas_public/kube-system/node:v3.25.0
仅 IPv6 模式配置
仅需修改：
kubectl edit configmap cni-config -n calico-system
设置：
"assign_ipv4": "false", "assign_ipv6": "true"
并在 calico-node 中删除 IPv4 相关配置。
测试 IPv6 Pod 与 Service
创建测试 Pod：
kubectl run test-pod --image=harbor地址:haror端口/library/busybox:1.28 -- sleep 3600
或使用以下双栈 Service 示例：
apiVersion: v1
kind: Service
metadata:
name: php-apache
spec:
ipFamilyPolicy: PreferDualStack
ipFamilies:
- IPv4
- IPv6
ports:
- port: 80
selector:
run: php-apache
验证结果：
kubectl describe pod php-apache-xxxx
kubectl describe service php-apache
应看到 IPv4 与 IPv6 地址均已分配。
总结与经验
✅ 经验要点：
- 启用 IPv6 时务必同步修改
sysctl与网卡配置； - 所有 Kubernetes 组件镜像统一使用私有仓库；
--feature-gates=IPv6DualStack=true必须在 apiserver、controller-manager、kubelet、kube-proxy 中同时启用；- Calico 需显式开启 IPv6 支持，否则 Pod 无法分配 IPv6 地址；
- 变更完配置后，请耐心等待 Pod 自动重启，或手动
rollout restart。
至此，Kubernetes 集群的 IPv6 双栈支持已全部启用并验证成功。🚀
