Skip to main content

Ingress (NGINX) to Gateway API Migration

The community-maintained Ingress NGINX controller (kubernetes/ingress-nginx) is being officially retired by the Kubernetes SIG Network and Security Response Committee.

  • The project has moved to best-effort maintenance mode
  • Only bug fixes and security updates will continue
  • Support is expected to continue until March 2026

In light of this, the Kubernetes community has been actively developing and promoting the Gateway API as the modern, extensible successor to Ingress for Kubernetes traffic management.

Adapting to this shift, as part of the Witboost v2.9.0 upgrade or installation, you can now choose to deploy either the Gateway API or continue using Ingress for traffic management. By default, Ingress remains enabled and Gateway is disabled to preserve existing behavior. If you wish to enable Gateway API, ensure you complete the required pre-requisites outlined below before switching from Ingress to Gateway as the default

Configure Gateway API​

This can be controlled via Witboost Helm chart's configuration values.

global:
  # -- Ingress Configuration for all components
  ingress:
    # -- Enable the creation of Ingress resources for all components
    create: false

  # -- Gateway Configuration for all components
  gateway:
    # -- Enable the creation of Gateway resources for all components
    create: true
    # -- Reuse an existing Gateway instead of creating one. `gateway.useExisting` has precedence over `gateway.create`
    useExisting: false
    # -- Name of the Gateway to use
    name: witboost-gateway
    # -- gateway class name
    gatewayClassName: nginx
    # -- Additional custom annotations for the Gateway
    annotations:
      cert-manager.io/cluster-issuer: <your-cluster-issuer>
    # -- Additional custom labels for the Gateway
    labels:
      app.kubernetes.io/name: shared-gateway
      app.kubernetes.io/part-of: platform

warning

Before applying this configuration, make sure that you have read the following pre-requisites.

Pre-requisites​

This section of document outlines the mandatory pre-requisites and configuration updates required when choosing to deploy Kubernetes Gateway API instead of traditional Ingress as part of Witboost deployment upgrade/installation.

Install Gateway API CRDs​

Gateway API resources are not installed by default in Kubernetes clusters.

Follow the official installation guide: https://gateway-api.sigs.k8s.io/guides/getting-started/#installing-gateway-api

Typical Installation (Example: v1.1.0)​

Standard CRDs:

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

Experimental CRDs (required by some controllers):

kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.1.0/experimental-install.yaml
Verify Installation​
kubectl get crds | grep gateway.networking.k8s.io

Expected resources include:

  • gateways.gateway.networking.k8s.io
  • httproutes.gateway.networking.k8s.io
  • referencegrants.gateway.networking.k8s.io
  • etc.

Install a Gateway Controller​

Installing CRDs alone is not sufficient. You must install a Gateway controller that implements the Gateway API specification.

Official controller installation guidance: https://gateway-api.sigs.k8s.io/guides/#installing-a-gateway-controller

This page lists multiple supported controllers (NGINX, Istio, Kong, Traefik, etc.) and their official documentation links.

Example Controller Deployment​

For demonstration, we use NGINX Gateway Fabric deployed via Helm (OCI chart).

helm install nginx-gateway \
oci://ghcr.io/nginxinc/charts/nginx-gateway-fabric \
 --namespace gatewayapi \
 --create-namespace

After installation, verify controller pods:

kubectl get pods -n gatewayapi
‼️ If you are using cert-manager and/or external-dns, additional steps are required

Upgrade cert-manager (Enable Gateway Support)​

To allow cert-manager to monitor Gateway resources and automatically generate certificates, the Gateway API feature must be enabled.

By default, cert-manager watches Ingress resources. For Gateway API deployments, it must:

  • Watch Gateway resources
  • Use the Gateway shim
  • Support Gateway-based HTTP01 solvers
Example Upgrade Command​
helm upgrade cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --set installCRDs=false \
  --set config.apiVersion="controller.config.cert-manager.io/v1alpha1" \
  --set config.kind="ControllerConfiguration" \
  --set config.enableGatewayAPI=true \
  --version v1.19.x

  • When using Helm (as in the example in this document), you must deploy at least cert-manager v1.15 or later in order to use:

    --set config.apiVersion="controller.config.cert-manager.io/v1alpha1" \
    --set config.kind="ControllerConfiguration" \
    --set config.enableGatewayAPI=true

    This Helm configuration enables the Gateway API watcher in the cert-manager controller.

  • Versions earlier than v1.15 do not natively support this configuration and will not function as expected for Gateway API certificate provisioning.

