OpenShift docs are moving and will soon only be available at docs.redhat.com, the home of all Red Hat product documentation. Explore the new docs experience today.
  1. Documentation
    2. history
×

Getting started with Knative Client

You are viewing documentation for a release of Red Hat OpenShift Serverless that is no longer supported. Red Hat OpenShift Serverless is currently supported on OpenShift Container Platform 4.3 and newer.

Knative Client (kn) is the Knative command line interface (CLI). The CLI exposes commands for managing your applications, as well as lower level tools to interact with components of OpenShift Container Platform. With kn, you can create applications and manage OpenShift Container Platform projects from the terminal.

Before you begin

Knative Client does not have its own log in mechanism. To log in to the cluster you must install the oc CLI and use oc login.

Installation options for the oc CLI will vary depending on your operating system. For more information on installing the oc CLI for your operating system and logging in with oc, see the CLI getting started documentation.

Installing Knative Client

Installing the kn CLI using the OpenShift Container Platform web console

Once the {ServerlessOperatorName} is installed, you will see a link to download the kn CLI for Linux, macOS and Windows from the Command Line Tools page in the OpenShift Container Platform web console.

You can access the Command Line Tools page by clicking the question circle icon in the top right corner of the web console and selecting Command Line Tools in the drop down menu.

Procedure

  1. Download the kn CLI from the Command Line Tools page.

  2. Unpack the archive:

    $ tar -xf <file>

  3. Move the kn binary to a directory on your PATH.

  4. To check your path, run:

    $ echo $PATH

    If you do not use RHEL or Fedora, ensure that libc is installed in a directory on your library path. If libc is not available, you might see the following error when you run CLI commands:

    $ kn: No such file or directory

Installing the kn CLI for Linux using an RPM

For Red Hat Enterprise Linux (RHEL), you can install kn as an RPM if you have an active OpenShift Container Platform subscription on your Red Hat account.

Procedure

  • Use the following command to install kn:

# subscription-manager register
# subscription-manager refresh
# subscription-manager attach --pool=<pool_id> (1)
# subscription-manager repos --enable="openshift-serverless-1-for-rhel-8-x86_64-rpms"
# yum install openshift-serverless-clients
1 Pool ID for an active OpenShift Container Platform subscription

Installing the kn CLI for Linux

For Linux distributions, you can download the CLI directly as a tar.gz archive.

Procedure

  1. Download the CLI.

  2. Unpack the archive:

    $ tar -xf <file>

  3. Move the kn binary to a directory on your PATH.

  4. To check your path, run:

    $ echo $PATH

    If you do not use RHEL or Fedora, ensure that libc is installed in a directory on your library path. If libc is not available, you might see the following error when you run CLI commands:

    $ kn: No such file or directory

Installing the kn CLI for macOS

kn for macOS is provided as a tar.gz archive.

Procedure

  1. Download the CLI.

  2. Unpack and unzip the archive.

  3. Move the kn binary to a directory on your PATH.

  4. To check your PATH, open a terminal window and run:

    $ echo $PATH

Installing the kn CLI for Windows

The CLI for Windows is provided as a zip archive.

Procedure

  1. Download the CLI.

  2. Unzip the archive with a ZIP program.

  3. Move the kn binary to a directory on your PATH.

  4. To check your PATH, open the Command Prompt and run the command:

    C:\> path

Basic workflow using Knative Client

Use this basic workflow to create, read, update, delete (CRUD) operations on a service. The following example deploys a simple Hello World service that reads the environment variable TARGET and prints its output.

Procedure

  1. Create a service in the default namespace from an image.

    $ kn service create hello --image gcr.io/knative-samples/helloworld-go --env TARGET=Knative
Creating service 'hello' in namespace 'default':

  0.085s The Route is still working to reflect the latest desired specification.
  0.101s Configuration "hello" is waiting for a Revision to become ready.
 11.590s ...
 11.650s Ingress has not yet been reconciled.
 11.726s Ready to serve.

Service 'hello' created with latest revision 'hello-gsdks-1' and URL:
http://hello.default.apps-crc.testing

  2. List the service.

    $ kn service list
NAME    URL                                     LATEST          AGE     CONDITIONS   READY   REASON
hello   http://hello.default.apps-crc.testing   hello-gsdks-1   8m35s   3 OK / 3     True

  3. Check if the service is working by using the curl service endpoint command:

    $ curl http://hello.default.apps-crc.testing

Hello Knative!

  4. Update the service.

    $ kn service update hello --env TARGET=Kn
Updating Service 'hello' in namespace 'default':

 10.136s Traffic is not yet migrated to the latest revision.
 10.175s Ingress has not yet been reconciled.
 10.348s Ready to serve.

Service 'hello' updated with latest revision 'hello-dghll-2' and URL:
http://hello.default.apps-crc.testing

    The service’s environment variable TARGET is now set to Kn.

  5. Describe the service.

    $ kn service describe hello
Name:       hello
Namespace:  default
Age:        13m
URL:        http://hello.default.apps-crc.testing
Address:    http://hello.default.svc.cluster.local

Revisions:
  100%  @latest (hello-dghll-2) [2] (1m)
        Image:  gcr.io/knative-samples/helloworld-go (pinned to 5ea96b)

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

  6. Delete the service.

    $ kn service delete hello
Service 'hello' successfully deleted in namespace 'default'.

    You can then verify that the hello service is deleted by attempting to list it.

    $ kn service list hello
No services found.

Autoscaling workflow using Knative Client

You can access autoscaling capabilities by using kn to modify Knative services without editing YAML files directly.

Use the service create and service update commands with the appropriate flags to configure the autoscaling behavior.

Flag Description

--concurrency-limit int

Hard limit of concurrent requests to be processed by a single replica.

--concurrency-target int

Recommendation for when to scale up based on the concurrent number of incoming requests. Defaults to --concurrency-limit.

--max-scale int

Maximum number of replicas.

--min-scale int

Minimum number of replicas.

Traffic splitting using Knative Client

kn helps you control which revisions get routed traffic on your Knative service.

Knative service allows for traffic mapping, which is the mapping of revisions of the service to an allocated portion of traffic. It offers the option to create unique URLs for particular revisions and has the ability to assign traffic to the latest revision.

With every update to the configuration of the service, a new revision is created with the service route pointing all the traffic to the latest ready revision by default.

You can change this behavior by defining which revision gets a portion of the traffic.

Procedure

  • Use the kn service update command with the --traffic flag to update the traffic.

--traffic RevisionName=Percent uses the following syntax:

  • The --traffic flag requires two values separated by separated by an equals sign (=).

  • The RevisionName string refers to the name of the revision.

  • Percent integer denotes the traffic portion assigned to the revision.

  • Use identifier @latest for the RevisionName to refer to the latest ready revision of the service. You can use this identifier only once with the --traffic flag.

  • If the service update command updates the configuration values for the service along with traffic flags, the @latest reference will point to the created revision to which the updates are applied.

  • --traffic flag can be specified multiple times and is valid only if the sum of the Percent values in all flags totals 100.

For example, to route 10% of traffic to your new revision before putting all traffic on, use the following command:

$ kn service update svc --traffic @latest=10 --traffic svc-vwxyz=90

Assigning tag revisions

A tag in a traffic block of service creates a custom URL, which points to a referenced revision. A user can define a unique tag for an available revision of a service which creates a custom URL by using the format http(s)://TAG-SERVICE.DOMAIN.

A given tag must be unique to its traffic block of the service. kn supports assigning and unassigning custom tags for revisions of services as part of the kn service update command.

If you have assigned a tag to a particular revision, a user can reference the revision by its tag in the --traffic flag as --traffic Tag=Percent.
Procedure

  • Use the following command:

    $ kn service update svc --tag @latest=candidate --tag svc-vwxyz=current

--tag RevisionName=Tag uses the following syntax:

  • --tag flag requires two values separated by a =.

  • RevisionName string refers to name of the Revision.

  • Tag string denotes the custom tag to be given for this Revision.

  • Use the identifier @latest for the RevisionName to refer to the latest ready revision of the service. You can use this identifier only once with the --tag flag.

  • If the service update command is updating the configuration values for the Service (along with tag flags), @latest reference will be pointed to the created Revision after applying the update.

  • --tag flag can be specified multiple times.

  • --tag flag may assign different tags to the same revision.

Unassigning tag revisions

Tags assigned to revisions in a traffic block can be unassigned. Unassigning tags removes the custom URLs.

If a revision is untagged and it is assigned 0% of the traffic, it is removed from the traffic block entirely.
Procedure

  • A user can unassign the tags for revisions using the kn service update command:

    $ kn service update svc --untag candidate

--untag Tag uses the following syntax:

  • The --untag flag requires one value.

  • The tag string denotes the unique tag in the traffic block of the service which needs to be unassigned. This also removes the respective custom URL.

  • The --untag flag can be specified multiple times.

Traffic flag operation precedence

All traffic-related flags can be specified using a single kn service update command. kn defines the precedence of these flags. The order of the flags specified when using the command is not taken into account.

The precedence of the flags as they are evaluated by kn are:

  1. --untag: All the referenced revisions with this flag are removed from the traffic block.

  2. --tag: Revisions are tagged as specified in the traffic block.

  3. --traffic: The referenced revisions are assigned a portion of the traffic split.

Traffic splitting flags

kn supports traffic operations on the traffic block of a service as part of the kn service update command.

The following table displays a summary of traffic splitting flags, value formats, and the operation the flag performs. The "Repetition" column denotes whether repeating the particular value of flag is allowed in a kn service update command.

Flag Value(s) Operation Repetition

--traffic

RevisionName=Percent

Gives Percent traffic to RevisionName

Yes

--traffic

Tag=Percent

Gives Percent traffic to the Revision having Tag

Yes

--traffic

@latest=Percent

Gives Percent traffic to the latest ready Revision

No

--tag

RevisionName=Tag

Gives Tag to RevisionName

Yes

--tag

@latest=Tag

Gives Tag to the latest ready Revision

No

--untag

Tag

Removes Tag from Revision

Yes