# Creating Highly Available Clusters with kubeadm

Creating Highly Available Clusters with kubeadmThis page explains two different approaches to setting up a highly available Kubernetes cluster using kubeadm:With stacked control plane nodes. This approach requires less infrastructure. The etcd members and control plane nodes are co-located.With an external etcd cluster. This approach requires more infrastructure. The control plane nodes and etcd members are separated.Before proceeding, you should carefully consider which approach best meets the needs of your applications and environment. Options for Highly Available topology outlines the advantages and disadvantages of each.If you encounter issues with setting up the HA cluster, please report these in the kubeadm issue tracker.See also the upgrade documentation.Caution:This page does not address running your cluster on a cloud provider. In a cloud environment, neither approach documented here works with Service objects of type LoadBalancer, or with dynamic PersistentVolumes.Before you beginThe prerequisites depend on which topology you have selected for your cluster's control plane:You need:Three or more machines that meet kubeadm's minimum requirements for the control-plane nodes. Having an odd number of control plane nodes can help with leader selection in the case of machine or zone failure.including a container runtime, already set up and workingThree or more machines that meet kubeadm's minimum requirements for the workersincluding a container runtime, already set up and workingFull network connectivity between all machines in the cluster (public or private network)Superuser privileges on all machines using sudoYou can use a different tool; this guide uses sudo in the examples.SSH access from one device to all nodes in the systemkubeadm and kubelet already installed on all machines.See Stacked etcd topology for context.You need:Three or more machines that meet kubeadm's minimum requirements for the control-plane nodes. Having an odd number of control plane nodes can help with leader selection in the case of machine or zone failure.including a container runtime, already set up and workingThree or more machines that meet kubeadm's minimum requirements for the workersincluding a container runtime, already set up and workingFull network connectivity between all machines in the cluster (public or private network)Superuser privileges on all machines using sudoYou can use a different tool; this guide uses sudo in the examples.SSH access from one device to all nodes in the systemkubeadm and kubelet already installed on all machines.And you also need:Three or more additional machines, that will become etcd cluster members. Having an odd number of members in the etcd cluster is a requirement for achieving optimal voting quorum.These machines again need to have kubeadm and kubelet installed.These machines also require a container runtime, that is already set up and working.See External etcd topology for context.Container imagesEach host should have access read and fetch images from the Kubernetes container image registry, registry.k8s.io. If you want to deploy a highly-available cluster where the hosts do not have access to pull images, this is possible. You must ensure by some other means that the correct container images are already available on the relevant hosts.Command line interfaceTo manage Kubernetes once your cluster is set up, you should install kubectl on your PC. It is also useful to install the kubectl tool on each control plane node, as this can be helpful for troubleshooting.First steps for both methodsCreate load balancer for kube-apiserverNote:There are many configurations for load balancers. The following example is only one option. Your cluster requirements may need a different configuration.Create a kube-apiserver load balancer with a name that resolves to DNS.In a cloud environment you should place your control plane nodes behind a TCP forwarding load balancer. This load balancer distributes traffic to all healthy control plane nodes in its target list. The health check for an apiserver is a TCP check on the port the kube-apiserver listens on (default value :6443).It is not recommended to use an IP address directly in a cloud environment.The load balancer must be able to communicate with all control plane nodes on the apiserver port. It must also allow incoming traffic on its listening port.Make sure the address of the load balancer always matches the address of kubeadm's ControlPlaneEndpoint.Read the Options for Software Load Balancing guide for more details.Add the first control plane node to the load balancer, and test the connection:nc -zv -w 2 <LOAD_BALANCER_IP> <PORT> A connection refused error is expected because the API server is not yet running. A timeout, however, means the load balancer cannot communicate with the control plane node. If a timeout occurs, reconfigure the load balancer to communicate with the control plane node.Add the remaining control plane nodes to the load balancer target group.Stacked control plane and etcd nodesSteps for the first control plane nodeInitialize the control plane:sudo kubeadm init --control-plane-endpoint "LOAD_BALANCER_DNS:LOAD_BALANCER_PORT" --upload-certs You can use the --kubernetes-version flag to set the Kubernetes version to use. It is recommended that the versions of kubeadm, kubelet, kubectl and Kubernetes match.The --control-plane-endpoint flag should be set to the address or DNS and port of the load balancer.The --upload-certs flag is used to upload the certificates that should be shared across all the control-plane instances to the cluster. If instead, you prefer to copy certs across control-plane nodes manually or using automation tools, please remove this flag and refer to Manual certificate distribution section below.Note:The kubeadm init flags --config and --certificate-key cannot be mixed, therefore if you want to use the kubeadm configuration you must add the certificateKey field in the appropriate config locations (under InitConfiguration and JoinConfiguration: controlPlane).Note:Some CNI network plugins require additional configuration, for example specifying the pod IP CIDR, while others do not. See the CNI network documentation. To add a pod CIDR pass the flag --pod-network-cidr, or if you are using a kubeadm configuration file set the podSubnet field under the networking object of ClusterConfiguration.The output looks similar to:... You can now join any number of control-plane node by running the following command on each as a root: kubeadm join 192.168.0.200:6443 --token 9vr73a.a8uxyaju799qwdjv --discovery-token-ca-cert-hash sha256:7c2e69131a36ae2a042a339b33381c6d0d43887e2de83720eff5359e26aec866 --control-plane --certificate-key f8902e114ef118304e561c3ecd4d0b543adc226b7a07f675f56564185ffe0c07 Please note that the certificate-key gives access to cluster sensitive data, keep it secret! As a safeguard, uploaded-certs will be deleted in two hours; If necessary, you can use kubeadm init phase upload-certs to reload certs afterward. Then you can join any number of worker nodes by running the following on each as root: kubeadm join 192.168.0.200:6443 --token 9vr73a.a8uxyaju799qwdjv --discovery-token-ca-cert-hash sha256:7c2e69131a36ae2a042a339b33381c6d0d43887e2de83720eff5359e26aec866 Copy this output to a text file. You will need it later to join control plane and worker nodes to the cluster.When --upload-certs is used with kubeadm init, the certificates of the primary control plane are encrypted and uploaded in the kubeadm-certs Secret.To re-upload the certificates and generate a new decryption key, use the following command on a control plane node that is already joined to the cluster:sudo kubeadm init phase upload-certs --upload-certs You can also specify a custom --certificate-key during init that can later be used by join. To generate such a key you can use the following command:kubeadm certs certificate-key The certificate key is a hex encoded string that is an AES key of size 32 bytes.Note:The kubeadm-certs Secret and the decryption key expire after two hours.Caution:As stated in the command output, the certificate key gives access to cluster sensitive data, keep it secret!Apply the CNI plugin of your choice: Follow these instructions to install the CNI provider. Make sure the configuration corresponds to the Pod CIDR specified in the kubeadm configuration file (if applicable).Note:You must pick a network plugin that suits your use case and deploy it before you move on to