Publishing through Gateway API

Overview

By default Deckhouse Optics publishes its components through Ingress resources served by the ingress-nginx module. Starting from version 1.15 the platform can also publish the same components through Gateway API, served by the alb module.

Both mechanisms run at the same time and serve the same hostnames from different addresses, so the switch takes no downtime: bring the gateway up next to the running Ingress, verify it, then move DNS.

Until you point the platform at a Gateway, no Gateway API resources are created and nothing changes for an existing installation.

Prerequisites

• Deckhouse Kubernetes Platform 1.76 or newer.
• The alb module 0.14.1 or newer.

Migration steps

1. Enable the alb module:

   apiVersion: deckhouse.io/v1alpha1
   kind: ModuleConfig
   metadata:
     name: alb
   spec:
     enabled: true
     version: 1
     source: deckhouse

2. Create a gateway — see the alb module documentation for how. The example below uses a cluster-wide instance with its own load balancer:

   apiVersion: network.deckhouse.io/v1alpha1
   kind: ClusterALBInstance
   metadata:
     name: public
   spec:
     gatewayName: public-gw
     inlet:
       type: LoadBalancer
       loadBalancer: {}
     defaultDeckhouseGateway: true

   defaultDeckhouseGateway: true makes this gateway the cluster default, and Deckhouse modules pick it up automatically. To point the platform at a specific gateway instead, set gatewayAPIGateway in the global module configuration:

   apiVersion: deckhouse.io/v1alpha1
   kind: ModuleConfig
   metadata:
     name: global
   spec:
     version: 2
     settings:
       modules:
         gatewayAPIGateway:
           name: public-gw
           namespace: d8-alb

3. Check that the platform created its Gateway API resources and that they were accepted:

   d8 k -n d8-observability-platform get listenerset,httproute,grpcroute

   The ListenerSet must be ACCEPTED=True and PROGRAMMED=True, and every route must have a parent that accepted it. If the list is empty, the platform did not find a Gateway: re-check step 2.

4. Look up the external address of the gateway. A LoadBalancer service can publish either an IP address or a hostname:

   d8 k -n d8-alb get svc -l alb.deckhouse.io/gateway=public-gw --field-selector spec.type=LoadBalancer -o jsonpath='{range .items[0].status.loadBalancer.ingress[*]}{.ip}{.hostname}{"\n"}{end}'

   Take the address from the load balancer service, not from the Gateway status: status.addresses holds the in-cluster name of the gateway (public.d8-alb.svc.cluster.local), not its external address.

5. Before changing DNS, send requests to the load balancer address while preserving the platform hostname for TLS and routing. For example, check the web interface hostname (replace both values with those from your installation):

   PLATFORM_HOST=dop.example.com
   GATEWAY_ADDRESS=203.0.113.10
   curl --verbose --connect-to "${PLATFORM_HOST}:443:${GATEWAY_ADDRESS}:443" "https://${PLATFORM_HOST}/"

   If the service publishes a load balancer hostname, resolve it to an IP address and use that IP as GATEWAY_ADDRESS. Confirm that the certificate is valid for the requested hostname and that the response has the status and content expected from the platform. Repeat the check for the API hostnames and paths that your agents use. These checks exercise TLS termination and HTTP routing, but do not replace the post-cutover checks for metrics, logs, and traces.

6. Replace the platform DNS records with the load balancer address. Keep the Ingress controller running: while DNS is propagating, part of the traffic still goes through it.

7. Check on the graphs that the traffic moved from Ingress to the gateway: requests to the platform hostnames disappear on the Ingress controller and show up on the gateway. Verify that the web interface opens, that agents keep delivering metrics and logs, and that traces are still accepted.

Rolling back

The steps are reversible at any point.

To move the traffic back to Ingress, point the DNS records back at the Ingress controller address: the platform’s Ingress resources never went away and start serving traffic again.

To turn the Gateway API mode off, remove modules.gatewayAPIGateway from the global module configuration and make sure that no gateway is selected automatically (for example, set defaultDeckhouseGateway: false on the ClusterALBInstance). The platform then deletes the Gateway API resources it created.