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

Update kubeadm implementation details page

This commit is contained in:
Prasad Katti 2020-04-21 15:42:19 -07:00
parent e0f5e77910
commit 4efaf2a3e0
2 changed files with 29 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

67
content/en/docs/reference/setup-tools/kubeadm/implementation-details.md
View File

@ -29,20 +29,19 @@ The cluster that `kubeadm init` and `kubeadm join` set up should be:
- lock-down the kubelet API - lock-down the kubelet API
- locking down access to the API for system components like the kube-proxy and CoreDNS - locking down access to the API for system components like the kube-proxy and CoreDNS
- locking down what a Bootstrap Token can access - locking down what a Bootstrap Token can access
- etc.
- **Easy to use**: The user should not have to run anything more than a couple of commands: - **Easy to use**: The user should not have to run anything more than a couple of commands:
- `kubeadm init` - `kubeadm init`
- `export KUBECONFIG=/etc/kubernetes/admin.conf` - `export KUBECONFIG=/etc/kubernetes/admin.conf`
- `kubectl apply -f <network-of-choice.yaml>` - `kubectl apply -f <network-of-choice.yaml>`
- `kubeadm join --token <token> <master-ip>:<master-port>` - `kubeadm join --token <token> <master-ip>:<master-port>`
- **Extendable**: - **Extendable**:
- It should for example _not_ favor any network provider, instead configuring a network is out-of-scope - It should _not_ favor any particular network provider. Configuring the cluster network is out-of-scope
- Should provide the possibility to use a config file for customizing various parameters - It should provide the possibility to use a config file for customizing various parameters
## Constants and well-known values and paths ## Constants and well-known values and paths
In order to reduce complexity and to simplify development of an on-top-of-kubeadm-implemented deployment solution, kubeadm uses a In order to reduce complexity and to simplify development of higher level tools that build on top of kubeadm, it uses a
limited set of constants values for well know-known paths and file names. limited set of constant values for well-known paths and file names.
The Kubernetes directory `/etc/kubernetes` is a constant in the application, since it is clearly the given path The Kubernetes directory `/etc/kubernetes` is a constant in the application, since it is clearly the given path
in a majority of cases, and the most intuitive location; other constants paths and file names are: in a majority of cases, and the most intuitive location; other constants paths and file names are:
@ -70,14 +69,14 @@ in a majority of cases, and the most intuitive location; other constants paths a
The `kubeadm init` [internal workflow](/docs/reference/setup-tools/kubeadm/kubeadm-init/#init-workflow) consists of a sequence of atomic work tasks to perform, The `kubeadm init` [internal workflow](/docs/reference/setup-tools/kubeadm/kubeadm-init/#init-workflow) consists of a sequence of atomic work tasks to perform,
as described in `kubeadm init`. as described in `kubeadm init`.
The [`kubeadm init phase`](/docs/reference/setup-tools/kubeadm/kubeadm-init-phase/) command allows users to invoke individually each task, and ultimately offers a reusable and composable The [`kubeadm init phase`](/docs/reference/setup-tools/kubeadm/kubeadm-init-phase/) command allows users to invoke each task individually, and ultimately offers a reusable and composable
API/toolbox that can be used by other Kubernetes bootstrap tools, by any IT automation tool or by advanced user API/toolbox that can be used by other Kubernetes bootstrap tools, by any IT automation tool or by an advanced user
for creating custom clusters. for creating custom clusters.
### Preflight checks ### Preflight checks
Kubeadm executes a set of preflight checks before starting the init, with the aim to verify preconditions and avoid common cluster startup problems. Kubeadm executes a set of preflight checks before starting the init, with the aim to verify preconditions and avoid common cluster startup problems.
In any case the user can skip specific preflight checks (or eventually all preflight checks) with the `--ignore-preflight-errors` option. The user can skip specific preflight checks or all of them with the `--ignore-preflight-errors` option.
- [warning] If the Kubernetes version to use (specified with the `--kubernetes-version` flag) is at least one minor version higher than the kubeadm CLI version. - [warning] If the Kubernetes version to use (specified with the `--kubernetes-version` flag) is at least one minor version higher than the kubeadm CLI version.
- Kubernetes system requirements: - Kubernetes system requirements:
@ -161,9 +160,9 @@ Certificates are stored by default in `/etc/kubernetes/pki`, but this directory
### Generate kubeconfig files for control plane components ### Generate kubeconfig files for control plane components
Kubeadm kubeconfig files with identities for control plane components: Kubeadm generates kubeconfig files with identities for control plane components:
- A kubeconfig file for kubelet to use, `/etc/kubernetes/kubelet.conf`; inside this file is embedded a client certificate with kubelet identity. - A kubeconfig file for the kubelet to use during TLS bootstrap - /etc/kubernetes/bootstrap-kubelet.conf. Inside this file there is a bootstrap-token or embedded client certificates for authenticating this node with the cluster.
This client cert should: This client cert should:
- Be in the `system:nodes` organization, as required by the [Node Authorization](/docs/reference/access-authn-authz/node/) module - Be in the `system:nodes` organization, as required by the [Node Authorization](/docs/reference/access-authn-authz/node/) module
- Have the Common Name (CN) `system:node:<hostname-lowercased>` - Have the Common Name (CN) `system:node:<hostname-lowercased>`
@ -173,11 +172,11 @@ by default [RBAC core components roles](/docs/reference/access-authn-authz/rbac/
- A kubeconfig file for scheduler, `/etc/kubernetes/scheduler.conf`; inside this file is embedded a client certificate with scheduler identity. - A kubeconfig file for scheduler, `/etc/kubernetes/scheduler.conf`; inside this file is embedded a client certificate with scheduler identity.
This client cert should have the CN `system:kube-scheduler`, as defined by default [RBAC core components roles](/docs/reference/access-authn-authz/rbac/#core-component-roles) This client cert should have the CN `system:kube-scheduler`, as defined by default [RBAC core components roles](/docs/reference/access-authn-authz/rbac/#core-component-roles)
Additionally, a kubeconfig file for kubeadm to use itself and the admin is generated and save into the `/etc/kubernetes/admin.conf` file. Additionally, a kubeconfig file for kubeadm itself and the admin is generated and saved into the `/etc/kubernetes/admin.conf` file.
The "admin" here is defined the actual person(s) that is administering the cluster and want to have full control (**root**) over the cluster. The "admin" here is defined as the actual person(s) that is administering the cluster and wants to have full control (**root**) over the cluster.
The embedded client certificate for admin should: The embedded client certificate for admin should be in the `system:masters` organization, as defined by default
- Be in the `system:masters` organization, as defined by default [RBAC user facing role bindings](/docs/reference/access-authn-authz/rbac/#user-facing-roles) [RBAC user facing role bindings](/docs/reference/access-authn-authz/rbac/#user-facing-roles). It should also include a
- Include a CN, but that can be anything. Kubeadm uses the `kubernetes-admin` CN CN. Kubeadm uses the `kubernetes-admin` CN.
Please note that: Please note that:
@ -189,28 +188,24 @@ Please note that:
### Generate static Pod manifests for control plane components ### Generate static Pod manifests for control plane components
Kubeadm writes static Pod manifest files for control plane components to `/etc/kubernetes/manifests`; the kubelet watches this directory for Pods to create on startup. Kubeadm writes static Pod manifest files for control plane components to `/etc/kubernetes/manifests`. The kubelet watches this directory for Pods to create on startup.
Static Pod manifest share a set of common properties: Static Pod manifest share a set of common properties:
- All static Pods are deployed on `kube-system` namespace - All static Pods are deployed on `kube-system` namespace
- All static Pods gets `tier:control-plane` and `component:{component-name}` labels - All static Pods get `tier:control-plane` and `component:{component-name}` labels
- All static Pods gets `scheduler.alpha.kubernetes.io/critical-pod` annotation (this will be moved over to the proper solution - All static Pods use the `system-node-critical` priority class
of using Pod Priority and Preemption when ready)
- `hostNetwork: true` is set on all static Pods to allow control plane startup before a network is configured; as a consequence: - `hostNetwork: true` is set on all static Pods to allow control plane startup before a network is configured; as a consequence:
* The `address` that the controller-manager and the scheduler use to refer the API server is `127.0.0.1` * The `address` that the controller-manager and the scheduler use to refer the API server is `127.0.0.1`
* If using a local etcd server, `etcd-servers` address will be set to `127.0.0.1:2379` * If using a local etcd server, `etcd-servers` address will be set to `127.0.0.1:2379`
- Leader election is enabled for both the controller-manager and the scheduler - Leader election is enabled for both the controller-manager and the scheduler
- Controller-manager and the scheduler will reference kubeconfig files with their respective, unique identities - Controller-manager and the scheduler will reference kubeconfig files with their respective, unique identities
- All static Pods gets any extra flags specified by the user as described in [passing custom arguments to control plane components](/docs/setup/production-environment/tools/kubeadm/control-plane-flags/) - All static Pods get any extra flags specified by the user as described in [passing custom arguments to control plane components](/docs/setup/production-environment/tools/kubeadm/control-plane-flags/)
- All static Pods gets any extra Volumes specified by the user (Host path) - All static Pods get any extra Volumes specified by the user (Host path)
Please note that: Please note that:
1. All the images, for the `--kubernetes-version`/current architecture, will be pulled from `k8s.gcr.io`; 1. All images will be pulled from k8s.gcr.io by default. See [using custom images](/docs/reference/setup-tools/kubeadm/kubeadm-init/#custom-images) for customizing the image repository
In case an alternative image repository or CI image repository is specified this one will be used; In case a specific container image
should be used for all control plane components, this one will be used. see [using custom images](/docs/reference/setup-tools/kubeadm/kubeadm-init/#custom-images)
for more details
2. In case of kubeadm is executed in the `--dry-run` mode, static Pods files are written in a temporary folder 2. In case of kubeadm is executed in the `--dry-run` mode, static Pods files are written in a temporary folder
3. Static Pod manifest generation for master components can be invoked individually with the [`kubeadm init phase control-plane all`](/docs/reference/setup-tools/kubeadm/kubeadm-init-phase/#cmd-phase-control-plane) command 3. Static Pod manifest generation for master components can be invoked individually with the [`kubeadm init phase control-plane all`](/docs/reference/setup-tools/kubeadm/kubeadm-init-phase/#cmd-phase-control-plane) command
@ -300,8 +295,7 @@ a local etcd instance running in a Pod with following attributes:
Please note that: Please note that:
1. The etcd image will be pulled from `k8s.gcr.io`. In case an alternative image repository is specified this one will be used; 1. The etcd image will be pulled from `k8s.gcr.io` by default. See [using custom images](/docs/reference/setup-tools/kubeadm/kubeadm-init/#custom-images) for customizing the image repository
In case an alternative image name is specified, this one will be used. see [using custom images](/docs/reference/setup-tools/kubeadm/kubeadm-init/#custom-images) for more details
2. in case of kubeadm is executed in the `--dry-run` mode, the etcd static Pod manifest is written in a temporary folder 2. in case of kubeadm is executed in the `--dry-run` mode, the etcd static Pod manifest is written in a temporary folder
3. Static Pod manifest generation for local etcd can be invoked individually with the [`kubeadm init phase etcd local`](/docs/reference/setup-tools/kubeadm/kubeadm-init-phase/#cmd-phase-etcd) command 3. Static Pod manifest generation for local etcd can be invoked individually with the [`kubeadm init phase etcd local`](/docs/reference/setup-tools/kubeadm/kubeadm-init-phase/#cmd-phase-etcd) command
@ -324,10 +318,9 @@ Please note that:
### Wait for the control plane to come up ### Wait for the control plane to come up
This is a critical moment in time for kubeadm clusters. kubeadm waits (upto 4m0s) until `localhost:6443/healthz` (kube-apiserver liveness) returns `ok`. However in order to detect
kubeadm waits until `localhost:6443/healthz` returns `ok`, however in order to detect deadlock conditions, kubeadm fails fast deadlock conditions, kubeadm fails fast if `localhost:10255/healthz` (kubelet liveness) or
if `localhost:10255/healthz` (kubelet liveness) or `localhost:10255/healthz/syncloop` (kubelet readiness) don't return `ok`, `localhost:10255/healthz/syncloop` (kubelet readiness) don't return `ok` within 40s and 60s respectively.
respectively after 40 and 60 second.
kubeadm relies on the kubelet to pull the control plane images and run them properly as static Pods. kubeadm relies on the kubelet to pull the control plane images and run them properly as static Pods.
After the control plane is up, kubeadm completes the tasks described in following paragraphs. After the control plane is up, kubeadm completes the tasks described in following paragraphs.
@ -343,19 +336,15 @@ If kubeadm is invoked with `--feature-gates=DynamicKubeletConfig`:
### Save the kubeadm ClusterConfiguration in a ConfigMap for later reference ### Save the kubeadm ClusterConfiguration in a ConfigMap for later reference
kubeadm saves the configuration passed to `kubeadm init`, either via flags or the config file, in a ConfigMap kubeadm saves the configuration passed to `kubeadm init` in a ConfigMap named `kubeadm-config` under `kube-system` namespace.
named `kubeadm-config` under `kube-system` namespace.
This will ensure that kubeadm actions executed in future (e.g `kubeadm upgrade`) will be able to determine the actual/current cluster This will ensure that kubeadm actions executed in future (e.g `kubeadm upgrade`) will be able to determine the actual/current cluster
state and make new decisions based on that data. state and make new decisions based on that data.
Please note that: Please note that:
1. Before uploading, sensitive information like e.g. the token is stripped from the configuration 1. Before saving the ClusterConfiguration, sensitive information like the token is stripped from the configuration
2. Upload of master configuration can be invoked individually with the [`kubeadm init phase upload-config`](/docs/reference/setup-tools/kubeadm/kubeadm-init-phase/#cmd-phase-upload-config) command 2. Upload of master configuration can be invoked individually with the [`kubeadm init phase upload-config`](/docs/reference/setup-tools/kubeadm/kubeadm-init-phase/#cmd-phase-upload-config) command
3. If you initialized your cluster using kubeadm v1.7.x or lower, you must create manually the master configuration ConfigMap
before `kubeadm upgrade` to v1.8 . In order to facilitate this task, the [`kubeadm config upload (from-flags|from-file)`](/docs/reference/setup-tools/kubeadm/kubeadm-config/)
was implemented
### Mark master ### Mark master
@ -421,8 +410,8 @@ and the default role `system:certificates.k8s.io:certificatesigningrequests:self
This phase creates the `cluster-info` ConfigMap in the `kube-public` namespace. This phase creates the `cluster-info` ConfigMap in the `kube-public` namespace.
Additionally it is created a role and a RoleBinding granting access to the ConfigMap for unauthenticated users Additionally it creates a Role and a RoleBinding granting access to the ConfigMap for unauthenticated users
(i.e. users in RBAC group `system:unauthenticated`) (i.e. users in RBAC group `system:unauthenticated`).
Please note that: Please note that:

3
content/en/docs/reference/setup-tools/kubeadm/kubeadm-init.md
View File

@ -23,8 +23,7 @@ following steps:
considered errors and will exit kubeadm until the problem is corrected or the considered errors and will exit kubeadm until the problem is corrected or the
user specifies `--ignore-preflight-errors=<list-of-errors>`. user specifies `--ignore-preflight-errors=<list-of-errors>`.
1. Generates a self-signed CA (or using an existing one if provided) to set up 1. Generates a self-signed CA to set up identities for each component in the cluster. The user can provide their
identities for each component in the cluster. If the user has provided their
own CA cert and/or key by dropping it in the cert directory configured via `--cert-dir` own CA cert and/or key by dropping it in the cert directory configured via `--cert-dir`
(`/etc/kubernetes/pki` by default). (`/etc/kubernetes/pki` by default).
The APIServer certs will have additional SAN entries for any `--apiserver-cert-extra-sans` arguments, lowercased if necessary. The APIServer certs will have additional SAN entries for any `--apiserver-cert-extra-sans` arguments, lowercased if necessary.