Egress gateway

Active contributors: pippolo84, julianwiedmann, joestringer

Purpose

By default, traffic leaving the cluster is SNATed to whatever node the source pod runs on. Egress gateway lets operators choose a specific node (or pool of nodes) as the egress point for selected traffic — useful for fixed-IP egress (firewall rules, IP allowlists at SaaS providers) and for routing traffic through a chosen security zone.

Directory layout

pkg/egressgateway/
├── manager.go            # the egress gateway cell
├── policy.go             # CRD reconciliation
├── ...
pkg/k8s/apis/cilium.io/v2/types_egress_gateway_policy.go  # CiliumEgressGatewayPolicy CRD
bpf/lib/egress_gateway.h     # dataplane lookup helpers
pkg/maps/egressmap/          # the BPF egress map

How it works

The user creates a CiliumEgressGatewayPolicy:

apiVersion: cilium.io/v2
kind: CiliumEgressGatewayPolicy
metadata:
  name: egress-via-gw1
spec:
  selectors:
    - podSelector:
        matchLabels:
          app: payments
  destinationCIDRs:
    - 0.0.0.0/0
  excludedCIDRs:
    - 10.0.0.0/8
  egressGateway:
    nodeSelector:
      matchLabels:
        kubernetes.io/hostname: gw1
    interface: eth0

The agent on every node consumes the CRD, computes which (srcIP, dstCIDR) tuples should be steered, and writes entries into the egress BPF map. On the source pod's node, traffic matching the tuple is encapsulated to the gateway node (or routed via the standard tunnel) and forwarded out the gateway's specified interface with SNAT to the gateway's IP.

graph LR
    Pod[Source pod]
    Node1[Source node]
    GW[Egress gateway node]
    Internet[Internet]

    Pod --> Node1
    Node1 -->|tunnel + egress map hit| GW
    GW -->|SNAT to gw1 IP| Internet

The dataplane lookup is in bpf/lib/egress_gateway.h; the userspace control is in pkg/egressgateway/manager.go.

Considerations

• High availability: today there is no automatic failover when an egress gateway node goes down. Multi-gateway support evolves over time; check the CRD schema (gatewayPolicy.egressGateways[]) for the latest options.
• MTU: egress traffic typically traverses an additional encapsulation hop, so MTU calculations include both pod-to-gateway and gateway-to-internet legs.
• Metrics: cilium_egress_gateway_* Prometheus metrics expose policy counts and dataplane hit counters.

Integration points

• Datapath: egress map is consulted in the per-pod TC program (bpf/bpf_lxc.c via bpf/lib/egress_gateway.h).
• Endpoint manager: changes to pod labels can flip a pod into or out of the policy's selector.
• Encryption: combines naturally with WireGuard / IPSec — the encrypted tunnel covers the gateway hop.

Key source files

File	Purpose
pkg/egressgateway/manager.go	Cell that reconciles CRD into BPF maps.
pkg/maps/egressmap/egressmap.go	The BPF map type.
bpf/lib/egress_gateway.h	Dataplane lookup.
pkg/k8s/apis/cilium.io/v2/types_egress_gateway_policy.go	CRD definition.