Gateway API vs Ingress for Kubernetes traffic

Same hostname, two APIs: classic Ingress versus role-split Gateway API—and how Universal Helm Chart maps both without inventing a third DSL.

Why Ingress hit a ceiling

Ingress is one object owned by whoever can edit annotations. Controllers disagree on annotation semantics. TLS, canaries, rewrites, and auth become vendor strings instead of typed fields. Status is thin: “it works” or “it doesn’t,” with little portable condition language.

Gateway API splits roles: platform owns GatewayClass and Gateway listeners; app teams own HTTPRoute (and related routes) that attach via parentRefs. Policies that are not portable stay in implementation CRDs (for kgateway: TrafficPolicy, BackendConfigPolicy, GatewayExtension)—labelled as such, not as “Ingress annotations 2.0.”

Role model

• GatewayClass — controller implementation (platform)
• Gateway — listeners, TLS termination at the edge, which namespaces may attach routes (allowedRoutes)
• HTTPRoute — hostnames, matches, filters, backendRefs (app or platform, depending on ownership)
• ReferenceGrant — cross-namespace Service/Secret references when required
• Backend Service/Pods — still the app chart’s job

Official type reference: HTTPRoute, Gateway.

Equivalent exposure in Universal Helm Chart

Defaults: ingress.enabled: false, route.enabled: false. Prefer one exposure path per release unless you intentionally dual-publish during migration.

Ingress values → networking.k8s.io/v1 Ingress

service:
  port: 8080
ingress:
  enabled: true
  className: nginx
  annotations: {}
  hosts:
    - host: app.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: app-example-tls
      hosts:
        - app.example.com

HTTPRoute values → gateway.networking.k8s.io/v1 HTTPRoute

route.gateway is required when route.enabled: true. The template sets parentRefs to that Gateway and backendRefs to the chart Service on service.port. Optional: gatewayNamespace, sectionName, path, pathMatchType (default PathPrefix), backendWeight (default 1), timeouts.request / timeouts.backendRequest.

service:
  port: 8080
route:
  enabled: true
  gateway: external
  gatewayNamespace: kgateway-system
  sectionName: https
  hostname: app.example.com
  path: /
  pathMatchType: PathPrefix
  backendWeight: 1
  timeouts:
    request: 75s
    backendRequest: 75s

route.gatewayNamespace must match where the platform Gateway lives. This series uses lab/platform namespace kgateway-system (kgateway Helm install). If your platform uses another NS, set the value accordingly—do not invent a chart default.

The chart does not create Gateway, GatewayClass, or kgateway policies. Those stay platform-owned (or separate manifests). Chart HTTPRoute is a single hostname + single path match per release—see Gateway API examples.

helm repo add universal https://chaser100.github.io/u-helm-chart
helm repo update
helm template app-ingress universal/application --version 0.4.3 -f values-ingress.yaml | rg -n 'kind: Ingress|host:'
helm template app-route universal/application --version 0.4.3 -f values-route.yaml | rg -n 'kind: HTTPRoute|parentRefs|hostname'

Ownership and TLS

• Ingress TLS — ingress.tls[].secretName on the Ingress object (often app-namespace Secret).
• Gateway TLS — typically on the Gateway listener (certificateRefs); HTTPRoute attaches to sectionName for the HTTPS listener. App values only need the correct route.gateway / sectionName. Provision the Secret out-of-band (cert-manager, External Secrets, or sealed)—never commit PEM material.
• Cross-namespace — if the Gateway rejects attachments, check allowedRoutes and any required ReferenceGrant. This is platform config, not a chart flag.

Status checks

# Gateway (platform NS)
kubectl get gateway -n kgateway-system
kubectl describe gateway -n kgateway-system external
# Expect: Accepted=True and Programmed=True

# Ingress
kubectl describe ingress -n apps app
# HTTPRoute (portable parent conditions)
kubectl get httproute -n apps
kubectl describe httproute -n apps app
# Expect parents: Accepted=True, ResolvedRefs=True
kubectl get httproute -n apps app -o jsonpath='{.status.parents}' ; echo

Battle-test evidence: twelve HTTPRoutes reported Accepted=True and ResolvedRefs=True through an external kgateway Gateway with wildcard TLS. Always confirm the Gateway itself is Programmed=True before blaming the chart HTTPRoute.

When to stay on Ingress

• Controller and annotation set are frozen, and migration cost exceeds benefit.
• You need an annotation with no Gateway API or implementation equivalent yet—document the gap; do not invent parity.
• Cluster has no Gateway API CRDs / controller—chart route.enabled=true will render YAML that cannot reconcile.

Migration decision checklist

1. Inventory Ingresses, classes, TLS secrets, and annotations (portable vs controller-specific).
2. Install Gateway API CRDs + choose implementation (here: kgateway); create shared Gateway listeners.
3. Convert with review—do not blind-apply (Ingress NGINX → kgateway).
4. Flip app values from ingress.enabled to route.* (or dual-publish briefly).
5. Validate status + curl; keep rollback to Ingress until cutover is proven.

Security and failure modes

• Overly broad allowedRoutes on a Gateway → route hijack risk across namespaces.
• Wildcard HTTPRoute hostnames (or overly broad matches) can steal traffic from more specific app routes—prefer exact hostnames on app routes.
• Dual Ingress + HTTPRoute on the same host without a plan → split-brain traffic.
• Secrets in Git: never; use external secret refs for TLS material.
• Chart limitation: no header match / rewrite / redirect filters in route.*—put those on reviewed HTTPRoute extras or kgateway policies, not fake values keys.

Known limitations

• One path match per chart release via route.path / route.pathMatchType.
• Weighted canaries with multiple backends need multi-backendRefs HTTPRoutes or separate releases—chart exposes a single backendWeight on one Service.
• Annotation parity with ingress-nginx is incomplete by design; see kgateway migration docs for what maps to portable filters vs TrafficPolicy.

Next: Ingress NGINX to kgateway → · Route conversions → · Chart HTTPRoute values → · Gateway API docs