This command initializes a Kubernetes control-plane node.
Run this command in order to set up the Kubernetes control plane.
The init
command executes the following phases:
preflight Run master pre-flight checks
kubelet-start Writes kubelet settings and (re)starts the kubelet
certs Certificate generation
/ca Generates the self-signed Kubernetes CA to provision identities for other Kubernetes components
/apiserver Generates the certificate for serving the Kubernetes API
/apiserver-kubelet-client Generates the Client certificate for the API server to connect to kubelet
/front-proxy-ca Generates the self-signed CA to provision identities for front proxy
/front-proxy-client Generates the client for the front proxy
/etcd-ca Generates the self-signed CA to provision identities for etcd
/etcd-server Generates the certificate for serving etcd
/etcd-peer Generates the credentials for etcd nodes to communicate with each other
/etcd-healthcheck-client Generates the client certificate for liveness probes to healtcheck etcd
/apiserver-etcd-client Generates the client apiserver uses to access etcd
/sa Generates a private key for signing service account tokens along with its public key
kubeconfig Generates all kubeconfig files necessary to establish the control plane and the admin kubeconfig file
/admin Generates a kubeconfig file for the admin to use and for kubeadm itself
/kubelet Generates a kubeconfig file for the kubelet to use *only* for cluster bootstrapping purposes
/controller-manager Generates a kubeconfig file for the controller manager to use
/scheduler Generates a kubeconfig file for the scheduler to use
control-plane Generates all static Pod manifest files necessary to establish the control plane
/apiserver Generates the kube-apiserver static Pod manifest
/controller-manager Generates the kube-controller-manager static Pod manifest
/scheduler Generates the kube-scheduler static Pod manifest
etcd Generates static Pod manifest file for local etcd.
/local Generates the static Pod manifest file for a local, single-node local etcd instance.
upload-config Uploads the kubeadm and kubelet configuration to a ConfigMap
/kubeadm Uploads the kubeadm ClusterConfiguration to a ConfigMap
/kubelet Uploads the kubelet component config to a ConfigMap
mark-control-plane Mark a node as a control-plane
bootstrap-token Generates bootstrap tokens used to join a node to a cluster
addon Installs required addons for passing Conformance tests
/coredns Installs the CoreDNS addon to a Kubernetes cluster
/kube-proxy Installs the kube-proxy addon to a Kubernetes cluster
kubeadm init [flags]
--apiserver-advertise-address string | |
The IP address the API Server will advertise it's listening on. Specify '0.0.0.0' to use the address of the default network interface. | |
--apiserver-bind-port int32 Default: 6443 | |
Port for the API Server to bind to. | |
--apiserver-cert-extra-sans stringSlice | |
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. | |
--config string | |
Path to kubeadm config file. WARNING: Usage of a configuration file is experimental. | |
--cri-socket string Default: "/var/run/dockershim.sock" | |
Specify the CRI socket to connect to. | |
--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: |
|
-h, --help | |
help for init | |
--ignore-preflight-errors stringSlice | |
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: "k8s.gcr.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. | |
--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-phases stringSlice | |
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 masters. 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 |
--rootfs string | |
[EXPERIMENTAL] The path to the 'real' host root filesystem. |
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) this step is skipped as described in the
Using custom certificates document.
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 named admin.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 are 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 the master 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.
ClusterConfiguration
. For more information about the configuration see the section
Using kubeadm init with a configuration file
bellow.
Please note that although the DNS server is deployed, it will not be scheduled until CNI is installed.Kubeadm allows you create a control-plane node in phases. In 1.13 the kubeadm init phase
command has graduated to GA from it’s previous alpha state under kubeadm alpha phase
.
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 expose 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.
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 in the --config
option.
In Kubernetes 1.11 and later, the default configuration can be printed out using the
kubeadm config print command.
It is recommended that you migrate your old v1alpha3
configuration to v1beta1
using
the kubeadm config migrate command,
because v1alpha3
will be removed in Kubernetes 1.14.
For more details on each field in the v1beta1
configuration you can navigate to our
API reference pages.
For information about kube-proxy parameters in the kubeadm configuration see: - kube-proxy
For information about enabling IPVS mode with kubeadm see: - IPVS
For information about passing flags to control plane components see: - control-plane-flags
By default, kubeadm pulls images from k8s.gcr.io
, unless
the requested Kubernetes version is a CI version. In this case,
gcr.io/kubernetes-ci-images
is used.
You can override this behavior by using kubeadm with a configuration file. Allowed customization are:
imageRepository
to be used instead of
k8s.gcr.io
.useHyperKubeImage
to true
to use the HyperKube image.imageRepository
and imageTag
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.
By default, kubeadm generates all the certificates needed for a cluster to run. You can override this behavior by providing your own certificates.
To do so, you must place them in whatever directory is specified by the
--cert-dir
flag or CertificatesDir
configuration file key. By default this
is /etc/kubernetes/pki
.
If a given certificate and private key pair exists, kubeadm skips the
generation step and existing files are used for the prescribed
use case. This means you can, for example, copy an existing CA into /etc/kubernetes/pki/ca.crt
and /etc/kubernetes/pki/ca.key
, and kubeadm will use this CA for signing the rest
of the certs.
It is also possible to provide just the ca.crt
file and not the
ca.key
file (this is only available for the root CA file, not other cert pairs).
If all other certificates and kubeconfig files are in place, kubeadm recognizes
this condition and activates the “External CA” mode. kubeadm will proceed without the
CA key on disk.
Instead, run the controller-manager standalone with --controllers=csrsigner
and
point to the CA certificate and key.
The kubeadm package ships with configuration for how the kubelet should
be run. Note that the kubeadm
CLI command never touches this drop-in file.
This drop-in file belongs to the kubeadm deb/rpm package.
This is what it looks like:
[Service]
Environment="KUBELET_KUBECONFIG_ARGS=--bootstrap-kubeconfig=/etc/kubernetes/bootstrap-kubelet.conf --kubeconfig=/etc/kubernetes/kubelet.conf"
Environment="KUBELET_SYSTEM_PODS_ARGS=--pod-manifest-path=/etc/kubernetes/manifests --allow-privileged=true"
Environment="KUBELET_NETWORK_ARGS=--network-plugin=cni --cni-conf-dir=/etc/cni/net.d --cni-bin-dir=/opt/cni/bin"
Environment="KUBELET_DNS_ARGS=--cluster-dns=10.96.0.10 --cluster-domain=cluster.local"
Environment="KUBELET_AUTHZ_ARGS=--authorization-mode=Webhook --client-ca-file=/etc/kubernetes/pki/ca.crt"
Environment="KUBELET_CADVISOR_ARGS="
Environment="KUBELET_CERTIFICATE_ARGS=--rotate-certificates=true --cert-dir=/var/lib/kubelet/pki"
ExecStart=/usr/bin/kubelet $KUBELET_KUBECONFIG_ARGS $KUBELET_SYSTEM_PODS_ARGS $KUBELET_NETWORK_ARGS $KUBELET_DNS_ARGS $KUBELET_AUTHZ_ARGS $KUBELET_CADVISOR_ARGS $KUBELET_CERTIFICATE_ARGS $KUBELET_EXTRA_ARGS
Here’s a breakdown of what/why:
--bootstrap-kubeconfig=/etc/kubernetes/bootstrap-kubelet.conf
path to a kubeconfig
file that is used to get client certificates for kubelet during node join.
On success, a kubeconfig file is written to the path specified by --kubeconfig
.--kubeconfig=/etc/kubernetes/kubelet.conf
points to the kubeconfig file that
tells the kubelet where the API server is. This file also has the kubelet’s
credentials.--pod-manifest-path=/etc/kubernetes/manifests
specifies from where to read
static Pod manifests used for starting the control plane.--allow-privileged=true
allows this kubelet to run privileged Pods.--network-plugin=cni
uses CNI networking.--cni-conf-dir=/etc/cni/net.d
specifies where to look for the
CNI spec file(s).--cni-bin-dir=/opt/cni/bin
specifies where to look for the actual CNI binaries.--cluster-dns=10.96.0.10
use this cluster-internal DNS server for nameserver
entries in Pods’ /etc/resolv.conf
.--cluster-domain=cluster.local
uses this cluster-internal DNS domain for
search
entries in Pods’ /etc/resolv.conf
.--client-ca-file=/etc/kubernetes/pki/ca.crt
authenticates requests to the Kubelet
API using this CA certificate.--authorization-mode=Webhook
authorizes requests to the Kubelet API by POST
-ing
a SubjectAccessReview
to the API server.--rotate-certificates
auto rotate the kubelet client certificates by requesting new
certificates from the kube-apiserver
when the certificate expiration approaches.--cert-dir
the directory where the TLS certs are located.Since v1.6.0, Kubernetes has enabled the use of CRI, Container Runtime Interface, by default.
The container runtime used by default is Docker, which is enabled through the built-in
dockershim
CRI implementation inside of the kubelet
.
Other CRI-based runtimes include:
Refer to the CRI installation instructions for more information.
After you have successfully installed kubeadm
and kubelet
, execute
these two additional steps:
Install the runtime shim on every node, following the installation document in the runtime shim project listing above.
Configure kubelet to use the remote CRI runtime. Please remember to change
RUNTIME_ENDPOINT
to your own value like /var/run/{your_runtime}.sock
:
cat > /etc/systemd/system/kubelet.service.d/20-cri.conf <<EOF
[Service]
Environment="KUBELET_EXTRA_ARGS=--container-runtime=remote --container-runtime-endpoint=$RUNTIME_ENDPOINT"
EOF
systemctl daemon-reload
Now kubelet
is ready to use the specified CRI runtime, and you can continue
with the kubeadm init
and kubeadm join
workflow to deploy Kubernetes cluster.
You may also want to set --cri-socket
to kubeadm init
and kubeadm reset
when
using an external CRI implementation.
In order to set up a cluster where the master and worker nodes communicate with internal IP addresses (instead of public ones), execute following steps.
kubeadm init --apiserver-advertise-address=<private-master-ip>
/etc/systemd/system/kubelet.service.d/10-kubeadm.conf
that specifies the private IP of the worker node:--node-ip=<private-node-ip>
kubeadm join
, make sure you provide the private IP of the API server addressed as defined in step 1.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
to the kubelet.
Be aware that overriding the hostname can interfere with cloud providers.
As of 1.8, you can experimentally create a self-hosted Kubernetes control plane. This means that key components such as the API server, controller manager, and scheduler run as DaemonSet pods configured via the Kubernetes API instead of static pods configured in the kubelet via static files.
To create a self-hosted cluster, pass the flag --feature-gates=SelfHosting=true
to kubeadm init
.
Caution:SelfHosting
is an alpha feature. It is deprecated in 1.12 and will be removed in 1.13.
Self-hosting in 1.8 and later has some important limitations. In particular, a self-hosted cluster cannot recover from a reboot of the control-plane node without manual intervention. This and other limitations are expected to be resolved before self-hosting graduates from alpha.
By default, self-hosted control plane Pods rely on credentials loaded from
hostPath
volumes. Except for initial creation, these credentials are not managed by
kubeadm.
In kubeadm 1.8, the self-hosted portion of the control plane does not include etcd, which still runs as a static Pod.
The self-hosting bootstrap process is documented in the kubeadm design document.
In summary, kubeadm alpha selfhosting
works as follows:
Waits for this bootstrap static control plane to be running and
healthy. This is identical to the kubeadm init
process without self-hosting.
Uses the static control plane Pod manifests to construct a set of DaemonSet manifests that will run the self-hosted control plane. It also modifies these manifests where necessary, for example adding new volumes for secrets.
Creates DaemonSets in the kube-system
namespace and waits for the
resulting Pods to be running.
Once self-hosted Pods are operational, their associated static Pods are deleted and kubeadm moves on to install the next component. This triggers kubelet to stop those static Pods.
When the original static control plane stops, the new self-hosted control plane is able to bind to listening ports and become active.
For running kubeadm without an internet connection you have to pre-pull the required master images for the version of choice:
Image Name | v1.10 release branch version |
---|---|
k8s.gcr.io/kube-apiserver-${ARCH} | v1.10.x |
k8s.gcr.io/kube-controller-manager-${ARCH} | v1.10.x |
k8s.gcr.io/kube-scheduler-${ARCH} | v1.10.x |
k8s.gcr.io/kube-proxy-${ARCH} | v1.10.x |
k8s.gcr.io/etcd-${ARCH} | 3.1.12 |
k8s.gcr.io/pause-${ARCH} | 3.1 |
k8s.gcr.io/k8s-dns-sidecar-${ARCH} | 1.14.8 |
k8s.gcr.io/k8s-dns-kube-dns-${ARCH} | 1.14.8 |
k8s.gcr.io/k8s-dns-dnsmasq-nanny-${ARCH} | 1.14.8 |
coredns/coredns | 1.0.6 |
Here v1.10.x
means the “latest patch release of the v1.10 branch”.
${ARCH}
can be one of: amd64
, arm
, arm64
, ppc64le
or s390x
.
If you run Kubernetes version 1.10 or earlier, and if you set --feature-gates=CoreDNS=true
,
you must also use the coredns/coredns
image, instead of the three k8s-dns-*
images.
In Kubernetes 1.11 and later, you can list and pull the images using the kubeadm config images
sub-command:
kubeadm config images list
kubeadm config images pull
Starting with Kubernetes 1.12, the k8s.gcr.io/kube-*
, k8s.gcr.io/etcd
and k8s.gcr.io/pause
images
don’t require an -${ARCH}
suffix.
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 master will have after it is started.
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 both kubeadm init
and kubeadm join
.
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.
kubeadm init
phaseskubeadm init
or kubeadm join
Was this page helpful?
Thanks for the feedback. If you have a specific, answerable question about how to use Kubernetes, ask it on Stack Overflow. Open an issue in the GitHub repo if you want to report a problem or suggest an improvement.