kubernetes
/
website
mirror of https://github.com/kubernetes/website.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge pull request #2779 from jbeda/bootstrap-token 

Add details on Bootstrap Tokens
pull/2926/head^2
devin-donnelly 2017-03-20 11:20:04 -07:00 committed by GitHub
parent 9886f27a2e 017f4e66ea
commit 691a680c89
4 changed files with 216 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
_data/reference.yml
View File

@ -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

16
docs/admin/accessing-the-api.md
View File

@ -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.
@ -63,7 +63,7 @@ users in its object store.
Once the request is authenticated as coming from a specific user,
it moves to a generic authorization step. This is shown as step **2** in the
diagram.
diagram.
The input to the Authorization step are attributes of the REST request, including:
- the username determined by the Authentication step.
@ -75,12 +75,12 @@ The input to the Authorization step are attributes of the REST request, includin
There are multiple supported Authorization Modules. The cluster creator configures the API
server with which Authorization Modules should be used. When multiple Authorization Modules
are configured, each is checked in sequence, and if any Module authorizes the request,
are configured, each is checked in sequence, and if any Module authorizes the request,
then the request can proceed. If all deny the request, then the request is denied (HTTP status
code 403).
The [Authorization Modules](/docs/admin/authorization) page describes what authorization modules
are available and how to configure them.
are available and how to configure them.
For version 1.2, clusters created by `kube-up.sh` are configured so that no authorization is
required for any request.
@ -108,7 +108,7 @@ They act on objects being created, deleted, updated or connected (proxy), but no
Multiple admission controllers can be configured. Each is called in order.
This is shown as step **3** in the diagram.
This is shown as step **3** in the diagram.
Unlike Authentication and Authorization Modules, if any admission controller module
rejects, then the request is immediately rejected.
@ -122,7 +122,7 @@ Once a request passes all admission controllers, it is validated using the valid
for the corresponding API object, and then written to the object store (shown as step **4**).
## API Server Ports and IPs
## API Server Ports and IPs
The previous discussion applies to requests sent to the secure port of the API server
(the typical case). The API server can actually serve on 2 ports:
@ -141,8 +141,8 @@ By default the Kubernetes API server serves HTTP on 2 ports:
- protected by need to have host access
2. `Secure Port`:
- use whenever possible
- use whenever possible
- uses TLS. Set cert with `--tls-cert-file` and key with `--tls-private-key-file` flag.
- default is port 6443, change with `--secure-port` flag.
- default IP is first non-localhost network interface, change with `--bind-address` flag.

37
docs/admin/authentication.md
View File

@ -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`
@ -512,7 +547,7 @@ using an existing deployment script or manually through `easyrsa` or `openssl.`
#### Using an Existing Deployment Script
**Using an existing deployment script** is implemented at
`cluster/saltbase/salt/generate-cert/make-ca-cert.sh`.
`cluster/saltbase/salt/generate-cert/make-ca-cert.sh`.
Execute this script with two parameters. The first is the IP address
of API server. The second is a list of subject alternate names in the form `IP:<ip-address> or DNS:<dns-name>`.

171
docs/admin/bootstrap-tokens.md Normal file
View File

@ -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.