#The Glossary

1. GatewayClass (The Implementation): a cluster-scoped resource that represents a class of Gateways. Similar role to IngressClass

2. Gateway (The Entry Point): the actual entry point (listeners, ports, TLS).

3. HTTPRoute (The Routing Rules): routing rules (matches, filters, backends).

That split is the point: it lets you centralize the “shared edge” configuration while still letting teams ship and change their own routes safely.

#The managed GKE route

If you are on Google Kubernetes Engine and want a fully managed experience, use the GKE Gateway Controller.

• Target Class: gke-l7-global-external-managed
• What it does: Deploys a Global External Application Load Balancer.

#Feature Mapping: Nginx Ingress to Gateway API

Gateway API gives you standard shapes for things like rewrites and redirects, but the exact behavior still depends on your controller and its supported filter set. Treat this mapping as a starting point, then verify each feature against your controller docs (and your own tests), especially for auth, rate limiting, and anything that used to rely on custom snippets.

A Note on Snippets: If you rely on configuration-snippet (raw NGINX directives/Lua), there’s no portable Gateway API translation. You’ll need to replace it with native Gateway API features where possible, or use your controller’s extension mechanism (policy attachments/custom filters—often Wasm/Lua/ext-proc depending on the implementation), or move the logic to another layer (edge/WAF/mesh/app).

#Step 1: Install & Enable

Ensure the Gateway API CRDs are installed in your cluster. On GKE Standard, enable the Gateway API feature; on GKE Autopilot, it is enabled by default.

#Step 2: Create the Gateway

Apply your Gateway manifest. This provisions the load balancer and wires up the entry point.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: gke-external-eu
spec:
  gatewayClassName: gke-l7-global-external-managed
  listeners:
  - name: http
    protocol: HTTP
    port: 80

Validation: kubectl get gateway — wait for PROGRAMMED=True and an External IP.

#Step 3: Start Small (The "Canary App" Strategy)

Do not migrate your most critical production service first.

Pick a "low-risk" candidate for your first conversion. Good candidates include:

• Internal admin tools (where downtime is annoying but not fatal).
• Staging/Development environments.
• A read-only marketing site.

Take this non-critical Ingress resource and convert it to an HTTPRoute. (See the "Concrete Conversions" section below).

• Tip: It is safe for a Service to accept traffic from both Ingress and Gateway simultaneously.

#Step 4: Test the New Path

Use curl to hit the new Gateway IP address directly, passing the Host header manually to verify routing without changing DNS.

curl -H "Host: app.example.com" http://<NEW_GATEWAY_IP>/api

#Step 5: The DNS Cutover

Once validated, update your DNS provider to point app.example.com to the new Gateway IP.

#Step 6: Monitor & Cleanup

During parallel-run you need a clean way to tell “Ingress traffic” from “Gateway traffic” in your logs and traces.

A simple trick is to inject a header on the Gateway path (or add a distinct label/attribute at the edge if your controller supports it). Then you can compare latency/error rate between the two paths without guessing.

Observability Tip: Pydantic Logfire can capture request headers as attributes, which makes it easy to filter/group by traffic source.

How to Configure Header Injection:

Add the RequestHeaderModifier filter to your HTTPRoute:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: api-route
spec:
  parentRefs:
  - name: gke-external-eu
  hostnames: ["app.example.com"]
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /api
    filters:
    - type: RequestHeaderModifier
      requestHeaderModifier:
        add:
        - name: X-Gateway-ID
          value: gke-external-eu
    backendRefs:
    - name: api
      port: 80

Your app will receive these headers on requests that come through the Gateway. In our example, we use Logfire httpx instrumentation to capture headers and we see them as http.request.header.* attributes. You can then create dashboards to compare latency histograms, error rates, and throughput side-by-side between your Ingress and Gateway API paths.

🔍 Live Example: RequestHeaderModifier in Action

We've used Logfire Public Traces so you can see exactly how this works:

👉 View the Live Logfire Trace

