For full text search please use the '?' prefix. e.g. ? Onboarding

kubeadm

kubeadm is the de facto tool for performing cluster deployments. Specialised tooling is available for deployments into specific vendor environments.

Create a new cluster

From the first control plane node:

# Verbosity level, for debugging output
export VERBOSITY=5
# Control plane endpoint for external clients; we'll need to set up a load balancer here or use a VIP
export CONTROL_PLANE_ENDPOINT=10.0.0.5
# Listen address for the API server on this node
export APISERVER_ADVERTISE_ADDRESS=10.0.0.6

kubeadm init \
    --v="$VERBOSITY" \
    --apiserver-advertise-address "$APISERVER_ADVERTISE_ADDRESS" \
    --control-plane-endpoint "$CONTROL_PLANE_ENDPOINT" \
    --upload-certs

Make a note of the following values:

  • --token
  • --discovery-token-ca-cert-hash
  • --certificate-key

We'll use them for joining additional nodes later.

If you're deploying multiple masters, we now need to configure either a load balancer or VIP to ensure the control plane is accessible at the configured --control-plane-endpoint. See `kube-vip` for one solution.

Join control plane node

Note that control plane nodes should generally be added in groups of two to ensure there's always an odd number of nodes.

From the new control plane node:

# Verbosity level, for debugging output
export VERBOSITY=5
# Control plane endpoint for external clients; must already work
export CONTROL_PLANE_ENDPOINT=10.0.0.5
# Listen address for the API server on this node
export APISERVER_ADVERTISE_ADDRESS=10.0.0.7

# The --token value from the control plane creation
export TOKEN=
# The --discovery-token-ca-cert-hash value from the control plane creation
export DISCOVERY_TOKEN_CA_CERT_HASH=
# The --certificate-key value from the control plane creation
export CERTIFICATE_KEY=

kubeadm join "$CONTROL_PLANE_ENDPOINT" \
    --v="$VERBOSITY" \
    --control-plane \
    --certificate-key "$CERTIFICATE_KEY" \
    --discovery-token-ca-cert-hash "$DISCOVERY_TOKEN_CA_CERT_HASH" \
    --token "$TOKEN" \
    --apiserver-advertise-address "$APISERVER_ADVERTISE_ADDRESS"

Join worker node

From the new worker node:

# Control plane endpoint for external clients; must already work
export CONTROL_PLANE_ENDPOINT=10.0.0.5

# The --token value from the control plane creation
export TOKEN=
# The --discovery-token-ca-cert-hash value from the control plane creation
export DISCOVERY_TOKEN_CA_CERT_HASH=

kubeadm join "$CONTROL_PLANE_ENDPOINT" \
    --token "$TOKEN" \
    --discovery-token-ca-cert-hash "$DISCOVERY_TOKEN_CA_CERT_HASH"

Upgrade a cluster

At a high level, the upgrade process for kubeadm-created clusters is:

  • kubeadm upgrade plan validates it's possible to upgrade the cluster.
  • kubeadm upgrade apply upgrades the first control plane node.
  • kubeadm upgrade diff shows the changes that will be applied.
  • kubeadm upgrade node enables updates of the local kubelet on secondary control plane nodes and worker nodes.
Backlinks