From 94b36f0a160d1a9e7ddef6498003a1b4210009c1 Mon Sep 17 00:00:00 2001 From: Jorge Alarcon Ochoa Date: Tue, 20 Nov 2018 15:01:45 -0600 Subject: [PATCH] Add "creating a cluster" section to user guide /kind documentation Signed-off-by: Jorge Alarcon Ochoa --- cmd/kind/create/cluster/createcluster.go | 7 +- cmd/kind/create/create.go | 3 +- docs/README.md | 3 +- docs/user-guide.md | 85 ++++++++++++++++++------ 4 files changed, 69 insertions(+), 29 deletions(-) diff --git a/cmd/kind/create/cluster/createcluster.go b/cmd/kind/create/cluster/createcluster.go index 7a61cc3cd2..84ff487204 100644 --- a/cmd/kind/create/cluster/createcluster.go +++ b/cmd/kind/create/cluster/createcluster.go @@ -36,15 +36,14 @@ type flags struct { func NewCommand() *cobra.Command { flags := &flags{} cmd := &cobra.Command{ - // TODO(bentheelder): more detailed usage Use: "cluster", - Short: "Creates a cluster", - Long: "Creates a Kubernetes cluster", + Short: "Creates a local Kubernetes cluster", + Long: "Creates a local Kubernetes cluster using Docker container 'nodes'", Run: func(cmd *cobra.Command, args []string) { run(flags, cmd, args) }, } - cmd.Flags().StringVar(&flags.Name, "name", "1", "the cluster context name") + cmd.Flags().StringVar(&flags.Name, "name", "1", "cluster context name") cmd.Flags().StringVar(&flags.Config, "config", "", "path to a kind config file") cmd.Flags().StringVar(&flags.ImageName, "image", "", "node docker image to use for booting the cluster") return cmd diff --git a/cmd/kind/create/create.go b/cmd/kind/create/create.go index 96f1faf335..4567c60dae 100644 --- a/cmd/kind/create/create.go +++ b/cmd/kind/create/create.go @@ -28,10 +28,9 @@ import ( // NewCommand returns a new cobra.Command for cluster creation func NewCommand() *cobra.Command { cmd := &cobra.Command{ - // TODO(bentheelder): more detailed usage Use: "create", Short: "Creates one of [cluster]", - Long: "Creates one of [cluster]", + Long: "Creates one of local Kubernetes cluster (cluster)", RunE: run, } cmd.AddCommand(createcluster.NewCommand()) diff --git a/docs/README.md b/docs/README.md index 1f88cb1a1e..166f6ca1e8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,9 +1,10 @@ # `kind` Documentation -For the primary design start with [design][design]. For usage documentation see the [user guide][user guide]. +For the primary design start with [design][design]. + [design]: ./design.md [user guide]: ./user-guide.md diff --git a/docs/user-guide.md b/docs/user-guide.md index 0c91cf435e..123cd3879f 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -1,16 +1,71 @@ # User Guide -## Advanced +## Creating a Cluster + +Creating a Kubernetes cluster is as simple as: +``` +$ kind create cluster +``` + +This will bootstrap a Kubernetes cluster using a pre-built +[node image][node image] - you can find it on docker hub +[`kindest/node`][kindest/node]. +If you desire to build the node image yourself see the +[building image](#building-images) section. +To specify another image use the `--image` flag. + +By default, the cluster will be given the name `kind-1`. "1," here, is the +default context name. +Use the `--name` flag to assign the cluster a different context name. + +Once a cluster is created you can use [kubectl][kubectl] to interact with it by +using the configuration file generated by `kind`: +``` +export KUBECONFIG="$(kind get kubeconfig-path)" +kubectl cluster-info +``` + +`kind get kubeconfig-path` returns the location of the generated confguration +file. + +`kind` also allows you to customize your Kubernetes cluster by using a kind +configuration file. +For a sample kind configuration file see +[kind-example-config][kind-example-config]. +To use a kind configuration file use the `--config` flag and pass the path to +the file. -### Building the base and node images -#### Base image -`kind` runs a local kubernetes cluster by using Docker containers as "nodes." -`kind` uses the [`node-image`][node image] to run kubernetes artifacts, such + +## Building Images + +`kind` runs a local Kubernetes cluster by using Docker containers as "nodes." +`kind` uses the [`node-image`][node image] to run Kubernetes artifacts, such as `kubeadm` or `kubelet`. The `node-image` in turn is built off the [`base-image`][base image], which installs all the dependencies needed for Docker and Kubernetes to run in a container. +See [base image](#base-image), for more advanced information information. + +Currently, `kind` supports three different ways to build a `node-image`: via +`apt`, or if you have the [Kubernetes][kubernetes] source in your host machine +(`$GOPATH/src/k8s.io/kubernetes`), by using `docker` or `bazel`. +To specify the build type use the flag `--type`. +`kind` will default to using the build type `docker` if none is specified. + +``` +$ kind build node-image --type apt +``` + +Similarly as for the base-image command, you can specify the name and tag of +the resulting node image using the flag `--image`. + +If you previously changed the name and tag of the base image, you can use here +the flag `--base-image` to specify the name and tag you used. + +## Advanced + +### Building The Base Image To build the `base-image` we use the `build` command: ``` $ kind build base-image @@ -29,25 +84,11 @@ If you want to change this, you can use the `--image` flag. $ kind build base-image --image base:v0.1.0 ``` -#### Node image -Currently, `kind` supports three different ways to build a `node-image`: via -`apt`, or if you have the [kubernetes][kubernetes] source in your host machine -(`$GOPATH/src/k8s.io/kubernetes`), by using `docker` or `bazel`. -To specified the build type use the flag `--type`. -`Kind` will default to using the build type `docker` if none is specified. - -``` -$ kind build node-image --type apt -``` - -Similarly as for the base-image command, you can specify the name and tag of -the resulting node image using the flag `--image`. - -If you previously changed the name and tag of the base image, you can use here -the flag `--base-image` to specify the name and tag you used. - [node image]: ./base-image.md [base image]: ./node-image.md +[kind-example-config]: ./kind-example-config.yaml [pkg/build/base/sources]: ./../pkg/build/base/sources [kubernetes]: https://github.com/kubernetes/kubernetes +[kindest/node]: https://hub.docker.com/r/kindest/node/ +[kubectl]: https://kubernetes.io/docs/reference/kubectl/overview/