Serving

Procedure

1. Create a YAML file containing the following sample code:

   apiVersion: serving.knative.dev/v1
   kind: Service
   metadata:
     name: showcase
     namespace: default
   spec:
     template:
       spec:
         containers:
           - image: quay.io/openshift-knative/showcase
             env:
               - name: GREET
                 value: Bonjour

2. Navigate to the directory where the YAML file is contained, and deploy the application by applying the YAML file:

   $ oc apply -f <filename>

Procedure

1. Navigate to the Serverless → Serving page.
2. In the Create list, select Service.
3. Manually enter YAML or JSON definitions, or by dragging and dropping a file into the editor.
4. Click Create.

Procedure

1. In offline mode, create a local Knative service descriptor file:

   $ kn service create showcase \
       --image quay.io/openshift-knative/showcase \
       --target ./ \
       --namespace test

   Example output

   Service 'showcase' created in namespace 'test'.

   • The --target ./ flag enables offline mode and specifies ./ as the directory for storing the new directory tree.

     If you do not specify an existing directory, but use a filename, such as --target my-service.yaml, then no directory tree is created. Instead, only the service descriptor file my-service.yaml is created in the current directory.

     The filename can have the .yaml, .yml, or .json extension. Choosing .json creates the service descriptor file in the JSON format.

   • The --namespace test option places the new service in the test namespace.

     If you do not use --namespace, and you are logged in to an OpenShift Container Platform cluster, the descriptor file is created in the current namespace. Otherwise, the descriptor file is created in the default namespace.

2. Examine the created directory structure:

   $ tree ./

   Example output

   ./
   └── test
       └── ksvc
           └── showcase.yaml
   
   2 directories, 1 file

   • The current ./ directory specified with --target contains the new test/ directory that is named after the specified namespace.
   • The test/ directory contains the ksvc directory, named after the resource type.
   • The ksvc directory contains the descriptor file showcase.yaml, named according to the specified service name.

3. Examine the generated service descriptor file:

   $ cat test/ksvc/showcase.yaml

   Example output

   apiVersion: serving.knative.dev/v1
   kind: Service
   metadata:
     creationTimestamp: null
     name: showcase
     namespace: test
   spec:
     template:
       metadata:
         annotations:
           client.knative.dev/user-image: quay.io/openshift-knative/showcase
         creationTimestamp: null
       spec:
         containers:
         - image: quay.io/openshift-knative/showcase
           name: ""
           resources: {}
   status: {}

4. List information about the new service:

   $ kn service describe showcase --target ./ --namespace test

   Example output

   Name:       showcase
   Namespace:  test
   Age:
   URL:
   
   Revisions:
   
   Conditions:
     OK TYPE    AGE REASON

   • The --target ./ option specifies the root directory for the directory structure containing namespace subdirectories.

     Alternatively, you can directly specify a YAML or JSON filename with the --target option. The accepted file extensions are .yaml, .yml, and .json.

   • The --namespace option specifies the namespace, which communicates to kn the subdirectory that contains the necessary service descriptor file.

     If you do not use --namespace, and you are logged in to an OpenShift Container Platform cluster, kn searches for the service in the subdirectory that is named after the current namespace. Otherwise, kn searches in the default/ subdirectory.

5. Use the service descriptor file to create the service on the cluster:

   $ kn service create -f test/ksvc/showcase.yaml

   Example output

   Creating service 'showcase' in namespace 'test':
   
     0.058s The Route is still working to reflect the latest desired specification.
     0.098s ...
     0.168s Configuration "showcase" is waiting for a Revision to become ready.
    23.377s ...
    23.419s Ingress has not yet been reconciled.
    23.534s Waiting for load balancer to be ready
    23.723s Ready to serve.
   
   Service 'showcase' created to latest revision 'showcase-00001' is available at URL:
   http://showcase-test.apps.example.com

Procedure

1. Find the application URL:

   $ oc get ksvc <service_name>

   Example output

   NAME       URL                                   LATESTCREATED    LATESTREADY      READY   REASON
   showcase   http://showcase-default.example.com   showcase-00001   showcase-00001   True