This trace shows a request routed through Gateway API. In the live view, you can:

• See the X-Gateway-ID header (gke-external-eu) in the request attributes
• Explore the complete user session with multiple API calls
• View latency metrics for each span

Dashboard Comparison:

Live comparison of Ingress vs Gateway API traffic in Logfire. Click image to view full size. Learn more about creating dashboards and querying traces in the Logfire documentation.

The Cutover: If the new path is stable for a confidence window (e.g., 24 hours), remove the old Ingress resource.

Validation Commands:

• kubectl get gateway,httproute -A
• kubectl describe gateway <name> (Check for attached routes)
• kubectl describe httproute <name> (Check for "Accepted" / "ResolvedRefs" conditions)

#Conversion 1: Host + PathPrefix Routing (Basic, Portable)

Ingress Version

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: app
spec:
  rules:
  - host: app.example.com
    http:
      paths:
      - path: /api
        pathType: Prefix
        backend:
          service:
            name: api
            port:
              number: 80

Gateway + HTTPRoute Version

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: external
spec:
  gatewayClassName: gke-l7-global-external-managed # Specific to GKE
  listeners:
  - name: http
    protocol: HTTP
    port: 80
    hostname: app.example.com
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: api-route
spec:
  parentRefs:
  - name: external
  hostnames: ["app.example.com"]
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /api
    backendRefs:
    - name: api
      port: 80

Note: If the route doesn't attach, check kubectl describe httproute. A common error is a mismatch between the hostname in the Route and the Gateway listener.

#Conversion 2: TLS (HTTPS) Termination

Ingress Version (TLS)

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: app-https
spec:
  tls:
  - hosts:
    - app.example.com
    secretName: app-tls
  rules:
  - host: app.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: web
            port:
              number: 80

Gateway (HTTPS Listener) + HTTPRoute

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: external-https
spec:
  gatewayClassName: gke-l7-global-external-managed
  listeners:
  - name: https
    protocol: HTTPS
    port: 443
    hostname: app.example.com
    tls:
      mode: Terminate
      certificateRefs:
      - kind: Secret
        name: app-tls
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: web-route
spec:
  parentRefs:
  - name: external-https
  hostnames: ["app.example.com"]
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /
    backendRefs:
    - name: web
      port: 80

GKE Callout: This configuration deploys a Google Global External Application Load Balancer with an HTTPS frontend, referencing your Kubernetes Secret for the SSL cert (supported patterns vary by controller and setup).

#Conversion 3: Redirect (HTTP → HTTPS)

Ingress Version (Annotation-based)

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: app
  annotations:
    nginx.ingress.kubernetes.io/force-ssl-redirect: "true"
spec:
  rules:
  - host: app.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: web
            port:
              number: 80

Gateway API (HTTPRoute Redirect Filter)

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: http-to-https
spec:
  parentRefs:
  - name: external   # your HTTP (port 80) Gateway/listener
  hostnames: ["app.example.com"]
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /
    filters:
    - type: RequestRedirect
      requestRedirect:
        scheme: https
        statusCode: 301

Note: Ingress annotations are not portable; Gateway API moves this into a standardized field.

#"Why doesn't my HTTPRoute attach?"

Check ParentRefs, namespace boundaries (need ReferenceGrant?), and hostname alignment. Use kubectl describe httproute <name> to see conditions.

#"Can multiple teams own routes safely?"

Yes, this is a core design principle. Think of a shared Gateway with root domain and TLS configuration, with multiple routes from specific hostnames (e.g *.mydomain.com at Gateway, admin.domain.com HTTPRoute) Use ReferenceGrant for cross-namespace attachment.

#"Do I still need Ingress?"

After verifying no traffic flows through it and your confidence window passes, you don't need it anymore.

#"What if I need to rollback?"

Before deleting Ingress: revert DNS to old IP (1-5 minutes). After deleting: reapply Ingress YAML, wait for provisioning (~10 min), update DNS.