kubeadm init

This command initializes a Kubernetes control-plane node.

Run this command in order to set up the Kubernetes control plane

Synopsis

Run this command in order to set up the Kubernetes control plane

The “init” command executes the following phases:

  1. preflight Run pre-flight checks
  2. certs Certificate generation
  3. /ca Generate the self-signed Kubernetes CA to provision identities for other Kubernetes components
  4. /apiserver Generate the certificate for serving the Kubernetes API
  5. /apiserver-kubelet-client Generate the certificate for the API server to connect to kubelet
  6. /front-proxy-ca Generate the self-signed CA to provision identities for front proxy
  7. /front-proxy-client Generate the certificate for the front proxy client
  8. /etcd-ca Generate the self-signed CA to provision identities for etcd
  9. /etcd-server Generate the certificate for serving etcd
  10. /etcd-peer Generate the certificate for etcd nodes to communicate with each other
  11. /etcd-healthcheck-client Generate the certificate for liveness probes to healthcheck etcd
  12. /apiserver-etcd-client Generate the certificate the apiserver uses to access etcd
  13. /sa Generate a private key for signing service account tokens along with its public key
  14. kubeconfig Generate all kubeconfig files necessary to establish the control plane and the admin kubeconfig file
  15. /admin Generate a kubeconfig file for the admin to use and for kubeadm itself
  16. /kubelet Generate a kubeconfig file for the kubelet to use *only* for cluster bootstrapping purposes
  17. /controller-manager Generate a kubeconfig file for the controller manager to use
  18. /scheduler Generate a kubeconfig file for the scheduler to use
  19. etcd Generate static Pod manifest file for local etcd
  20. /local Generate the static Pod manifest file for a local, single-node local etcd instance
  21. control-plane Generate all static Pod manifest files necessary to establish the control plane
  22. /apiserver Generates the kube-apiserver static Pod manifest
  23. /controller-manager Generates the kube-controller-manager static Pod manifest
  24. /scheduler Generates the kube-scheduler static Pod manifest
  25. kubelet-start Write kubelet settings and (re)start the kubelet
  26. upload-config Upload the kubeadm and kubelet configuration to a ConfigMap
  27. /kubeadm Upload the kubeadm ClusterConfiguration to a ConfigMap
  28. /kubelet Upload the kubelet component config to a ConfigMap
  29. upload-certs Upload certificates to kubeadm-certs
  30. mark-control-plane Mark a node as a control-plane
  31. bootstrap-token Generates bootstrap tokens used to join a node to a cluster
  32. kubelet-finalize Updates settings relevant to the kubelet after TLS bootstrap
  33. /experimental-cert-rotation Enable kubelet client certificate rotation
  34. addon Install required addons for passing conformance tests
  35. /coredns Install the CoreDNS addon to a Kubernetes cluster
  36. /kube-proxy Install the kube-proxy addon to a Kubernetes cluster
  37. show-join-command Show the join command for control-plane and worker node
  1. kubeadm init [flags]

Options

—apiserver-advertise-address string

The IP address the API Server will advertise it’s listening on. If not set the default network interface will be used.

—apiserver-bind-port int32     Default: 6443

Port for the API Server to bind to.

—apiserver-cert-extra-sans strings

Optional extra Subject Alternative Names (SANs) to use for the API Server serving certificate. Can be both IP addresses and DNS names.

—cert-dir string     Default: “/etc/kubernetes/pki”

The path where to save and store the certificates.

—certificate-key string

Key used to encrypt the control-plane certificates in the kubeadm-certs Secret.

—config string

Path to a kubeadm configuration file.

—control-plane-endpoint string

Specify a stable IP address or DNS name for the control plane.

—cri-socket string

Path to the CRI socket to connect. If empty kubeadm will try to auto-detect this value; use this option only if you have more than one CRI installed or if you have non-standard CRI socket.

—dry-run

Don’t apply any changes; just output what would be done.

—feature-gates string

A set of key=value pairs that describe feature gates for various features. Options are:
EtcdLearnerMode=true|false (ALPHA - default=false)
PublicKeysECDSA=true|false (ALPHA - default=false)
RootlessControlPlane=true|false (ALPHA - default=false)
UpgradeAddonsBeforeControlPlane=true|false (DEPRECATED - default=false)

-h, —help

help for init

—ignore-preflight-errors strings

A list of checks whose errors will be shown as warnings. Example: ‘IsPrivilegedUser,Swap’. Value ‘all’ ignores errors from all checks.