2. Make a request to your cluster and observe the output.

   Example HTTP request (using HTTPie tool)

   $ http showcase-default.example.com

   Example HTTPS request

   $ https showcase-default.example.com

   Example output

   HTTP/1.1 200 OK
   Content-Type: application/json
   Server: Quarkus/2.13.7.Final-redhat-00003 Java/17.0.7
   X-Config: {"sink":"http://localhost:31111","greet":"Ciao","delay":0}
   X-Version: v0.7.0-4-g23d460f
   content-length: 49
   
   {
       "artifact": "knative-showcase",
       "greeting": "Ciao"
   }

3. Optional. If you don’t have the HTTPie tool installed on your system, you can likely use curl tool instead:

   Example HTTPS request

   $ curl http://showcase-default.example.com

   Example output

   {"artifact":"knative-showcase","greeting":"Ciao"}

4. Optional. If you receive an error relating to a self-signed certificate in the certificate chain, you can add the --verify=no flag to the HTTPie command to ignore the error:

   $ https --verify=no showcase-default.example.com

   Example output

   HTTP/1.1 200 OK
   Content-Type: application/json
   Server: Quarkus/2.13.7.Final-redhat-00003 Java/17.0.7
   X-Config: {"sink":"http://localhost:31111","greet":"Ciao","delay":0}
   X-Version: v0.7.0-4-g23d460f
   content-length: 49
   
   {
       "artifact": "knative-showcase",
       "greeting": "Ciao"
   }

   Important

   Self-signed certificates must not be used in a production deployment. This method is only for testing purposes.

5. Optional. If your OpenShift Container Platform cluster is configured with a certificate that is signed by a certificate authority (CA) but not yet globally configured for your system, you can specify this with the curl command. The path to the certificate can be passed to the curl command by using the --cacert flag:

   $ curl https://showcase-default.example.com --cacert <file>

   Example output

   {"artifact":"knative-showcase","greeting":"Ciao"}

Procedure

1. Modify your service to include additional containers. Only one container can handle requests, so specify ports for exactly one container. Here is an example configuration with two containers:

   Multiple containers configuration

   apiVersion: serving.knative.dev/v1
   kind: Service
   ...
   spec:
     template:
       spec:
         containers:
           - name: first-container 1
             image: gcr.io/knative-samples/helloworld-go
             ports:
               - containerPort: 8080 2
           - name: second-container 3
             image: gcr.io/knative-samples/helloworld-java

   1

   First container configuration.

   2

   Port specification for the first container.

   3

   Second container configuration.

Procedure

1. Configure multi-container probing for your service by enabling the multi-container-probing feature in the KnativeServing CR.

   Multi-container probing configuration

   ...
   spec:
     config:
       features:
         "multi-container-probing": enabled 1
   ...

   1

   Enabled multi-container-probing feature

2. Apply the updated KnativeServing CR.

   $ oc apply -f <filename>

3. Modify your multi-container service to include the specified probes.

   Multi-container probing

   apiVersion: serving.knative.dev/v1
   kind: Service
   ...
   spec:
    template:
      spec:
        containers:
          - name: first-container
            image: ghcr.io/knative/helloworld-go:latest
            ports:
              - containerPort: 8080
            readinessProbe: 1
              httpGet:
                port: 8080
          - name: second-container
            image: gcr.io/knative-samples/helloworld-java
            readinessProbe: 2
              httpGet:
                port: 8090

   1

   Readiness probe of the first container

   2

   Readiness probe of the second container

Procedure

1. To enable Knative Serving to use PVCs and write to them, modify the KnativeServing custom resource (CR) to include the following YAML:

   Enabling PVCs with write access

   ...
   spec:
     config:
       features:
         "kubernetes.podspec-persistent-volume-claim": enabled
         "kubernetes.podspec-persistent-volume-write": enabled
   ...

   • The kubernetes.podspec-persistent-volume-claim extension controls whether persistent volumes (PVs) can be used with Knative Serving.
   • The kubernetes.podspec-persistent-volume-write extension controls whether PVs are available to Knative Serving with the write access.

2. To claim a PV, modify your service to include the PV configuration. For example, you might have a persistent volume claim with the following configuration:

   Note

   Use the storage class that supports the access mode you are requesting. For example, you can use the ocs-storagecluster-cephfs storage class for the ReadWriteMany access mode.

   The ocs-storagecluster-cephfs storage class is supported and comes from Red Hat OpenShift Data Foundation.

   PersistentVolumeClaim configuration

   apiVersion: v1
   kind: PersistentVolumeClaim
   metadata:
     name: example-pv-claim
     namespace: my-ns
   spec:
     accessModes:
       - ReadWriteMany
     storageClassName: ocs-storagecluster-cephfs
     resources:
       requests:
         storage: 1Gi

   In this case, to claim a PV with write access, modify your service as follows:

   Knative service PVC configuration

   apiVersion: serving.knative.dev/v1
   kind: Service
   metadata:
     namespace: my-ns
   ...
   spec:
    template:
      spec:
        containers:
            ...
            volumeMounts: 1
              - mountPath: /data
                name: mydata
                readOnly: false
        volumes:
          - name: mydata
            persistentVolumeClaim: 2
              claimName: example-pv-claim
              readOnly: false 3

   1

   Volume mount specification.

   2

   Persistent volume claim specification.

   3

   Flag that enables read-only access.

   Note

   To successfully use persistent storage in Knative services, you need additional configuration, such as the user permissions for the Knative container user.

Procedure

1. To enable administrator interface access, locate this configuration in your bootstrapping configuration map:

   pipe:
     path: /tmp/envoy.admin

   Substitute it with the following configuration:

   socket_address: 1
     address: 127.0.0.1
     port_value: 9901

   1

   This configuration enables access to the Envoy admin interface on the loopback address (127.0.0.1) and port 9901.

2. Apply the socket_address configuration in the service_stats cluster configuration and in the admin configuration:

   1. The first is in the service_stats cluster configuration:

      clusters:
        - name: service_stats
          connect_timeout: 0.250s
          type: static
          load_assignment:
            cluster_name: service_stats
            endpoints:
              lb_endpoints:
                endpoint:
                  address:
                    socket_address:
                      address: 127.0.0.1
                      port_value: 9901

   2. The second is in the admin configuration:

      admin:
        access_log:
          - name: envoy.access_loggers.stdout
            typed_config:
              "@type": type.googleapis.com/envoy.extensions.access_loggers.stream.v3.StdoutAccessLog
        address:
          socket_address:
            address: 127.0.0.1
            port_value: 9901

Procedure

1. Add the knative.openshift.io/system-namespace=true label to each Knative system namespace that requires access to your application:

   1. Label the knative-serving namespace:

      $ oc label namespace knative-serving knative.openshift.io/system-namespace=true

   2. Label the knative-serving-ingress namespace:

      $ oc label namespace knative-serving-ingress knative.openshift.io/system-namespace=true

   3. Label the knative-eventing namespace:

      $ oc label namespace knative-eventing knative.openshift.io/system-namespace=true

   4. Label the knative-kafka namespace:

      $ oc label namespace knative-kafka knative.openshift.io/system-namespace=true

2. Create a NetworkPolicy object in your application namespace to allow access from namespaces with the knative.openshift.io/system-namespace label:

   Example NetworkPolicy object

   apiVersion: networking.k8s.io/v1
   kind: NetworkPolicy
   metadata:
     name: <network_policy_name> 1
     namespace: <namespace> 2
   spec:
     ingress:
     - from:
       - namespaceSelector:
           matchLabels:
             knative.openshift.io/system-namespace: "true"
     podSelector: {}
     policyTypes:
     - Ingress

   1

   Provide a name for your network policy.

   2

   The namespace where your application exists.

Procedure

