Skip to content

Latest commit

 

History

History
156 lines (116 loc) · 7.43 KB

README.md

File metadata and controls

156 lines (116 loc) · 7.43 KB
Raw

kn

kn is the Knative command line interface (CLI).

Getting Started

Installing kn

You can grab the latest nightly binary executable for:

Add the binary to the system PATH and ensure that it is executable.

Alternatively, check out the client repository, and type:

go install ./cmd/kn

To use the kn container image:

  • Nightly: gcr.io/knative-nightly/knative.dev/client/cmd/kn
  • Latest release: gcr.io/knative-releases/knative.dev/client/cmd/kn

To install kn using Homebrew:

brew tap knative/client
brew install kn

Connecting to your cluster

You'll need a kubectl-style config file to connect to your cluster.

  • Starting minikube writes this file (or gives you an appropriate context in an existing config file)
  • Instructions for Google GKE
  • Instructions for Amazon EKS
  • Instructions for IBM IKS
  • Instructions for Red Hat OpenShift
  • Or contact your cluster administrator

kn will pick up your kubectl config file in the default location of $HOME/.kube/config. You can specify an alternate kubeconfig connection file with --kubeconfig, or the env var $KUBECONFIG, for any command.

Configuration

There are a set of configuration parameters you can set up to customize kn. For example, you can specify where your kn plugins are located and how they are found or add prefixes for Knative eventing sink mappings.

Location

You can customize your kn CLI setup by creating a config.yaml configuration file. You can either provide the configuration via a --config flag or is picked up from a default location. The default configuration location conforms to the XDG Base Directory Specification and is different for Unix systems and Windows systems. If XDG_CONFIG_HOME env var is set, the default config location kn looks for is $XDG_CONFIG_HOME/kn, otherwise the file is looked up under the home directory of the user at $HOME/.config/kn/config.yaml. For Windows systems, the default kn configuration location is %APPDATA%\kn.

kn does not create a configuration file on its own, nor does it write into an existing configuration file. When kn does not find a configuration file it uses the default values described below.

Options

Options in config.yaml are grouped into categories:

  • Global - Global configuration values that affect all kn
  • Plugins - Plugin related configuration values like where to find plugins (sedction plugins:)
  • Eventing - Configuration that impacts eventing related operations (section: eventing:)

The following example contains a fully commented config.yaml with all available options:

# Plugins related configuration
plugins:
  # Whether to lookup configuration in the execution path (default: true). This option is deprecated and will be removed in a future version where path lookup will be enabled unconditionally
  path-lookup: true
  # Directory from where plugins with the prefix "kn-" are looked up. (default: "$base_dir/plugins"
  # where "$base_dir" is the directory where this configuration file is stored)
  directory: ~/.config/kn/plugins
# Eventing related configuration
eventing:
  # List of sink mappings that allow custom prefixes wherever a sink
  # specification is used (like for the --sink option of a broker)
  sink-mappings:
    # Prefix as used in the command (e.g. "--sink svc:myservice")
  - prefix: svc
    # Api group of the mapped resource
    group: core
    # Api version of the mapped resource
    version: v1
    # Resource name (lowercased plural form of the 'kind')
    resource: services
  # Channel mappings that you can use in --channel options
  channel-type-mappings:
    # Alias that can be used as a type for a channel option (e.g. "kn create channel mychannel --type Kafka")
  - alias: Kafka
    # Api group of the mapped resource
    group: messaging.knative.dev
    # Api version of the mapped resource
    version: v1alpha1
    # Kind of the resource
    kind: KafkaChannel

Plugin configuration

You can specify plugin related configuration in the top-level plugins: sections. You can specify the following options:

  • directory, which is the same as the persistent flag --plugins-dir and specifies the kn plugins directory. It defaults to: ~/.config/kn/plugins. By using the persistent flag (when you issue a command) or by specifying the value in the kn config, a user can select which directory to find kn plugins. It can be any directory that is visible to the user. The plugins need have a kn- prefix in their name (eg. kn-quickstart) to be detected by kn

  • path-lookup, which is the same as the persistent flag --lookup-plugins-in-path and specifies if kn should look for plugins anywhere in the specified PATH environment variable. This option is a boolean type, and the default value is true. This option is DEPRECATED and will be removed in a future version, when path lookup will be always enabled.

Eventing configuration

The eventing: top-level configuration section holds configuration options that influence the behaviour of eventing related commands.

  • sink-mappings defines prefixes to refer to Kubernetes Addressable resources as used in --sink kind of options. `sink-mappings refers to an array of individual mapping definitions that you can configure with these fields:

    • prefix: Prefix you want to describe your sink as. ksvc (serving.knative.dev/v1), broker (eventing.knative.dev/v1) and channel (messaging.knative.dev/v1) are predefined prefixes. Values in the configuration file can override these predefined prefixes.
    • group: The APIGroup of Kubernetes resource.
    • version: The version of Kubernetes resources.
    • resource: The plural name of Kubernetes resources (for example: services).

  • channel-type-mappings can be used to define aliases for custom channel types that can be used wherever a channel type is required (as in kn channel create --type). This configuration section defines an array of entries with the following fields:

    • alias: The name that can be used as the type
    • group: The APIGroup of the channel CRD.
    • version: The version of the channel CRD.
    • kind: Kind of the channel CRD (e.g. KafkaChannel)

Commands

Plugins

Kn supports plugins, which allow you to extend the functionality of your kn installation with custom commands and shared commands that are not part of the core distribution of kn. See the plugins documentation for more information.

More information on kn: