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 desired 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 Section 3.3.1.1, “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
       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: All

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 without the addresses field:

   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: All

   • metadata.name: 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.
   • Replace <cluster_domain> with your actual cluster ingress domain (for example, example.com).
   • The spec.addresses field is omitted from this configuration to ensure automatic assignment.
   • The gatewayClassName dictates which controller provisions the address and populates the status.addresses field.

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 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.5.1.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.5.2.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.5.3.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.5.4.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