Choose a Cilium Gateway API External Entry Point

Key takeaways

• Cilium translates Gateway and HTTPRoute resources into Envoy configuration, while its eBPF data path delivers incoming connections to per-node Envoy
• The external entry point must be chosen explicitly from a LoadBalancer Service, a NodePort consumed by an external appliance, or a direct hostNetwork listener
• A highly available Kubernetes control plane and a highly available application ingress path solve different problems
• A public IP missing from eth0 can still be associated with a node vNIC by provider SDN or virtual networking, so inspect the observed destination and provider requirements first
• Production readiness requires routing, advertisement, policy, client-IP trust, and failure removal checks in addition to address allocation

Gateway API separates roles from the data path

• Gateway API separates infrastructure ownership from application routing ownership

  • Platform teams own the implementation, listeners, and TLS boundary through GatewayClass and Gateway
  • Application teams own host, path, and backend rules through HTTPRoute and GRPCRoute

• Cilium Gateway API is integrated into the CNI data path rather than being only another ingress-controller Deployment

  • The Cilium operator validates resources and produces CiliumEnvoyConfig
  • Cilium eBPF intercepts Service or host-port traffic and transparently directs it to Envoy
  • Envoy performs L7 routing and TLS termination before opening a connection to the backend Service

Establish the common prerequisites first

• The examples are verified against Cilium 1.20.1 and Gateway API 1.6.1

  • Check the documentation and upgrade guide for the exact Cilium version deployed in the cluster
  • Treat CiliumGatewayClassConfig as a v2alpha1 API that can change between releases

• Cilium Gateway API requires kube-proxy replacement and the L7 proxy

kubeProxyReplacement: true
l7Proxy: true
gatewayAPI:
    enabled: true

• Install compatible Gateway API CRDs before enabling the controller

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

helm upgrade cilium cilium/cilium \
  --namespace kube-system \
  --reuse-values \
  --values values-cilium-gateway.yaml

• Verify both the Cilium settings and the GatewayClass after installation

cilium status --wait
kubectl -n kube-system exec ds/cilium -- \
  cilium-dbg config --all | rg 'KubeProxyReplacement|EnableL7Proxy'
kubectl get gatewayclass cilium

Choose exposure based on network ownership

• LB IPAM allocates an address but does not make it reachable by itself

  • Use Cilium BGP Control Plane when routers can learn the Service VIP over BGP
  • Use L2 Announcements when the VIP is reachable on the same L2 network
  • Use hostNetwork and external DNS when provider SDN associates a distinct public IP with each node vNIC

• hostNetwork and the default LoadBalancer Service mode are mutually exclusive

  • Host-network listeners bind on all interfaces of selected nodes
  • Review the current limitations before selecting it when TCPRoute or UDPRoute is required

Keep one portable Gateway contract

• The same Gateway and HTTPRoute contract can remain in place while the external exposure mode changes

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
    name: public
    namespace: edge
spec:
    gatewayClassName: cilium
    listeners:
        - name: https
          protocol: HTTPS
          port: 443
          hostname: "*.example.com"
          tls:
              mode: Terminate
              certificateRefs:
                  - kind: Secret
                    name: wildcard-example-com
          allowedRoutes:
              namespaces:
                  from: Selector
                  selector:
                      matchLabels:
                          gateway-access: public
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
    name: shop
    namespace: shop
spec:
    parentRefs:
        - name: public
          namespace: edge
    hostnames: ["shop.example.com"]
    rules:
        - backendRefs:
              - name: shop-web
                port: 8080

• Cross-namespace attachment requires explicit permission on both sides
  • allowedRoutes must admit the Route namespace
  • Cross-namespace backend or Secret references require a ReferenceGrant owned by the target namespace

Design policy and client-IP trust together

• Cilium policy sees the external-to-Envoy and Envoy-to-backend segments as distinct flows

  • The first segment is commonly world to the ingress identity
  • The second segment is the ingress identity to the application identity

• An external LB requires an explicit authority for client IP information

  • Keep the default remote-address behavior when an L4 LB preserves source IP
  • Trust X-Forwarded-For only when a controlled L7 LB creates it and direct node access is blocked
  • An Internet client must never be able to inject a header that bypasses IP policy or audit attribution

Verify the request path, not just the address

• Programmed=True confirms that configuration was produced, not that the Gateway is reachable from the Internet

kubectl get gateway -A
kubectl describe gateway -n edge public
kubectl get httproute -A
kubectl get svc -n edge
kubectl -n kube-system logs ds/cilium-envoy --since=10m

• Test DNS, TCP, TLS, and HTTP from an external vantage point

dig +short shop.example.com
nc -vz shop.example.com 443
openssl s_client -connect shop.example.com:443 -servername shop.example.com </dev/null
curl --fail-with-body --resolve shop.example.com:443:203.0.113.10 \
  https://shop.example.com/healthz

• The remaining articles keep this Gateway contract and change only the entry-point topology
  • External load balancer
  • Highly available control plane
  • Per-node cloud public IPs without an LB

References

• Cilium Gateway API Support
• Cilium Gateway API use case
• Cilium LoadBalancer IPAM
• Gateway API concepts