knative
/
client
mirror of https://github.com/knative/client.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update and reorganise kn cli setup docs (#1799) 

* Update and reorganise kn cli setup docs

* fix grammar

Co-authored-by: David Simansky <dsimansk@redhat.com>

* restore docs/README.md with selective content

* Update user guide link to point to official website

Co-authored-by: David Simansky <dsimansk@redhat.com>

---------

Co-authored-by: David Simansky <dsimansk@redhat.com>
This commit is contained in:
Dhruv Garg 2023-04-12 18:13:49 +05:30 committed by GitHub
parent dde1a60298
commit 1f9ece20ee
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 11 additions and 144 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/DEVELOPMENT.md → DEVELOPMENT.md
View File

@ -94,7 +94,7 @@ can be directly executed.
**Testing:**
Please follow the [guide](../test/README.md) here to test the `knative client`.
Please follow the [guide](test/README.md) here to test the `knative client`.
**Notes:**

13
README.md
View File

@ -37,13 +37,14 @@ install Knative with its prerequisites.
## Documentation
Start with the [user's guide](docs/README.md) to learn more. You can read about
Refer to the [user's guide](https://knative.dev/docs/client/) to learn more. You can read about
common use cases, get detailed documentation on each command, and learn how to
extend the `kn` CLI. For more information, have a look at:
extend the `kn` CLI.
- [User guide](docs/README.md)
- Installation - How to install `kn` and run on your machine
- Examples - Use case based examples
Following are some useful resources for getting-started using `kn` CLI:
- [Installation](https://knative.dev/docs/client/install-kn/) - how to install `kn` and run on your machine
- [Configuration](https://knative.dev/docs/client/configure-kn/) - how to customize `kn`
- [Reference Manual](docs/cmd/kn.md) - all possible commands and options with
usage examples
@ -52,4 +53,4 @@ Additionally you can visit [knative.dev](https://knative.dev) for more examples.
## Developers
If you are interested in contributing, see [CONTRIBUTING.md](./CONTRIBUTING.md)
and [DEVELOPMENT.md](docs/DEVELOPMENT.md).
and [DEVELOPMENT.md](DEVELOPMENT.md).

138
docs/README.md
View File

@ -1,141 +1,7 @@
# kn
`kn` is the Knative command line interface (CLI).
## Getting Started
### Installing `kn`
You can grab the latest nightly binary executable for:
- [macOS](https://storage.googleapis.com/knative-nightly/client/latest/kn-darwin-amd64)
- [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)
Add the binary to the system PATH and ensure that it is executable.
Alternatively, check out the client repository, and type:
```bash
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](https://brew.sh):
```bash
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](https://github.com/kubernetes/minikube) writes this file
(or gives you an appropriate context in an existing config file)
- Instructions for Google
[GKE](https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl)
- Instructions for Amazon
[EKS](https://docs.aws.amazon.com/eks/latest/userguide/create-kubeconfig.html)
- Instructions for IBM
[IKS](https://cloud.ibm.com/docs/containers?topic=containers-getting-started)
- Instructions for Red Hat
[OpenShift](https://docs.openshift.com/container-platform/4.1/cli_reference/administrator-cli-commands.html#create-kubeconfig)
- 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](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
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:
```yaml
# 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`)
`kn` is the Knative command line interface (CLI). Check out the
[official documentation](https://knative.dev/docs/client/).
## Commands

2
test/README.md
View File

@ -20,7 +20,7 @@ which need [`-tags=e2e`](#running-end-to-end-tests) to be enabled._
To run [the e2e tests](./e2e) locally, you need to have:
1. [Running knative environment.](../docs/DEVELOPMENT.md#create-a-cluster)
1. [Running knative environment.](../DEVELOPMENT.md#create-a-cluster)
2. `kn` binary in the \$PATH.
3. Please Make sure that you are able to connect to the cluster by following the
[guide here](./../docs#connecting-to-your-cluster)