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>
     ...

     Copy to Clipboard Toggle word wrap

   • 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>

     Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

   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>
      ...

      Copy to Clipboard Toggle word wrap

   2. Apply the Service resource:

      $ oc apply -f <filename>

      Copy to Clipboard Toggle word wrap

   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

      Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

   You will see the following output:

   No resources found in knative-serving-ingress namespace.

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

   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>

   Copy to Clipboard Toggle word wrap

Procedure

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

   $ export san="knative"

   Copy to Clipboard Toggle word wrap
   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

   Copy to Clipboard Toggle word wrap

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"

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

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 -

      Copy to Clipboard Toggle word wrap

   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
      ...

      Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

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}"

   Copy to Clipboard Toggle word wrap

   Example output

   h2c

   Copy to Clipboard Toggle word wrap

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

   
   )

   Copy to Clipboard Toggle word wrap

   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

   Copy to Clipboard Toggle word wrap

   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

   Copy to Clipboard Toggle word wrap

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}'

   Copy to Clipboard Toggle word wrap

   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

   Copy to Clipboard Toggle word wrap