From 65ca6a74c00f470d1d0bb679c3f063ae73eb891b Mon Sep 17 00:00:00 2001 From: Tim Smith Date: Wed, 17 Jan 2024 22:08:11 -0800 Subject: [PATCH] Rework upgrade docs to not mention pre-1.0 (#1003) * Rework upgrade docs to not mention pre-1.0 Restructure this around Helm, OLM, and manual installs and remove mention of pre-1.0 since we've already upgraded those folks at this point. Signed-off-by: Tim Smith * Update docs/operator-upgrades.md Co-authored-by: Letha * Update docs/operator-upgrades.md Co-authored-by: Letha * Update docs/operator-upgrades.md Co-authored-by: Letha * Shuffle the paragraphs Signed-off-by: Tim Smith * Edit to make following instructions easier --------- Signed-off-by: Tim Smith Co-authored-by: Letha --- docs/operator-upgrades.md | 79 ++++++++++++++------------------------- 1 file changed, 29 insertions(+), 50 deletions(-) diff --git a/docs/operator-upgrades.md b/docs/operator-upgrades.md index dd2606dd5..0fecb575e 100644 --- a/docs/operator-upgrades.md +++ b/docs/operator-upgrades.md @@ -1,30 +1,12 @@ -# Upgrading the Mondoo Operator +# Upgrade the Mondoo Operator -The Mondoo Operator version numbers are expressed as `x.y.z`, where `x` is the major version, `y` is the minor version, and `z` is the patch version, following [Semantic Versioning](https://semver.org/) standards. Our release approach ensures there are no breaking changes between two adjacent minor versions. For example, you can upgrade the Mondoo Operator from `v0.2.15` to `v0.3.0` without any manual actions. The Mondoo Operator automatically executes any required migration and/or cleanup steps. +The Mondoo Operator version numbers are expressed as `x.y.z`, where `x` is the major version, `y` is the minor version, and `z` is the patch version, following [Semantic Versioning](https://semver.org/) standards. Our release approach ensures there are no breaking changes between two adjacent minor versions. For example, you can upgrade the Mondoo Operator from `v1.2.15` to `v1.3.0` without any manual actions. The Mondoo Operator automatically executes any required migration and/or cleanup steps. -You can skip Mondoo Operator patch and minor versions. - -## Version 1.0 and later - -As of version 1.0, the Mondoo Operator can be upgraded from major version to major version as long as each major version is visited during the upgrade. For example, if you are on version 1.3.2 and wanted to upgrade to version 3.0.5, you should first upgrade to a 2.y.z release to ensure any migrations that need to take place from 1.x to 2.x are completed before upgrading to 3.x. Jumping from any 1.x to any 2.x is a safe operation. - -### Updating an operator deployed with Helm - -Two update your operator installed with Helm, you have two options: - -- Upgrade the Helm chart to the [latest release](https://github.com/mondoohq/mondoo-operator/releases/latest) -- Update the [values](https://github.com/mondoohq/mondoo-operator/blob/main/charts/mondoo-operator/values.yaml#L17) for the Helm chart to the latest image tag which matched the latest Helm chart release. - You can also find it [here](https://github.com/mondoohq/mondoo-operator/pkgs/container/mondoo-operator/versions?filters%5Bversion_type%5D=tagged) - -## Pre 1.0 - -For pre-1.0 releases, we don't recommend skipping minor versions. For example, if you upgrade from `v0.2.0` directly to `v0.4.0`, the Mondoo Operator may not behave as expected, and you may leave behind unused resources in the cluster. Skipping a minor version may require manual actions to ensure the Mondoo Operator is fully functional. - -**NOTE: all upgrade text below is written against 1.0 behavior. If using pre-1.0, then all mentions that follow of checking major versions should be read as checking against minor versions.** +You can upgrade the Mondoo Operator from major version to major version as long as each major version is visited during the upgrade. For example, if you are on version 1.3.2 and want to upgrade to version 3.0.5, you should first upgrade to a 2.y.z release to ensure any migrations that need to take place from 1.x to 2.x are completed before upgrading to 3.x. Jumping from any 1.x to any 2.x is a safe operation. **WARNING: Never try to upgrade the Mondoo Operator by simply changing the tag for the Mondoo Operator container image.** -## Recommended Mondoo Operator upgrade process +## Update a manually deployed operator Follow these steps for a smooth Mondoo Operator upgrade: @@ -46,9 +28,9 @@ kubectl apply -f https://github.com/mondoohq/mondoo-operator/releases/latest/dow ### If your current Mondoo Operator is more than one major version behind -If there **is** more than one major version difference between the installed Mondoo Operator and the latest release, you must apply the manifest files for each major version between the two versions. For example, if the version installed is `v1.2.0` and the latest version is `v3.4.3`, you must install something from the `v2.x` releases. Follow these steps: +If there **is** more than one major version difference between the installed Mondoo Operator and the latest release, you must apply the manifest files for each major version between the two versions. For example, if the version installed is `v1.2.0` and the latest version is `v3.4.3`, you must install you must install a x2.x release. Follow these steps: -1. Apply the manifest for `v2.0.0` (the version you skipped): +1. Apply the manifest for the version you skipped, such as `v2.0.0`: ```bash kubectl apply -f https://github.com/mondoohq/mondoo-operator/releases/v2.0.0/download/mondoo-operator-manifests.yaml ``` @@ -66,42 +48,39 @@ If there **is** more than one major version difference between the installed Mon kubectl get mondooauditconfigs.k8s.mondoo.com -o jsonpath='{range .items[*]}{.status.reconciledByOperatorVersion}{"\n"}{end}' -A | uniq ``` - The version of your running Mondoo Operator and the version in the `Status` field have to be the same before you can proceed with the next version update. + The version of your running Mondoo Operator and the version in the `Status` field must be the same before you proceed. -3. Apply the manifest for `v3.4.3` (the latest version): - `bash kubectl apply -f https://github.com/mondoohq/mondoo-operator/releases/latest/download/mondoo-operator-manifests.yaml ` - Adjust the steps above to fit your current situation. There may be multiple major release versions between your installed version and the latest release. You must install each major version independently, wait between each update to verify that the version installed properly and the log is error-free. +3. Repeat steps 1 and 2 for every major release between your version and the latest release. You must install each major version independently, waiting between each update to verify that the version installed properly and the log is error free. -## Upgrading to Mondoo Operator v0.8.0 +4. Apply the manifest for the latest version, such as `v3.4.3`: + `bash kubectl apply -f https://github.com/mondoohq/mondoo-operator/releases/latest/download/mondoo-operator-manifests.yaml -In case you are running a Mondoo Operator with a version older than v0.8.0 in your cluster, it is required to perform extra steps before upgrading. +## Update an operator deployed with Helm -### Helm and kubectl installations - -For Helm and kubectl installations before applying the `v0.8.0` manifests run: +Two update your operator installed with Helm, you have two options: -```bash -kubectl delete -n mondoo-operator deployments.apps mondoo-operator-controller-manager -``` +- Upgrade the Helm chart to the [latest release](https://github.com/mondoohq/mondoo-operator/releases/latest) +- Update the [values](https://github.com/mondoohq/mondoo-operator/blob/main/charts/mondoo-operator/values.yaml#L17) for the Helm chart to the latest image tag which matched the latest Helm chart release. + You can also find it [here](https://github.com/mondoohq/mondoo-operator/pkgs/container/mondoo-operator/versions?filters%5Bversion_type%5D=tagged) -### OLM installations +## Update an OLM installation -For OLM installations first list the subscriptions: +1. List the subscriptions: -```bash -kubectl get subscription -n mondoo-operator -``` + ```bash + kubectl get subscription -n mondoo-operator + ``` -Delete the Mondoo Operator subscription: +2. Delete the Mondoo Operator subscription: -```bash -kubectl delete sub -n mondoo-operator mondoo-operator-v0-7-1-sub -``` + ```bash + kubectl delete sub -n mondoo-operator mondoo-operator-v0-7-1-sub + ``` -Delete the Mondoo Operator cluster service version: +3. Delete the Mondoo Operator cluster service version: -```bash -kubectl delete csv -n mondoo-operator mondoo-operator.v0.7.1 -``` + ```bash + kubectl delete csv -n mondoo-operator mondoo-operator.v0.7.1 + ``` -After that you can install the latest Mondoo Operator version using the standard OLM installation command. +4. Install the latest Mondoo Operator version using the standard OLM installation command. \ No newline at end of file