Gateway API adoption and migration — from Ingress to Gateway API

Migrating from Ingress to Gateway API is a significant change. The migration path is: install the Gateway API CRDs, install the controller, create the GatewayClass, create the Gateways, migrate the Ingresses to HTTPRoutes, verify the traffic, and remove the Ingress controller. This lesson walks the migration path, the coexistence patterns, and the operational discipline.

The migration path

The migration path:

flowchart TD
    A[Install Gateway API CRDs] --> B[Install Gateway controller]
    B --> C[Create GatewayClass]
    C --> D[Create Gateways]
    D --> E[Test in staging]
    E --> F[Migrate by namespace]
    F --> G[Verify traffic]
    G --> H[Remove Ingress controller]

The migration is a sequence of steps. Each step must be verified before the next.

Step 1: Install the Gateway API CRDs

The Gateway API CRDs are the custom resources:

kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.0.0/standard-install.yaml

The CRDs include GatewayClass, Gateway, HTTPRoute, TCPRoute, UDPRoute, TLSRoute, and GRPCRoute.

Step 2: Install the Gateway controller

The controller implements the Gateway API:

kubectl apply -f https://example.com/gateway-controller.yaml

The controller is the data plane. The cluster operator must verify the controller’s installation.

Step 3: Create the GatewayClass

The GatewayClass is the cluster-wide controller reference:

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: nginx
spec:
  controllerName: gateway.nginx.org/nginx

The GatewayClass is created by the infrastructure provider.

Step 4: Create the Gateways

The Gateway is the load balancer instance:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: prod-gateway
  namespace: prod-app
spec:
  gatewayClassName: nginx
  listeners:
    - name: http
      port: 80
      protocol: HTTP
      allowedRoutes:
        namespaces:
          from: Same

The Gateway is created by the cluster operator.

Step 5: Test in staging

The migration must be tested in staging before production:

kubectl apply -f staging-test.yaml

The test must cover the same use cases as the production workloads.

Step 6: Migrate by namespace

The migration is staged by namespace:

kubectl apply -f app-route.yaml

The application developer creates the HTTPRoute. The cluster operator verifies the route is bound.

Step 7: Verify the traffic

The traffic must be verified after the migration:

curl -H "Host: billing.example.com" http://gateway-ip/

The verification must cover the same use cases as the Ingress.

Step 8: Remove the Ingress controller

The Ingress controller is removed after the migration is complete:

kubectl delete -f ingress-controller.yaml

The removal is the last step. The migration is complete.

The coexistence patterns

The Ingress and Gateway API can coexist:

flowchart LR
    A[External client] --> B[LoadBalancer]
    B --> C[Ingress controller]
    B --> D[Gateway controller]
    C --> E[Service A]
    D --> F[Service B]

The Ingress controller handles the old Ingresses; the Gateway controller handles the new HTTPRoutes. The coexistence is supported by the load balancer.

The failure modes

The migration’s failure modes:

• CRDs missing: the Gateway API CRDs are not installed. The fix is to install the CRDs.
• Controller missing: the Gateway controller is not installed. The fix is to install the controller.
• GatewayClass missing: the GatewayClass is not created. The fix is to create the GatewayClass.
• Routing mismatch: the HTTPRoute routes to the wrong backend. The fix is to verify the HTTPRoute.
• Traffic loss: the migration causes traffic loss. The fix is to verify the Listener’s IP.

The operational discipline

The migration’s operational discipline:

• Document the migration path. The migration path is the cluster’s operational reference.
• Test the migration in staging. The migration must work for the workload.
• Migrate by namespace. The migration is staged to minimise the blast radius.
• Verify the traffic. The verification must cover the same use cases.
• Document the troubleshooting. The troubleshooting is the cluster’s operational reference.
• Plan the migration’s evolution. The migration is the cluster’s evolution to Gateway API.

Quiz

Production discipline

• The migration is a significant change. The cluster operator must plan the migration.
• Document the migration path. The migration path is the cluster’s operational reference.
• Test the migration in staging. The migration must work for the workload.
• Migrate by namespace. The migration is staged to minimise the blast radius.
• Verify the traffic. The verification must cover the same use cases.
• Document the troubleshooting. The troubleshooting is the cluster’s operational reference.
• Plan the migration’s evolution. The migration is the cluster’s evolution to Gateway API.
• Train the teams on the migration. The teams must understand the migration path.
• Document the migration’s design. The migration is the cluster’s evolution; the documentation is the reference.