Chapter 4. Serving

Procedure

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

   apiVersion: serving.knative.dev/v1
   kind: Service
   metadata:
     name: event-delivery
     namespace: default
   spec:
     template:
       spec:
         containers:
           - image: quay.io/openshift-knative/knative-eventing-sources-event-display:latest
             env:
               - name: RESPONSE
                 value: "Hello Serverless!"

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 event-display \
       --image quay.io/openshift-knative/knative-eventing-sources-event-display:latest \
       --target ./ \
       --namespace test

   Example output

   Service 'event-display' 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
           └── event-display.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 event-display.yaml, named according to the specified service name.

3. Examine the generated service descriptor file:

   $ cat test/ksvc/event-display.yaml

   Example output

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

4. List information about the new service:

   $ kn service describe event-display --target ./ --namespace test

   Example output

   Name:       event-display
   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/event-display.yaml

   Example output

   Creating service 'event-display' in namespace 'test':
   
     0.058s The Route is still working to reflect the latest desired specification.
     0.098s ...
     0.168s Configuration "event-display" 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 'event-display' created to latest revision 'event-display-00001' is available at URL:
   http://event-display-test.apps.example.com

Procedure

1. Find the application URL:

   $ oc get ksvc <service_name>

   Example output

   NAME            URL                                        LATESTCREATED         LATESTREADY           READY   REASON
   event-delivery   http://event-delivery-default.example.com   event-delivery-4wsd2   event-delivery-4wsd2   True

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

   Example HTTP request

   $ curl http://event-delivery-default.example.com

   Example HTTPS request

   $ curl https://event-delivery-default.example.com

   Example output

   Hello Serverless!

3. Optional. If you receive an error relating to a self-signed certificate in the certificate chain, you can add the --insecure flag to the curl command to ignore the error:

   $ curl https://event-delivery-default.example.com --insecure

   Example output

   Hello Serverless!

   Important

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

4. 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://event-delivery-default.example.com --cacert <file>

   Example output

   Hello Serverless!

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. 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 that you are requesting. For example, you can use the ocs-storagecluster-cephfs class for the ReadWriteMany access mode.

   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. Create a Knative service that includes the internal-encryption: "true" field in the spec:

   ...
   spec:
     config:
       network:
         internal-encryption: "true"
   ...

2. Restart the activator pods in the knative-serving namespace to load the certificates:

   $ oc delete pod -n knative-serving --selector app=activator

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.

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 4.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 4.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 example-service -o=jsonpath='{.status.latestCreatedRevisionName}'

   Example output

   $ example-service-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. Find the application host. See the instructions in Verifying your serverless application deployment.

2. Find the ingress gateway’s public address:

   $ oc -n knative-serving-ingress get svc kourier

   Example output

   NAME                   TYPE           CLUSTER-IP      EXTERNAL-IP                                                             PORT(S)                                                                                                                                      AGE
   kourier   LoadBalancer   172.30.51.103   a83e86291bcdd11e993af02b7a65e514-33544245.us-east-1.elb.amazonaws.com   80:31380/TCP,443:31390/TCP   67m

   The public address is surfaced in the EXTERNAL-IP field, and in this case is a83e86291bcdd11e993af02b7a65e514-33544245.us-east-1.elb.amazonaws.com.

3. Manually set the host header of your HTTP request to the application’s host, but direct the request itself against the public address of the ingress gateway.

   $ curl -H "Host: hello-default.example.com" a83e86291bcdd11e993af02b7a65e514-33544245.us-east-1.elb.amazonaws.com

   Example output

   Hello Serverless!

   You can also make a direct gRPC request against the ingress gateway:

   import "google.golang.org/grpc"
   
   grpc.Dial(
       "a83e86291bcdd11e993af02b7a65e514-33544245.us-east-1.elb.amazonaws.com:80",
       grpc.WithAuthority("hello-default.example.com:80"),
       grpc.WithInsecure(),
   )

   Note

   Ensure that you append the respective port, 80 by default, to both hosts as shown in the previous example.

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/v1alpha1
   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/v1alpha1
   kind: DomainMapping
   metadata:
    name: example-domain
    namespace: default
   spec:
    ref:
      name: example-service
      kind: Service
      apiVersion: serving.knative.dev/v1

   Example route domain mapping

   apiVersion: serving.knative.dev/v1alpha1
   kind: DomainMapping
   metadata:
    name: example-domain
    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 on the service that you want to map to a domain, and select the Edit option that contains the service name. For example, if the service is named example-service, select the Edit example-service 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/v1alpha1
   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/v1alpha1
   kind: DomainMapping
   metadata:
    name: custom-ksvc-domain.example.com
    namespace: default
   spec:
    ref:
      name: example-service
      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} is a Technology Preview feature. For more information, see the Installing the {cert-manager-operator} documentation.

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

   apiVersion: serving.knative.dev/v1alpha1
   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