💡 In practice, using recent stable versions (e.g., v1.19.x or newer) ensures better compatibility with today’s Gateway API CRDs and ACME HTTP-01 challenges via Gateway resources.

Upgrade / Configure External-DNS​

External-DNS must be configured to detect Gateway HTTPRoute resources, not just Ingress. Gateway API uses HTTPRoute objects instead of Ingress for routing. Without this update DNS records will not be created for Gateway-managed routes.

Example Upgrade Command (AWS Cloud Provider)​

helm upgrade --install external-dns external-dns/external-dns \
  --namespace <namespace> \
  --set provider=aws \
  --set region=<region> \
  --set 'sources[0]=gateway-httproute' \
  --set 'sources[1]=ingress' \
  --set 'domainFilters[0]=<domain>'

Gateway-specific ClusterIssuer​

When using Gateway API, it is recommended that a separate ClusterIssuer is created with a Gateway-based solver.

Why Separate Issuer?​

Traditional Ingress solver:

http01:
  ingress:

Gateway-specific solver:

http01:
  gatewayHTTPRoute:

These two solver types are not interchangeable.

Gateway ClusterIssuer Example​

Below is a minimal example of a Gateway API–based ClusterIssuer in cert-manager using ACME (e.g., Let’s Encrypt) with an HTTP-01 solver via Gateway API.

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-gateway
spec:
  acme:
    email: <admin@example.com>
    server: https://acme-v02.api.letsencrypt.org/directory
    privateKeySecretRef:
      name: letsencrypt-gateway
    solvers:
    - http01:
        gatewayHTTPRoute:
          parentRefs:
          - name: witboost-gateway
            namespace: <gateway-namespace>
            kind: Gateway

Important Notes​

  • parentRefs.name must match your deployed Gateway.
  • parentRefs.namespace must match the namespace where your Gateway is deployed.
  • Ensure Gateway listener supports HTTP (port 80) for ACME challenge.

Using an Existing Gateway – Hostname & Certificate Considerations​

If the customer is already using gateway APIs and the cluster is already configured with an existing Gateway, you can configure Witboost to use it, without creating it. When reusing an existing Gateway, additional care must be taken around hostname configuration and certificate issuance, especially when using cert-manager with the HTTP-01 solver.

Gateway Listener Hostname Is Mandatory for cert-manager​

Although the hostname field in a Gateway listener is optional for routing purposes:

cert-manager requires a non-empty hostname on TLS listeners to issue certificates.

If the Gateway listener does not define a hostname:

  • cert-manager will not issue certificates
  • TLS automation via HTTP-01 will fail

Hostname Matching Rules (Gateway ↔ HTTPRoute)​

For an HTTPRoute to attach to a Gateway:

  • At least one HTTPRoute hostname must match the Gateway listener hostname.
  • Non-matching hostnames are ignored.
  • If none match → the route is not accepted.

Example:

If Gateway listener:

*.example.com

Then valid HTTPRoute hostnames include:

  • test.example.com
  • foo.example.com

But non-matching domains are ignored.

Wildcard Hostname Strategy – Trade-offs​

One possible approach when reusing an existing Gateway is:

hostname: *.example.com

This simplifies route attachment across multiple subdomains.

However for ACME-based certificate authorities (e.g., Let’s Encrypt):

  • Wildcard certificates require DNS-01 validation
  • HTTP-01 validation does not support wildcards

This DNS-01 requirement applies to all ACME-based issuers.

Note : Other Certificate Authorities

Some environments may use traditional or enterprise public CAs that may:

  • Use different validation mechanisms
  • Allow wildcard certificate issuance outside ACME constraints
warning

Because customer CA choices may vary, behavior cannot be universally predicted. If customers are able to generate and manage wildcard certificates in their environment without issue, they may use a wildcard hostname on their Gateway. However, wildcard + DNS-01 approach has NOT been tested as of Witboost v2.9.0.