Document kubeadm automation.

docs/admin/kubeadm.md

@@ -9,7 +9,7 @@ assignees:
 
 This document provides information on how to use kubeadm's advanced options.
 
-Running kubeadm init bootstraps a Kubernetes cluster. This consists of the
+Running `kubeadm init` bootstraps a Kubernetes cluster. This consists of the
 following steps:
 
 1. kubeadm runs a series of pre-flight checks to validate the system state
@@ -17,23 +17,35 @@ before making changes. Some checks only trigger warnings, others are
 considered errors and will exit kubeadm until the problem is corrected or
 the user specifies `--skip-preflight-checks`.
 
-1. kubeadm generates a token that additional nodes can use to register themselves
-with the master in future.
+1. kubeadm generates a token that additional nodes can use to register
+themselves with the master in future.  Optionally, the user can provide a token.
 
 1. kubeadm generates a self-signed CA using openssl to provision identities
 for each node in the cluster, and for the API server to secure communication
 with clients.
 
-1. Outputting a kubeconfig file for the kubelet to use to connect to the API server,
-as well as an additional kubeconfig file for administration.
+1. Outputting a kubeconfig file for the kubelet to use to connect to the API
+server, as well as an additional kubeconfig file for administration.
 
-1. kubeadm generates Kubernetes resource manifests for the API server, controller manager
-and scheduler, and placing them in `/etc/kubernetes/manifests`. The kubelet watches
-this directory for static resources to create on startup. These are the core
-components of Kubernetes, and once they are up and running we can use `kubectl`
-to set up/manage any additional components.
+1. kubeadm generates Kubernetes resource manifests for the API server,
+controller manager and scheduler, and placing them in
+`/etc/kubernetes/manifests`. The kubelet watches this directory for static
+resources to create on startup. These are the core components of Kubernetes, and
+once they are up and running we can use `kubectl` to set up/manage any
+additional components.
 
-1. kubeadm installs any add-on components, such as DNS or discovery, via the API server.
+1. kubeadm installs any add-on components, such as DNS or discovery, via the API
+server.
+
+Running `kubeadm join` on each node in the cluster consists of the following steps:
+
+1. Use the token to talk to the API server and securely get the root CA
+certificate.
+
+1. Creates a local key pair.  Prepares a certificate signing request (CSR) and
+sends that off to the API server for signing.
+
+1. Configures the local kubelet to connect to the API server
 
 ## Usage
 
@@ -127,7 +139,7 @@ necessary.
 
 By default, `kubeadm init` automatically generates the token used to initialise
 each new node. If you would like to manually specify this token, you can use the
-`--token` flag. The token must be of the format '<6 character string>.<16 character string>'.
+`--token` flag. The token must be of the format `<6 character string>.<16 character string>`.
 
 - `--use-kubernetes-version` (default 'v1.4.1') the kubernetes version to initialise
 
@@ -138,8 +150,8 @@ for a full list of available versions).
 
 ### `kubeadm join`
 
-`kubeadm join` has one mandatory flag, the token used to secure cluster bootstrap,
-and one mandatory argument, the master IP address.
+When you use kubeadm join, you must supply the token used to secure cluster
+boostrap as a mandatory flag, and the master IP address as a mandatory argument.
 
 Here's an example on how to use it:
 
@@ -156,6 +168,26 @@ necessary.
 By default, when `kubeadm init` runs, a token is generated and revealed in the output.
 That's the token you should use here.
 
+## Automating kubeadm
+
+Rather than copying the token you obtained from `kubeadm init` to each node, as
+in the basic `kubeadm` tutorials, you can parallelize the token distribution for
+easier automation. To implement this automation, you must know the IP address
+that the master will have after it is started.
+
+1.  Generate a token.  This token must have the form  `<6 character string>.<16
+character string>`
+
+    Here is a simple python one-liner for this:
+
+    ```
+    python -c 'import random; print "%0x.%0x" % (random.SystemRandom().getrandbits(3*8), random.SystemRandom().getrandbits(8*8))'
+    ```
+
+1. Start both the master node and the worker nodes concurrently with this token.  As they come up they should find each other and form the cluster.
+
+Once the cluster is up, you can grab the admin credentials from the master node at `/etc/kubernetes/admin.conf` and use that to talk to the cluster.
+
 ## Troubleshooting
 
 * Some users on RHEL/CentOS 7 have reported issues with traffic being routed incorrectly due to iptables being bypassed. You should ensure `net.bridge.bridge-nf-call-iptables` is set to 1 in your sysctl config, eg.

docs/getting-started-guides/kubeadm.md

@@ -13,6 +13,8 @@ The installation uses a tool called `kubeadm` which is part of Kubernetes 1.4.
 This process works with local VMs, physical servers and/or cloud servers.
 It is simple enough that you can easily integrate its use into your own automation (Terraform, Chef, Puppet, etc).
 
+See the full [`kubeadm` reference](/docs/admin/kubeadm) for information on all `kubeadm` command-line flags and for advice on automating `kubeadm` itself.
+
 **The `kubeadm` tool is currently in alpha but please try it out and give us [feedback](/docs/getting-started-guides/kubeadm/#feedback)!**
 
 ## Prerequisites