mirror of https://github.com/knative/docs.git
Clean up and add to CLI docs (#3302)
* Clean up and add to CLI docs * updates from SME review * updates from SME review
This commit is contained in:
Ashleigh Brennan
GitHub
parent
914ef3188f
commit
2055f181ac
|
|
@ -0,0 +1,43 @@
|
|||
---
|
||||
title: "CLI tools"
|
||||
weight: 06
|
||||
type: "docs"
|
||||
showlandingtoc: "false"
|
||||
aliases:
|
||||
- /docs/reference/resources
|
||||
- /docs/client/connecting-kn-to-your-cluster
|
||||
---
|
||||
|
||||
The following CLI tools are supported for use with Knative.
|
||||
|
||||
## kubectl
|
||||
|
||||
You can use `kubectl` to apply the YAML files required to install Knative components, and also to create Knative resources, such as services and event sources using YAML.
|
||||
|
||||
See <a href="https://kubernetes.io/docs/tasks/tools/install-kubectl/" target="_blank">Install and Set Up `kubectl`</a>.
|
||||
|
||||
## kn
|
||||
|
||||
`kn` provides a quick and easy interface for creating Knative resources such as services and event sources, without the need to create or modify YAML files directly. `kn` also simplifies completion of otherwise complex procedures such as autoscaling and traffic splitting.
|
||||
|
||||
**NOTE:** `kn` cannot be used to install Knative components such as Serving or Eventing.
|
||||
|
||||
See [Installing `kn`](./install-kn/).
|
||||
|
||||
## Connecting CLI tools to your cluster
|
||||
|
||||
After you have installed `kubectl` or `kn`, these tools will search for the `kubeconfig` file of your cluster in the default location of `$HOME/.kube/config`, and will use this file to connect to the cluster.
|
||||
|
||||
A `kubeconfig` file is usually automatically created when you create a Kubernetes cluster.
|
||||
|
||||
For more information about `kubeconfig` files, see <a href="https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/" target="_blank">Organizing Cluster Access Using kubeconfig Files</a>.
|
||||
|
||||
### Using kubeconfig files with your platform
|
||||
|
||||
Instructions for using `kubeconfig` files are available for the following platforms:
|
||||
|
||||
- <a href="https://docs.aws.amazon.com/eks/latest/userguide/create-kubeconfig.html" target="_blank">Amazon EKS</a>
|
||||
- <a href="https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl" target="_blank">Google GKE</a>
|
||||
- <a href="https://cloud.ibm.com/docs/containers?topic=containers-getting-started" target="_blank">IBM IKS</a>
|
||||
- <a href="https://docs.openshift.com/container-platform/4.6/cli_reference/openshift_cli/administrator-cli-commands.html#create-kubeconfig" target="_blank">Red Hat OpenShift Cloud Platform</a>
|
||||
- Starting <a href="https://minikube.sigs.k8s.io/docs/start/" target="_blank">minikube</a> writes this file automatically, or provides an appropriate context in an existing configuration file.
|
||||
|
|
@ -1,18 +0,0 @@
|
|||
---
|
||||
title: "Connecting the `kn` Client to your cluster"
|
||||
linkTitle: "Connecting to your cluster"
|
||||
weight: 10
|
||||
type: "docs"
|
||||
---
|
||||
|
||||
The `kn` Client uses your `kubectl` client configuration, the kubeconfig file, to connect to your cluster. This file is usually automatically created when you create a Kubernetes cluster. `kn` looks for your kubeconfig file in the default location of `$HOME/.kube/config`.
|
||||
|
||||
For more information about kubeconfig files, see [Organizing Cluster Access Using kubeconfig Files](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/).
|
||||
|
||||
## Using kubeconfig files with your platform
|
||||
Instructions for using kubeconfig files are available for the following platforms:
|
||||
- [Amazon EKS](https://docs.aws.amazon.com/eks/latest/userguide/create-kubeconfig.html)
|
||||
- [Google GKE](https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl)
|
||||
- [IBM IKS](https://cloud.ibm.com/docs/containers?topic=containers-getting-started)
|
||||
- [Red Hat OpenShift Cloud Platform](https://docs.openshift.com/container-platform/4.1/cli_reference/administrator-cli-commands.html#create-kubeconfig)
|
||||
- Starting [minikube](https://github.com/kubernetes/minikube) writes this file (or gives you an appropriate context in an existing configuration file).
|
||||
|
|
@ -0,0 +1,73 @@
|
|||
---
|
||||
title: "Setting up kn"
|
||||
weight: 10
|
||||
type: "docs"
|
||||
aliases:
|
||||
- /docs/install/install-kn
|
||||
---
|
||||
|
||||
This guide provides details about how you can set up the Knative `kn` CLI.
|
||||
|
||||
## Install kn using a binary
|
||||
|
||||
You can install `kn` by downloading the executable binary for your system and placing it in the system path.
|
||||
|
||||
A link to the latest stable binary release is available on the <a href="https://github.com/knative/client/releases" target="_blank">`kn` release page</a>.
|
||||
|
||||
### Install kn using the nightly-built binary
|
||||
|
||||
Nightly-built executable binaries are available for users who want to install the latest pre-release build of `kn`.
|
||||
|
||||
**WARNING:** Nightly-built executable binaries include features which may not be included in the latest Knative release and are not considered to be stable.
|
||||
|
||||
Links to the latest nightly-built executable binaries are available here:
|
||||
|
||||
- <a href="https://storage.googleapis.com/knative-nightly/client/latest/kn-darwin-amd64" target="_blank">macOS</a>
|
||||
- <a href="https://storage.googleapis.com/knative-nightly/client/latest/kn-linux-amd64" target="_blank">Linux</a>
|
||||
- <a href="https://storage.googleapis.com/knative-nightly/client/latest/kn-windows-amd64.exe" target="_blank">Windows</a>
|
||||
|
||||
## Install kn using Go
|
||||
|
||||
1. Check out the `kn` client repository:
|
||||
|
||||
```
|
||||
git clone https://github.com/knative/client.git
|
||||
cd client/
|
||||
```
|
||||
|
||||
1. Build an executable binary:
|
||||
|
||||
```
|
||||
hack/build.sh -f
|
||||
```
|
||||
|
||||
1. Move `kn` into your system path, and verify that `kn` commands are working properly. For example:
|
||||
|
||||
```
|
||||
kn version
|
||||
```
|
||||
|
||||
## Install kn using brew
|
||||
|
||||
For macOs, you can install `kn` by using <a href="https://github.com/knative/homebrew-client" target="_blank">brew</a>.
|
||||
|
||||
## Running kn using container images
|
||||
|
||||
**WARNING:** Nightly container images include features which may not be included in the latest Knative release and are not considered to be stable.
|
||||
|
||||
Links to images are available here:
|
||||
|
||||
- <a href="https://gcr.io/knative-releases/knative.dev/client/cmd/kn" target="_blank">Latest release</a>
|
||||
- <a href="https://gcr.io/knative-nightly/knative.dev/client/cmd/kn" target="_blank">Nightly container image</a>
|
||||
|
||||
You can run `kn` from a container image. For example:
|
||||
|
||||
```
|
||||
docker run --rm -v "$HOME/.kube/config:/root/.kube/config" gcr.io/knative-releases/knative.dev/client/cmd/kn:latest service list
|
||||
```
|
||||
|
||||
**NOTE:** Running `kn` from a container image does not place the binary on a permanent path. This procedure must be repeated each time you want to use `kn`.
|
||||
|
||||
## Using kn with Tekton
|
||||
|
||||
See the <a href="http://hub.tekton.dev/tekton/task/kn" target="_blank">Tekton documentation</a>.
|
||||
|
|
@ -1,69 +0,0 @@
|
|||
---
|
||||
title: "Installing the Knative CLI"
|
||||
weight: 10
|
||||
type: "docs"
|
||||
---
|
||||
|
||||
This guide provides details about how you can install the Knative `kn` client (CLI) using various methods.
|
||||
|
||||
## Install `kn` using an executable binary
|
||||
|
||||
To install the `kn` Client, you must download the executable binary for your system. Links to the latest stable executable binary releases are available on the [`kn` release page](https://github.com/knative/client/releases).
|
||||
|
||||
You must place the executable binary in your system path, and make sure that it is executable.
|
||||
|
||||
### Install `kn` using nightly executable binary
|
||||
|
||||
Nightly executable binaries are available for users who want to install the most recent pre-release features of `kn`. These binaries include all `kn` features, even those not included in the latest stable release.
|
||||
|
||||
**WARNING:** Nightly executable binaries include features which may not be included in the latest stable Knative release, and are therefore not considered to be stable.
|
||||
|
||||
To install the `kn` Client, you must download the executable binary for your system. Links to the latest nightly executable binaries are available here:
|
||||
|
||||
- [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)
|
||||
|
||||
You must place the executable binary in your system path, and make sure that it is executable.
|
||||
|
||||
## Install `kn` using Go
|
||||
**Prerequisite:** Building `kn` requires Go v1.14 or newer. You will first need a working Go environment.
|
||||
1. Check out the [Client repository](https://github.com/knative/client):
|
||||
```bash
|
||||
git clone https://github.com/knative/client.git
|
||||
cd client/
|
||||
```
|
||||
1. Build an executable binary:
|
||||
```bash
|
||||
hack/build.sh -f
|
||||
```
|
||||
1. Move `kn` into your system path, and verify that `kn` commands are working properly. For example:
|
||||
```bash
|
||||
kn version
|
||||
```
|
||||
|
||||
## Install `kn` using brew
|
||||
|
||||
For macOs, you can [install kn using brew.](https://github.com/knative/homebrew-client)
|
||||
|
||||
## `kn` container images
|
||||
|
||||
The `kn` container images are available for users who require these for additional use cases. For example, if you want to use the `kn` container image with [Tekton](https://github.com/tektoncd/catalog/tree/master/kn).
|
||||
|
||||
Links to either the nightly container image or the latest stable container image are available here:
|
||||
|
||||
- [Nightly container image](https://gcr.io/knative-nightly/knative.dev/client/cmd/kn)
|
||||
- [Latest release](https://gcr.io/knative-releases/knative.dev/client/cmd/kn)
|
||||
|
||||
You can run `kn` from a container image. For example:
|
||||
```bash
|
||||
docker run --rm -v "$HOME/.kube/config:/root/.kube/config" gcr.io/knative-releases/knative.dev/client/cmd/kn:latest service list
|
||||
```
|
||||
|
||||
## Using `kn` with Tekton
|
||||
|
||||
You can also [run kn using Tekton](https://github.com/tektoncd/catalog/tree/master/kn).
|
||||
|
||||
## What's next
|
||||
To learn more about using `kn`, see the [documentation](https://github.com/knative/client/blob/master/docs/cmd/kn.md).
|
||||
|
||||
|
|
@ -1,56 +0,0 @@
|
|||
---
|
||||
title: "Additional resources"
|
||||
weight: 100
|
||||
type: "docs"
|
||||
aliases:
|
||||
- /docs/concepts/resources
|
||||
---
|
||||
|
||||
This page contains information about various tools and technologies that are
|
||||
useful to anyone developing on Knative.
|
||||
|
||||
### [`ko`](https://github.com/google/ko)
|
||||
|
||||
`ko` is a tool designed to make development of Go apps on Kubernetes easier, by
|
||||
abstracting away the container image being used, and instead referring to Go
|
||||
packages by their [import paths](https://golang.org/doc/code.html#ImportPaths)
|
||||
(e.g., `github.com/kaniko/serving/cmd/controller`)
|
||||
|
||||
The typical usage is `ko apply --filename config.yaml`, which reads in the
|
||||
config YAML, and looks for Go import paths representing runnable commands (i.e.,
|
||||
`package main`). When it finds a matching import path, `ko` builds the package
|
||||
using `go build` then pushes a container image containing that binary on top of
|
||||
a base image (by default, `gcr.io/distroless/base`) to
|
||||
`$KO_DOCKER_REPO/unique-string`. After pushing those images, `ko` replaces
|
||||
instances of matched import paths with fully-qualified references to the images
|
||||
it pushed.
|
||||
|
||||
So if `ko apply` was passed this config:
|
||||
|
||||
```yaml
|
||||
---
|
||||
image: github.com/my/repo/cmd/foo
|
||||
```
|
||||
|
||||
...it would produce YAML like:
|
||||
|
||||
```yaml
|
||||
---
|
||||
image: gcr.io/my-docker-repo/foo-zyxwvut@sha256:abcdef # image by digest
|
||||
```
|
||||
|
||||
(This assumes that you have set the environment variable
|
||||
`KO_DOCKER_REPO=gcr.io/my-docker-repo`)
|
||||
|
||||
`ko apply` then passes this generated YAML config to `kubectl apply`.
|
||||
|
||||
`ko` also supports:
|
||||
|
||||
- `ko publish` to simply push images and not produce configs.
|
||||
- `ko resolve` to push images and output the generated configs, but not
|
||||
`kubectl apply` them.
|
||||
- `ko delete` to simply passthrough to `kubectl delete` for convenience.
|
||||
|
||||
`ko` is used during development and release of Knative components, but is not
|
||||
intended to be required for _users_ of Knative -- they should only need to
|
||||
`kubectl apply` released configs generated by `ko`.
|
||||
Loading…
Reference in New Issue