agentleFS
Aidas-devAidas-dev/k8s-agent-skills/skills/cilium-gateway/SKILL.md

cilium-gateway

Skill4 starsChanged 5 months agoMITView on GitHub

Use when creating Gateway API resources for ingress, configuring TLS termination or passthrough, setting up HTTP-to-HTTPS redirect or traffic splitting, integrating oauth2-proxy or ExternalDNS with Cilium, or debugging Cilium Gateway controller issues including the Programmed=False cosmetic bug.

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

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

    line 79
  2. Distinctive:

    Do not treat this as a failure — routes are functional

    line 251
  3. Distinctive:

    When using TLS passthrough, backends see Envoy IP (node IP) as source, not the client IP.

    line 254

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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)

CRDVersionPurpose
GatewayClassgateway.networking.k8s.io/v1Class reference (parametersRef → CiliumGatewayClassConfig)
Gatewaygateway.networking.k8s.io/v1Shared LB listener — hostname, TLS, ports
HTTPRoutegateway.networking.k8s.io/v1HTTP route rules — matches, filters, backends
GRPCRoutegateway.networking.k8s.io/v1gRPC route rules
TLSRoutegateway.networking.k8s.io/v1alpha2TLS passthrough routing by SNI (experimental)
ReferenceGrantgateway.networking.k8s.io/v1beta1Allow cross-namespace references (Secret, Service)

Cilium-specific

CRDVersionPurpose
CiliumGatewayClassConfigcilium.io/v2alpha1Cilium-specific GatewayClass parameters (envoy config, LB type, etc.)
CiliumEnvoyConfigcilium.io/v2Low-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

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

Gateway API v1.4.1 CRDs must be pre-installed:

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.

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

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

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: http-to-https
  namespace: cilium-gateway
spec:
  parentRefs:
  - name: cilium-gateway
    sectionName: http
  hostnames:
  - "*.example.com"
  rules:
  - filters:
    - type: RequestRedirect
      requestRedirect:
        scheme: https
        statusCode: 301

HTTPRoute with Backend

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: app-route
  namespace: myapp
spec:
  parentRefs:
  - name: cilium-gateway
    namespace: cilium-gateway
    sectionName: https
  hostnames:
  - app.example.com
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /
    backendRefs:
    - name: app-service
      port: 8080

Cross-Namespace Reference (ReferenceGrant)

apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  name: allow-httproutes
  namespace: cilium-gateway
spec:
  from:
  - group: gateway.networking.k8s.io
    kind: HTTPRoute
    namespace: kube-system
  to:
  - group: ""
    kind: Secret
    name: example-tls

Needed when HTTPRoute is in a different namespace than the Gateway or the Secret.

oauth2-proxy Integration

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: hubble-ui
  namespace: kube-system
spec:
  parentRefs:
  - name: cilium-gateway
    namespace: cilium-gateway
    sectionName: https
  hostnames:
  - hubble.example.com
  rules:
  - backendRefs:
    - name: oauth2-proxy-hubble
      port: 4180

Traffic Splitting

spec:
  rules:
  - backendRefs:
    - name: app-v1
      port: 80
      weight: 90
    - name: app-v2
      port: 80
      weight: 10

Header Modification

spec:
  rules:
  - filters:
    - type: RequestHeaderModifier
      requestHeaderModifier:
        set:
        - name: X-Custom-Header
          value: my-value
        add:
        - name: X-Trace-Id
          value: "abc123"

LB IPAM Integration with Gateway Addresses

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: my-gateway
spec:
  addresses:
  - type: IPAddress
    value: 172.18.0.140
  gatewayClassName: cilium
  listeners:
  - ...

Or via annotation (deprecated): io.cilium/lb-ipam-ips: "172.18.0.141"

Known Issues

Programmed=False (Cosmetic)

Cilium Gateway may show PROGRAMMED=False status even though routes work fine.

  • Gateway status: "Address not ready yet" / Programmed: False
  • HTTPRoute status: Accepted: True, ResolvedRefs: True
  • Traffic flows despite Programmed=False
  • Do not treat this as a failure — routes are functional

TLS Passthrough Source IP

When using TLS passthrough, backends see Envoy IP (node IP) as source, not the client IP. This is inherent to TCP proxy mode.

Troubleshooting

# Check gateway status
kubectl get gateway -A
kubectl describe gateway <name>

# Check HTTPRoute
kubectl describe httproute <name>

# Check operator logs for Gateway API errors
kubectl logs -n kube-system deployments/cilium-operator | grep gateway

# Check Envoy config
kubectl get ciliumenvoyconfigs -A

# Verify Gateway API CRDs installed
kubectl get crd | grep gateway.networking.k8s.io

Common Mistakes

SymptomCauseFix
GatewayClass not foundGateway API CRDs not installedInstall v1.4.1 CRDs
Secret "X" not foundMissing ReferenceGrant for cross-namespace SecretAdd ReferenceGrant in Secret's namespace
BackendNotFoundService doesn't exist or wrong namespaceCheck backendRefs names
Programmed=FalseCosmetic bug (see above)Verify HTTPRoute shows Accepted/ResolvedRefs
HostNetwork port clashPort already in useUse unique ports per Gateway resource

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.