mirror of https://github.com/knative/client.git
chore: fixed documentation of configuration options in README (#1297)
* chore: fixed documentation of configuration options in README * chore: Updated according to review comments.
This commit is contained in:
Roland Huß
GitHub
parent
e5b19e12ab
commit
5ce3d1b71d
118
docs/README.md
118
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.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue