k8wiz
Back to Articles

Ready to test your Kubernetes knowledge? Try our Kubernetes quiz!

Migrating from Ingress to Gateway API in Kubernetes

Kubernetes Ingress handles external HTTP/HTTPS access but lacks advanced features like traffic splitting. Gateway API is its successor, offering better portability, extensibility, and role separation for teams. This guide covers migration steps, tools, and changes.

3 min read
By k8wiz Team
kubernetesingressgatewayciliumnginx

Key Differences

AspectIngressGateway API
RoutingBasic host/path; annotations for extras.Native traffic splitting, headers, redirects.
ExtensibilityController-specific annotations.Filters, policies; no annotations.
ResourcesSingle Ingress object.Gateway (entry points), HTTPRoute (rules).
PersonasOne user manages all.Separate roles: developer, operator.
ProtocolsHTTP/HTTPS only.Adds TCP/UDP support.

Gateway API avoids vendor lock-in and supports multi-team clusters.

Prerequisites

  • Kubernetes v1.24 or later.
  • Backup existing Ingress setups.
  • Install Gateway API CRDs: kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.3.0/standard-install.yaml (or specify the latest version ).
  • Choose a Gateway implementation (e.g., Envoy, NGINX, Cilium).
  • Install the chosen controller.
  • Test in a non-production environment.
  • Have Ingress resources ready for conversion.

Migration Steps

You can migrate manually or use tools. Run Ingress and Gateway API in parallel for zero-downtime.

Step 1: Install Gateway API

  • Apply CRDs as above.
  • Deploy a GatewayClass (provided by your controller, e.g., prod).

Step 2: Choose Conversion Method

Option A: Use ingress2gateway Tool

  • Install: go install github.com/kubernetes-sigs/ingress2gateway@v0.1.0 (check for updates).
  • Run: ingress2gateway print to convert Ingress to Gateway/HTTPRoute YAML.
  • Review output: Check for unsupported features.
  • Apply: kubectl apply -f output.yaml.
  • Supports general Ingress; extensions for NGINX, etc.

Option B: Manual Conversion

  1. Create Gateway resource:

    • Define listeners (HTTP port 80, HTTPS port 443).
    • Set TLS: Reference Secrets in tls.certificateRefs.
    • Specify allowed hostnames (e.g., *.example.com).

  2. Create HTTPRoute resources:

    • One per hostname or group.
    • Set parentRefs to link to Gateway.
    • Define rules: Matches (path/host), backendRefs (Services).
    • Add filters for redirects (e.g., HTTP to HTTPS).

  3. Handle defaults:

    • Explicitly route / for default backends.
    • Move annotations to native filters (e.g., redirect via RequestRedirect).

  4. For TLS redirect:

    • Separate HTTPRoute for HTTP listener.
    • Use filter to redirect to HTTPS.

Step 3: Apply and Configure

  • Apply new resources: kubectl apply.
  • Update DNS to point to new Gateway IP (get via kubectl get gateway).
  • Handle non-Service backends via BackendObjectReference.

Testing and Validation

  • Send test traffic to new Gateway.
  • Verify routing, TLS, and features.
  • Monitor logs for errors.
  • Use kubectl get httproute to check status.
  • Test failover: Switch traffic gradually.

Cleanup

  • Once verified, delete old Ingress resources.
  • Remove unused controllers if switching.
  • Update CI/CD pipelines for Gateway API.

Potential Challenges

  • Missing features: Some annotations need custom policies.
  • Complexity: More resources to manage.
  • Run both APIs side-by-side during transition.

References

Ready to test your Kubernetes knowledge? Try our Kubernetes quiz!