From 0904e8828a64b0d56bd2577435f9beb29adbeab7 Mon Sep 17 00:00:00 2001 From: Brett Tofel Date: Mon, 16 Sep 2024 17:03:09 -0400 Subject: [PATCH 1/4] Update downgrade guide for ClusterExtension Significantly expanded the documentation to include detailed steps on downgrading a ClusterExtension, including disabling CRD safety checks and overriding upgrade constraints. Added prerequisites, troubleshooting, and post-downgrade verification sections. Signed-off-by: Brett Tofel --- docs/drafts/Tasks/downgrading-an-extension.md | 212 +++++++++++++++++- 1 file changed, 210 insertions(+), 2 deletions(-) diff --git a/docs/drafts/Tasks/downgrading-an-extension.md b/docs/drafts/Tasks/downgrading-an-extension.md index 58d9ec846..f3608c427 100644 --- a/docs/drafts/Tasks/downgrading-an-extension.md +++ b/docs/drafts/Tasks/downgrading-an-extension.md @@ -1,3 +1,211 @@ -# Downgrade an Extension -Placeholder. This topic is under development. \ No newline at end of file +# Downgrade a ClusterExtension + +## Introduction + +Downgrading a `ClusterExtension` involves reverting the extension to a previous version. This process might be necessary due to compatibility issues, unexpected behavior in the newer version, or specific feature requirements that are only available in an earlier release. This guide provides step-by-step instructions to safely downgrade a `ClusterExtension`, including necessary overrides to bypass default constraints and disable CRD safety checks. + +## Prerequisites + +Before initiating the downgrade process, ensure the following prerequisites are met: + +- **Backup Configurations:** Always back up your current configurations and data to prevent potential loss during the downgrade. +- **Access Rights:** Ensure you have the necessary permissions to modify `ClusterExtension` resources and perform administrative tasks. +- **Version Availability:** Verify that the target downgrade version is available in your catalogs. +- **Compatibility Check:** Ensure that the target version is compatible with your current system and other dependencies. + +## Steps to Downgrade + +### 1. Disabling the CRD Upgrade Safety Check + +Custom Resource Definitions (CRDs) ensure that the resources used by the `ClusterExtension` are valid and consistent. During a downgrade, the CRD Upgrade Safety check might prevent reverting to an incompatible version. Disabling the CRD Upgrade Safety check allows the downgrade to proceed without these validations. + +**Disable CRD Safety Check Configuration:** + +Add the `crdUpgradeSafety` field and set its `policy` to `Disabled` in the `ClusterExtension` resource under the `preflight` section. + +**Example:** + +```yaml +apiVersion: olm.operatorframework.io/v1alpha1 +kind: ClusterExtension +metadata: + name: example-extension +spec: + install: + preflight: + crdUpgradeSafety: + policy: Disabled + namespace: argocd + serviceAccount: + name: argocd-installer + source: + sourceType: Catalog + catalog: + packageName: argocd-operator + version: 0.6.0 + upgradeConstraintPolicy: SelfCertified +``` + +**Steps to Disable CRD Upgrade Safety Check:** + +1. **Edit the ClusterExtension Resource:** + + ```bash + kubectl edit clusterextension + ``` + +2. **Add the `crdUpgradeSafety.policy` Field:** + + Insert the following line under the `spec.install.preflight` section: + + ```yaml + crdUpgradeSafety: + policy: Disabled + ``` + +3. **Save and Exit:** + + Kubernetes will apply the updated configuration, disabling CRD safety checks during the downgrade process. + +### 2. Ignoring Catalog Provided Upgrade Constraints + +By default, Operator Lifecycle Manager (OLM) enforces upgrade constraints based on semantic versioning and catalog definitions. To allow downgrades, you need to override these constraints. + +**Override Configuration:** + +Set the `upgradeConstraintPolicy` to `SelfCertified` in the `ClusterExtension` resource. This configuration permits downgrades, sidegrades, and any version changes without adhering to the predefined upgrade paths. + +**Example:** + +```yaml +apiVersion: olm.operatorframework.io/v1alpha1 +kind: ClusterExtension +metadata: + name: example-extension +spec: + source: + sourceType: Catalog + catalog: + packageName: argocd-operator + version: 0.6.0 + upgradeConstraintPolicy: SelfCertified + install: + namespace: argocd + serviceAccount: + name: argocd-installer +``` + +**Command Example:** + +If you prefer using the command line, you can use `kubectl` to modify the upgrade constraint policy. + +```bash +kubectl patch clusterextension --patch '{"spec":{"upgradeConstraintPolicy":"SelfCertified"}}' --type=merge +``` + +### 3. Executing the Downgrade + +Once the CRD safety checks are disabled and upgrade constraints are set, you can proceed with the actual downgrade. + +1. **Edit the ClusterExtension Resource:** + + Modify the `ClusterExtension` custom resource to specify the target version and adjust the upgrade constraints. + + ```bash + kubectl edit clusterextension + ``` + +2. **Update the Version:** + + Within the YAML editor, update the `spec` section as follows: + + ```yaml + apiVersion: olm.operatorframework.io/v1alpha1 + kind: ClusterExtension + metadata: + name: + spec: + source: + sourceType: Catalog + catalog: + packageName: + version: + install: + namespace: + serviceAccount: + name: + ``` + + - **`version`:** Specify the target version you wish to downgrade to. + +3. **Apply the Changes:** + + Save and exit the editor. Kubernetes will apply the changes and initiate the downgrade process. + +### 4. Post-Downgrade Verification + +After completing the downgrade, verify that the `ClusterExtension` is functioning as expected. + +**Verification Steps:** + +1. **Check the Status of the ClusterExtension:** + + ```bash + kubectl get clusterextension -o yaml + ``` + + Ensure that the `status` reflects the target version and that there are no error messages. + +2. **Validate CRD Integrity:** + + Confirm that all CRDs associated with the `ClusterExtension` are correctly installed and compatible with the downgraded version. + + ```bash + kubectl get crd | grep + ``` + +3. **Test Extension Functionality:** + + Perform functional tests to ensure that the extension operates correctly in its downgraded state. + +4. **Monitor Logs:** + + Check the logs of the operator managing the `ClusterExtension` for any warnings or errors. + + ```bash + kubectl logs deployment/ -n + ``` + +## Troubleshooting + +During the downgrade process, you might encounter issues. Below are common problems and their solutions: + +### Downgrade Fails Due to Version Constraints + +**Solution:** + +- Ensure that the `upgradeConstraintPolicy` is set to `SelfCertified`. +- Verify that the target version exists in the catalog. +- Check for typos or incorrect version numbers in the configuration. + +### CRD Compatibility Issues + +**Solution:** + +- Review the changes in CRDs between versions to ensure compatibility. +- If disabling the CRD safety check, ensure that the downgraded version can handle the existing CRDs without conflicts. +- Consider manually reverting CRDs if necessary, but proceed with caution to avoid data loss. + +### Extension Becomes Unresponsive After Downgrade + +**Solution:** + +- Restore from the backup taken before the downgrade. +- Investigate logs for errors related to the downgraded version. +- Verify that all dependencies required by the downgraded version are satisfied. + +## Additional Resources + +- [Semantic Versioning Specification](https://semver.org/) +- [Manually Verified Upgrades and Downgrades](https://github.com/operator-framework/operator-controller/blob/main/docs/drafts/upgrade-support.md#manually-verified-upgrades-and-downgrades) From 7bf7974673ecbaf7ca4c061551133ccc2ebf53b1 Mon Sep 17 00:00:00 2001 From: Brett Tofel Date: Mon, 16 Sep 2024 17:10:58 -0400 Subject: [PATCH 2/4] Refactor location of downgrade doc Signed-off-by: Brett Tofel --- README.md | 2 +- docs/drafts/Tasks/upgrading-an-extension.md | 2 +- docs/drafts/{Tasks => }/downgrading-an-extension.md | 0 3 files changed, 2 insertions(+), 2 deletions(-) rename docs/drafts/{Tasks => }/downgrading-an-extension.md (100%) diff --git a/README.md b/README.md index 275486209..c4a1ce3af 100644 --- a/README.md +++ b/README.md @@ -102,7 +102,7 @@ kubectl patch clusterextension argocd --type='merge' -p '{"spec": {"source": {"c ``` -For information on the downgrade process, see [here](./docs/drafts/Tasks/downgrading-an-extension.md). +For information on the downgrade process, see [here](docs/drafts/downgrading-an-extension.md). ### Uninstall the Cluster Extension diff --git a/docs/drafts/Tasks/upgrading-an-extension.md b/docs/drafts/Tasks/upgrading-an-extension.md index 648093e87..ec13c7317 100644 --- a/docs/drafts/Tasks/upgrading-an-extension.md +++ b/docs/drafts/Tasks/upgrading-an-extension.md @@ -2,7 +2,7 @@ Existing extensions can be upgraded by updating the version field in the ClusterExtension resource. -For information on downgrading an extension, see [Downgrade an Extension](downgrading-an-extension). +For information on downgrading an extension, see [Downgrade an Extension](../downgrading-an-extension.md). ## Prerequisites diff --git a/docs/drafts/Tasks/downgrading-an-extension.md b/docs/drafts/downgrading-an-extension.md similarity index 100% rename from docs/drafts/Tasks/downgrading-an-extension.md rename to docs/drafts/downgrading-an-extension.md From f7b73d9dab76c08b7788aa001981a084b1dd13ad Mon Sep 17 00:00:00 2001 From: Brett Tofel Date: Tue, 17 Sep 2024 09:42:19 -0400 Subject: [PATCH 3/4] Wording corrections on intro paragraph Signed-off-by: Brett Tofel --- docs/drafts/downgrading-an-extension.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/drafts/downgrading-an-extension.md b/docs/drafts/downgrading-an-extension.md index f3608c427..e47bbd453 100644 --- a/docs/drafts/downgrading-an-extension.md +++ b/docs/drafts/downgrading-an-extension.md @@ -3,7 +3,7 @@ ## Introduction -Downgrading a `ClusterExtension` involves reverting the extension to a previous version. This process might be necessary due to compatibility issues, unexpected behavior in the newer version, or specific feature requirements that are only available in an earlier release. This guide provides step-by-step instructions to safely downgrade a `ClusterExtension`, including necessary overrides to bypass default constraints and disable CRD safety checks. +Downgrading a `ClusterExtension` involves reverting the extension to a previous available version. This process might be required due to compatibility issues, unexpected behavior in the newer version, or specific feature requirements that are only available in an earlier release. This guide provides step-by-step instructions to safely downgrade a `ClusterExtension`, including necessary overrides to bypass default constraints and disable CRD safety checks. ## Prerequisites From 220ec73db6dcea960cde7ff5945e4d18479074e3 Mon Sep 17 00:00:00 2001 From: Brett Tofel Date: Tue, 17 Sep 2024 12:20:40 -0400 Subject: [PATCH 4/4] Update intro & CRD safety check procedure Enhanced downgrade guide with new risks and update steps. Replaced manual `kubectl edit` step with a `kubectl patch` command for disabling CRD safety checks. Signed-off-by: Brett Tofel --- docs/drafts/downgrading-an-extension.md | 20 ++++---------------- 1 file changed, 4 insertions(+), 16 deletions(-) diff --git a/docs/drafts/downgrading-an-extension.md b/docs/drafts/downgrading-an-extension.md index e47bbd453..c372ce8e2 100644 --- a/docs/drafts/downgrading-an-extension.md +++ b/docs/drafts/downgrading-an-extension.md @@ -3,7 +3,7 @@ ## Introduction -Downgrading a `ClusterExtension` involves reverting the extension to a previous available version. This process might be required due to compatibility issues, unexpected behavior in the newer version, or specific feature requirements that are only available in an earlier release. This guide provides step-by-step instructions to safely downgrade a `ClusterExtension`, including necessary overrides to bypass default constraints and disable CRD safety checks. +Downgrading a `ClusterExtension` involves reverting the extension to a previously available version. This process may be necessary due to compatibility issues, unexpected behavior in the newer version, or specific feature requirements only available in an earlier release. However, downgrading carries inherent risks, such as potential data loss, issues with new CRD versions, and possible breakage of clients that rely on the newer version. Users should carefully consider these risks and be confident in their decision to proceed with the downgrade. This guide provides step-by-step instructions for performing a downgrade, including overrides to bypass default constraints and disable CRD safety checks. ## Prerequisites @@ -47,25 +47,13 @@ spec: upgradeConstraintPolicy: SelfCertified ``` -**Steps to Disable CRD Upgrade Safety Check:** +** Disable CRD Upgrade Safety Check:** -1. **Edit the ClusterExtension Resource:** +**Patch the ClusterExtension Resource:** ```bash - kubectl edit clusterextension + kubectl patch clusterextension --patch '{"spec":{"install":{"preflight":{"crdUpgradeSafety":{"policy":"Disabled"}}}}}' --type=merge ``` - -2. **Add the `crdUpgradeSafety.policy` Field:** - - Insert the following line under the `spec.install.preflight` section: - - ```yaml - crdUpgradeSafety: - policy: Disabled - ``` - -3. **Save and Exit:** - Kubernetes will apply the updated configuration, disabling CRD safety checks during the downgrade process. ### 2. Ignoring Catalog Provided Upgrade Constraints