From 031cdb00dcdd0fd9e1ae8f8d271f54aef6db2b8b Mon Sep 17 00:00:00 2001 From: fabriziopandini Date: Wed, 8 Nov 2017 23:35:49 +0100 Subject: [PATCH] user-mantained kubeadm reference doc --- _data/reference.yml | 12 +- docs/admin/_kubeadm/kubeadm.md | 39 ++ docs/admin/kubeadm-alpha.md | 266 +++++++++ docs/admin/kubeadm-config.md | 36 ++ docs/admin/kubeadm-init.md | 425 ++++++++++++++ docs/admin/kubeadm-join.md | 222 +++++++ docs/admin/kubeadm-reset.md | 33 ++ docs/admin/kubeadm-token.md | 46 ++ docs/admin/kubeadm-upgrade.md | 29 + docs/admin/kubeadm-version.md | 17 + docs/admin/kubeadm.md | 1012 +------------------------------- 11 files changed, 1136 insertions(+), 1001 deletions(-) create mode 100644 docs/admin/_kubeadm/kubeadm.md create mode 100755 docs/admin/kubeadm-alpha.md create mode 100644 docs/admin/kubeadm-config.md create mode 100755 docs/admin/kubeadm-init.md create mode 100755 docs/admin/kubeadm-join.md create mode 100644 docs/admin/kubeadm-reset.md create mode 100644 docs/admin/kubeadm-token.md create mode 100755 docs/admin/kubeadm-upgrade.md create mode 100644 docs/admin/kubeadm-version.md mode change 100644 => 100755 docs/admin/kubeadm.md diff --git a/_data/reference.yml b/_data/reference.yml index 08842016084af..cf82a3385d68c 100644 --- a/_data/reference.yml +++ b/_data/reference.yml @@ -70,7 +70,17 @@ toc: - title: Setup Tools section: - - docs/admin/kubeadm.md + - title: Kubeadm + section: + - docs/admin/kubeadm.md + - docs/admin/kubeadm-init.md + - docs/admin/kubeadm-join.md + - docs/admin/kubeadm-upgrade.md + - docs/admin/kubeadm-config.md + - docs/admin/kubeadm-reset.md + - docs/admin/kubeadm-token.md + - docs/admin/kubeadm-version.md + - docs/admin/kubeadm-alpha.md - title: Kubefed section: - docs/admin/kubefed.md diff --git a/docs/admin/_kubeadm/kubeadm.md b/docs/admin/_kubeadm/kubeadm.md new file mode 100644 index 0000000000000..ccfebfd552c7a --- /dev/null +++ b/docs/admin/_kubeadm/kubeadm.md @@ -0,0 +1,39 @@ + +kubeadm: easily bootstrap a secure Kubernetes cluster + +### Synopsis + + + +kubeadm: easily bootstrap a secure Kubernetes cluster. + + ┌──────────────────────────────────────────────────────────┐ + │ KUBEADM IS BETA, DO NOT USE IT FOR PRODUCTION CLUSTERS! │ + │ │ + │ But, please try it out! Give us feedback at: │ + │ https://github.com/kubernetes/kubeadm/issues │ + │ and at-mention @kubernetes/sig-cluster-lifecycle-bugs │ + │ or @kubernetes/sig-cluster-lifecycle-feature-requests │ + └──────────────────────────────────────────────────────────┘ + +Example usage: + + Create a two-machine cluster with one master (which controls the cluster), + and one node (where your workloads, like Pods and Deployments run). + + ┌──────────────────────────────────────────────────────────┐ + │ On the first machine │ + ├──────────────────────────────────────────────────────────┤ + │ master# kubeadm init │ + └──────────────────────────────────────────────────────────┘ + + ┌──────────────────────────────────────────────────────────┐ + │ On the second machine │ + ├──────────────────────────────────────────────────────────┤ + │ node# kubeadm join │ + └──────────────────────────────────────────────────────────┘ + + You can then repeat the second step on as many other machines as you like. + + + diff --git a/docs/admin/kubeadm-alpha.md b/docs/admin/kubeadm-alpha.md new file mode 100755 index 0000000000000..6a99af8ec35ce --- /dev/null +++ b/docs/admin/kubeadm-alpha.md @@ -0,0 +1,266 @@ +--- +approvers: +- mikedanese +- luxas +- jbeda +title: Kubeadm alpha +notitle: true +--- + +# Kubeadm alpha +`kubeadm alpha` provides a preview of a set of features made available for gathering feedback + from the community. Please try it out and give us feedback! +{: .caution} + +In v1.8.0, kubeadm introduced `kubeadm alpha phase` command with the aim to make kubeadm more +modular, letting you invoke atomic sub-steps of the bootstrap process; basically, you can +let kubeadm do some parts and fill in yourself where you need customizations. + +`kubeadm alpha phase` is consistent with [kubeadm init workflow](/docs/admin/kubeadm-init.md#init-workflow), +and behind the scene both use the same code. + +* [Kubeadm alpha phase preflight](#cmd-phase-preflight) +* [Kubeadm token create](#cmd-phase-token) +* [Kubeadm alpha phase certs](#cmd-phase-certs) +* [Kubeadm alpha phase kubeconfig](#cmd-phase-kubeconfig) +* [Kubeadm alpha phase controlplane](#cmd-phase-controlplane) +* [Kubeadm alpha phase etcd](#cmd-phase-etcd) +* [Kubeadm alpha phase mark-master](#cmd-phase-mark-master) +* [Kubeadm alpha phase bootstrap-token](#cmd-phase-bootstrap-token) +* [Kubeadm alpha phase upload-config](#cmd-phase-upload-config) +* [Kubeadm alpha phase addon](#cmd-phase-addon) +* [Kubeadm alpha phase selfhosting](#cmd-phase-self-hosting) + +## Kubeadm alpha phase preflight {#cmd-phase-preflight} + +You can execute preflight checks both for master node, like in `kubeadm init`, or for worker node +like in `kubeadm join`. + +{% capture preflight_master %} +{% include_relative _kubeadm/kubeadm_alpha_phase_preflight_master.md %} +{% endcapture %} + +{% capture preflight_node %} +{% include_relative _kubeadm/kubeadm_alpha_phase_preflight_node.md %} +{% endcapture %} + +{% assign tab_set_name = "tab-preflight" %} +{% assign tab_names = "master,node" | split: ',' | compact %} +{% assign tab_contents = site.emptyArray | push: preflight_master | push: preflight_node %} + +{% include tabs.md %} + +## Kubeadm token create {#cmd-phase-token} + +Currently there is no a specific command under `kubeadm alpha phase` for creating a token; however +you can use [kubeadm token create](/docs/admin/kubeadm-token.md#cmd-token-create) command. + +## Kubeadm alpha phase certs {#cmd-phase-certs} + +You can create all required certificates with the `all` sub command or selectively create certificates. + +{% capture certs_all %} +{% include_relative _kubeadm/kubeadm_alpha_phase_certs_all.md %} +{% endcapture %} + +{% capture certs_ca %} +{% include_relative _kubeadm/kubeadm_alpha_phase_certs_ca.md %} +{% endcapture %} + +{% capture certs_apiserver %} +{% include_relative _kubeadm/kubeadm_alpha_phase_certs_apiserver.md %} +{% endcapture %} + +{% capture certs_apiserver-kubelet-client %} +{% include_relative _kubeadm/kubeadm_alpha_phase_certs_apiserver-kubelet-client.md %} +{% endcapture %} + +{% capture certs_sa %} +{% include_relative _kubeadm/kubeadm_alpha_phase_certs_sa.md %} +{% endcapture %} + +{% capture certs_front-proxy-ca %} +{% include_relative _kubeadm/kubeadm_alpha_phase_certs_front-proxy-ca.md %} +{% endcapture %} + +{% capture certs_front-proxy-client %} +{% include_relative _kubeadm/kubeadm_alpha_phase_certs_front-proxy-client.md %} +{% endcapture %} + +{% assign tab_set_name = "tab-certs" %} +{% assign tab_names = "all,ca,apiserver,apiserver-kubelet-client,sa,front-proxy-ca,front-proxy-client" | split: ',' | compact %} +{% assign tab_contents = site.emptyArray | push: certs_all | push: certs_ca | push: certs_apiserver | push: certs_apiserver-kubelet-client | push: certs_sa | push: certs_front-proxy-ca | push: certs_front-proxy-client %} + +{% include tabs.md %} + +## Kubeadm alpha phase kubeconfig {#cmd-phase-kubeconfig} + +You can create all required kubeconfig files with the `all` sub command, or selectively create the files. Additionally, the `user` sub command supports the creation of kubeconfig files for additional users. + +{% capture kubeconfig_all %} +{% include_relative _kubeadm/kubeadm_alpha_phase_kubeconfig_all.md %} +{% endcapture %} + +{% capture kubeconfig_admin %} +{% include_relative _kubeadm/kubeadm_alpha_phase_kubeconfig_admin.md %} +{% endcapture %} + +{% capture kubeconfig_kubelet %} +{% include_relative _kubeadm/kubeadm_alpha_phase_kubeconfig_kubelet.md %} +{% endcapture %} + +{% capture kubeconfig_controller-manager %} +{% include_relative _kubeadm/kubeadm_alpha_phase_kubeconfig_controller-manager.md %} +{% endcapture %} + +{% capture kubeconfig_scheduler %} +{% include_relative _kubeadm/kubeadm_alpha_phase_kubeconfig_scheduler.md %} +{% endcapture %} + +{% capture kubeconfig_user %} +{% include_relative _kubeadm/kubeadm_alpha_phase_kubeconfig_user.md %} +{% endcapture %} + +{% assign tab_set_name = "tab-kubeconfig" %} +{% assign tab_names = "all,admin,kubelet,controller-manager,scheduler,user" | split: ',' | compact %} +{% assign tab_contents = site.emptyArray | push: kubeconfig_all | push: kubeconfig_admin | push: kubeconfig_kubelet | push: kubeconfig_controller-manager | push: kubeconfig_scheduler | push: kubeconfig_user %} + +{% include tabs.md %} + +## Kubeadm alpha phase controlplane {#cmd-phase-controlplane} + +You can create all required static pod files for control plane components with the `all` sub command, +or selectively create the files. + +{% capture controlplane_all %} +{% include_relative _kubeadm/kubeadm_alpha_phase_controlplane_all.md %} +{% endcapture %} + +{% capture controlplane_apiserver %} +{% include_relative _kubeadm/kubeadm_alpha_phase_controlplane_apiserver.md %} +{% endcapture %} + +{% capture controlplane_controller-manager %} +{% include_relative _kubeadm/kubeadm_alpha_phase_controlplane_controller-manager.md %} +{% endcapture %} + +{% capture controlplane_scheduler %} +{% include_relative _kubeadm/kubeadm_alpha_phase_controlplane_scheduler.md %} +{% endcapture %} + +{% assign tab_set_name = "tab-controlplane" %} +{% assign tab_names = "all,apiserver,controller-manager,scheduler" | split: ',' | compact %} +{% assign tab_contents = site.emptyArray | push: controlplane_all | push: controlplane_apiserver | push: controlplane_controller-manager | push: controlplane_scheduler %} + +{% include tabs.md %} + +## Kubeadm alpha phase etcd {#cmd-phase-etcd} + +Use the following command to create a self-hosted, local etcd instance based on a static pod file. + +{% capture etcd-local %} +{% include_relative _kubeadm/kubeadm_alpha_phase_etcd_local.md %} +{% endcapture %} + +{% assign tab_set_name = "tab-etcd" %} +{% assign tab_names = "etcd local" | split: ',' | compact %} +{% assign tab_contents = site.emptyArray | push: etcd-local %} + +{% include tabs.md %} + +## Kubeadm alpha phase mark-master {#cmd-phase-mark-master} + +Use the following command to label the node with the `node-role.kubernetes.io/master` taint. + +{% capture mark-master %} +{% include_relative _kubeadm/kubeadm_alpha_phase_mark-master.md %} +{% endcapture %} + +{% assign tab_set_name = "tab-mark-master" %} +{% assign tab_names = "mark-master" | split: ',' | compact %} +{% assign tab_contents = site.emptyArray | push: mark-master %} + +{% include tabs.md %} + +## Kubeadm alpha phase bootstrap-token {#cmd-phase-bootstrap-token} + +Use the following actions to fully configure bootstrap tokens. + +**Note:** You have to run all commands sequentially to replicate the `kubeadm init` behaviour. +{: .note} + +{% capture bootstrap-token_cluster-info %} +{% include_relative _kubeadm/kubeadm_alpha_phase_bootstrap-token_cluster-info.md %} +{% endcapture %} + +{% capture bootstrap-token_node_allow-auto-approve %} +{% include_relative _kubeadm/kubeadm_alpha_phase_bootstrap-token_node_allow-auto-approve.md %} +{% endcapture %} + +{% capture bootstrap-token_node_allow-post-csrs %} +{% include_relative _kubeadm/kubeadm_alpha_phase_bootstrap-token_node_allow-post-csrs.md %} +{% endcapture %} + +{% assign tab_set_name = "tab-bootstrap-token" %} +{% assign tab_names = "cluster-info,node allow-auto-approve,node allow-post-csrs" | split: ',' | compact %} +{% assign tab_contents = site.emptyArray | push: bootstrap-token_cluster-info | push: bootstrap-token_node_allow-auto-approve | push: bootstrap-token_node_allow-post-csrs %} + +{% include tabs.md %} + +## Kubeadm alpha phase upload-config {#cmd-phase-upload-config} + +You can use this command to upload the configuration of your cluster. Alternatively, you +can use [kubeadm config](kubeadm-config.md) as well. + +{% capture upload-config %} +{% include_relative _kubeadm/kubeadm_alpha_phase_upload-config.md %} +{% endcapture %} + +{% assign tab_set_name = "tab-upload-config" %} +{% assign tab_names = "upload-config" | split: ',' | compact %} +{% assign tab_contents = site.emptyArray | push: upload-config %} + +{% include tabs.md %} + +## Kubeadm alpha phase addon {#cmd-phase-addon} + +You can install all the available abbons with the `all` sub command, or +install them selectively. + +{% capture addon-all %} +{% include_relative _kubeadm/kubeadm_alpha_phase_addon_all.md %} +{% endcapture %} + +{% capture addon-kube-proxy %} +{% include_relative _kubeadm/kubeadm_alpha_phase_addon_kube-proxy.md %} +{% endcapture %} + +{% capture addon-kube-dns %} +{% include_relative _kubeadm/kubeadm_alpha_phase_addon_kube-dns.md %} +{% endcapture %} + +{% assign tab_set_name = "tab-addon" %} +{% assign tab_names = "all,kube-proxy,kube-dns" | split: ',' | compact %} +{% assign tab_contents = site.emptyArray | push: addon-all | push: addon-kube-proxy | push: addon-kube-dns %} + +{% include tabs.md %} + +## Kubeadm alpha phase selfhosting {#cmd-phase-self-hosting} + +**Caution:** Self-hosting is an alpha feature in kubeadm 1.8, and is expected to +become the default in a future version. +{: .caution} + +{% capture self-hosting %} +{% include_relative _kubeadm/kubeadm_alpha_phase_selfhosting_convert-from-staticpods.md %} +{% endcapture %} + +{% assign tab_set_name = "tab-self-hosting" %} +{% assign tab_names = "self-hosting" | split: ',' | compact %} +{% assign tab_contents = site.emptyArray | push: self-hosting %} + +{% include tabs.md %} + +## What's next +* [kubeadm init](kubeadm-init.md) to bootstraps a Kubernetes master node +* [kubeadm reset](kubeadm-reset.md) to revert any changes made to this host by `kubeadm init` or `kubeadm join` diff --git a/docs/admin/kubeadm-config.md b/docs/admin/kubeadm-config.md new file mode 100644 index 0000000000000..0d92c02f3c08d --- /dev/null +++ b/docs/admin/kubeadm-config.md @@ -0,0 +1,36 @@ +--- +approvers: +- mikedanese +- luxas +- jbeda +title: Kubeadm config +notitle: true +--- +{% capture overview %} +# Kubeadm config +Beginning with v1.8.0, kubeadm uploads the configuration of your cluster to a ConfigMap called +`kubeadm-config` in the `kube-system` namespace, and later reads that configuration when upgrading +in order to configure system components correctly. This provides a seamless user experience. + +With `kubeadm config view` you can view the above ConfigMap, or, if you initialized your cluster + using kubeadm v1.7.x or lower, you can use the `kubeadm config upload` commands to create this +ConfigMap before executing `kubeadm upgrade`. + +{% endcapture %} + +{% capture body %} +## Kubeadm config upload from-file {#cmd-config-from-file} +{% include_relative _kubeadm/kubeadm_config_upload_from-file.md %} + +## Kubeadm config upload from-flags {#cmd-config-from-flags} +{% include_relative _kubeadm/kubeadm_config_upload_from-flags.md %} + +## Kubeadm config view {#cmd-config-view} +{% include_relative _kubeadm/kubeadm_config_view.md %} +{% endcapture %} + +{% capture whatsnext %} +* [kubeadm upgrade](kubeadm-upgrade.md) to upgrade a Kubernetes cluster to a newer version +{% endcapture %} + +{% include templates/concept.md %} \ No newline at end of file diff --git a/docs/admin/kubeadm-init.md b/docs/admin/kubeadm-init.md new file mode 100755 index 0000000000000..996c0c431f0d8 --- /dev/null +++ b/docs/admin/kubeadm-init.md @@ -0,0 +1,425 @@ +--- +approvers: +- mikedanese +- luxas +- jbeda +title: Kubeadm init +notitle: true +--- +{% capture overview %} +## Kubeadm init {#cmd-init} +{% endcapture %} + +{% capture body %} +{% include_relative _kubeadm/kubeadm_init.md %} + +### Init workflow {#init-workflow} +`kubeadm init` bootstraps a Kubernetes master node by executing the +following steps: + +1. kubeadm runs a series of pre-flight checks to validate the system state + 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 the token that additional nodes can use to register + themselves with the master in the future. Optionally, the user can provide a + token via `--token`, as described in the + [kubeadm token](kubeadm-token.md) docs. + +1. kubeadm generates a self-signed CA to provision identities for each component + (including nodes) in the cluster. It also generates client certificates to + be used by various components. If the user has provided their own CA by + dropping it in the cert directory configured via `--cert-dir` + (`/etc/kubernetes/pki` by default) this step is skipped as described in the + [Using custom certificates](#custom-certificates) document. + +1. kubeadm writes kubeconfig files in `/etc/kubernetes/` for + the kubelet, the controller-manager and the scheduler to use to connect to the + API server, each one with their respective identities, as well as an additional + kubeconfig file for administration named `admin.conf`. + +1. kubeadm generates static Pod manifests for the API server, + controller manager and scheduler. In case an external etcd is not provided, + an additional static Pod manifest will be generated for etcd. + + Static Pod manifests are written to `/etc/kubernetes/manifests` folder; the kubelet + watches this directory for Pods to create on startup. + + Once control plane Pods are up and running kubeadm init sequence can continue. + +1. kubeadm "labels" and "taints" the master node so that only control plane + components will run there. + +1. kubeadm makes all the necessary configurations for allowing node joining with the + [Bootstrap Tokens](/docs/admin/bootstrap-tokens/) and + [TLS Bootstrap](/docs/admin/kubelet-tls-bootstrapping/) + mechanism: + + - Write a ConfigMap for making available all the information required + for joining and set up related RBAC access rules. + + - Ensure access to the CSR signing API for bootstrap tokens. + + - Configure auto approval for new CSR requests. + + See [kubeadm join](kubeadm-join.md) for additional info. + +1. kubeadm installs add-on components via the API server. Right now this is + the internal DNS server and the kube-proxy DaemonSet. + Please note that although the DNS server is deployed, it will not be scheduled until CNI is installed. + +1. If `kubeadm init` is invoked with the alpha self-hosting feature enabled, + (`--feature-gates=SelfHosting=true`), the static Pod based control plane will + be transformed into a [self-hosted control plane](#self-hosting). + + +### Using kubeadm init with a configuration file {#config-file} + +**Caution:** the config file is +still considered alpha and may change in future versions. +{: .caution} + +It's possible to configure `kubeadm init` with a configuration file instead of command +line flags, and some more advanced features may only be available as +configuration file options. This file is passed in to the `--config` option. + +```yaml +apiVersion: kubeadm.k8s.io/v1alpha1 +kind: MasterConfiguration +api: + advertiseAddress: + bindPort: +etcd: + endpoints: + - + - + caFile: + certFile: + keyFile: + dataDir: + extraArgs: + : + : + image: +networking: + dnsDomain: + serviceSubnet: + podSubnet: +kubernetesVersion: +cloudProvider: +nodeName: +authorizationModes: +- +- +token: +tokenTTL: