Chapter 3. Configuring Gateway API

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.

        Important

        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 OpenShift Container Platform, 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

Procedure

1. Create or edit a Gateway YAML file to include your listener configuration.

   The following example demonstrates a Gateway CR with two listeners, one for HTTP and one for HTTPS. For detailed descriptions of the listener fields, see "Gateway listener configuration reference".

   kind: Gateway
   apiVersion: gateway.networking.k8s.io/v1
   metadata:
     name: <example_gateway>
     namespace: openshift-ingress
   spec:
     gatewayClassName: openshift-default
     listeners:
     - protocol: HTTP
       port: 80
       name: http
       hostname: "*.<example_domain.tld>"
       allowedRoutes:
         namespaces:
           from: Selector
           selector:
             matchLabels:
               env: "dev"
     - protocol: HTTPS
       port: 443
       name: https
       hostname: "*.<example_domain.tld>"
       tls:
         mode: Terminate
         certificateRefs:
           - name: <listener_cert>
             kind: Secret
       allowedRoutes:
         namespaces:
           from: Selector
           selector:
             matchLabels:
               env: "dev"

   With this configuration, only HTTPRoute resources in namespaces that have the env: "dev" label can attach to these listeners.

2. Apply the Gateway CR by running the following command:

   $ oc apply -f <gateway_cr>.yaml

Procedure

1. Check the status conditions of your Gateway custom resource (CR) by running the following command:

   $ oc describe gateway <gateway_cr> -n <namespace>

   • <gateway_cr>: Specify the name of your gateway.

   • <namespace>: Specify the namespace where the gateway resides.

     For details on how to interpret the output and resolve common errors, see Section 3.3.3.1, “Gateway listener troubleshooting reference”.

Procedure

1. Create a YAML file, such as hello-gateway.yaml, that defines your Gateway object.

   apiVersion: gateway.networking.k8s.io/v1
   kind: Gateway
   metadata:
     name: sample-gateway
     namespace: openshift-ingress
   spec:
     gatewayClassName: openshift-default
     listeners:
     - name: http
       hostname: "*.gwapi.<cluster_domain>"
       port: 80
       protocol: HTTP
       allowedRoutes:
         namespaces:
           from: Selector
           selector:
             matchLabels:
               shared-gateway-access: "true"

   • metadata.name: Specify the name of your Gateway 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.
   • spec.gatewayClassName: Specify the GatewayClass object whose controller provisions the address and populates the status.addresses field.
   • spec.listeners[].hostname: Specify the listener hostname. Replace <cluster_domain> with your actual cluster ingress domain (for example, example.com). Setting a hostname limits which route hostnames can match this listener.
   • spec.listeners[].allowedRoutes.namespaces: Allow route attachment only from namespaces that have the shared-gateway-access: "true" label.

2. Apply the Gateway configuration by running the following command:

   $ oc apply -f hello-gateway.yaml

3. Verify that the controller automatically assigned an address to your gateway by running the following command:

   $ oc -n openshift-ingress get gateway sample-gateway

   Example output

   NAME             CLASS               ADDRESS             PROGRAMMED   AGE
   sample-gateway   openshift-default   <gateway_address>   True         6m16s

   The ADDRESS column in the output displays the dynamically provisioned network address for your gateway.

Procedure

1. Create or edit your Gateway CR to include the cloud-specific annotation under spec.infrastructure.annotations.

   The following example provisions an internal load balancer for an AWS cluster:

   Example Gateway CR for an AWS internal load balancer

   apiVersion: gateway.networking.k8s.io/v1
   kind: Gateway
   metadata:
     name: mygateway
     namespace: openshift-ingress
   spec:
     gatewayClassName: openshift-default
     infrastructure:
       annotations:
       # Specifies the cloud provider annotation and value required to provision an internal load balancer:
         service.beta.kubernetes.io/aws-load-balancer-internal: "true"
     listeners:
     - name: https
       hostname: "*.example.com"
       port: 443
       protocol: HTTPS
       tls:
         mode: Terminate
         certificateRefs:
         - name: gateway-tls-secret
   # ...

2. Apply the updated Gateway CR by running the following command:

   $ oc apply -f <gateway_filename>.yaml

Procedure

1. Retrieve the external IP address assigned to your gateway by the load balancer by running the following command:

   $ oc -n openshift-ingress get gateway <gateway_name>

   Note the IP address listed in the ADDRESS column.

2. Access your organization’s DNS provider or server.
3. Create a DNS record, such as an A record or wildcard A record, that maps the listener’s hostname to the external IP address of your gateway.

Procedure

1. Create an HTTPRoute CR file that references your parent gateway, application hostnames, and backend service, and save it as httproute.yaml:

   apiVersion: gateway.networking.k8s.io/v1
   kind: HTTPRoute
   metadata:
     name: sample-route
     namespace: my-application
   spec:
     parentRefs:
     - name: generic-gateway
       namespace: openshift-ingress
     hostnames:
     - app1.example.com
     - app2.example.com
     rules:
     - backendRefs:
       - name: application-backend
         port: 8080

   • You must include application hostnames and a backendRef rule that points to your backend service.
   • If your HTTPRoute and Gateway CRs are deployed in different namespaces, the Gateway CR listener must allow routes from the HTTPRoute namespace. You must configure the spec.listeners.allowedRoutes.namespaces field in the Gateway CR and specify a selector for trusted namespaces.
   • The listener hostname on the parent Gateway CR should cover the hostnames in your HTTPRoute CR. For example, a listener hostname of *.gwapi.apps.example.com accepts an HTTPRoute hostname such as app.gwapi.apps.example.com, but rejects hostnames outside that domain.

2. Apply the HTTPRoute CR file to your cluster:

   $ oc apply -f httproute.yaml

Procedure

1. Create or edit an HTTPRoute YAML file to include your desired match conditions under the spec.rules.matches field.

   The following example demonstrates a complete HTTPRoute custom resource (CR) configured with path-based matching to route requests for /<example_app> to a backend service. For details on configuring other match types, see Section 3.6.2.1, “Supported HTTPRoute match types”.

   apiVersion: gateway.networking.k8s.io/v1
   kind: HTTPRoute
   metadata:
     name: <path_match_example>
     namespace: <example_application>
   spec:
     parentRefs:
     - name: <example_gateway>
       namespace: openshift-ingress
     hostnames:
     - "<example.com>"
     rules:
     - matches:
       - path:
           type: Exact
           value: /<example_app>
       backendRefs:
       - name: <example_backend>
         port: 8080

2. Apply the HTTPRoute CR by running the following command:

   $ oc apply -f <filename>.yaml

Procedure

1. Create or edit an HTTPRoute YAML file to include your desired processing directives under the spec.rules.filters field.

   The following example demonstrates a complete HTTPRoute custom resource (CR) with a requestRedirect filter that issues a permanent redirect (301) from HTTP to HTTPS. For details on configuring other filter types, see Section 3.6.3.1, “Supported HTTPRoute filters”.

   apiVersion: gateway.networking.k8s.io/v1
   kind: HTTPRoute
   metadata:
     name: <http_filter_example>
     namespace: <example_application>
   spec:
     parentRefs:
     - name: <example_gateway>
       namespace: openshift-ingress
     hostnames:
     - "<example.com>"
     rules:
     - filters:
       - type: RequestRedirect
         requestRedirect:
           scheme: https
           statusCode: 301

2. Apply the HTTPRoute CR by running the following command:

   $ oc apply -f <filename>.yaml

Procedure

1. Create or edit an HTTPRoute YAML file to include your desired service destinations under the spec.rules.backendRefs field.

   The following example demonstrates a complete HTTPRoute custom resource (CR) with a single backend destination that routes traffic to a service named <service_v1>. For details on configuring weights and routing to multiple destinations, see Section 3.6.4.1, “HTTPRoute backendRef configuration”.

   apiVersion: gateway.networking.k8s.io/v1
   kind: HTTPRoute
   metadata:
     name: <backend_route_example>
     namespace: <example_application>
   spec:
     parentRefs:
     - name: <example_gateway>
       namespace: openshift-ingress
     rules:
     - backendRefs:
       - name: <service_v1>
         port: 8080

2. Apply the HTTPRoute CR by running the following command:

   $ oc apply -f <filename>.yaml

Procedure

1. Create or edit an HTTPRoute YAML file to include your desired timeout configurations under the spec.rules.timeouts field.

   The following example demonstrates a complete HTTPRoute custom resource (CR) where the entire request must complete within 30 seconds. For details on timeout formatting rules and backend request timeouts, see Section 3.6.5.1, “HTTPRoute timeout configuration”.

   apiVersion: gateway.networking.k8s.io/v1
   kind: HTTPRoute
   metadata:
     name: <timeout_example>
     namespace: <example_application>
   spec:
     parentRefs:
     - name: <example_gateway>
       namespace: openshift-ingress
     rules:
     - matches:
       - path:
           type: PathPrefix
           value: /<timeout_path>
       timeouts:
         request: 30s
       backendRefs:
       - name: <example_service>
         port: 8080

2. Apply the HTTPRoute CR by running the following command:

   $ oc apply -f <filename>.yaml

Procedure

