Knative Serving CLI commands - Knative CLI | Serverless

kn service commands
About the Knative CLI offline mode
- Creating a service using offline mode
kn container commands
- Knative client multi-container support
kn domain commands
- Creating a custom domain mapping by using the Knative CLI
- Managing custom domain mappings by using the Knative CLI

You can use the following Knative (kn) CLI commands to complete Knative Serving tasks on the cluster.

kn service commands

You can use the following commands to create and manage Knative services.

Creating serverless applications by using the Knative CLI

Using the Knative (kn) CLI to create serverless applications provides a more streamlined and intuitive user interface over modifying YAML files directly. You can use the kn service create command to create a basic serverless application.

Prerequisites

OpenShift Serverless Operator and Knative Serving are installed on your cluster.
You have installed the Knative (kn) CLI.
You have created a project or have access to a project with the appropriate roles and permissions to create applications and other workloads in OpenShift Container Platform.

Procedure

Create a Knative service:

$ kn service create <service_name> --image <image> --tag <tag-value>

Where:

--image is the URI of the image for the application.

--tag is an optional flag that can be used to add a tag to the initial revision that is created with the service.

Example command

$ kn service create event-display \
    --image quay.io/openshift-knative/knative-eventing-sources-event-display:latest

Example output

Creating service 'event-display' in namespace 'default':

  0.271s The Route is still working to reflect the latest desired specification.
  0.580s Configuration "event-display" is waiting for a Revision to become ready.
  3.857s ...
  3.861s Ingress has not yet been reconciled.
  4.270s Ready to serve.

Service 'event-display' created with latest revision 'event-display-bxshg-1' and URL:
http://event-display-default.apps-crc.testing

Updating serverless applications by using the Knative CLI

You can use the kn service update command for interactive sessions on the command line as you build up a service incrementally. In contrast to the kn service apply command, when using the kn service update command you only have to specify the changes that you want to update, rather than the full configuration for the Knative service.

Example commands

Update a service by adding a new environment variable:

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

Update a service by adding a new port:

$ kn service update <service_name> --port 80

Update a service by adding new request and limit parameters:

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

Assign the latest tag to a revision:

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

