Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update kubeadm docs for 1.6 #2829

Merged
merged 2 commits into from
Mar 20, 2017

Conversation

jbeda
Copy link
Contributor

@jbeda jbeda commented Mar 15, 2017

It is also built on top of #2779 so ignore that commit.


This change is Reviewable

@jbeda jbeda added the do-not-merge DEPRECATED. Indicates that a PR should not merge. Label can only be manually applied/removed. label Mar 15, 2017
@jbeda jbeda added this to the 1.6 milestone Mar 15, 2017
@jbeda jbeda requested review from lukemarsden and luxas March 15, 2017 04:42
@k8s-ci-robot k8s-ci-robot added the cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. label Mar 15, 2017
@@ -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).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

oxford comma

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in #2779.

as a "Bootstrap Token".

These tokens are stored as Secrets in the `kube-system` namespace. As such they
can be dynamically created and managed. There is a controller (BootstrapSigner)
Copy link
Contributor

@deads2k deads2k Mar 15, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I thought it was the tokencleaner.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch! Fixed in #2779

Copy link
Member

@luxas luxas left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd still like a section at the bottom describing what kind of stability we have on different components in kubeadm:

CLI UX: beta
Config file: alpha
Selfhosting: alpha
The phases command: alpha
Implementation under the hood: alpha

  • Due to that we're targeting upgrades/HA in future versions and the fact we're using alpha features in core (the bootstrapsigner/tokencleaner and tokenauthmodule)

