From 8f8e2be7f6ac085fe53f957c7cf423e47d39efae Mon Sep 17 00:00:00 2001 From: Chuck Ha Date: Mon, 9 Mar 2020 14:41:55 -0400 Subject: [PATCH] Add documentation around KubeadmControlPlanes Signed-off-by: Chuck Ha --- docs/book/src/SUMMARY.md | 1 + docs/book/src/tasks/kubeadm-control-plane.md | 46 ++++++++++++++++++++ 2 files changed, 47 insertions(+) create mode 100644 docs/book/src/tasks/kubeadm-control-plane.md diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md index dbd725f6db70..62024764b018 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](./tasks/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..6558f9da3592 --- /dev/null +++ b/docs/book/src/tasks/kubeadm-control-plane.md @@ -0,0 +1,46 @@ +# Kubeadm control plane + +Using the Kubeadm control plane type to manage a control plane provides several ways to upgrade control plane machines. + +## Upgrading workload clusters + +The high level steps to fully upgrading a workload cluster are to first upgrade the control plane and then upgrade +the worker machines. + +### Upgrading the control plane 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 + +1. Copy the existing `MachineTemplate`. +2. Modify the values that need changing, such as instance type or image ID. +3. Create the new `MachineTemplate` on the management cluster. +4. Modify the existing `KubeadmControlPlane` resource to reference the new `MachineTemplate` resource. + +The final step 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 `Spec.Version` field. This will +trigger a rolling upgrade of the control plane. + +Some infrastructure providers, such as [CAPA](https://github.com/kubernetes-sigs/cluster-api-provider-aws), require +that if a specific machine image is specified, it has to match the Kubernetes version specified in the +`KubeadmControlPlane` spec. In order to only trigger a single upgrade, the new `MachineTemplate` should be created first +and then both the `Version` and `InfrastructureTemplate` should be modified in a single transaction. + +### Upgrading workload machines managed by a `MachineDeployment` + +Upgrades are not limited to just the control plane. This section is not related to Kubeadm control plane specifically, +but is the final step in fully upgrading a Cluster API managed cluster. + +It is recommended to manage workload machines with one or more `MachineDeployment`s. `MachineDeployment`s 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. + +For a more in-depth look at how `MachineDeployments` manage scaling events, take a look at the [`MachineDeployment` +controller documentation](../developer/architecture/controllers/machine-deployment.md) and the [`MachineSet` controller +documentation](../developer/architecture/controllers/machine-set.md).