diff --git a/docs/README.md b/docs/README.md index 59a57c53b..c1fec4dd6 100644 --- a/docs/README.md +++ b/docs/README.md @@ -12,7 +12,7 @@ You can grab the latest nightly binary executable for: - [Linux](https://storage.googleapis.com/knative-nightly/client/latest/kn-linux-amd64) - [Windows](https://storage.googleapis.com/knative-nightly/client/latest/kn-windows-amd64.exe) -Put it on your system path, and make sure it's executable. +Add the binary to the system PATH and ensure that it is executable. Alternatively, check out the client repository, and type: @@ -52,67 +52,93 @@ You'll need a `kubectl`-style config file to connect to your cluster. `$HOME/.kube/config`. You can specify an alternate kubeconfig connection file with `--kubeconfig`, or the env var `$KUBECONFIG`, for any command. -## Kn Config +## Configuration -There are a set of configuration parameters you can setup to better customize +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, and you can specify the prefix for your addressable `sink` -objects. The `kn` configuration file is meant to capture these configuration -options. Let's explore this file's location, and the options you are able to -change with it. +they are found or add prefixes for Knative eventing sink mappings. ### Location -The default location `kn` looks for config is under the home directory of the -user at `$HOME/.config/kn/config.yaml`. It is not created for you as part of the -`kn` installation. You can create this file elsewhere and use the `--config` -flag to specify its path. +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](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) 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 -Below are the options you can specify in the `kn` config file. +Options in `config.yaml` are grouped into categories: -1. `pluginsDir` which is the same as the persistent flag `--plugins-dir` and - specifies the kn plugins directory. It defaults to: `~/.config/kn/plugins`. +* **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: + +```yaml +# Plugins related configuration +plugins: + # Whether to lookup configuration in the execution path (default: false) + path-lookup: true + # Directory from where plugins are looked up. (default: "$base_dir/plugins" + # where "$base_dir" is the directory where this configuration file is stored) + directory: ~/.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. -2. `lookupPluginsInPath` 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 is a boolean - configuration option and the default value is `false`. +* `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 `false`. -3. `sink` defines your prefix to refer to Kubernetes addressable resources. To - configure a sink prefix, define following in the config file: - 1. `prefix`: Prefix you want to describe your sink as. `service` or `svc` - (`serving.knative.dev/v1`) and `broker` (`eventing.knative.dev/v1alpha1`) - are predefined prefixes in `kn`. These predefined prefixes can be - overridden by values in configuration file. - 2. `group`: The APIGroup of Kubernetes resource. - 3. `version`: The version of Kubernetes resources. - 4. `resource`: The plural name of Kubernetes resources (for example: - services). +#### Eventing configuration -For example, the following `kn` config will look for `kn` plugins in the user's -`PATH` and also execute plugin in `~/kn/.config/plugins`. It also defines a sink -prefix `myprefix` which refers to `brokers` in `eventing.knative.dev/v1alpha1`. -With this configuration, you can use `myprefix:default` to describe a Broker -`default` in `kn` command line. +The `eventing:` top-level configuration section holds configuration options that influence the behaviour of eventing related commands. -```bash -cat ~/.config/kn/config.yaml -lookupPluginsInPath: true -pluginsdir: ~/.config/kn/plugins -sink: -- prefix: myprefix - group: eventing.knative.dev - version: v1alpha1 - resource: brokers -``` - ---- +* `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 - See the [generated documentation](cmd/kn.md) @@ -121,7 +147,7 @@ sink: ## Plugins Kn supports plugins, which allow you to extend the functionality of your `kn` -installation with custom commands as well as shared commands that are not part +installation with custom commands and shared commands that are not part of the core distribution of `kn`. See the [plugins documentation](plugins/README.md) for more information.