1. Documentation
×

Enable Gateway API

To route traffic using Gateway API, you must first enable the feature on your cluster. You can enable Gateway API by creating a GatewayClass custom resource, which triggers the Ingress Operator to provision the necessary controller and components.

After you successfully enable Gateway API, you can begin deploying gateways, assigning network addresses, and configuring listeners to control your network traffic flow.

Enable Gateway API for the Ingress Operator

To configure Gateway API for use on your cluster, you must create a GatewayClass resource. During the creation of the GatewayClass resource, the Ingress Operator installs a lightweight Istio control plane, based on Red Hat OpenShift Service Mesh, in the openshift-ingress namespace.

Prerequisites

  • You have access to the cluster as a user with the cluster-admin role.

  • You have installed the OpenShift CLI (oc).

Procedure

  1. Create a GatewayClass object:

    1. Create a YAML file, openshift-default.yaml, that contains the following information:

      Example GatewayClass CR
      apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: openshift-default
spec:
  controllerName: openshift.io/gateway-controller/v1

      • metadata.name: The name of your GatewayClass object. The name must consist of a maximum of 63 lowercase alphanumeric characters or hyphens (-). The name must also start and end with an alphanumeric character.

        The controllerName value must be exactly as shown for the Ingress Operator to manage it. If you set this field to anything else, the Ingress Operator ignores the GatewayClass object and all associated Gateway, GRPCRoute, and HTTPRoute objects. The controller name is tied to the implementation of Gateway API in OKD, and openshift.io/gateway-controller/v1 is the only controller name allowed.

    2. Run the following command to create the GatewayClass resource:

      $ oc create -f openshift-default.yaml
      Example output
      gatewayclass.gateway.networking.k8s.io/openshift-default created
Verification

  • Verify that the GatewayClass CR has been accepted and the controller is successfully installed by running the following command:

    $ oc get gatewayclass openshift-default -o yaml
    Example output
    # ...
status:
  conditions:
  - lastTransitionTime: "2026-05-15T10:00:00Z"
    message: The GatewayClass has been accepted
    reason: Accepted
    status: "True"
    type: Accepted
  - lastTransitionTime: "2026-05-15T10:00:00Z"
    message: Istio installed successfully
    reason: Installed
    status: "True"
    type: ControllerInstalled
  - lastTransitionTime: "2026-05-15T10:00:00Z"
    message: Istio CRDs are being managed by cluster-ingress-operator
    reason: ManagedByCIO
    status: "True"
    type: CRDsReady
# ...

    Inspect the status.conditions block in the output. A healthy GatewayClass CR reports a status of True for the Accepted, ControllerInstalled, and CRDsReady conditions.