From fbe0948d768b23829f477c8dbaa9081131a1ba9c Mon Sep 17 00:00:00 2001 From: Berkay Tekin Oz Date: Mon, 16 Sep 2024 10:43:39 +0000 Subject: [PATCH 1/4] Add how-to for capi in place upgrades --- docs/src/capi/howto/in-place-upgrades.md | 89 ++++++++++++++++++++++++ docs/src/capi/howto/index.md | 1 + 2 files changed, 90 insertions(+) create mode 100644 docs/src/capi/howto/in-place-upgrades.md diff --git a/docs/src/capi/howto/in-place-upgrades.md b/docs/src/capi/howto/in-place-upgrades.md new file mode 100644 index 000000000..c0f75acb7 --- /dev/null +++ b/docs/src/capi/howto/in-place-upgrades.md @@ -0,0 +1,89 @@ +# Perform an in place upgrade for a machine + +This guide walks you through the steps to perform an in place upgrade for a +Cluster API managed Machine. + +## Prerequisites + +To follow this guide, you will need: + +- A Kubernetes management cluster with Cluster API and providers installed + and configured. +- A target workload cluster managed by CAPI. +- `kubectl` installed and configured to access your management cluster. +- The workload cluster kubeconfig. We will refer to it as `c1-kubeconfig.yaml` + in the following steps. + +Please refer to the [getting-started guide][getting-started] for further +details on the required setup. +This guide refers to the workload cluster as `c1` and its +kubeconfig as `c1-kubeconfig.yaml`. + +## Check the current cluster status + +Prior to the upgrade, ensure that the management cluster is in a healthy +state. + +``` +kubectl get nodes -o wide +``` + +Confirm the Kubernetes version of the workload cluster: + +``` +kubectl --kubeconfig c1-kubeconfig.yaml get nodes -o wide +``` + +## Annotate the machine + +In this first step, annotate the Machine resource with +the in place upgrade annotation. In this example, the machine +is called `c1-control-plane-xyzbw`. + +``` +kubectl annotate machine c1-control-plane-xyzbw "v1beta2.k8sd.io/in-place-upgrade-to=" +``` + +`` can be one of: +* `channel=` which refreshes k8s to the given snap channel. e.g. `channel=1.30-classic/stable` +* `revision=` which refreshes k8s to the given revision. e.g. `revision=123` +* `localPath=` which refreshes k8s with the snap file from the given absolute path. `localPath=full/path/to/k8s.snap` + +Please refer to the [ClusterAPI Annotations Reference][capi-annotations-reference] for further +details on the options. + +## Monitor the in place upgrade + +Watch the status of the in place upgrade for the machine, by running the +following command and checking the `v1beta2.k8sd.io/in-place-upgrade-status` annotation: + +``` +kubectl get machine c1-control-plane-xyzbw -o yaml +``` + +On a successful upgrade: +* Value of the `v1beta2.k8sd.io/in-place-upgrade-status` annotation will be changed to `done` +* Value of the `v1beta2.k8sd.io/in-place-upgrade-release` annotation will be changed to the `` used to perform the upgrade. + +## Cancelling a failing upgrade +The upgrade is retried periodically if the operation was unsuccessful. + +The upgrade can be cancelled by running the following commands that remove the annotations: + +``` +kubectl annotate machine c1-control-plane-xyzbw "v1beta2.k8sd.io/in-place-upgrade-to-" +kubectl annotate machine c1-control-plane-xyzbw "v1beta2.k8sd.io/in-place-upgrade-change-id-" +``` + +## Verify the Kubernetes upgrade + +Confirm that the node is healthy and runs on the new Kubernetes version: + +``` +kubectl --kubeconfig c1-kubeconfig.yaml get nodes -o wide +``` + + + +[getting-started]: ../tutorial/getting-started.md +[capi-annotations-reference]: ../reference/annotations.md diff --git a/docs/src/capi/howto/index.md b/docs/src/capi/howto/index.md index 375a5025a..b05a55fa4 100644 --- a/docs/src/capi/howto/index.md +++ b/docs/src/capi/howto/index.md @@ -16,6 +16,7 @@ Overview external-etcd rollout-upgrades +in-place-upgrades upgrade-providers migrate-management custom-ck8s From 0c46e8e31bb927efd2f89a9bec2948722de205d1 Mon Sep 17 00:00:00 2001 From: Berkay Tekin Oz Date: Wed, 18 Sep 2024 09:21:49 +0000 Subject: [PATCH 2/4] Addressing comments --- docs/src/capi/howto/in-place-upgrades.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/docs/src/capi/howto/in-place-upgrades.md b/docs/src/capi/howto/in-place-upgrades.md index c0f75acb7..323e6e491 100644 --- a/docs/src/capi/howto/in-place-upgrades.md +++ b/docs/src/capi/howto/in-place-upgrades.md @@ -1,6 +1,6 @@ -# Perform an in place upgrade for a machine +# Perform an in-place upgrade for a machine -This guide walks you through the steps to perform an in place upgrade for a +This guide walks you through the steps to perform an in-place upgrade for a Cluster API managed Machine. ## Prerequisites @@ -11,8 +11,7 @@ To follow this guide, you will need: and configured. - A target workload cluster managed by CAPI. - `kubectl` installed and configured to access your management cluster. -- The workload cluster kubeconfig. We will refer to it as `c1-kubeconfig.yaml` - in the following steps. +- The workload cluster kubeconfig. Please refer to the [getting-started guide][getting-started] for further details on the required setup. @@ -37,7 +36,7 @@ kubectl --kubeconfig c1-kubeconfig.yaml get nodes -o wide ## Annotate the machine In this first step, annotate the Machine resource with -the in place upgrade annotation. In this example, the machine +the in-place upgrade annotation. In this example, the machine is called `c1-control-plane-xyzbw`. ``` @@ -50,11 +49,11 @@ kubectl annotate machine c1-control-plane-xyzbw "v1beta2.k8sd.io/in-place-upgrad * `localPath=` which refreshes k8s with the snap file from the given absolute path. `localPath=full/path/to/k8s.snap` Please refer to the [ClusterAPI Annotations Reference][capi-annotations-reference] for further -details on the options. +details on these options. -## Monitor the in place upgrade +## Monitor the in-place upgrade -Watch the status of the in place upgrade for the machine, by running the +Watch the status of the in-place upgrade for the machine, by running the following command and checking the `v1beta2.k8sd.io/in-place-upgrade-status` annotation: ``` From c7093f2191836c41e945f1cf6352b3a7ca76923a Mon Sep 17 00:00:00 2001 From: Berkay Tekin Oz Date: Wed, 18 Sep 2024 10:49:21 +0000 Subject: [PATCH 3/4] Linting fixes --- docs/src/capi/howto/in-place-upgrades.md | 32 ++++++++++++++++-------- 1 file changed, 21 insertions(+), 11 deletions(-) diff --git a/docs/src/capi/howto/in-place-upgrades.md b/docs/src/capi/howto/in-place-upgrades.md index 323e6e491..5763181ff 100644 --- a/docs/src/capi/howto/in-place-upgrades.md +++ b/docs/src/capi/howto/in-place-upgrades.md @@ -44,30 +44,40 @@ kubectl annotate machine c1-control-plane-xyzbw "v1beta2.k8sd.io/in-place-upgrad ``` `` can be one of: -* `channel=` which refreshes k8s to the given snap channel. e.g. `channel=1.30-classic/stable` -* `revision=` which refreshes k8s to the given revision. e.g. `revision=123` -* `localPath=` which refreshes k8s with the snap file from the given absolute path. `localPath=full/path/to/k8s.snap` -Please refer to the [ClusterAPI Annotations Reference][capi-annotations-reference] for further -details on these options. +* `channel=` which refreshes k8s to the given snap channel. + e.g. `channel=1.30-classic/stable` +* `revision=` which refreshes k8s to the given revision. + e.g. `revision=123` +* `localPath=` which refreshes k8s with the snap file from + the given absolute path. e.g. `localPath=full/path/to/k8s.snap` + +Please refer to the [ClusterAPI Annotations Reference][annotations-reference] +for further details on these options. ## Monitor the in-place upgrade -Watch the status of the in-place upgrade for the machine, by running the -following command and checking the `v1beta2.k8sd.io/in-place-upgrade-status` annotation: +Watch the status of the in-place upgrade for the machine, +by running the following command and checking the +`v1beta2.k8sd.io/in-place-upgrade-status` annotation: ``` kubectl get machine c1-control-plane-xyzbw -o yaml ``` On a successful upgrade: -* Value of the `v1beta2.k8sd.io/in-place-upgrade-status` annotation will be changed to `done` -* Value of the `v1beta2.k8sd.io/in-place-upgrade-release` annotation will be changed to the `` used to perform the upgrade. + +* Value of the `v1beta2.k8sd.io/in-place-upgrade-status` annotation + will be changed to `done` +* Value of the `v1beta2.k8sd.io/in-place-upgrade-release` annotation + will be changed to the `` used to perform the upgrade. ## Cancelling a failing upgrade + The upgrade is retried periodically if the operation was unsuccessful. -The upgrade can be cancelled by running the following commands that remove the annotations: +The upgrade can be cancelled by running the following commands +that remove the annotations: ``` kubectl annotate machine c1-control-plane-xyzbw "v1beta2.k8sd.io/in-place-upgrade-to-" @@ -85,4 +95,4 @@ kubectl --kubeconfig c1-kubeconfig.yaml get nodes -o wide [getting-started]: ../tutorial/getting-started.md -[capi-annotations-reference]: ../reference/annotations.md +[annotations-reference]: ../reference/annotations.md From 8cd625c06e76f448e349dad2f483d6e26d9993df Mon Sep 17 00:00:00 2001 From: Nick Veitch Date: Wed, 18 Sep 2024 15:12:10 +0100 Subject: [PATCH 4/4] Update docs/src/capi/howto/in-place-upgrades.md --- docs/src/capi/howto/in-place-upgrades.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/capi/howto/in-place-upgrades.md b/docs/src/capi/howto/in-place-upgrades.md index 5763181ff..7b20c9dab 100644 --- a/docs/src/capi/howto/in-place-upgrades.md +++ b/docs/src/capi/howto/in-place-upgrades.md @@ -1,7 +1,7 @@ # Perform an in-place upgrade for a machine This guide walks you through the steps to perform an in-place upgrade for a -Cluster API managed Machine. +Cluster API managed machine. ## Prerequisites