kn service commands

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

Creating serverless applications by using the Knative CLI

The following procedure describes how you can create a basic serverless application using the kn CLI.

Prerequisites
  • OpenShift Serverless Operator and Knative Serving are installed on your cluster.

  • You have installed the kn CLI.

Procedure
  • Create a Knative service:

    $ kn service create <service_name> --image <image> --env <key=value>
    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

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 use the 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.

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. The examples in the following procedure show the prefixes for mapping to 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 kn CLI tool.

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-domain-map --ref example-service
  • 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-domain-map --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-domain-map --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 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 kn CLI tool.

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>