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 that has the YAML file and run the following command to deploy the application:

   $ oc apply -f <filename>

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

   You get an output similar to the following example:

   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, the command does not create a directory tree. Instead, the command creates the service descriptor file my-service.yaml 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 log in to an OpenShift Container Platform cluster, the command creates the descriptor file in the current namespace. If you do not log in to a cluster, the command creates the descriptor file in the default namespace.

2. Examine the created directory structure:

   $ tree ./

   You get an output similar to the following example:

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

   • The ./ directory specified with --target now has a test/ directory named after the specified namespace.
   • The test/ directory has the ksvc directory, named after the resource type.
   • The ksvc directory has the descriptor file showcase.yaml, named according to the specified service name.

3. Examine the generated service descriptor file:

   $ cat test/ksvc/showcase.yaml

   You get an output similar to the following example:

   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

   You get an output similar to the following example:

   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.

     You can also 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 has the necessary service descriptor file.

     If you do not use --namespace and you log in to an OpenShift Container Platform cluster, kn searches for the service in the subdirectory that matches 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

   You get an output similar to the following example:

   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 do not 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

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

5. Optional. If your OpenShift Container Platform cluster uses a certificate signed by a certificate authority (CA) that your system does not yet trust, specify the certificate when you run the curl command. Pass the certificate path to the curl command by using the --cacert flag:

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

   Example output

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