12 KiB
reviewers | title | content_template | weight | ||
---|---|---|---|---|---|
|
kubeadm init | templates/concept | 20 |
{{% capture overview %}} This command initializes a Kubernetes control-plane node. {{% /capture %}}
{{% capture body %}}
{{< include "generated/kubeadm_init.md" >}}
Init workflow
kubeadm init
bootstraps a Kubernetes control-plane node by executing the
following steps:
-
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
--ignore-preflight-errors=<list-of-errors>
. -
Generates a self-signed CA (or using an existing one if provided) to set up 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
(/etc/kubernetes/pki
by default). The APIServer certs will have additional SAN entries for any--apiserver-cert-extra-sans
arguments, lowercased if necessary. -
Writes kubeconfig files in
/etc/kubernetes/
for the kubelet, the controller-manager and the scheduler to use to connect to the API server, each with its own identity, as well as an additional kubeconfig file for administration namedadmin.conf
. -
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 is generated for etcd.
Static Pod manifests are written to
/etc/kubernetes/manifests
; the kubelet watches this directory for Pods to create on startup.Once control plane Pods are up and running, the
kubeadm init
sequence can continue. -
Apply labels and taints to the control-plane node so that no additional workloads will run there.
-
Generates the token that additional nodes can use to register themselves with a control-plane in the future. Optionally, the user can provide a token via
--token
, as described in the kubeadm token docs. -
Makes all the necessary configurations for allowing node joining with the Bootstrap Tokens and TLS Bootstrap mechanism:
-
Write a ConfigMap for making available all the information required for joining, and set up related RBAC access rules.
-
Let Bootstrap Tokens access the CSR signing API.
-
Configure auto-approval for new CSR requests.
See kubeadm join for additional info.
-
-
Installs a DNS server (CoreDNS) and the kube-proxy addon components via the API server. In Kubernetes version 1.11 and later CoreDNS is the default DNS server. To install kube-dns instead of CoreDNS, the DNS addon has to be configured in the kubeadm
ClusterConfiguration
. For more information about the configuration see the sectionUsing kubeadm init with a configuration file
below. Please note that although the DNS server is deployed, it will not be scheduled until CNI is installed.{{< warning >}} kube-dns usage with kubeadm is deprecated as of v1.18 and will be removed in a future release. {{< /warning >}}
Using init phases with kubeadm
Kubeadm allows you to create a control-plane node in phases using the kubeadm init phase
command.
To view the ordered list of phases and sub-phases you can call kubeadm init --help
. The list will be located at the top of the help screen and each phase will have a description next to it.
Note that by calling kubeadm init
all of the phases and sub-phases will be executed in this exact order.
Some phases have unique flags, so if you want to have a look at the list of available options add --help
, for example:
sudo kubeadm init phase control-plane controller-manager --help
You can also use --help
to see the list of sub-phases for a certain parent phase:
sudo kubeadm init phase control-plane --help
kubeadm init
also exposes a flag called --skip-phases
that can be used to skip certain phases. The flag accepts a list of phase names and the names can be taken from the above ordered list.
An example:
sudo kubeadm init phase control-plane all --config=configfile.yaml
sudo kubeadm init phase etcd local --config=configfile.yaml
# you can now modify the control plane and etcd manifest files
sudo kubeadm init --skip-phases=control-plane,etcd --config=configfile.yaml
What this example would do is write the manifest files for the control plane and etcd in /etc/kubernetes/manifests
based on the configuration in configfile.yaml
. This allows you to modify the files and then skip these phases using --skip-phases
. By calling the last command you will create a control plane node with the custom manifest files.
Using kubeadm init with a configuration file
{{< caution >}} The config file is still considered beta 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 with the --config
option.
The default configuration can be printed out using the kubeadm config print command.
It is recommended that you migrate your old v1beta1
configuration to v1beta2
using
the kubeadm config migrate command.
For more details on each field in the v1beta2
configuration you can navigate to our
API reference pages.
Adding kube-proxy parameters
For information about kube-proxy parameters in the kubeadm configuration see:
For information about enabling IPVS mode with kubeadm see:
Passing custom flags to control plane components
For information about passing flags to control plane components see:
Using custom images
By default, kubeadm pulls images from k8s.gcr.io
. If the
requested Kubernetes version is a CI label (such as ci/latest
)
gcr.io/kubernetes-ci-images
is used.
You can override this behavior by using kubeadm with a configuration file. Allowed customization are:
- To provide an alternative
imageRepository
to be used instead ofk8s.gcr.io
. - To set
useHyperKubeImage
totrue
to use the HyperKube image. - To provide a specific
imageRepository
andimageTag
for etcd or DNS add-on.
Please note that the configuration field kubernetesVersion
or the command line flag
--kubernetes-version
affect the version of the images.
Uploading control-plane certificates to the cluster
By adding the flag --upload-certs
to kubeadm init
you can temporary upload
the control-plane certificates to a Secret in the cluster. Please note that this Secret
will expire automatically after 2 hours. The certificates are encrypted using
a 32byte key that can be specified using --certificate-key
. The same key can be used
to download the certificates when additional control-plane nodes are joining, by passing
--control-plane
and --certificate-key
to kubeadm join
.
The following phase command can be used to re-upload the certificates after expiration:
kubeadm init phase upload-certs --upload-certs --certificate-key=SOME_VALUE --config=SOME_YAML_FILE
If the flag --certificate-key
is not passed to kubeadm init
and
kubeadm init phase upload-certs
a new key will be generated automatically.
The following command can be used to generate a new key on demand:
kubeadm alpha certs certificate-key
Certificate management with kubeadm
For detailed information on certificate management with kubeadm see Certificate Management with kubeadm. The document includes information about using external CA, custom certificates and certificate renewal.
Managing the kubeadm drop-in file for the kubelet
The kubeadm
package ships with a configuration file for running the kubelet
by systemd
. Note that the kubeadm CLI never touches this drop-in file. This drop-in file is part of the kubeadm DEB/RPM package.
For further information, see Managing the kubeadm drop-in file for systemd.
Use kubeadm with CRI runtimes
By default kubeadm attempts to detect your container runtime. For more details on this detection, see the kubeadm CRI installation guide.
Setting the node name
By default, kubeadm
assigns a node name based on a machine's host address. You can override this setting with the --node-name
flag.
The flag passes the appropriate --hostname-override
value to the kubelet.
Be aware that overriding the hostname can interfere with cloud providers.
Running kubeadm without an internet connection
For running kubeadm without an internet connection you have to pre-pull the required control-plane images.
You can list and pull the images using the kubeadm config images
sub-command:
kubeadm config images list
kubeadm config images pull
All images that kubeadm requires such as k8s.gcr.io/kube-*
, k8s.gcr.io/etcd
and k8s.gcr.io/pause
support multiple architectures.
Automating kubeadm
Rather than copying the token you obtained from kubeadm init
to each node, as
in the basic kubeadm tutorial, you can parallelize the
token distribution for easier automation. To implement this automation, you must
know the IP address that the control-plane node will have after it is started,
or use a DNS name or an address of a load balancer.
-
Generate a token. This token must have the form
<6 character string>.<16 character string>
. More formally, it must match the regex:[a-z0-9]{6}\.[a-z0-9]{16}
.kubeadm can generate a token for you:
kubeadm token generate
-
Start both the control-plane node and the worker nodes concurrently with this token. As they come up they should find each other and form the cluster. The same
--token
argument can be used on bothkubeadm init
andkubeadm join
. -
Similar can be done for
--certificate-key
when joining additional control-plane nodes. The key can be generated using:kubeadm alpha certs certificate-key
Once the cluster is up, you can grab the admin credentials from the control-plane node
at /etc/kubernetes/admin.conf
and use that to talk to the cluster.
Note that this style of bootstrap has some relaxed security guarantees because
it does not allow the root CA hash to be validated with
--discovery-token-ca-cert-hash
(since it's not generated when the nodes are
provisioned). For details, see the kubeadm join.
{{% /capture %}}
{{% capture whatsnext %}}
- kubeadm init phase to understand more about
kubeadm init
phases - kubeadm join to bootstrap a Kubernetes worker node and join it to the cluster
- kubeadm upgrade to upgrade a Kubernetes cluster to a newer version
- kubeadm reset to revert any changes made to this host by
kubeadm init
orkubeadm join
{{% /capture %}}