diff --git a/docs/client/_index.md b/docs/client/_index.md new file mode 100755 index 000000000..ec03f86be --- /dev/null +++ b/docs/client/_index.md @@ -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 Install and Set Up `kubectl`. + +## 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 Organizing Cluster Access Using kubeconfig Files. + +### Using kubeconfig files with your platform + +Instructions for using `kubeconfig` files are available for the following platforms: + +- Amazon EKS +- Google GKE +- IBM IKS +- Red Hat OpenShift Cloud Platform +- Starting minikube writes this file automatically, or provides an appropriate context in an existing configuration file. diff --git a/docs/client/connecting-kn-to-your-cluster.md b/docs/client/connecting-kn-to-your-cluster.md deleted file mode 100644 index b81db4bff..000000000 --- a/docs/client/connecting-kn-to-your-cluster.md +++ /dev/null @@ -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). diff --git a/docs/client/install-kn.md b/docs/client/install-kn.md new file mode 100644 index 000000000..4258cf389 --- /dev/null +++ b/docs/client/install-kn.md @@ -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 `kn` release page. + +### 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: + +- macOS +- Linux +- Windows + +## 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 brew. + +## 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: + +- Latest release +- Nightly container image + +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 Tekton documentation. diff --git a/docs/install/install-kn.md b/docs/install/install-kn.md deleted file mode 100644 index 66a6fe59a..000000000 --- a/docs/install/install-kn.md +++ /dev/null @@ -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). - diff --git a/docs/reference/resources.md b/docs/reference/resources.md deleted file mode 100644 index 9a53b0fd3..000000000 --- a/docs/reference/resources.md +++ /dev/null @@ -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`.