—image-repository string     Default: “registry.k8s.io”

Choose a container registry to pull control plane images from

—kubernetes-version string     Default: “stable-1”

Choose a specific Kubernetes version for the control plane.

—node-name string

Specify the node name.

—patches string

Path to a directory that contains files named “target[suffix][+patchtype].extension”. For example, “kube-apiserver0+merge.yaml” or just “etcd.json”. “target” can be one of “kube-apiserver”, “kube-controller-manager”, “kube-scheduler”, “etcd”, “kubeletconfiguration”. “patchtype” can be one of “strategic”, “merge” or “json” and they match the patch formats supported by kubectl. The default “patchtype” is “strategic”. “extension” must be either “json” or “yaml”. “suffix” is an optional string that can be used to determine which patches are applied first alpha-numerically.

—pod-network-cidr string

Specify range of IP addresses for the pod network. If set, the control plane will automatically allocate CIDRs for every node.

—service-cidr string     Default: “10.96.0.0/12”

Use alternative range of IP address for service VIPs.

—service-dns-domain string     Default: “cluster.local”

Use alternative domain for services, e.g. “myorg.internal”.

—skip-certificate-key-print

Don’t print the key used to encrypt the control-plane certificates.

—skip-phases strings

List of phases to be skipped

—skip-token-print

Skip printing of the default bootstrap token generated by ‘kubeadm init’.

—token string

The token to use for establishing bidirectional trust between nodes and control-plane nodes. The format is [a-z0-9]{6}.[a-z0-9]{16} - e.g. abcdef.0123456789abcdef

—token-ttl duration     Default: 24h0m0s

The duration before the token is automatically deleted (e.g. 1s, 2m, 3h). If set to ‘0’, the token will never expire

—upload-certs

Upload control-plane certificates to the kubeadm-certs Secret.

Options inherited from parent commands

—rootfs string

[EXPERIMENTAL] The path to the ‘real’ host root filesystem.

Init workflow

kubeadm init bootstraps a Kubernetes control-plane node by executing the following steps:

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

  2. Generates a self-signed CA to set up identities for each component in the cluster. The user can provide 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.

  3. 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 named admin.conf.

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

  5. Apply labels and taints to the control-plane node so that no additional workloads will run there.

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

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

  8. 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. 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 is removed in v1.21.

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:

  1. 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:

  1. 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:

  1. sudo kubeadm init phase control-plane all --config=configfile.yaml
  2. sudo kubeadm init phase etcd local --config=configfile.yaml
  3. # you can now modify the control plane and etcd manifest files
  4. 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.

FEATURE STATE: Kubernetes v1.22 [beta]

Alternatively, you can use the skipPhases field under InitConfiguration.

Using kubeadm init with a configuration file

Caution: The config file is still considered beta and may change in future versions.

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 using the --config flag and it must contain a ClusterConfiguration structure and optionally more structures separated by ---\n Mixing --config with others flags may not be allowed in some cases.

The default configuration can be printed out using the kubeadm config print command.

If your configuration is not using the latest version it is recommended that you migrate using the kubeadm config migrate command.

For more information on the fields and usage of the configuration you can navigate to our API reference page.

Using kubeadm init with feature gates

Kubeadm supports a set of feature gates that are unique to kubeadm and can only be applied during cluster creation with kubeadm init. These features can control the behavior of the cluster. Feature gates are removed after a feature graduates to GA.

To pass a feature gate you can either use the --feature-gates flag for kubeadm init, or you can add items into the featureGates field when you pass a configuration file using --config.

Passing feature gates for core Kubernetes components directly to kubeadm is not supported. Instead, it is possible to pass them by Customizing components with the kubeadm API.

List of feature gates:

kubeadm feature gates
FeatureDefaultAlphaBetaGA
PublicKeysECDSAfalse1.19--
RootlessControlPlanefalse1.22--
UnversionedKubeletConfigMaptrue1.221.231.25

Note: Once a feature gate goes GA its value becomes locked to true by default.

Feature gate descriptions:

PublicKeysECDSA

Can be used to create a cluster that uses ECDSA certificates instead of the default RSA algorithm. Renewal of existing ECDSA certificates is also supported using kubeadm certs renew, but you cannot switch between the RSA and ECDSA algorithms on the fly or during upgrades.

RootlessControlPlane

