Course outline

01 · Kubernetes Architecture Deep Dive

02 · Workloads & Scheduling

03 · Networking, Storage & Service Mesh

04 · Platform Engineering & Multi-Tenancy

05 · Networking & Service Mesh

06 · Observability & Autoscaling

07 · Configuration & Secrets Management

08 · Stateful Storage Operations

09 · Security, Identity & Admission

10 · Release Packaging with Helm & Kustomize

11 · Operators, CRDs & Controllers

12 · Production Troubleshooting & Operations

Stage 5 · Platform

Networking & Service Mesh

Ingress & Gateway API

NGINX, Envoy Gateway, HTTPRoute, TLS termination, and multi-tenant routing.

8 min readKubernetes & Cloud NativePlatform

Ingress Limitations

Kubernetes Ingress has limitations: it only handles HTTP/HTTPS, lacks TCP/UDP support, has no standard annotation format, and doesn't support advanced traffic management. Gateway API was created to address these shortcomings with a richer, role-oriented API.

Feature	Ingress	Gateway API
Protocols	HTTP/HTTPS only	HTTP, gRPC, TCP, UDP, TLS
Traffic splitting	No (annotations only)	Yes (HTTPRoute)
Header matching	No	Yes
Role separation	Single resource	GatewayClass, Gateway, Route
Cross-namespace	No	Yes (ReferenceGrant)

Gateway API Overview

Gateway API introduces three core resource types: GatewayClass (infrastructure provider), Gateway (listener configuration), and Route (traffic routing rules). This separation of concerns lets platform teams manage infrastructure while app teams manage routing.

GatewayClass definition


apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: envoy-gateway
spec:
  controllerName: gateway.envoyproxy.io/gatewayclass-controller
  parametersRef:
    group: gateway.envoyproxy.io
    kind: EnvoyProxy
    name: custom-config
---
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyProxy
metadata:
  name: custom-config
  namespace: infra
spec:
  provider:
    type: Kubernetes
    envoyGateway:
      gateway:
        envoyDeployment:
          replicas: 3
          container:
            resources:
              requests:
                cpu: "500m"
                memory: "512Mi"

GatewayClass defines which controller handles Gateways. The parametersRef points to controller-specific configuration. Platform teams manage GatewayClass; app teams create Gateways and Routes.

HTTPRoute

HTTPRoute defines routing rules for HTTP traffic: host matching, path matching, header matching, request transformation, and traffic splitting. Routes attach to Gateways and can span namespaces using ReferenceGrant.

HTTPRoute with path and header matching


apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: api-routes
  namespace: production
spec:
  parentRefs:
  - name: production-gateway
    namespace: infra
  hostnames:
  - "api.example.com"
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /v1
      headers:
      - name: x-api-version
        value: "1"
    backendRefs:
    - name: api-v1
      port: 80
  - matches:
    - path:
        type: PathPrefix
        value: /v2
    backendRefs:
    - name: api-v2
      port: 80
  - matches:
    - path:
        type: PathPrefix
        value: /
    filters:
    - type: RequestHeaderModifier
      requestHeaderModifier:
        add:
        - name: x-forwarded-by
          value: gateway
    backendRefs:
    - name: api-default
      port: 80

HTTPRoute matches requests by path and headers. The first rule matches /v1 with x-api-version: 1 header. Filters modify requests before forwarding. Multiple backendRefs enable traffic splitting.

TLS Termination

Gateway API supports TLS termination at the Gateway. TLS certificates are stored in Kubernetes Secrets and referenced in the Gateway listener. Multiple TLS configurations support different hostnames and protocols.

Gateway with TLS termination


apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: production-gateway
  namespace: infra
spec:
  gatewayClassName: envoy-gateway
  listeners:
  - name: https
    protocol: HTTPS
    port: 443
    tls:
      mode: Terminate
      certificateRefs:
      - name: api-tls-cert
        namespace: infra
      options:
        gateway.envoyproxy.io/minimum-tls-version: "1.3"
    allowedRoutes:
      namespaces:
        from: Selector
        selector:
          matchLabels:
            shared-gateway: "true"
  - name: http
    protocol: HTTP
    port: 80
    allowedRoutes:
      namespaces:
        from: Selector
        selector:
          matchLabels:
            shared-gateway: "true"

The Gateway listens on 443 (HTTPS) and 80 (HTTP). TLS terminates at the Gateway — backend traffic is plain HTTP. allowedRoutes with namespace selector controls which namespaces can attach Routes to this listener.

Cross-namespace routing with ReferenceGrant

Routes in one namespace can attach to Gateways in another namespace using ReferenceGrant. This lets app teams manage their own Routes while sharing a central Gateway managed by the platform team.

Multi-Tenant Routing

Gateway API supports multi-tenant routing by allowing multiple namespaces to attach Routes to a shared Gateway. Each namespace manages its own Routes while the platform team manages the Gateway and TLS certificates.

ReferenceGrant for cross-namespace routing


apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  name: allow-team-alpha
  namespace: infra
spec:
  from:
  - group: gateway.networking.k8s.io
    kind: HTTPRoute
    namespace: team-alpha
  to:
  - group: ""
    kind: Service
    namespace: team-alpha

ReferenceGrant in the infra namespace allows HTTPRoutes from team-alpha to reference Services in team-alpha through the Gateway. Without this ReferenceGrant, cross-namespace references are blocked.

NGINX vs Envoy Gateway

NGINX Ingress Controller is mature and widely used. Envoy Gateway is the official Gateway API implementation for Envoy. Both support Gateway API, but Envoy Gateway provides more advanced features: rate limiting, authentication, and observability.

Feature	NGINX Ingress	Envoy Gateway
Maturity	Very mature	Newer but stable
Performance	Good	Excellent (eBPF)
Advanced routing	Annotations	Native Gateway API
Extensibility	Lua plugins	Wasm/ExtProc
Observability	Basic metrics	Full Envoy telemetry

Migrate from Ingress to Gateway API

Start by deploying Gateway API alongside Ingress. Use the Ingress2Gateway tool to convert existing Ingress resources to HTTPRoute. Gradually migrate namespaces, testing each one before moving to the next.

Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.