1. Create a SelfSigned ClusterIssuer custom resource (CR):

   Example ClusterIssuer CR

   apiVersion: cert-manager.io/v1
   kind: ClusterIssuer
   metadata:
     name: knative-serving-selfsigned-issuer
   spec:
     selfSigned: {}

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

   $ oc apply -f <filename>

3. Create a root certificate that refers to the ClusterIssuer CR:

   Example root certificate

   apiVersion: cert-manager.io/v1
   kind: Certificate
   metadata:
     name: knative-serving-selfsigned-ca
     namespace: cert-manager 1
   spec:
     secretName: knative-serving-ca 2
   
     isCA: true
     commonName: selfsigned-ca
     privateKey:
       algorithm: ECDSA
       size: 256
   
     issuerRef:
       name: knative-serving-selfsigned-issuer
       kind: ClusterIssuer
       group: cert-manager.io

   1

   The cert-manager Operator for Red Hat OpenShift namespace, cert-manager by default.

   2

   Secret name later used for the ClusterIssuer CR for Knative Serving.

4. Apply the Certificate CR by running the following command:

   $ oc apply -f <filename>

Procedure

1. Create the knative-serving-ca-issuer ClusterIssuer for Serving:

   apiVersion: cert-manager.io/v1
   kind: ClusterIssuer
   metadata:
     name: knative-serving-ca-issuer
   spec:
     ca:
       secretName: knative-serving-ca 1

   1

   Secret name in the cert-manager Operator for Red Hat OpenShift namespace (cert-manager by default) containing the certificate that can be used by OpenShift Serverless Serving components for new certificates.

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

   $ oc apply -f <filename>

1. Specifying the ClusterIssuer issuer to use:

   • clusterLocalIssuerRef: issuer for cluster-local-domain certificates used for ingress.
   • systemInternalIssuerRef: issuer for certificates for system-internal-tls certificates used by Knative internal components.

2. Specifying transport encryption features to use:

   • cluster-local-domain-tls: Enables the transport encryption feature for cluster-local domains
   • system-internal-tls: Enables the transport encryption feature for OpenShift Serverless Serving internal components.

Procedure

1. Enable transport encryption in the KnativeServing resource:

   apiVersion: operator.knative.dev/v1beta1
   kind: KnativeServing
   metadata:
     name: knative-serving
     namespace: knative-serving
   spec:
     ...
     config:
       certmanager:
         clusterLocalIssuerRef: |
           kind: ClusterIssuer
           name: knative-serving-ca-issuer 1
         systemInternalIssuerRef: |
           kind: ClusterIssuer
           name: knative-serving-ca-issuer 2
       network:
         cluster-local-domain-tls: Enabled 3
         system-internal-tls: Enabled 4

   1

   Define the cluster issuer for each feature. The same or individual cluster issuers can be used.

   2

   Define the cluster issuer.

   3

   Enable the cluster-local-domain-tls feature. This and other features can be enabled or disabled individually.

   4

   Enable the system-internal-tls feature.

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

   $ oc apply -f <filename>

3. Optionally, change the defaultCertificate value in the Ingress Controller:

   apiVersion: operator.openshift.io/v1
   kind: IngressController
    ...
   spec:
     defaultCertificate:
       name: ca-ingress-cert

4. If you changed the defaultCertificate value, you must specify the custom certificate name in the openshift-ingress-default-certificate field in the KnativeServing custom resource.

   For example, if the custom certificate name is ca-ingress-cert, add the following configuration:

   ...
   spec:
     config:
       network:
         system-internal-tls: Enabled
         openshift-ingress-default-certificate: "ca-ingress-cert"
   ...

5. If you enabled cluster-local-domain-tls or system-internal-tls, restart the Controller component by running the following command.

   Important

   When either the cluster-local-domain-tls or the system-internal-tls feature is enabled, you must restart the Controller component to enable the Knative Serving cert-manager integration.

   $ oc rollout restart deploy/controller -n knative-serving

