Chapter 1. Getting started with Knative 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"}