Be sure to read the [limitations](#limitations); in particular note that kubeadm doesn't have great support for
automatically configuring cloud providers. Please refer to the specific cloud provider documentation or
use another provisioning system.**
**The kubeadm tool is currently in beta but please try it out and give us
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The kubeadm command-line UX is in beta, but please...

We should mention the implementation somehow might change yet (especially when we're targeting HA it will change). And somehow we should point out that the kubeadm alpha subcommands are unstable and that we're using alpha features in core (BS, TC and BootstrapTokenAuth)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That could be a separate section later in the doc indeed with a link to it here

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Created a sub-section of "Overview" with more details.


If you are not constrained, there are some other tools built to give you complete clusters:
If you are not constrained, there are some other tools built to give you
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

some other more higher-level tools that aim to give you a complete cluster:

1. 1GB or more of RAM per machine (any less will leave little room for your
apps)
1. Full network connectivity between all machines in the cluster (public or
private network is fine)

## Objectives

* Install a secure Kubernetes cluster on your machines
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are we confident in the secure here? :) I know it wasn't changed here but...

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Making it clear that we "aim to create a secure cluster"

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Where did you make this change? Can't see it in the diff

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Found it!

It runs on all of the machines in your cluster and does things like starting pods and containers.
* `kubectl`: the command to control the cluster once it's running.
You will only need this on the master, but it can be useful to have on the other nodes as well.
* `docker`: the container runtime, which Kubernetes depends on. v1.12 is
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess v1.11.2 is still recommended or?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that v1.12 is supported so i'm going to list that.

See the reference doc if you want to read about the different [kubeadm releases](https://github.com/kubernetes/kubeadm/blob/master/CHANGELOG.md)
**Note:** If you already have kubeadm installed, you should do a `apt-get update &&
apt-get upgrade` or `yum update` to get the latest version of kubeadm. See the
reference doc if you want to read about the different [kubeadm
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See the kubeadm-specific Release Notes if you want to know more about what has changed between releases


``` bash
kubectl describe svc front-end -n sock-shop
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

a simple kubectl -n sock-shop get svc front-end is sufficent here

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

BTW -- sock shop demo outputs errors like:

the namespace from the provided object "zipkin" does not match the namespace "sock-shop". You must pass '--namespace=zipkin' to perform this operation.

Might want to pass that on to weave folks.


### (Optional) Installing a sample application
Currently, only the pod network flannel is working on multiple architectures.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You can remove the flannel install statement here now and just say that flannel works on amd64, arm, arm64 and ppc64le and weave works on amd64, arm, arm64

`kubeadm.conf` with the following contents:

``` yaml
cloudProvider: <cloud provider>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

please make this a full example:

kind: MasterConfiguration
apiVersion: kubeadm.k8s.io/v1alpha1
cloudProvider: <cloud provider>

and point out that this part (the config file) of kubeadm is alpha


Currently, only the pod network flannel is working on multiple architectures. You can install it this way:
You may have trouble in the configuration if you see the following statuses.
This example is for canal but there may be similar errors for other pod network
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we have something more generic to not favor anyone?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I just moved this down to make the main flow better. I'm open to reviewing a PR that changes the example. For now I want to get this in without having to test out a bunch of stuff by forcing some errors.

1. The cluster created here has a single master, with a single `etcd` database running on it.
This means that if the master fails, your cluster loses its configuration data and will need to be recreated from scratch.
Adding HA support (multiple `etcd` servers, multiple API servers, etc) to `kubeadm` is still a work-in-progress.
The ```kubectl describe``` comand gives you more details about what went wrong.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

only one ` is sufficent

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah -- someone added that in there and I thought I got them all.

@luxas
Copy link
Member

luxas commented Mar 15, 2017

Yeah, just noting that some of my comments here weren't direct comments to @jbeda's changes, but improvements that we could make at the same time we're really reading through and trying to make the docs better.

@devin-donnelly
Copy link
Contributor

@jbeda This PR modifies several of the same files as #2779. I think that's going to cause merge conflicts. I've already commented on the changes there; perhaps those files should be backed out of this PR?

@jbeda
Copy link
Contributor Author

jbeda commented Mar 16, 2017

@devin-donnelly I based this on that so that I could review them the same. As I manage the rebase I'm keeping things clean and making sure I can resolve. Just look at the last two commits in the set. (actually, just the last one should matter).

@jbeda
Copy link
Contributor Author

jbeda commented Mar 16, 2017

@luxas Comments addressed. PTAL

@devin-donnelly This merges in the latest changes in the other PR.

I'm removing the WIP mark as I think this is ready for review.

@jbeda jbeda removed the do-not-merge DEPRECATED. Indicates that a PR should not merge. Label can only be manually applied/removed. label Mar 16, 2017
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 where using a "detached" mode. To validate the
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the "where" in this sentence is superfluous.

`certificate-authority-data`. This may be expanded in the future.

The signature is a JWS signature where using a "detached" mode. To validate the
signature, the user should encode the `kubeconfig` payload according to JWS
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the user -> you

The signature is a JWS signature where using a "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. The JWS
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"You can verify the 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. The JWS
can be verified using the `HS256` scheme (HMAC-SHA256) with the full token (e.g.
`07401b.f395accd246ae52d`) as the shared secret. Users MUST verify that HS256
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Users MUST -> You must

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changed but... All caps MUST is a language from RFCs to say that this should not be ignored. People used to implementing protocols know that this is something that you shouldn't ignore.

The kubelet is now restarting every few seconds, as it waits in a crashloop for
kubeadm to tell it what to do.

Note: Disabling SELinux by running `setenforce 0` is required in order to allow
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Note: You must disable SELinux to allow containers to access the host filesystem..."

| gcr.io/google_containers/kube-discovery-amd64 | 1.0
| gcr.io/google_containers/pause-amd64 | 3.0

Right now you can't run `kubeadm init` twice without tearing down the cluster in
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remove "right now" unless we can tell the user something about when this might change.


A few seconds later, you should notice that running `kubectl get nodes` on the master shows a cluster with as many machines as you created.
The nodes are where your workloads (containers and pods, etc) run. If you want
to add any new machines as nodes to your cluster, for each machine: SSH to that
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"To add any new machines to your cluster as nodes, you must do the following for each machine"

Reformat the instructions as a numbered list.


If there is a firewall, make sure it exposes this port to the internet before you try to access it.
It takes several minutes to download and start all the containers, watch the
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Replace comma with period. Start the resulting second sentence with:

"You can watch the output of..."


## Tear down
Then go to the IP address of your cluster's master node in your browser, and
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Comma after "Then".


This workflow is not yet fully supported, however we hope to make it extremely easy to spin up clusters with cloud providers in the future.
(See [this proposal](https://github.com/kubernetes/community/pull/128) for more information) The [Kubelet Dynamic Settings](https://github.com/kubernetes/kubernetes/pull/29459) feature may also help to fully automate this process in the future.
Enabling specific cloud providers is a common request, this currently requires
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Replace comma with period. Second sentence becomes: "However, specific cloud providers require manual configuration and are therefore not supported by kubeadm in version 1.6."

Copy link
Contributor

@lukemarsden lukemarsden left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great work @jbeda! Please address my comments as you see fit and merge at will. No need for me to take another look.

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. ThYou specify the token
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ThYou -> You

Authorization: Bearer 781292.db7bc3a58fc5f07e
```

You must enable the Bootstrap Token Authenticator with the
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When must you do this? Does kubeadm do this for you?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To be clear, these docs are written not assuming kubeadm as this can be used by other systems that aren't kubeadm. I'd rather have real docs vs. referring folks to a design doc that may be a little raw.


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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you give an example of when they're used in kubeadm?

And an example of how you might expect users to use them in other contexts?

@@ -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).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What's the difference between Bootstrap Tokens and JWT Tokens? Are JWT tokens the old separate-to-API-server version, whereas Bootstrap Tokens are the new built-in thing? If we're no longer supporting "JWT Tokens" can we just remove the reference to them here?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bootstrap tokens don't use JWT at all -- they are just random values. The JWT tokens actually are encoded and signed tokens used for authentication. We do use JWS for doing the configmap signing, but that is unrelated and not part of the authentication flow.


This feature is currently in **alpha**.

o allow for streamlined bootstrapping for new clusters, Kubernetes includes a
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

o -> To


``` bash
scp root@<master ip>:/etc/kubernetes/admin.conf .
kubectl --kubeconfig ./admin.conf get nodes
```

**Note:** By default GCE instances disable ssh access for root. First log in to
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

First -> If you are using GCE, first

the machine, copy the file someplace that can be accessed and then use [`gcloud
compute
copy-files`](https://cloud.google.com/sdk/gcloud/reference/compute/copy-files)

### (Optional) Connecting to the API Server

If you want to connect to the API Server for viewing the dashboard (note: the
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

let's just get rid of the reference to dashboard here, if we're not going to describe how to install it

"If you want to connect to the API Server from outside the cluster you can use"

@@ -428,23 +415,34 @@ running.

Then go to the IP address of your cluster's master node in your browser, and
specify the given port. So for example, `http://<master_ip>:<port>`. In the
example above, this was `30001`, but it is a different port for you.
example above, this was `30001`, but it may be a different port for you.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

actually, it'll always be 30001 now, so we can reword this accordingly

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not if you've installed other services....

* To undo what kubeadm did, simply run:
To undo what kubeadm did, you should first [drain the
node](https://kubernetes.io/docs/user-guide/kubectl/kubectl_drain/) and make
sure that the node is empty before turning it down.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"turning it down" -> "shutting it down" (we're not all {ex-,}googlers 😉)

kubeadm reset
```

If you wish to start over simply run `kubeadm init` or `kubeadm join`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

with the appropriate arguments as described above

* Word wrap paragraphs
* Switch to fenced code blocks for all code samples
* Render programs as plain text
* Separate out program invocation from program output

Much of this is to follow the style guide: https://kubernetes.io/docs/contribute/style-guide/

Signed-off-by: Joe Beda <joe.github@bedafamily.com>
@jbeda
Copy link
Contributor Author

jbeda commented Mar 18, 2017

Pushed new changes and separated out the stuff from #2779. It turns out building these on top of each other just confused all reviewers.

Copy link
Member

@luxas luxas left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One review round on the docs/admin/kubeadm.md file

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. kubeadm generates a self-signed CA using openssl to provision identities for
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's not using openssl and it's generating much more than only a CA and a serving cert

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ref: kubernetes/kubeadm#156 if you want to describe more in detail about what kubeadm does

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm just reformatting here but happy to update. Once that PR goes in we can (a) turn it in to user facing docs and (b) reference it from here.


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.
server, as well as an additional kubeconfig file for administration.

1. kubeadm generates Kubernetes resource manifests for the API server,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

generates Static Pod manifests for the API Server...

`/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 or manage any
additional components.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

in between here kubeadm taints the master unschedulable, sets up RBAC, creates the cluster-info configmap for the token discovery and deploys both kube-proxy and kube-dns


1. Use the token to talk to the API server and securely get the root CA
certificate.
1. Download root CA infromation from the API server. Use the token to verify
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

information

- `--kubernetes-version` (default 'latest') the kubernetes version to initialise

The **v1.6** version of kubeadm only supports building clusters that are at
least **v1.6.0**. This requirement is due to kubeadm's use of RBAC. With this
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the Certificates API, Token Auth module, Token controllers, etc.
There are many reasons

WARNING: kubeadm is in alpha and the configuration API syntax will likely change before GA.
WARNING: While kubeadm command line interface is in beta, the config file is
still considered alpha. We are aiming to not break any scripted use of the main
`kubeadm init` and `kubeadm join` flow.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

but the config file UX may still change in non-backwards-compatible ways

- <address|string>

tlsBootstrapToken: <string>
token: <string>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would leave token invisible here, if the config file is used, one should really specify the separate tokens.
token is more of a CLI-convenience kind of thing

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Gah -- then it should be there. But I'll remove it.

a new token. This token is of the correct form for specifying with the
`--token` argument to `kubeadm init`.

For the gory details on how the tokens are implemented (including manaing them
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

managing


1. Generate a token. This token must have the form `<6 character string>.<16 character string>`.
1. Generate a token. This token must have the form `<6 character string>.<16
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

use of regex instead of . is preferred

| `KUBE_HOST_ETCD_PATH` | `/var/lib/etcd` | Local etcd state for Kubernetes cluster |
| `KUBE_HYPERKUBE_IMAGE` | `` | If set, use a single hyperkube image with this name. If not set, individual images per server component will be used. |
| `KUBE_DISCOVERY_IMAGE` | `gcr.io/google_containers/kube-discovery-<arch>:1.0` | The bootstrap discovery helper image to use. |
| `KUBE_HYPERKUBE_IMAGE` | | If set, use a single hyperkube image with this name. If not set, individual images per server component will be used. |
| `KUBE_ETCD_IMAGE` | `gcr.io/google_containers/etcd-<arch>:2.2.5` | The etcd container image to use. |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

:3.0.17

Signed-off-by: Joe Beda <joe.github@bedafamily.com>
@jbeda
Copy link
Contributor Author

jbeda commented Mar 19, 2017

Addressed all of @luxas's comments. PTAL.

and handed out to each node with the `--pod-network-cidr` flag. This should be a
minimum of a /16 so controller-manager is able to assign /24 subnets to each
node in the cluster. If you are using flannel with [this
manifest](https://github.com/coreos/flannel/blob/master/Documentation/kube-flannel.yml)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

shouldn't we use this the manifest that includes rbac? https://github.com/coreos/flannel/blob/master/Documentation/kube-flannel-rbac.yml

@devin-donnelly
Copy link
Contributor

Just waiting on @luxas 's LGTM.

Copy link
Member

@luxas luxas left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@devin-donnelly
Copy link
Contributor

Great, thanks.

@devin-donnelly devin-donnelly merged commit ab6166b into kubernetes:release-1.6 Mar 20, 2017
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
cncf-cla: yes Indicates the PR's author has signed the CNCF CLA.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

8 participants