6. If you enabled system-internal-tls, restart the Activator component by running the following command.

   Important

   When the system-internal-tls feature is activated, you must restart the Activator component to reconfigure its internal web server, as this is not possible during runtime.

   $ oc rollout restart deploy/activator -n knative-serving

1. Click the Knative service to see its overview in the side panel.

2. Click the Resources tab, to see a list of Revisions and Routes for the service.

   Figure 8.1. Serverless application

   
3. Click the service, indicated by the S icon at the top of the side panel, to see an overview of the service details.
4. Click the YAML tab and modify the service configuration in the YAML editor, and click Save. For example, change the timeoutseconds from 300 to 301 . This change in the configuration triggers a new revision. In the Topology view, the latest revision is displayed and the Resources tab for the service now displays the two revisions.

5. In the Resources tab, click Set Traffic Distribution to see the traffic distribution dialog box:

   1. Add the split traffic percentage portion for the two revisions in the Splits field.
   2. Add tags to create custom URLs for the two revisions.

   3. Click Save to see two nodes representing the two revisions in the Topology view.

      Figure 8.2. Serverless application revisions

      

Procedure

1. Create and deploy an app as a Knative service.

2. Find the name of the first revision that was created when you deployed the service, by viewing the output from the following command:

   $ oc get ksvc <service_name> -o=jsonpath='{.status.latestCreatedRevisionName}'

   Example command

   $ oc get ksvc showcase -o=jsonpath='{.status.latestCreatedRevisionName}'

   Example output

   $ showcase-00001

3. Add the following YAML to the service spec to send inbound traffic to the revision:

   ...
   spec:
     traffic:
       - revisionName: <first_revision_name>
         percent: 100 # All traffic goes to this revision
   ...

4. Verify that you can view your app at the URL output you get from running the following command:

   $ oc get ksvc <service_name>

5. Deploy a second revision of your app by modifying at least one field in the template spec of the service and redeploying it. For example, you can modify the image of the service, or an env environment variable. You can redeploy the service by applying the service YAML file, or by using the kn service update command if you have installed the Knative (kn) CLI.

6. Find the name of the second, latest revision that was created when you redeployed the service, by running the command:

   $ oc get ksvc <service_name> -o=jsonpath='{.status.latestCreatedRevisionName}'

   At this point, both the first and second revisions of the service are deployed and running.

7. Update your existing service to create a new, test endpoint for the second revision, while still sending all other traffic to the first revision:

   Example of updated service spec with test endpoint

   ...
   spec:
     traffic:
       - revisionName: <first_revision_name>
         percent: 100 # All traffic is still being routed to the first revision
       - revisionName: <second_revision_name>
         percent: 0 # No traffic is routed to the second revision
         tag: v2 # A named route
   ...

   After you redeploy this service by reapplying the YAML resource, the second revision of the app is now staged. No traffic is routed to the second revision at the main URL, and Knative creates a new service named v2 for testing the newly deployed revision.

8. Get the URL of the new service for the second revision, by running the following command:

   $ oc get ksvc <service_name> --output jsonpath="{.status.traffic[*].url}"

   You can use this URL to validate that the new version of the app is behaving as expected before you route any traffic to it.

9. Update your existing service again, so that 50% of traffic is sent to the first revision, and 50% is sent to the second revision:

   Example of updated service spec splitting traffic 50/50 between revisions

   ...
   spec:
     traffic:
       - revisionName: <first_revision_name>
         percent: 50
       - revisionName: <second_revision_name>
         percent: 50
         tag: v2
   ...

10. When you are ready to route all traffic to the new version of the app, update the service again to send 100% of traffic to the second revision:

    Example of updated service spec sending all traffic to the second revision

    ...
    spec:
      traffic:
        - revisionName: <first_revision_name>
          percent: 0
        - revisionName: <second_revision_name>
          percent: 100
          tag: v2
    ...

    Tip

    You can remove the first revision instead of setting it to 0% of traffic if you do not plan to roll back the revision. Non-routeable revision objects are then garbage-collected.