1. Create or edit a GRPCRoute YAML file to include your desired match conditions under the spec.rules.matches field.

   The following example demonstrates a complete GRPCRoute resource configured with matching conditions for a specific gRPC service, method, and header:

   apiVersion: gateway.networking.k8s.io/v1
   kind: GRPCRoute
   metadata:
     name: grpc-match-example
     namespace: my-application
   spec:
     parentRefs:
     - name: my-gateway
       namespace: openshift-ingress
     hostnames:
     - "example.com"
     rules:
     - matches:
       - method:
           service: helloworld.Greeter
           method: SayHello
         headers:
         - name: x-version
           value: v1
       backendRefs:
       - name: greeter-service
         port: 50051
         weight: 1

   • parentRefs attaches the route to the my-gateway Gateway.
   • method specifies that the incoming request must be targeting the helloworld.Greeter service and specifically calling the SayHello method.
   • headers requires that the request must also include an x-version header with a value of v1. Both the method and header conditions must be met for this rule to apply.
   • backendRefs routes the matching traffic to the greeter-service backend.

2. Apply the GRPCRoute resource by running the following command:

   $ oc apply -f <filename>.yaml

Procedure

1. Create or edit a GRPCRoute YAML file to include your desired processing directives under the spec.rules.filters field.

   The following example demonstrates a complete GRPCRoute resource configured with a filter that adds a custom request header before routing to the backend service:

   apiVersion: gateway.networking.k8s.io/v1
   kind: GRPCRoute
   metadata:
     name: grpc-filter-example
     namespace: my-application
   spec:
     parentRefs:
     - name: my-gateway
       namespace: openshift-ingress
     hostnames:
     - "example.com"
     rules:
     - filters:
       - type: RequestHeaderModifier
         requestHeaderModifier:
           add:
           - name: custom-grpc-header
             value: my-custom-value
       backendRefs:
       - name: greeter-service
         port: 50051

   • parentRefs attaches the route to a specific Gateway.
   • hostnames limits the route to requests intended for "example.com".
   • filters specifies the processing logic. In this example, the RequestHeaderModifier adds a custom header to the gRPC request before it reaches the backend.
   • backendRefs directs the modified traffic to the greeter-service backend on port 50051.

2. Apply the GRPCRoute resource by running the following command:

   $ oc apply -f <filename>.yaml

Procedure

1. Create or edit a GRPCRoute YAML file to include your desired service destinations and traffic weights under the spec.rules.backendRefs field.

   The following example demonstrates a complete GRPCRoute resource that routes gRPC traffic between two versions of a backend service using proportional traffic weights:

   apiVersion: gateway.networking.k8s.io/v1
   kind: GRPCRoute
   metadata:
     name: grpc-weight-example
     namespace: my-application
   spec:
     parentRefs:
     - name: my-gateway
       namespace: openshift-ingress
     hostnames:
     - "example.com"
     rules:
     - backendRefs:
       - name: greeter-service-v1
         port: 50051
         weight: 90
       - name: greeter-service-v2
         port: 50051
         weight: 10

   • parentRefs attaches the route to the my-gateway Gateway.
   • backendRefs defines the destination services for the traffic.
   • weight dictates the traffic split. In this configuration, the total sum of the weights is 100. The route forwards 90% of the traffic to greeter-service-v1 and 10% to greeter-service-v2.

2. Apply the GRPCRoute resource by running the following command:

   $ oc apply -f <filename>.yaml

Procedure

1. Create a BackendTLSPolicy CR that targets your backend service. Use one of the following configuration options:

   • To use system certificates for re-encrypt termination, set the wellKnownCACertificates parameter to the "System" value as shown in the following example:

     apiVersion: gateway.networking.k8s.io/v1
     kind: BackendTLSPolicy
     metadata:
       name: tls-upstream-dev
       namespace: my-application
     spec:
       targetRefs:
         - kind: Service
           name: dev
           group: ""
       validation:
         wellKnownCACertificates: "System"
         hostname: dev.example.com

   • To use explicit CA certificates for re-encrypt termination, configure the CR to use your pre-existing ConfigMap object, such as auth-cert in the following example:

     apiVersion: gateway.networking.k8s.io/v1
     kind: BackendTLSPolicy
     metadata:
       name: tls-upstream-auth
       namespace: my-application
     spec:
       targetRefs:
         - kind: Service
           name: auth
           group: ""
       validation:
         caCertificateRefs:
           - kind: ConfigMap
             name: auth-cert
             group: ""
         hostname: "authentication.example.com"
         subjectAltNames:
         - type: "URI"
           uri: "spiffe://authorization.example.com/identity"

   • To configure re-encrypt termination for a target service that exposes multiple ports and requires different policies, explicitly specify the port name using the sectionName parameter. The following example demonstrates this setup within your targetRefs configuration:

     Important

     If you omit the sectionName parameter when multiple references target the same service, the BackendTLSPolicy CR fails validation or results in a Conflicted status.

     apiVersion: gateway.networking.k8s.io/v1
     kind: BackendTLSPolicy
     metadata:
       name: tls-upstream-multi-port
       namespace: my-application
     spec:
       targetRefs:
         - kind: Service
           name: my-service
           group: ""
           sectionName: https
       validation:
         wellKnownCACertificates: "System"
         hostname: my-service.example.com

2. Apply the policy to your cluster by running the following command:

   $ oc apply -f <filename>.yaml