cilium-gateway

Files (1)

• SKILL.md

SKILL.md (first lines)

# Cilium Gateway

Cilium v1.19.4 — Gateway API implementation for ingress traffic via per-node Envoy.

## Overview

Cilium implements Gateway API v1.4.1 using per-node Envoy proxies with eBPF TPROXY interception. Supports GatewayClass, Gateway, HTTPRoute, GRPCRoute, TLSRoute, and ReferenceGrant. Host network mode exposes listeners directly on node IPs without a LoadBalancer Service. TLS termination, traffic splitting, and header modification all handled in Envoy.

## CRDs Used

### Gateway API (standard)
| CRD | Version | Purpose |
|-----|---------|---------|
| `GatewayClass` | `gateway.networking.k8s.io/v1` | Class reference (parametersRef → `CiliumGatewayClassConfig`) |
| `Gateway` | `gateway.networking.k8s.io/v1` | Shared LB listener — hostname, TLS, ports |
| `HTTPRoute` | `gateway.networking.k8s.io/v1` | HTTP route rules — matches, filters, backends |
| `GRPCRoute` | `gateway.networking.k8s.io/v1` | gRPC route rules |
| `TLSRoute` | `gateway.networking.k8s.io/v1alpha2` | TLS passthrough routing by SNI (experimental) |
| `ReferenceGrant` | `gateway.networking.k8s.io/v1beta1` | Allow cross-namespace references (Secret, Service) |

### Cilium-specific
| CRD | Version | Purpose |
|-----|---------|---------|
| `CiliumGatewayClassConfig` | `cilium.io/v2alpha1` | Cilium-specific GatewayClass parameters (envoy config, LB type, etc.) |
| `CiliumEnvoyConfig` | `cilium.io/v2` | Low-level Envoy config (used internally by Gateway controller) |

## Architecture

```
Internet → LB IP → any node → eBPF TPROXY → per-node Envoy → identity "ingress" → backend pod
```

- Traffic arrives at any node, eBPF intercepts via TPROXY using `ingress` identity
- Per-node Envoy (DaemonSet or cilium-agent embedded) handles L7
- Two policy enforcement points: `world → ingress` and `ingress → backend`
- Source IP preserved in `X-Forwarded-For` and `X-Envoy-External-Address` headers

## Prerequisites

```yaml
# Helm values needed
kubeProxyReplacement: true
gatewayAPI:
  enabled: true
```

Gateway API v1.4.1 CRDs must be pre-installed:
```bash
kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/gateway-api/v1.4.1/config/crd/standard/gateway.networking.k8s.io_*.yaml
```

## Host Network Mode

Cilium 1.16+ — expose Gateway directly on host network (no LoadBalancer Service). **Requires Envoy hostNetwork.**

```yaml
gatewayAPI:
  enabled: true
  hostNetwork:
    enabled: true
    nodes:
      matchLabels:
        role: infra
envoy:
  enabled: true
  hostNetwork: true
  securityContext:
    capabilities:
      keepCapNetBindService: true
      envoy:
        - NET_BIND_SERVICE
```

**Privileged ports (≤1023):** Add `NET_BIND_SERVICE` capability to Envoy.

## Common Patterns

### Gateway with TLS Termination
```yaml
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: cilium-gateway
  namespace: cilium-gateway
  annotations:
    external-dns.alpha.kubernetes.io/target: 79.76.124.104
spec:
  gatewayClassName: cilium
  listeners:
  - name: http
    protocol: HTTP
    port: 80
    hostname: "*.example.com"
    allowedRoutes:
      namespaces:
        from: All
  - name: https
    protocol: HTTPS
    port: 443
    hostname: "*.example.com"
    tls:
      mode: Terminate
      certificateRefs:
      - name: example-tls
        kind: Secret
  allowedRoutes:
    namespaces:
      from: All
```

### HTTP → HTTPS Redirect
```yaml
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: http-to-https
  namespace: cilium-gateway
spec:
  parentRefs:

From Aidas-dev/k8s-agent-skills, MIT.

More from Aidas-dev/k8s-agent-skills