11. Visit the URL of the first revision to verify that no more traffic is being sent to the old version of the app.

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

Procedure

1. Add the sidecar.istio.io/inject="true" annotation to your service:

   Example service

   apiVersion: serving.knative.dev/v1
   kind: Service
   metadata:
     name: <service_name>
   spec:
     template:
       metadata:
         annotations:
           sidecar.istio.io/inject: "true" 1
           sidecar.istio.io/rewriteAppHTTPProbers: "true" 2
   ...

   1

   Add the sidecar.istio.io/inject="true" annotation.

   2

   You must set the annotation sidecar.istio.io/rewriteAppHTTPProbers: "true" in your Knative service, because OpenShift Serverless versions 1.14.0 and higher use an HTTP probe as the readiness probe for Knative services by default.

2. Apply the Service resource:

   $ oc apply -f <filename>

3. Create a RequestAuthentication resource in each serverless application namespace that is a member in the ServiceMeshMemberRoll object:

   apiVersion: security.istio.io/v1beta1
   kind: RequestAuthentication
   metadata:
     name: jwt-example
     namespace: <namespace>
   spec:
     jwtRules:
     - issuer: testing@secure.istio.io
       jwksUri: https://raw.githubusercontent.com/istio/istio/release-1.8/security/tools/jwt/samples/jwks.json

4. Apply the RequestAuthentication resource:

   $ oc apply -f <filename>

5. Allow access to the RequestAuthenticaton resource from system pods for each serverless application namespace that is a member in the ServiceMeshMemberRoll object, by creating the following AuthorizationPolicy resource:

   apiVersion: security.istio.io/v1beta1
   kind: AuthorizationPolicy
   metadata:
     name: allowlist-by-paths
     namespace: <namespace>
   spec:
     action: ALLOW
     rules:
     - to:
       - operation:
           paths:
           - /metrics 1
           - /healthz 2

   1

   The path on your application to collect metrics by system pod.

   2

   The path on your application to probe by system pod.

6. Apply the AuthorizationPolicy resource:

   $ oc apply -f <filename>

7. For each serverless application namespace that is a member in the ServiceMeshMemberRoll object, create the following AuthorizationPolicy resource:

   apiVersion: security.istio.io/v1beta1
   kind: AuthorizationPolicy
   metadata:
     name: require-jwt
     namespace: <namespace>
   spec:
     action: ALLOW
     rules:
     - from:
       - source:
          requestPrincipals: ["testing@secure.istio.io/testing@secure.istio.io"]

8. Apply the AuthorizationPolicy resource:

   $ oc apply -f <filename>

Verification

1. If you try to use a curl request to get the Knative service URL, it is denied:

   Example command

   $ curl http://hello-example-1-default.apps.mycluster.example.com/

   Example output

   RBAC: access denied

