Chapter 9. External and Ingress routing

Procedure

1. Create a Knative service that contains the label or annotation that you want to propagate to the OpenShift Container Platform route:

   • To create a service by using YAML:

     Example service created by using YAML

     apiVersion: serving.knative.dev/v1
     kind: Service
     metadata:
       name: <service_name>
       labels:
         <label_name>: <label_value>
       annotations:
         <annotation_name>: <annotation_value>
     ...

   • To create a service by using the Knative (kn) CLI, enter:

     Example service created by using a kn command

     $ kn service create <service_name> \
       --image=<image> \
       --annotation <annotation_name>=<annotation_value> \
       --label <label_value>=<label_value>

2. Verify that the OpenShift Container Platform route has been created with the annotation or label that you added by inspecting the output from the following command:

   Example command for verification

   $ oc get routes.route.openshift.io \
        -l serving.knative.openshift.io/ingressName=<service_name> \ 1
        -l serving.knative.openshift.io/ingressNamespace=<service_namespace> \ 2
        -n knative-serving-ingress -o yaml \
            | grep -e "<label_name>: \"<label_value>\""  -e "<annotation_name>: <annotation_value>" 3

   1

   Use the name of your service.

   2

   Use the namespace where your service was created.

   3

   Use your values for the label and annotation names and values.

Procedure

1. Create a Knative service that includes the serving.knative.openshift.io/disableRoute=true annotation:

   Important

   The serving.knative.openshift.io/disableRoute=true annotation instructs OpenShift Serverless to not automatically create a route for you. However, the service still shows a URL and reaches a status of Ready. This URL does not work externally until you create your own route with the same hostname as the hostname in the URL.

   1. Create a Knative Service resource:

      Example resource

      apiVersion: serving.knative.dev/v1
      kind: Service
      metadata:
        name: <service_name>
        annotations:
          serving.knative.openshift.io/disableRoute: "true"
      spec:
        template:
          spec:
            containers:
            - image: <image>
      ...

   2. Apply the Service resource:

      $ oc apply -f <filename>

   3. Optional. Create a Knative service by using the kn service create command:

      Example kn command

      $ kn service create <service_name> \
        --image=gcr.io/knative-samples/helloworld-go \
        --annotation serving.knative.openshift.io/disableRoute=true

2. Verify that no OpenShift Container Platform route has been created for the service:

   Example command

   $ $ oc get routes.route.openshift.io \
     -l serving.knative.openshift.io/ingressName=$KSERVICE_NAME \
     -l serving.knative.openshift.io/ingressNamespace=$KSERVICE_NAMESPACE \
     -n knative-serving-ingress

   You will see the following output:

   No resources found in knative-serving-ingress namespace.

3. Create a Route resource in the knative-serving-ingress namespace:

   apiVersion: route.openshift.io/v1
   kind: Route
   metadata:
     annotations:
       haproxy.router.openshift.io/timeout: 600s 1
     name: <route_name> 2
     namespace: knative-serving-ingress 3
   spec:
     host: <service_host> 4
     port:
       targetPort: http2
     to:
       kind: Service
       name: kourier
       weight: 100
     tls:
       insecureEdgeTerminationPolicy: Allow
       termination: edge 5
       key: |-
         -----BEGIN PRIVATE KEY-----
         [...]
         -----END PRIVATE KEY-----
       certificate: |-
         -----BEGIN CERTIFICATE-----
         [...]
         -----END CERTIFICATE-----
       caCertificate: |-
         -----BEGIN CERTIFICATE-----
         [...]
         -----END CERTIFICATE----
     wildcardPolicy: None

   1

   The timeout value for the OpenShift Container Platform route. You must set the same value as the max-revision-timeout-seconds setting (600s by default).

   2

   The name of the OpenShift Container Platform route.

   3

   The namespace for the OpenShift Container Platform route. This must be knative-serving-ingress.

   4

   The hostname for external access. You can set this to <service_name>-<service_namespace>.<domain>.

   5

   The certificates you want to use. Currently, only edge termination is supported.

4. Apply the Route resource:

   $ oc apply -f <filename>

Procedure

1. Deploy server certificates in the knative-serving-ingress namespace:

   $ export san="knative"

   Note

   Subject Alternative Name (SAN) validation is required so that these certificates can serve the request to <app_name>.<namespace>.svc.cluster.local.

2. Generate a root key and certificate:

   $ openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 \
       -subj '/O=Example/CN=Example' \
       -keyout ca.key \
       -out ca.crt

3. Generate a server key that uses SAN validation:

   $ openssl req -out tls.csr -newkey rsa:2048 -nodes -keyout tls.key \
     -subj "/CN=Example/O=Example" \
     -addext "subjectAltName = DNS:$san"

4. Create server certificates:

   $ openssl x509 -req -extfile <(printf "subjectAltName=DNS:$san") \
     -days 365 -in tls.csr \
     -CA ca.crt -CAkey ca.key -CAcreateserial -out tls.crt

5. Configure a secret for the Kourier local gateway:

   1. Deploy a secret in knative-serving-ingress namespace from the certificates created by the previous steps:

      $ oc create -n knative-serving-ingress secret tls server-certs \
          --key=tls.key \
          --cert=tls.crt --dry-run=client -o yaml | oc apply -f -

   2. Update the KnativeServing custom resource (CR) spec to use the secret that was created by the Kourier gateway:

      Example KnativeServing CR

      ...
      spec:
        config:
          kourier:
            cluster-cert-secret: server-certs
      ...

Procedure

1. Add the serverless.openshift.io/default-enable-http2=true annotation to the KnativeServing Custom Resource:

   $ oc annotate knativeserving <your_knative_CR> -n knative-serving serverless.openshift.io/default-enable-http2=true

2. After the annotation is added, you can verify that the appProtocol value of the Kourier service is h2c:

   $ oc get svc -n knative-serving-ingress kourier -o jsonpath="{.spec.ports[0].appProtocol}"

   Example output

   h2c

3. Now you can use the gRPC framework over the HTTP/2 protocol for external traffic, for example:

   import "google.golang.org/grpc"
   
   grpc.Dial(
      YOUR_URL, 1
      grpc.WithTransportCredentials(insecure.NewCredentials())), 2
   )

   1

   Your ksvc URL.

   2

   Your certificate.

Procedure

1. Print information about the services in the cluster by running the following command:

   $ oc get ksvc

   Example output

   NAME         URL                                                             LATESTCREATED      LATESTREADY        READY   REASON
   hello-dev    https://hello-dev-default.dev.serverless.cluster.example.com    hello-dev-00001    hello-dev-00001    True
   hello-prod   https://hello-prod-default.prod.serverless.cluster.example.com  hello-prod-00001   hello-prod-00001   True

2. Verify that your service uses the correct route and the selected ingress shard by running the following command:

   $ oc get route -n knative-serving-ingress -o jsonpath='{range .items[*]}{@.metadata.name}{" "}{@.spec.host}{" "}{@.status.ingress[*].routerName}{"\n"}{end}'

   Example output

   route-19e6628b-77af-4da0-9b4c-1224934b2250-323461616533 hello-prod-default.prod.serverless.cluster.example.com ingress-prod
   route-cb5085d9-b7da-4741-9a56-96c88c6adaaa-373065343266 hello-dev-default.dev.serverless.cluster.example.com ingress-dev