Chapter 1. Knative Serving CLI commands 1.1. kn service commands You can use the following commands to create and manage Knative services. 1.1.1. 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: USD 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 USD kn service create showcase \ --image quay.io/openshift-knative/showcase Example output Creating service 'showcase' in namespace 'default': 0.271s The Route is still working to reflect the latest desired specification. 0.580s Configuration "showcase" is waiting for a Revision to become ready. 3.857s ... 3.861s Ingress has not yet been reconciled. 4.270s Ready to serve. Service 'showcase' created with latest revision 'showcase-00001' and URL: http://showcase-default.apps-crc.testing 1.1.2. 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: USD kn service update <service_name> --env <key>=<value> Update a service by adding a new port: USD kn service update <service_name> --port 80 Update a service by adding new request and limit parameters: USD kn service update <service_name> --request cpu=500m --limit memory=1024Mi --limit cpu=1000m Assign the latest tag to a revision: USD kn service update <service_name> --tag <revision_name>=latest Update a tag from testing to staging for the latest READY revision of a service: USD 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: USD kn service update <service_name> --tag <revision_name>=test --traffic test=10,@latest=90 1.1.3. 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: USD kn service apply <service_name> --image <image> Add an environment variable to a service: USD kn service apply <service_name> --image <image> --env <key>=<value> Read the service declaration from a JSON or YAML file: USD kn service apply <service_name> -f <filename> 1.1.4. 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: USD 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: 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 Example output with --verbose flag 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 Describe a service in YAML format: USD kn service describe <service_name> -o yaml Describe a service in JSON format: USD kn service describe <service_name> -o json Print the service URL only: USD kn service describe <service_name> -o url 1.2. kn service commands in offline mode 1.2.1. 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. Important 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 Technology Preview Features Support Scope . 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. 1.2.2. 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. Important 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 Technology Preview Features Support Scope . 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: USD 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. Examine the created directory structure: USD 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. Examine the generated service descriptor file: USD 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: {} List information about the new service: USD 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. Use the service descriptor file to create the service on the cluster: USD 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 1.3. kn container commands You can use the following commands to create and manage multiple containers in a Knative service spec. 1.3.1. 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: USD kn container add <container_name> --image <image_uri> Example command USD 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: USD 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 USD 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: USD kn service create <service_name> --image <image_uri> --extra-containers <filename> Example command USD kn service create my-service --image docker.io/example/my-app:latest --extra-containers my-extra-containers.yaml 1.4. kn domain commands You can use the following commands to create and manage domain mappings. 1.4.1. Creating a custom domain mapping by using the Knative CLI 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. Note 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: USD kn domain create <domain_mapping_name> --ref <target_name> Example command USD kn domain create example.com --ref showcase 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: USD kn domain create <domain_mapping_name> --ref <ksvc:service_name:service_namespace> Example command USD kn domain create example.com --ref ksvc:showcase:example-namespace Map a domain to a Knative route: USD kn domain create <domain_mapping_name> --ref <kroute:route_name> Example command USD kn domain create example.com --ref kroute:example-route 1.4.2. 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: USD kn domain list -n <domain_mapping_namespace> View details of an existing DomainMapping CR: USD kn domain describe <domain_mapping_name> Update a DomainMapping CR to point to a new target: USD kn domain update --ref <target> Delete a DomainMapping CR: USD kn domain delete <domain_mapping_name>

Commands:
kn service create <service-name> --image <image> --tag <tag-value>
kn service create showcase --image quay.io/openshift-knative/showcase
Creating service 'showcase' in namespace 'default': 0.271s The Route is still working to reflect the latest desired specification. 0.580s Configuration "showcase" is waiting for a Revision to become ready. 3.857s 3.861s Ingress has not yet been reconciled. 4.270s Ready to serve. Service 'showcase' created with latest revision 'showcase-00001' and URL: http://showcase-default.apps-crc.testing
kn service update <service_name> --env <key>=<value>
kn service update <service_name> --port 80
kn service update <service_name> --request cpu=500m --limit memory=1024Mi --limit cpu=1000m
kn service update <service_name> --tag <revision_name>=latest
kn service update <service_name> --untag testing --tag @latest=staging
kn service update <service_name> --tag <revision_name>=test --traffic test=10,@latest=90
kn service apply <service_name> --image <image>
kn service apply <service_name> --image <image> --env <key>=<value>
kn service apply <service_name> -f <filename>
kn service describe --verbose <service_name>
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
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
kn service describe <service_name> -o yaml
kn service describe <service_name> -o json
kn service describe <service_name> -o url
kn service create showcase --image quay.io/openshift-knative/showcase --target ./ --namespace test
Service 'showcase' created in namespace 'test'.
tree ./
./ └── test └── ksvc └── showcase.yaml 2 directories, 1 file
cat test/ksvc/showcase.yaml
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: {}
kn service describe showcase --target ./ --namespace test
Name: showcase Namespace: test Age: URL: Revisions: Conditions: OK TYPE AGE REASON
kn service create -f test/ksvc/showcase.yaml
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
kn container add <container_name> --image <image_uri>
kn container add sidecar --image docker.io/example/sidecar
containers: - image: docker.io/example/sidecar name: sidecar resources: {}
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 -
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 -
kn service create <service_name> --image <image_uri> --extra-containers <filename>
kn service create my-service --image docker.io/example/my-app:latest --extra-containers my-extra-containers.yaml
kn domain create <domain_mapping_name> --ref <target_name>
kn domain create example.com --ref showcase
kn domain create <domain_mapping_name> --ref <ksvc:service_name:service_namespace>
kn domain create example.com --ref ksvc:showcase:example-namespace
kn domain create <domain_mapping_name> --ref <kroute:route_name>
kn domain create example.com --ref kroute:example-route
kn domain list -n <domain_mapping_namespace>
kn domain describe <domain_mapping_name>
kn domain update --ref <target>
kn domain delete <domain_mapping_name>