rkojedzinszky/kube-router

Kube-router 多架构镜像文档

1. 镜像概述和主要用途

Kube-router 多架构镜像是基于 Kube-router 项目构建的跨平台容器镜像，旨在为 Kubernetes 集群提供统一的网络解决方案。Kube-router 是一款轻量级网络插件，集成了服务代理（Service Proxy）、网络策略（Network Policy）和覆盖网络（Overlay Network）功能。该多架构镜像通过一次构建支持多种 CPU 架构，可无缝部署于不同硬件平台的 Kubernetes 节点，简化多架构集群的网络配置与管理。

2. 核心功能和特性

2.1 核心功能

• 服务代理：基于 IPVS（IP Virtual Server）实现 Kubernetes Service 的负载均衡，支持 TCP/UDP 协议，提供高性能流量转发。
• 网络策略：通过 iptables 实现 Kubernetes Network Policy，支持 Pod 间通信控制，满足微服务安全隔离需求。
• 覆盖网络：支持 VXLAN 或 HostGW 模式的跨节点 Pod 网络，实现集群内 Pod 互通，支持自定义 CIDR 配置。

2.2 多架构特性

• 跨平台支持：兼容主流 CPU 架构，包括 amd64（x86_64）、arm64（AArch64）、arm/v7（32位 ARM）、ppc64le（PowerPC）、s390x（IBM Z）。
• 统一镜像标签：通过多架构清单（Manifest List）实现单标签分发，镜像自动匹配节点架构（如 kube-router/kube-router:latest-multiarch）。
• 原生兼容性：与 upstream Kube-router 功能完全一致，配置参数无缝迁移，无需修改现有部署流程。

3. 使用场景和适用范围

3.1 典型使用场景

• 多架构 Kubernetes 集群：混合部署 x86_64（如服务器）和 ARM64（如边缘设备、树莓派）节点的集群，统一网络插件配置。
• 边缘计算环境：在 ARM 架构边缘设备（如工业网关、IoT 设备）上部署 Kubernetes 集群，提供轻量化网络解决方案。
• 多云/混合云环境：跨不同架构云服务器（如 AWS Graviton2（ARM64）与 x86 实例）构建 Kubernetes 集群，简化网络层管理。

3.2 适用范围

• Kubernetes 版本：1.16+（需匹配 Kube-router 兼容版本）。
• 节点架构：支持 amd64、arm64、arm/v7、ppc64le、s390x 的 Linux 节点。
• 网络模式：支持 Calico、Flannel 等现有 CNI 插件的迁移，或作为全新集群的默认网络插件。

4. 详细使用方法和配置说明

4.1 镜像拉取

通过 Docker 或容器运行时拉取多架构镜像：

bash
docker pull docker.xuanyuan.run/kube-router/kube-router:latest-multiarch  # 最新稳定版
# 或指定版本（如 v1.8.0）
docker pull docker.xuanyuan.run/kube-router/kube-router:v1.8.0-multiarch

4.2 Docker 运行示例（单节点测试）

在非 Kubernetes 环境中通过 Docker 直接运行（仅用于功能验证，生产环境建议通过 Kubernetes DaemonSet 部署）：

bash
docker run -d \
  --name kube-router \
  --privileged \
  --net=host \
  --restart=always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /lib/modules:/lib/modules \
  -v /etc/cni/net.d:/etc/cni/net.d \
  -e KUBECONFIG=/etc/kubernetes/kubeconfig \
  -e NODE_IP=192.168.1.100 \  # 节点 IP
  -e CLUSTER_CIDR=10.244.0.0/16 \  # Pod CIDR
  kube-router/kube-router:latest-multiarch \
  --run-service-proxy \
  --run-network-policy \
  --run-router

参数说明：

• --privileged：需特权模式以操作网络设备和 iptables/IPVS 规则。
• --net=host：使用主机网络命名空间，直接管理节点网络。
• 挂载卷：/lib/modules 提供内核模块访问，/etc/cni/net.d 配置 CNI 插件。

4.3 Kubernetes 部署示例（DaemonSet）

生产环境中，Kube-router 需以 DaemonSet 形式部署，确保每个节点运行一个实例。以下为多架构集群部署 YAML 示例：

yaml
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: kube-router
  namespace: kube-system
spec:
  selector:
    matchLabels:
      k8s-app: kube-router
  template:
    metadata:
      labels:
        k8s-app: kube-router
    spec:
      hostNetwork: true
      tolerations:
        - effect: NoSchedule
          operator: Exists
        - effect: NoExecute
          operator: Exists
      containers:
        - name: kube-router
          image: docker.xuanyuan.run/kube-router/kube-router:latest-multiarch
          imagePullPolicy: Always
          args:
            - --run-service-proxy
            - --run-network-policy
            - --run-router
            - --cluster-cidr=10.244.0.0/16  # 替换为集群 Pod CIDR
          env:
            - name: NODE_NAME
              valueFrom:
                fieldRef:
                  fieldPath: spec.nodeName
            - name: KUBE_ROUTER_NAMESPACE
              valueFrom:
                fieldRef:
                  fieldPath: metadata.namespace
          securityContext:
            privileged: true
          volumeMounts:
            - name: lib-modules
              mountPath: /lib/modules
              readOnly: true
            - name: cni-conf
              mountPath: /etc/cni/net.d
      volumes:
        - name: lib-modules
          hostPath:
            path: /lib/modules
        - name: cni-conf
          hostPath:
            path: /etc/cni/net.d

部署命令：

bash
kubectl apply -f kube-router-daemonset.yaml

5. 配置参数与环境变量

5.1 核心环境变量

5.2 关键命令行参数

6. 注意事项

• 内核版本要求：IPVS 功能需内核版本 ≥ 4.19，VXLAN 需内核支持 VXLAN 模块。
• 架构兼容性：确保节点架构在镜像支持列表中（如 arm/v7 需 32 位内核）。
• CNI 冲突：部署前需移除集群中其他 CNI 插件（如 Calico、Flannel），避免规则冲突。
• 升级策略：多架构镜像版本需与 Kubernetes 版本兼容，升级前参考 Kube-router 官方兼容性矩阵。