2. Verify the request with a valid JWT.

   1. Get the valid JWT token:

      $ TOKEN=$(curl https://raw.githubusercontent.com/istio/istio/release-1.8/security/tools/jwt/samples/demo.jwt -s) && echo "$TOKEN" | cut -d '.' -f2 - | base64 --decode -

   2. Access the service by using the valid token in the curl request header:

      $ curl -H "Authorization: Bearer $TOKEN"  http://hello-example-1-default.apps.example.com

      The request is now allowed:

      Example output

      Hello OpenShift!

Procedure

1. Add the sidecar.istio.io/inject="true" annotation to your service:

   Example service

   apiVersion: serving.knative.dev/v1
   kind: Service
   metadata:
     name: <service_name>
   spec:
     template:
       metadata:
         annotations:
           sidecar.istio.io/inject: "true" 1
           sidecar.istio.io/rewriteAppHTTPProbers: "true" 2
   ...

   1

   Add the sidecar.istio.io/inject="true" annotation.

   2

   You must set the annotation sidecar.istio.io/rewriteAppHTTPProbers: "true" in your Knative service, because OpenShift Serverless versions 1.14.0 and higher use an HTTP probe as the readiness probe for Knative services by default.

2. Apply the Service resource:

   $ oc apply -f <filename>

3. Create a policy in a serverless application namespace which is a member in the ServiceMeshMemberRoll object, that only allows requests with valid JSON Web Tokens (JWT):

   Important

   The paths /metrics and /healthz must be included in excludedPaths because they are accessed from system pods in the knative-serving namespace.

   apiVersion: authentication.istio.io/v1alpha1
   kind: Policy
   metadata:
     name: default
     namespace: <namespace>
   spec:
     origins:
     - jwt:
         issuer: testing@secure.istio.io
         jwksUri: "https://raw.githubusercontent.com/istio/istio/release-1.6/security/tools/jwt/samples/jwks.json"
         triggerRules:
         - excludedPaths:
           - prefix: /metrics 1
           - prefix: /healthz 2
     principalBinding: USE_ORIGIN

   1

   The path on your application to collect metrics by system pod.

   2

   The path on your application to probe by system pod.

4. Apply the Policy resource:

   $ oc apply -f <filename>

Verification

1. If you try to use a curl request to get the Knative service URL, it is denied:

   $ curl http://hello-example-default.apps.mycluster.example.com/

   Example output

   Origin authentication failed.

2. Verify the request with a valid JWT.

   1. Get the valid JWT token:

      $ TOKEN=$(curl https://raw.githubusercontent.com/istio/istio/release-1.6/security/tools/jwt/samples/demo.jwt -s) && echo "$TOKEN" | cut -d '.' -f2 - | base64 --decode -

   2. Access the service by using the valid token in the curl request header:

      $ curl http://hello-example-default.apps.mycluster.example.com/ -H "Authorization: Bearer $TOKEN"

      The request is now allowed:

      Example output

      Hello OpenShift!

Procedure

1. Create a YAML file containing the DomainMapping CR in the same namespace as the target CR you want to map to:

   apiVersion: serving.knative.dev/v1beta1
   kind: DomainMapping
   metadata:
    name: <domain_name> 1
    namespace: <namespace> 2
   spec:
    ref:
      name: <target_name> 3
      kind: <target_type> 4
      apiVersion: serving.knative.dev/v1

   1

   The custom domain name that you want to map to the target CR.

   2

   The namespace of both the DomainMapping CR and the target CR.

   3

   The name of the target CR to map to the custom domain.

   4

   The type of CR being mapped to the custom domain.

   Example service domain mapping

   apiVersion: serving.knative.dev/v1beta1
   kind: DomainMapping
   metadata:
    name: example.com
    namespace: default
   spec:
    ref:
      name: showcase
      kind: Service
      apiVersion: serving.knative.dev/v1

   Example route domain mapping

   apiVersion: serving.knative.dev/v1beta1
   kind: DomainMapping
   metadata:
    name: example.com
    namespace: default
   spec:
    ref:
      name: example-route
      kind: Route
      apiVersion: serving.knative.dev/v1

2. Apply the DomainMapping CR as a YAML file:

   $ oc apply -f <filename>

Procedure

1. Navigate to the Topology page.
2. Right-click the service you want to map to a domain, and select the Edit option that contains the service name. For example, if the service is named showcase, select the Edit showcase option.

3. In the Advanced options section, click Show advanced Routing options.

   1. If the domain mapping CR that you want to map to the service already exists, you can select it in the Domain mapping list.
   2. If you want to create a new domain mapping CR, type the domain name into the box, and select the Create option. For example, if you type in example.com, the Create option is Create "example.com".
4. Click Save to save the changes to your service.

Verification

1. Navigate to the Topology page.
2. Click on the service that you have created.
3. In the Resources tab of the service information window, you can see the domain you have mapped to the service listed under Domain mappings.

Procedure

1. Navigate to CustomResourceDefinitions and use the search box to find the DomainMapping custom resource definition (CRD).
2. Click the DomainMapping CRD, then navigate to the Instances tab.
3. Click Create DomainMapping.

4. Modify the YAML for the DomainMapping CR so that it includes the following information for your instance:

   apiVersion: serving.knative.dev/v1beta1
   kind: DomainMapping
   metadata:
    name: <domain_name> 1
    namespace: <namespace> 2
   spec:
    ref:
      name: <target_name> 3
      kind: <target_type> 4
      apiVersion: serving.knative.dev/v1

   1

   The custom domain name that you want to map to the target CR.

   2

   The namespace of both the DomainMapping CR and the target CR.

   3

   The name of the target CR to map to the custom domain.

   4

   The type of CR being mapped to the custom domain.

   Example domain mapping to a Knative service

   apiVersion: serving.knative.dev/v1beta1
   kind: DomainMapping
   metadata:
    name: custom-ksvc-domain.example.com
    namespace: default
   spec:
    ref:
      name: showcase
      kind: Service
      apiVersion: serving.knative.dev/v1

Procedure

1. Create a Kubernetes TLS secret:

   $ oc create secret tls <tls_secret_name> --cert=<path_to_certificate_file> --key=<path_to_key_file>

2. Add the networking.internal.knative.dev/certificate-uid: <id>` label to the Kubernetes TLS secret:

   $ oc label secret <tls_secret_name> networking.internal.knative.dev/certificate-uid="<id>"

   If you are using a third-party secret provider such as cert-manager, you can configure your secret manager to label the Kubernetes TLS secret automatically. cert-manager users can use the secret template offered to automatically generate secrets with the correct label. In this case, secret filtering is done based on the key only, but this value can carry useful information such as the certificate ID that the secret contains.

   Note

   The cert-manager Operator for Red Hat OpenShift is a Technology Preview feature. For more information, see the Installing the cert-manager Operator for Red Hat OpenShift documentation.

3. Update the DomainMapping CR to use the TLS secret that you have created:

   apiVersion: serving.knative.dev/v1beta1
   kind: DomainMapping
   metadata:
     name: <domain_name>
     namespace: <namespace>
   spec:
     ref:
       name: <service_name>
       kind: Service
       apiVersion: serving.knative.dev/v1
   # TLS block specifies the secret to be used
     tls:
       secretName: <tls_secret_name>

Verification

1. Verify that the DomainMapping CR status is True, and that the URL column of the output shows the mapped domain with the scheme https:

   $ oc get domainmapping <domain_name>

   Example output

   NAME                      URL                               READY   REASON
   example.com               https://example.com               True

2. Optional: If the service is exposed publicly, verify that it is available by running the following command:

   $ curl https://<domain_name>

   If the certificate is self-signed, skip verification by adding the -k flag to the curl command.

Procedure

1. In the OpenShift Container Platform web console Administrator perspective, navigate to OperatorHub → Installed Operators.
2. Select the knative-serving namespace.
3. Click Knative Serving in the list of Provided APIs for the OpenShift Serverless Operator to go to the Knative Serving tab.

4. Click knative-serving, then go to the YAML tab in the knative-serving page.

   

5. Modify the number of replicas in the KnativeServing CR:

   Example YAML

   apiVersion: operator.knative.dev/v1beta1
   kind: KnativeServing
   metadata:
     name: knative-serving
     namespace: knative-serving
   spec:
     high-availability:
       replicas: 3

6. You can also specify the number of replicas for a specific workload.

   Note

   Workload-specific configuration overrides the global setting for Knative Serving.

   Example YAML

   apiVersion: operator.knative.dev/v1beta1
   kind: KnativeServing
   metadata:
     name: knative-serving
     namespace: knative-serving
   spec:
     high-availability:
       replicas: 3
     workloads:
     - name: webhook
       replicas: 4

7. Verify that the high availability limits are respected:

   Example command

   $ oc get hpa -n knative-serving

   Example output

   NAME        REFERENCE              TARGETS   MINPODS   MAXPODS   REPLICAS   AGE
   activator   Deployment/activator   0%/100%   3         22        3          2m24s
   webhook     Deployment/webhook     2%/100%   4         8         4          2m23s