Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 1. Knative Serving CLI commands

1.1. kn service commands
Copy link

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

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>
    Copy to Clipboard Toggle word wrap

    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 showcase \
    --image quay.io/openshift-knative/showcase
      Copy to Clipboard Toggle word wrap

      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
      Copy to Clipboard Toggle word wrap

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>
    Copy to Clipboard Toggle word wrap

  • Update a service by adding a new port: 

    $ kn service update <service_name> --port 80
    Copy to Clipboard Toggle word wrap

  • Update a service by adding new request and limit parameters: 

    $ kn service update <service_name> --request cpu=500m --limit memory=1024Mi --limit cpu=1000m
    Copy to Clipboard Toggle word wrap

  • Assign the latest tag to a revision: 

    $ kn service update <service_name> --tag <revision_name>=latest
    Copy to Clipboard Toggle word wrap

  • 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
    Copy to Clipboard Toggle word wrap

  • 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
    Copy to Clipboard Toggle word wrap

1.1.3. Applying service declarations
Copy link

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>
    Copy to Clipboard Toggle word wrap

  • Add an environment variable to a service: 

    $ kn service apply <service_name> --image <image> --env <key>=<value>
    Copy to Clipboard Toggle word wrap

  • Read the service declaration from a JSON or YAML file: 

    $ kn service apply <service_name> -f <filename>
    Copy to Clipboard Toggle word wrap

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

Example commands

  • Describe a service: 

    $ kn service describe --verbose <service_name>
    Copy to Clipboard Toggle word wrap

    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
    Copy to Clipboard Toggle word wrap

    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
    Copy to Clipboard Toggle word wrap

  • Describe a service in YAML format: 

    $ kn service describe <service_name> -o yaml
    Copy to Clipboard Toggle word wrap

  • Describe a service in JSON format: 

    $ kn service describe <service_name> -o json
    Copy to Clipboard Toggle word wrap

  • Print the service URL only: 

    $ kn service describe <service_name> -o url
    Copy to Clipboard Toggle word wrap

1.2. kn service commands in offline mode
Copy link

1.2.1. About the Knative CLI offline mode
Copy link

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
Copy link

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

  1. In offline mode, create a local Knative service descriptor file: 

    $ kn service create showcase \
    --image quay.io/openshift-knative/showcase \
    --target ./ \
    --namespace test
    Copy to Clipboard Toggle word wrap

    Example output

    Service 'showcase' created in namespace 'test'.
    Copy to Clipboard Toggle word wrap

    • 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 ./
    Copy to Clipboard Toggle word wrap

    Example output

    ./
└── test
    └── ksvc
        └── showcase.yaml

2 directories, 1 file
    Copy to Clipboard Toggle word wrap

    • 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
    Copy to Clipboard Toggle word wrap

    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: {}
    Copy to Clipboard Toggle word wrap

  4. List information about the new service: 

    $ kn service describe showcase --target ./ --namespace test
    Copy to Clipboard Toggle word wrap

    Example output

    Name:       showcase
Namespace:  test
Age:
URL:

Revisions:

Conditions:
  OK TYPE    AGE REASON
    Copy to Clipboard Toggle word wrap

    • 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
    Copy to Clipboard Toggle word wrap

    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
    Copy to Clipboard Toggle word wrap

1.3. kn container commands
Copy link

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
Copy link

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>
    Copy to Clipboard Toggle word wrap

    Example command

    $ kn container add sidecar --image docker.io/example/sidecar
    Copy to Clipboard Toggle word wrap

    Example output

    containers:
- image: docker.io/example/sidecar
  name: sidecar
  resources: {}
    Copy to Clipboard Toggle word wrap

  • 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 -
    Copy to Clipboard Toggle word wrap

    --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 -
    Copy to Clipboard Toggle word wrap

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

    $ kn service create <service_name> --image <image_uri> --extra-containers <filename>
    Copy to Clipboard Toggle word wrap

    Example command

    $ kn service create my-service --image docker.io/example/my-app:latest --extra-containers my-extra-containers.yaml
    Copy to Clipboard Toggle word wrap

1.4. kn domain commands
Copy link

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

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: 

    $ kn domain create <domain_mapping_name> --ref <target_name>
    Copy to Clipboard Toggle word wrap

    Example command

    $ kn domain create example.com --ref showcase
    Copy to Clipboard Toggle word wrap

    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>
    Copy to Clipboard Toggle word wrap

    Example command

    $ kn domain create example.com --ref ksvc:showcase:example-namespace
    Copy to Clipboard Toggle word wrap

  • Map a domain to a Knative route: 

    $ kn domain create <domain_mapping_name> --ref <kroute:route_name>
    Copy to Clipboard Toggle word wrap

    Example command

    $ kn domain create example.com --ref kroute:example-route
    Copy to Clipboard Toggle word wrap

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>
    Copy to Clipboard Toggle word wrap

  • View details of an existing DomainMapping CR: 

    $ kn domain describe <domain_mapping_name>
    Copy to Clipboard Toggle word wrap

  • Update a DomainMapping CR to point to a new target: 

    $ kn domain update --ref <target>
    Copy to Clipboard Toggle word wrap

  • Delete a DomainMapping CR: 

    $ kn domain delete <domain_mapping_name>
    Copy to Clipboard Toggle word wrap
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat