Cilium Gateway API 配置手册

概述

Cilium Gateway API 基于 eBPF 实现，具有高性能、低延迟的特点，支持自动 VIP 分配和 L2 广播

使用 Cilium Gateway API 作为 Kubernetes（V1.36.0）入口网关方案

环境信息：

ubuntu24.04.2

kubeadm v1.36.0

kubernetes v1.36.0

containerd v2.2.3

cilium version v1.19.1

网络接口：ens160

VIP 地址池：192.168.2.24/24

一、部署 Cilium

1.1 安装 Cilium CLI 工具

复制代码

curl -L --remote-name https://github.com/cilium/cilium-cli/releases/latest/download/cilium-linux-amd64.tar.gz
tar xzvf cilium-linux-amd64.tar.gz
sudo mv cilium /usr/local/bin

验证:

复制代码

cilium version

1.2 安装 Cilium

复制代码

cilium install \
  --version 1.19.1 \
  \
  --set kubeProxyReplacement=true \
  --set kubeProxyReplacementMode=strict \
  \
  --set k8sServiceHost=192.168.2.21 \
  --set k8sServicePort=6443 \
  \
  --set routingMode=native \
  --set ipam.mode=kubernetes \
  --set autoDirectNodeRoutes=true \
  --set ipv4NativeRoutingCIDR=10.244.0.0/16 \
  \
  --set loadBalancer.mode=snat \
  \
  --set nodePort.enabled=true \
  --set externalIPs.enabled=true \
  --set hostServices.enabled=true \
  \
  --set l2announcements.enabled=true \
  \
  --set gatewayAPI.enabled=true \
  \
  --set hubble.enabled=true \
  --set hubble.relay.enabled=true \
  --set hubble.ui.enabled=true \
  \
  --set prometheus.enabled=true \
  --set operator.prometheus.enabled=true

-----两种写法差不多，可参考

复制代码

cilium install   --version 1.19.1
     --set kubeProxyReplacement=true
	 --set kubeProxyReplacementMode=strict
     --set k8sServiceHost=192.168.2.21
	 --set k8sServicePort=6443
     --set routingMode=native
	 --set ipam.mode=kubernetes
	 --set autoDirectNodeRoutes=true
	 --set ipv4NativeRoutingCIDR=10.244.0.0/16
     --set loadBalancer.mode=snat
     --set nodePort.enabled=true
	 --set externalIPs.enabled=true
	 --set hostServices.enabled=true
     --set l2announcements.enabled=true
     --set gatewayAPI.enabled=true
     --set gatewayAPI.hostNetwork.enabled=false
     --set hubble.enabled=true
	 --set hubble.relay.enabled=true
	 --set hubble.ui.enabled=true
     --set prometheus.enabled=true
	 --set operator.prometheus.enabled=true

参数说明：

gatewayAPI.enabled=true - 启用 Gateway API 支持

gatewayAPI.service.type=LoadBalancer - Gateway Service 使用 LoadBalancer 类型以自动分配 VIP

l2announcements.enabled=true - 启用 L2 广播功能（ARP 广播 VIP）

kubeProxyReplacement=true - 启用 kube-proxy 替换模式（Gateway API 必需）

k8sServiceHost / k8sServicePort - Kubernetes API Server 地址和端口

1.3 验证 Cilium 状态

kubectl get pods -n kube-system -l k8s-app=cilium

复制代码

root@ops-test-021:~# kubectl get pods -n kube-system -l k8s-app=cilium
NAME           READY   STATUS    RESTARTS   AGE
cilium-42jkw   1/1     Running   0          20h
cilium-8zjd6   1/1     Running   0          20h
cilium-s7b6n   1/1     Running   0          20h

二、配置 Gateway API CRD

2.1 安装 Gateway API CRD (v1.3.0)

复制代码

kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.3.0/standard-install.yaml

查看ReferenceGrant 状态

复制代码

kubectl api-resources | grep ReferenceGrant
root@ops-test-021:~# kubectl api-resources | grep ReferenceGrant
referencegrants                     refgrant     gateway.networking.k8s.io/v1beta1    true         ReferenceGrant

2.2 验证 CRD 安装

复制代码

kubectl get gatewayclass
kubectl get gateway

三、配置自动 VIP 分配

3.1 创建 CiliumLoadBalancerIPPool

定义 VIP 地址池，Gateway 将自动从该池分配 VIP：

复制代码

apiVersion: cilium.io/v2
kind: CiliumLoadBalancerIPPool
metadata:
  name: gateway-pool
spec:
  blocks:
  - start: 192.168.2.24
    stop: 192.168.2.24

kubectl apply -f lb-pool.yaml

3.2 创建 CiliumL2AnnouncementPolicy

