Add "creating a cluster" section to user guide

/kind documentation

Signed-off-by: Jorge Alarcon Ochoa <[email protected]>

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

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())

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

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 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.
+
+## 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/