Add details on Bootstrap Tokens

_data/reference.yml

@@ -25,6 +25,7 @@ toc:
     section:
     - docs/admin/accessing-the-api.md
     - docs/admin/authentication.md
+    - docs/admin/bootstrap-tokens.md
     - title: Authorization Plugins
       section:
       - docs/admin/authorization/index.md

docs/admin/accessing-the-api.md

@@ -42,7 +42,7 @@ The input to the authentication step is the entire HTTP request, however, it typ
 just examines the headers and/or client certificate.
 
 Authentication modules include Client Certificates, Password, and Plain Tokens,
-and JWT Tokens (used for service accounts).
+Bootstrap Tokens, and JWT Tokens (used for service accounts).
 
 Multiple authentication modules can be specified, in which case each one is tried in sequence,
 until one of them succeeds.

docs/admin/authentication.md

@@ -107,6 +107,41 @@ header as shown below.
 Authorization: Bearer 31ada4fd-adec-460c-809a-9e56ceb75269
 ```
 
+### Bootstrap Tokens
+
+This feature is currently in **alpha**.
+
+To allow for streamlined bootstrapping for new clusters, Kubernetes includes a
+dynamically-managed Bearer token type called a *Bootstrap Token*. These tokens
+are stored as Secrets in the `kube-system` namespace, where they can be
+dynamically managed and created. Controller Manager contains a TokenCleaner
+controller that deletes bootstrap tokens as they expire.
+
+The tokens are of the form `[a-z0-9]{6}.[a-z0-9]{16}`.  The first component is a
+Token ID and the second component is the Token Secret.  You specify the token
+in an HTTP header as follows:
+
+```http
+Authorization: Bearer 781292.db7bc3a58fc5f07e
+```
+
+You must enable the Bootstrap Token Authenticator with the
+`--experimental-bootstrap-token-auth` flag on the API Server.  You must enable
+the TokenCleaner controller via the `--controllers` flag on the Controller
+Manager.  This is done with something like `--controllers=*,tokencleaner`.
+`kubeadm` will do this for you if you are using it to bootstrapping a cluster.
+
+The authenticator authenticates as `system:bootstrap:<Token ID>`.  It is
+included in the `system:bootstrappers` group.  The naming and groups are
+intentionally limited to discourage users from using these tokens past
+bootstrapping.  The user names and group can be used (and are used by `kubeadm`)
+to craft the appropriate authorization policies to support bootstrapping a
+cluster.
+
+Please see [Bootstrap Tokens](/docs/admin/bootstrap-tokens/) for in depth
+documentation on the Bootstrap Token authenticator and controllers along with
+how to manage these tokens with `kubeadm`.
+
 ### Static Password File
 
 Basic authentication is enabled by passing the `--basic-auth-file=SOMEFILE`

docs/admin/bootstrap-tokens.md

@@ -0,0 +1,171 @@
+---
+assignees:
+- jbeda
+title: Authenticating with Bootstrap Tokens
+---
+
+* TOC
+{:toc}
+
+## Overview
+
+Bootstrap tokens are a simple bearer token that is meant to be used when
+creating new clusters or joining new nodes to an existing cluster.  It was built
+to support [`kubeadm`](/docs/admin/kubeadm/), but can be used in other contexts
+for users that wish to start clusters without `kubeadm`. It is also built to
+work, via RBAC policy, with the [Kubelet TLS
+Bootstrap](/docs/admin/kubelet-tls-bootstrap/) system.
+
+Bootstrap Tokens are defined with a specific type
+(`bootstrap.kubernetes.io/token`) of secrets that lives in the `kube-system`
+namespace.  These Secrets are then read by the Bootstrap Authenticator in the
+API Server.  Expired tokens are removed with the TokenCleaner controller in the
+Controller Manager.  The tokens are also used to create a signature for a
+specific ConfigMap used in a "discovery" process through a BootstrapSigner
+controller.
+
+Currently, Bootstrap Tokens are **alpha** but there are no large breaking
+changes expected.
+
+## Token Format
+
+Bootstrap Tokens take the form of `abcdef.0123456789abcdef`.  More formally,
+they must match the regular expression `[a-z0-9]{6}\.[a-z0-9]{16}`.
+
+The first part of the token is the "Token ID" and is considered public
+information.  It is used when referring to a token without leaking the secret
+part used for authentication. The second part is the "Token Secret" and should
+only be shared with trusted parties.
+
+## Enabling Bootstrap Tokens
+
+All features for Bootstrap Tokens are disabled by default in Kubernetes v1.6.
+
+You can enable the Bootstrap Token authenticator with the
+`--experimental-bootstrap-token-auth` flag on the API server.  You can enable
+the Bootstrap controllers by specifying them withthe `--controllers` flag on the
+controller manager with something like
+`--controllers=*,tokencleaner,bootstrapsigner`.  This is done automatically when
+using `kubeadm`.
+
+Tokens are used in an HTTPS call as follows:
+
+```http
+Authorization: Bearer 07401b.f395accd246ae52d
+```
+
+## Bootstrap Token Secret Format
+
+Each valid token is backed by a secret in the `kube-system` namespace.  You can
+find the full design doc
+[here](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/bootstrap-discovery.md).
+
+Here is what the secret looks like.  Note that `base64(string)` indicates the
+value should be base64 encoded.  The undecoded version is provided here for
+readability.
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: bootstrap-token-07401b
+  namespace: kube-system
+type: bootstrap.kubernetes.io/token
+data:
+  description: base64(The default bootstrap token generated by 'kubeadm init'.)
+  token-id: base64(07401b)
+  token-secret: base64(f395accd246ae52d)
+  expiration: base64(2017-03-10T03:22:11Z)
+  usage-bootstrap-authentication: base64(true)
+  usage-bootstrap-signing: base64(true)
+```
+
+The type of the secret must be `bootstrap.kubernetes.io/token` and the name must
+be `bootstrap-token-<token id>`.  It must also exist in the `kube-system`
+namespace.  `description` is a human readable discription that should not be
+used for machine readable information.  The Token ID and Secret are included in
+the data dictionary.
+
+The `usage-bootstrap-*` members indicate what this secret is intended to be used
+for.  A value must be set to `true` to be enabled.
+
+`usage-bootstrap-authentication` indicates that the token can be used to
+authenticate to the API server.  The authenticator authenticates as
+`system:bootstrap:<Token ID>`.  It is included in the `system:bootstrappers`
+group.  The naming and groups are intentionally limited to discourage users from
+using these tokens past bootstrapping.
+
+`usage-bootstrap-signing` indicates that the token should be used to sign the
+`cluster-info` ConfigMap as described below.
+
+The `expiration` data member lists a time after which the token is no longer
+valid.  This is encoded as an absolute UTC time using RFC3339.  The TokenCleaner
+controller will delete expired tokens.
+
+## Token Management with `kubeadm`
+
+You can use the `kubeadm` tool to manage tokens on a running cluster.  It will
+automatically grab the default admin credentials on a master from a `kubeadm`
+created cluster (`/etc/kubernetes/admin.conf`).  You can specify an alternate
+kubeconfig file for credentials with the `--kubeconfig` to the following
+commands.
+
+* `kubeadm token list` Lists the tokens along with when they expire and what the
+  approved usages are.
+* `kubeadm token create` Creates a new token.
+    * `--description` Set the description on the new token.
+    * `--ttl duration` Set expiration time of the token as a delta from "now".
+      Default is 0 for no expiration.
+    * `--usages` Set the ways that the token can be used.  The default is
+      `signing,authentication`.  These are the usages as described above.
+* `kubeadm token delete <token id>|<token id>.<token secret>` Delete a token.
+  The token can either be identified with just an ID or with the entire token
+  value.  Only the ID is used; the token is still deleted if the secret does not
+  match.
+
+## ConfigMap Signing
+
+In addition to authentication, the tokens can be used to sign a ConfigMap.  This
+is used early in a cluster bootstrap process before the client trusts the API
+server.  The signed ConfigMap can be authenicated by the shared token.
+
+The ConfigMap that is signed is `cluster-info` in the `kube-public` namespace.
+The typical flow is that a client reads this ConfigMap while unauthenticated and
+ignoring TLS errors.  It then validates the payload of the ConfigMap by looking
+at a signature embedded in the ConfigMap.
+
+The ConfigMap may look like this:
+
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: cluster-info
+  namespace: kube-public
+data:
+  jws-kubeconfig-07401b: eyJhbGciOiJIUzI1NiIsImtpZCI6IjA3NDAxYiJ9..tYEfbo6zDNo40MQE07aZcQX2m3EB2rO3NuXtxVMYm9U
+  kubeconfig: |
+    apiVersion: v1
+    clusters:
+    - cluster:
+        certificate-authority-data: <really long certificate data>
+        server: https://10.138.0.2:6443
+      name: ""
+    contexts: []
+    current-context: ""
+    kind: Config
+    preferences: {}
+    users: []
+```
+
+The `kubeconfig` member of the ConfigMap is a config file with just the cluster
+information filled out.  The key thing being communicated here is the
+`certificate-authority-data`.  This may be expanded in the future.
+
+The signature is a JWS signature using the "detached" mode.  To validate the
+signature, the user should encode the `kubeconfig` payload according to JWS
+rules (base64 encoded while discarding any trailing `=`).  That encoded payload
+is then used to form a whole JWS by inserting it between the 2 dots.  You can
+verify the JWS using the `HS256` scheme (HMAC-SHA256) with the full token (e.g.
+`07401b.f395accd246ae52d`) as the shared secret.  Users _must_ verify that HS256
+is used.