大规模Kubernetes集群IPv6单栈迁移实践与故障排查

Kubernetes集群IPv6单栈迁移为什么现在必须推进

2026年7月28日，中央网信办在雄安新区启动”人工智能大模型IPv6能力提升专项行动”，联合北京、上海、浙江、深圳四地网信办推动生成式大模型应用全面支持IPv6，专项行动为期一年。政策层面已将IPv6升级从”鼓励”推进到”倒计时”，智算中心和大模型服务集群首当其冲。对Kubernetes运维团队来说，IPv6单栈迁移不再是技术储备，而是合规红线。

IPv6单栈迁移的难点不在协议本身，而在于Kubernetes网络栈的复杂性——CNI插件、Service、Ingress、CoreDNS、NetworkPolicy层层依赖IP协议族，任何一层残留IPv4硬编码都会导致集群功能异常。

迁移前的兼容性审计清单

在全量切换之前，必须对现有集群做IPv4依赖审计。遗漏一个硬编码IPv4地址，切换后就是一次生产事故。

# 审计脚本: 扫描集群中所有IPv4硬编码引用
#!/bin/bash
echo "=== Service ClusterIP 审计 ==="
kubectl get svc --all-namespaces -o json | \
  jq -r '.items[] | select(.spec.clusterIP != "None" and .spec.clusterIP != "") |
  "\(.metadata.namespace)/\(.metadata.name): \(.spec.clusterIP)"'

echo "=== ConfigMap/Secret 中的 IPv4 引用 ==="
kubectl get configmap,secret --all-namespaces -o json | \
  jq -r '.items[] | .data // {} | to_strings[] | select(test("\\b([0-9]{1,3}\\.){3}[0-9]{1,3}\\b")) |
  .[:80]'

echo "=== NetworkPolicy IPv4 选择器 ==="
kubectl get networkpolicy --all-namespaces -o json | \
  jq -r '.items[] | select(.spec.ingress[]?.from[]?.ipBlock?.cidr // "" | test("^[0-9]")) |
  "\(.metadata.namespace)/\(.metadata.name)"'

echo "=== Ingress Controller IP 白名单 ==="
kubectl get ingress --all-namespaces -o json | \
  jq -r '.items[] | .metadata.annotations // {} |
  to_entries[] | select(.value | test("\\b([0-9]{1,3}\\.){3}[0-9]{1,3}\\b")) |
  "\(.key): \(.value[:60])"'

审计完成后，按优先级处理：ClusterIP类型Service改为IPv6 CIDR范围分配，ConfigMap中的IP引用改为域名，NetworkPolicy的ipBlock.cidr从IPv4段改为IPv6段。

CNI插件IPv6单栈配置实战

Calico和Cilium是当前支持IPv6单栈最成熟的两款CNI插件。以Calico为例，IPv6单栈安装：

# Calico IPv6 单栈安装
# 1. 下载Calico manifest
curl -O https://raw.githubusercontent.com/projectcalico/calico/v3.28/manifests/calico.yaml

# 2. 修改IP配置段
# 在calico-node容器的环境变量中设置:
- name: IP6
  value: "autodetect"
- name: CALICO_IPV6POOL_CIDR
  value: "fd00::/80"        # Pod IPv6 CIDR
- name: FELIX_IPV6SUPPORT
  value: "true"
- name: IP
  value: ""                 # 留空禁用IPv4

# 3. kube-apiserver 启动参数增加IPv6支持
--service-cluster-ip-range=fd00:1::/112
--node-cidr-mask-size-ipv6=80

# 4. kubelet 启动参数
--node-ip=<node-ipv6-address>
--cluster-dns=fd00:1::a     # CoreDNS IPv6 Service IP

# 5. 应用配置
kubectl apply -f calico.yaml

Calico的BGP模式在IPv6下需要注意：BGP Router ID仍然需要IPv4地址（RFC 6996），可以分配一个内部的虚拟IPv4地址作为Router ID，实际数据面流量走IPv6。

Cilium的IPv6单栈配置更简洁：

# Cilium IPv6 单栈 Helm 安装
helm install cilium cilium/cilium \
  --namespace kube-system \
  --set ipv4.enabled=false \
  --set ipv6.enabled=true \
  --set ipam.operator.clusterPoolIPv6CIDR=fd00::/80 \
  --set ipam.operator.clusterPoolIPv6MaskSize=82 \
  --set kubeProxyReplacement=strict \
  --set hubble.enabled=true