配置 L2 广播策略，让选中的节点广播 VIP：

复制代码

apiVersion: cilium.io/v2alpha1
kind: CiliumL2AnnouncementPolicy
metadata:
  name: l2-policy
spec:
  loadBalancerIPs: true
  interfaces:
  - ens160
  nodeSelector:
    matchLabels:
      node-role.kubernetes.io/gateway: "true"

kubectl apply -f l2-policy.yaml

3.3 验证 VIP 配置

kubectl get ciliumloadbalancerippool gateway-pool

kubectl get ciliuml2announcementpolicy l2-policy

复制代码

root@ops-test-021:~/gateway/vip# kubectl get ciliumloadbalancerippool gateway-pool
NAME           DISABLED   CONFLICTING   IPS AVAILABLE   AGE
gateway-pool   false      True          1               22h

root@ops-test-021:~/gateway/vip# kubectl get ciliuml2announcementpolicy l2-policy
NAME        AGE
l2-policy   22h

四、创建 Gateway

4.1 GatewayClass默认会自动创建

略

4.2 HTTPS/TLS 配置

创建 TLS Secret

复制代码

kubectl create secret tls tls-secret \
  --cert=/root/certs/tls.crt \
  --key=/root/certs/tls.key \
  -n infra

查看tls-secret

复制代码

kubectl get secret -n infra

4.3 创建 Gateway 这里配置https 需要先配置一下证书参看4.2中HTTPS/TLS 配置

复制代码

apiVersion: v1
kind: Namespace
metadata:
  name: infra
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: cilium-gw
  namespace: infra
spec:
  gatewayClassName: cilium
  listeners:
  - name: http
    protocol: HTTP
    port: 80
    allowedRoutes:
      namespaces:
        from: All
  - name: https  #些部分为HTTPS Gateway 配置
    protocol: HTTPS
    port: 443
    allowedRoutes:
      namespaces:
        from: All
    tls:
      mode: Terminate
      certificateRefs:
      - name: tls-secret

kubectl apply -f gateway.yaml

4.3 验证 Gateway 状态

kubectl get gateway cilium-gw -n infra -o yaml

输出：

复制代码

status:
  addresses:
  - type: IPAddress
    value: 192.168.2.24
  conditions:
  - lastTransitionTime: "2026-05-07T07:19:12Z"
    message: Gateway successfully scheduled
    observedGeneration: 1
    reason: Accepted
    status: "True"
    type: Accepted

五、配置 HTTPRoute 路由规则

5.1 创建 HTTPRoute 示例

复制代码

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: hubble-ui
  namespace: kube-system

spec:
  parentRefs:
  - name: cilium-gw
    namespace: infra
    sectionName: http

  hostnames:
  - hubble.cctbb.com

  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /

    backendRefs:
    - name: hubble-ui
      port: 80

kubectl apply -f httproute.yaml

5.2 验证路由状态

kubectl get httproute -n kube-system -o yaml

复制代码

root@ops-test-021:~/gateway/vip# kubectl get httproute -A
NAMESPACE     NAME        HOSTNAMES              AGE
kube-system   hubble-ui   ["hubble.cctbb.com"]   22h

六、故障排查

复制代码

6.1 Gateway 状态为 Pending 或 Programmed=False
# 检查 Gateway 状态

kubectl describe gateway cilium-gateway

# 检查 Cilium 状态

kubectl get pods -n kube-system -l k8s-app=cilium
kubectl logs -n kube-system -l k8s-app=cilium

# 检查 GatewayClass

kubectl describe gatewayclass cilium

6.2 VIP 未分配

复制代码

# 检查 IP Pool
kubectl get ciliumloadbalancerippool

# 检查 L2 广播策略
kubectl get ciliuml2announcementpolicy

# 检查 Service 状态
kubectl get svc -n infra cilium-gateway-cilium-gw

6.3 路由不生效

复制代码

# 检查 HTTPRoute 状态
kubectl describe httproute -A

# 检查后端 Service 和 Pods
kubectl get svc -n kube-system
kubectl get pods -n kube-system

6.4 常见错误

GatewayClass 状态 Unknown：

确保 kubeProxyReplacement=true

kubectl get cm cilium-config -n kube-system -o yaml | grep kube-proxy-replacement

复制代码

root@ops-test-021:~/gateway/vip# kubectl get cm cilium-config -n kube-system -o yaml | grep kube-proxy-replacement
  kube-proxy-replacement: "true"
  kube-proxy-replacement-healthz-bind-address: ""

七、参考文档

Cilium 官方文档：https://docs.cilium.io/

Gateway API 官方文档：https://gateway-api.sigs.k8s.io/

Cilium Gateway API：https://docs.cilium.io/en/stable/network/servicemesh/gateway-api/gateway-api/