diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md index dbd725f6db70..0d9c08557132 100644 --- a/docs/book/src/SUMMARY.md +++ b/docs/book/src/SUMMARY.md @@ -11,6 +11,7 @@ - [Generating a Kubeconfig](./tasks/certs/generate-kubeconfig.md) - [Upgrade](./tasks/upgrade.md) - [Configure a MachineHealthCheck](./tasks/healthcheck.md) + - [Kubeadm based control plane management](./kubeadm-control-plane.md) - [clusterctl CLI](./clusterctl/overview.md) - [clusterctl Commands](clusterctl/commands/commands.md) - [init](clusterctl/commands/init.md) diff --git a/docs/book/src/tasks/kubeadm-control-plane.md b/docs/book/src/tasks/kubeadm-control-plane.md new file mode 100644 index 000000000000..155d2019b0a2 --- /dev/null +++ b/docs/book/src/tasks/kubeadm-control-plane.md @@ -0,0 +1,28 @@ +# Kubeadm control plane + +Using the Kubeadm control plane type to manage a control plane provides several ways to upgrade control plane machines. + +## Upgrading + +The high level steps to fully upgrading a workload cluster are to first upgrade the control plane and then upgrade +the worker machines. + +### Upgrading workload machines managed by a `MachineDeployment` + +It is recommended to manage workload machines with a `MachineDeployment` as this will transparently manage `MachineSet`s +and `Machine`s to allow for a seamless scaling experience. A modification to the `MachineDeployment`s spec will begin a +rolling update of the workload machines. + +### How to upgrade the underlying machine image + +To upgrade the control plane machines underlying machine images, the `MachineTemplate` resource referenced by the +`KubeadmControlPlane` must be changed. Since `MachineTemplate` resources are immutable, the recommended approach is to +copy the existing `MachineTemplate`, modify the necessary values, create the new `MachineTemplate` on the management +cluster, and finally, modify the existing `KubeadmControlPlane` resource to reference the new `MachineTemplate` +resource. This will trigger a rolling update of the control plane using the new values found in the `MachineTemplate`. + +### How to upgrade the Kubernetes control plane version + +To upgrade the Kubernetes control plane version, which will likely, depending on the provider, also upgrade the +underlying machine image, make a modification to the `KubeadmControlPlane` resource's `Version` field. This will trigger +a rolling upgrade of the control plane.