CoreDNS IPv6适配与调试

CoreDNS在IPv6单栈下的核心变化是监听地址和上游DNS配置：

# CoreDNS Corefile IPv6 单栈配置
.:53 {
    bind fd00:1::a          # CoreDNS Service IPv6 地址
    errors
    health
    ready
    kubernetes cluster.local in-addr.arpa ip6.arpa {
      endpoint https://[fd00:1::1]:443   # API Server IPv6 地址
      fallthrough in-addr.arpa ip6.arpa
    }
    prometheus :9153
    forward . /etc/resolv.conf {
      policy sequential
    }
    cache 30
    loop
    reload
    loadbalance
}

常见问题：Pod内nslookup解析失败。排查步骤：

# 1. 检查Pod DNS配置
kubectl exec -it <pod> -- cat /etc/resolv.conf
# nameserver 应为 fd00:1::a, 而非 10.96.0.10

# 2. 检查CoreDNS Service ClusterIP
kubectl get svc kube-dns -n kube-system -o jsonpath='{.spec.clusterIP}'
# 应返回 IPv6 地址

# 3. 直接查询CoreDNS Pod验证
kubectl exec -it <pod> -- nslookup kubernetes.default.svc.cluster.local fd00:1::a

Ingress Controller与外部流量接入

Nginx Ingress Controller在IPv6单栈下需要确保监听地址和代理配置正确：

# Nginx Ingress Controller IPv6 单栈配置
# ConfigMap: nginx-configuration
data:
  use-forwarded-headers: "true"
  bind-address: "::"           # 监听所有IPv6地址
  proxy-bind-address: "::"
  forwarded-for-header: "X-Forwarded-For"

# Service 类型改为 LoadBalancer, 指定IPv6
apiVersion: v1
kind: Service
metadata:
  name: ingress-nginx-controller
spec:
  ipFamilyPolicy: SingleStack
  ipFamilies:
    - IPv6
  type: LoadBalancer
  ports:
    - port: 80
      targetPort: 80
    - port: 443
      targetPort: 443

外部流量入口需要确保上游LB（如AWS ALB、MetalLB）支持IPv6。MetalLB的IPv6 BGP配置：

# MetalLB IPv6 BGP 配置
apiVersion: metallb.io/v1beta2
kind: BGPPeer
metadata:
  name: bgp-peer-ipv6
spec:
  myASN: 64512
  peerASN: 64513
  peerAddress: "fd00:ff::1"
  peerPort: 179
---
apiVersion: metallb.io/v1beta1
kind: IPAddressPool
metadata:
  name: ipv6-pool
spec:
  addresses:
    - "2001:db8::/64"
  autoAssign: true

NetworkPolicy在IPv6单栈下的变更

IPv6单栈下NetworkPolicy的ipBlock必须使用IPv6 CIDR格式，此前用IPv4 CIDR白名单的规则全部失效：

# 修正前（IPv4, 迁移后失效）
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
spec:
  ingress:
    - from:
        - ipBlock:
            cidr: 10.0.0.0/8      # 迁移后无效

# 修正后（IPv6）
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
spec:
  ingress:
    - from:
        - ipBlock:
            cidr: fd00::/48        # IPv6 内部网段
        - ipBlock:
            cidr: 2001:db8::/64   # IPv6 外部可信网段

NetworkPolicy审计脚本可批量扫描集群中所有ipBlock规则，将残留IPv4 CIDR标记为待修正项。

迁移验证全流程

# IPv6 单栈迁移验证清单
# 1. 节点网络
ping6 -c 3 <peer-node-ipv6>
# 2. Pod跨节点通信
kubectl run test --image=busybox --overrides='{"spec":{"containers":[{"name":"t","image":"busybox","command":["sleep","3600"]}]}}'
kubectl exec test -- ping6 -c 3 fd00::1
# 3. Service解析
kubectl exec test -- nslookup kubernetes.default
# 4. Ingress外部访问
curl -6 https://your-app.example.com
# 5. NetworkPolicy阻断验证
# 从非白名单Pod尝试访问被保护的Service, 应被拒绝

IPv6单栈迁移是系统工程，CNI、DNS、Ingress、NetworkPolicy逐层验证才能避免生产事故。政策窗口已开启，运维团队应当立即启动审计，制定分阶段迁移计划。