Chapter 1. Knative Serving CLI commands

Procedure

1. Update a service by adding a new environment variable by running the command:

   $ kn service update <service_name> --env <key>=<value>

2. Update a service by adding a new port by running the command:

   $ kn service update <service_name> --port 80

3. Update a service by adding new request and limit parameters by running the command:

   $ kn service update <service_name> --request cpu=500m --limit memory=1024Mi --limit cpu=1000m

4. Assign the latest tag to a revision by running the command:

   $ kn service update <service_name> --tag <revision_name>=latest

5. Update a tag from testing to staging for the latest READY revision of a service by running the command:

   $ kn service update <service_name> --untag testing --tag @latest=staging

6. Add the test tag to a revision that receives 10% of traffic, and send the rest of the traffic to the latest READY revision of a service:

   $ kn service update <service_name> --tag <revision_name>=test --traffic test=10,@latest=90

Procedure

1. Create a service by running the command:

   $ kn service apply <service_name> --image <image>

2. Add an environment variable to a service by running the command:

   $ kn service apply <service_name> --image <image> --env <key>=<value>

3. Read the service declaration from a JSON or YAML file by running the command:

   $ kn service apply <service_name> -f <filename>

Procedure

1. Describe a service by running the command:

   $ kn service describe --verbose <service_name>

   The --verbose flag is optional and provides a more detailed description. The following examples show the difference between regular and verbose output:

   You get an output similar to the following example:

   Name:       showcase
   Namespace:  default
   Age:        2m
   URL:        http://showcase-default.apps.ocp.example.com
   
   Revisions:
     100%  @latest (showcase-00001) [1] (2m)
           Image:  quay.io/openshift-knative/showcase (pinned to aaea76)
   
   Conditions:
     OK TYPE                   AGE REASON
     ++ Ready                   1m
     ++ ConfigurationsReady     1m
     ++ RoutesReady             1m

   You get an output similar to the following example:

   Name:         showcase
   Namespace:    default
   Annotations:  serving.knative.dev/creator=system:admin
                 serving.knative.dev/lastModifier=system:admin
   Age:          3m
   URL:          http://showcase-default.apps.ocp.example.com
   Cluster:      http://showcase.default.svc.cluster.local
   
   Revisions:
     100%  @latest (showcase-00001) [1] (3m)
           Image:  quay.io/openshift-knative/showcase (pinned to aaea76)
           Env:    GREET=Bonjour
   
   Conditions:
     OK TYPE                   AGE REASON
     ++ Ready                   3m
     ++ ConfigurationsReady     3m
     ++ RoutesReady             3m

2. Describe a service in YAML format by running the command:

   $ kn service describe <service_name> -o yaml

3. Describe a service in JSON format by running the command:

   $ kn service describe <service_name> -o json

4. Print the service URL only by running the command:

   $ kn service describe <service_name> -o url

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. List existing DomainMapping CRs:

   $ kn domain list -n <domain_mapping_namespace>

2. View details of an existing DomainMapping CR:

   $ kn domain describe <domain_mapping_name>

3. Update a DomainMapping CR to point to a new target:

   $ kn domain update --ref <target>

4. Delete a DomainMapping CR:

   $ kn domain delete <domain_mapping_name>