Update a tag from testing to staging for the latest READY revision of a service:

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

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
```

Applying service declarations

You can declaratively configure a Knative service by using the kn service apply command. If the service does not exist it is created, otherwise the existing service is updated with the options that have been changed.

The kn service apply command is especially useful for shell scripts or in a continuous integration pipeline, where users typically want to fully specify the state of the service in a single command to declare the target state.

When using kn service apply you must provide the full configuration for the Knative service. This is different from the kn service update command, which only requires you to specify in the command the options that you want to update.

Example commands

Create a service:

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

Add an environment variable to a service:

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

Read the service declaration from a JSON or YAML file:
```
$ kn service apply <service_name> -f <filename>
```

Describing serverless applications by using the Knative CLI

You can describe a Knative service by using the kn service describe command.

Example commands

Describe a service:

$ kn service describe --verbose <service_name>

The --verbose flag is optional but can be included to provide a more detailed description. The difference between a regular and verbose output is shown in the following examples:

Example output without --verbose flag

Name:       hello
Namespace:  default
Age:        2m
URL:        http://hello-default.apps.ocp.example.com

Revisions:
  100%  @latest (hello-00001) [1] (2m)
        Image:  docker.io/openshift/hello-openshift (pinned to aaea76)

Conditions:
  OK TYPE                   AGE REASON
  ++ Ready                   1m
  ++ ConfigurationsReady     1m
  ++ RoutesReady             1m

Example output with --verbose flag

Name:         hello
Namespace:    default
Annotations:  serving.knative.dev/creator=system:admin
              serving.knative.dev/lastModifier=system:admin
Age:          3m
URL:          http://hello-default.apps.ocp.example.com
Cluster:      http://hello.default.svc.cluster.local

Revisions:
  100%  @latest (hello-00001) [1] (3m)
        Image:  docker.io/openshift/hello-openshift (pinned to aaea76)
        Env:    RESPONSE=Hello Serverless!

Conditions:
  OK TYPE                   AGE REASON
  ++ Ready                   3m
  ++ ConfigurationsReady     3m
  ++ RoutesReady             3m

Describe a service in YAML format:

$ kn service describe <service_name> -o yaml

Describe a service in JSON format:

$ kn service describe <service_name> -o json

Print the service URL only:

$ kn service describe <service_name> -o url

About the Knative CLI offline mode

When you execute kn service commands, the changes immediately propagate to the cluster. However, as an alternative, you can execute kn service commands in offline mode. When you create a service in offline mode, no changes happen on the cluster, and instead the service descriptor file is created on your local machine.

The offline mode of the Knative CLI is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red Hat Technology Preview features, see https://access.redhat.com/support/offerings/techpreview/.

After the descriptor file is created, you can manually modify it and track it in a version control system. You can also propagate changes to the cluster by using the kn service create -f, kn service apply -f, or oc apply -f commands on the descriptor files.

The offline mode has several uses:

You can manually modify the descriptor file before using it to make changes on the cluster.
You can locally track the descriptor file of a service in a version control system. This enables you to reuse the descriptor file in places other than the target cluster, for example in continuous integration (CI) pipelines, development environments, or demos.
You can examine the created descriptor files to learn about Knative services. In particular, you can see how the resulting service is influenced by the different arguments passed to the kn command.

The offline mode has its advantages: it is fast, and does not require a connection to the cluster. However, offline mode lacks server-side validation. Consequently, you cannot, for example, verify that the service name is unique or that the specified image can be pulled.

Creating a service using offline mode

You can execute kn service commands in offline mode, so that no changes happen on the cluster, and instead the service descriptor file is created on your local machine. After the descriptor file is created, you can modify the file before propagating changes to the cluster.

For more information about the support scope of Red Hat Technology Preview features, see https://access.redhat.com/support/offerings/techpreview/.

Prerequisites

OpenShift Serverless Operator and Knative Serving are installed on your cluster.
You have installed the Knative (kn) CLI.

Procedure

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 cluster, the descriptor file is created in the current namespace. Otherwise, the descriptor file is created in the default namespace.
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.

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: {}

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 cluster, kn searches for the service in the subdirectory that is named after the current namespace. Otherwise, kn searches in the default/ subdirectory.

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

kn container commands

You can use the following commands to create and manage multiple containers in a Knative service spec.

Knative client multi-container support

You can use the kn container add command to print YAML container spec to standard output. This command is useful for multi-container use cases because it can be used along with other standard kn flags to create definitions.

The kn container add command accepts all container-related flags that are supported for use with the kn service create command. The kn container add command can also be chained by using UNIX pipes (|) to create multiple container definitions at once.

Example commands

Add a container from an image and print it to standard output:

$ kn container add <container_name> --image <image_uri>

Example command

$ kn container add sidecar --image docker.io/example/sidecar

Example output

containers:
- image: docker.io/example/sidecar
  name: sidecar
  resources: {}

Chain two kn container add commands together, and then pass them to a kn service create command to create a Knative service with two containers:

$ kn container add <first_container_name> --image <image_uri> | \
kn container add <second_container_name> --image <image_uri> | \
kn service create <service_name> --image <image_uri> --extra-containers -

--extra-containers - specifies a special case where kn reads the pipe input instead of a YAML file.

Example command

$ kn container add sidecar --image docker.io/example/sidecar:first | \
kn container add second --image docker.io/example/sidecar:second | \
kn service create my-service --image docker.io/example/my-app:latest --extra-containers -

The --extra-containers flag can also accept a path to a YAML file:

$ kn service create <service_name> --image <image_uri> --extra-containers <filename>

Example command

$ kn service create my-service --image docker.io/example/my-app:latest --extra-containers my-extra-containers.yaml

kn domain commands

You can use the following commands to create and manage domain mappings.

Creating a custom domain mapping by using the Knative CLI

You can customize the domain for your Knative service by mapping a custom domain name that you own to a Knative service. You can use the Knative (kn) CLI to create a DomainMapping custom resource (CR) that maps to an Addressable target CR, such as a Knative service or a Knative route.

Prerequisites

The OpenShift Serverless Operator and Knative Serving are installed on your cluster.
You have created a Knative service or route, and control a custom domain that you want to map to that CR.

Your custom domain must point to the DNS of the OpenShift Container Platform cluster.
You have installed the Knative (kn) CLI.
You have created a project or have access to a project with the appropriate roles and permissions to create applications and other workloads in OpenShift Container Platform.

Procedure

Map a domain to a CR in the current namespace:
```
$ kn domain create <domain_mapping_name> --ref <target_name>
```
Example command
```
$ kn domain create example.com --ref example-service
```
The --ref flag specifies an Addressable target CR for domain mapping.

If a prefix is not provided when using the --ref flag, it is assumed that the target is a Knative service in the current namespace.

Map a domain to a Knative service in a specified namespace:

$ kn domain create <domain_mapping_name> --ref <ksvc:service_name:service_namespace>

Example command

$ kn domain create example.com --ref ksvc:example-service:example-namespace

Map a domain to a Knative route:

$ kn domain create <domain_mapping_name> --ref <kroute:route_name>

Example command

$ kn domain create example.com --ref kroute:example-route

Managing custom domain mappings by using the Knative CLI

After you have created a DomainMapping custom resource (CR), you can list existing CRs, view information about an existing CR, update CRs, or delete CRs by using the Knative (kn) CLI.

Prerequisites

The OpenShift Serverless Operator and Knative Serving are installed on your cluster.
You have created at least one DomainMapping CR.
You have installed the Knative (kn) CLI tool.
You have created a project or have access to a project with the appropriate roles and permissions to create applications and other workloads in OpenShift Container Platform.

Procedure

List existing DomainMapping CRs:

$ kn domain list -n <domain_mapping_namespace>

View details of an existing DomainMapping CR:

$ kn domain describe <domain_mapping_name>

Update a DomainMapping CR to point to a new target:
```
$ kn domain update --ref <target>
```

Delete a DomainMapping CR:

$ kn domain delete <domain_mapping_name>