Setting this flag configures the kubeadm deployed control plane component static Pod containers for kube-apiserver, kube-controller-manager, kube-scheduler and etcd to run as non-root users. If the flag is not set, those components run as root. You can change the value of this feature gate before you upgrade to a newer version of Kubernetes.

UnversionedKubeletConfigMap

This flag controls the name of the ConfigMap where kubeadm stores kubelet configuration data. With this flag not specified or set to true, the ConfigMap is named kubelet-config. If you set this flag to false, the name of the ConfigMap includes the major and minor version for Kubernetes (for example: kubelet-config-1.28). Kubeadm ensures that RBAC rules for reading and writing that ConfigMap are appropriate for the value you set. When kubeadm writes this ConfigMap (during kubeadm init or kubeadm upgrade apply), kubeadm respects the value of UnversionedKubeletConfigMap. When reading that ConfigMap (during kubeadm join, kubeadm reset, kubeadm upgrade ...), kubeadm attempts to use unversioned ConfigMap name first; if that does not succeed, kubeadm falls back to using the legacy (versioned) name for that ConfigMap.

List of deprecated feature gates:

kubeadm deprecated feature gates
FeatureDefault
UpgradeAddonsBeforeControlPlanefalse

Feature gate descriptions:

UpgradeAddonsBeforeControlPlane

This is as a disabled feature gate that was introduced for Kubernetes v1.28, in order to allow reactivating a legacy and deprecated behavior during cluster upgrade. For kubeadm versions prior to v1.28, kubeadm upgrades cluster addons (including CoreDNS and kube-proxy) immediately during kubeadm upgrade apply, regardless of whether there are other control plane instances that have not been upgraded. This may cause compatibility problems. Since v1.28, kubeadm defaults to a mode that always checks whether all the control plane instances have been upgraded before starting to upgrade the addons. This behavior is applied to both kubeadm upgrade apply and kubeadm upgrade node. kubeadm determines whether a control plane instance has been upgraded by checking whether the image of the kube-apiserver Pod has been upgraded. You must perform control plane instances upgrade sequentially or at least ensure that the last control plane instance upgrade is not started until all the other control plane instances have been upgraded completely, and the addons upgrade will be performed after the last control plane instance is upgraded. The deprecated UpgradeAddonsBeforeControlPlane feature gate gives you a chance to keep the old upgrade behavior. You should not need this old behavior; if you do, you should consider changing your cluster or upgrade processes, as this feature gate will be removed in a future release.

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:

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:

  1. kubeadm config images list
  2. kubeadm config images pull

You can pass --config to the above commands with a kubeadm configuration file to control the kubernetesVersion and imageRepository fields.

All default registry.k8s.io images that kubeadm requires support multiple architectures.

Using custom images

By default, kubeadm pulls images from registry.k8s.io. If the requested Kubernetes version is a CI label (such as ci/latest) gcr.io/k8s-staging-ci-images is used.

You can override this behavior by using kubeadm with a configuration file. Allowed customization are:

  • To provide kubernetesVersion which affects the version of the images.
  • To provide an alternative imageRepository to be used instead of registry.k8s.io.
  • To provide a specific imageRepository and imageTag for etcd or CoreDNS.

Image paths between the default registry.k8s.io and a custom repository specified using imageRepository may differ for backwards compatibility reasons. For example, one image might have a subpath at registry.k8s.io/subpath/image, but be defaulted to my.customrepository.io/image when using a custom repository.

To ensure you push the images to your custom repository in paths that kubeadm can consume, you must:

  • Pull images from the defaults paths at registry.k8s.io using kubeadm config images {list|pull}.
  • Push images to the paths from kubeadm config images list --config=config.yaml, where config.yaml contains the custom imageRepository, and/or imageTag for etcd and CoreDNS.
  • Pass the same config.yaml to kubeadm init.

Custom sandbox (pause) images

To set a custom image for these you need to configure this in your container runtime to use the image. Consult the documentation for your container runtime to find out how to change this setting; for selected container runtimes, you can also find advice within the Container Runtimes topic.

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:

  1. kubeadm init phase upload-certs --upload-certs --config=SOME_YAML_FILE

Note: A predefined certificateKey can be provided in InitConfiguration when passing the configuration file with --config.

If a predefined 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:

  1. kubeadm 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.

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.

  1. 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:

    1. kubeadm token generate
  2. 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 both kubeadm init and kubeadm join.

  3. Similar can be done for --certificate-key when joining additional control-plane nodes. The key can be generated using:

    1. kubeadm 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.

What’s next

  • 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 or kubeadm join