From ae278797be5a5c6f949974d3709cb7a1bcc654d7 Mon Sep 17 00:00:00 2001 From: Christian Kugler Date: Wed, 8 Feb 2023 12:22:26 +0100 Subject: [PATCH] doc: Add basic upgrade documentation for Helm Charts Without this patch the READMEs for the Helm Charts do not provide any documentation on how to upgrade to a newer version. There is at least one known issue when updating to a newer versions that is unavoidable as of writing. There is a workaround for the issue which should be documented in the upgrade section. This is a problem because currently the only way to find this workaround is to go through closed GitHub issues. These might not be around at the time someone needs this information. Furthermore the issue should be communicated to the operator before it occurs. This patch adds basic documentation for updating the Helm repository, and upgrading the installed release of the Helm Chart. How values can be set is not part of the documentation. If an operator used custom values, e.g. for the secret, they probably already know how to deal with setting values. However, the docs still remind the reader to take values into account. Reusing the installed values (`--reuse-values`) has lead to problems in past, which is why it is explicitly discouraged. An example for this would be the value `logLevel` which was changed to `sidecarLogLevel`. Reusing values lead to `.Values.sidecarLogLevel` being empty and the `csi-provisioner` not being started due to invalid value `-v=""`. Comparing new values with set values is encouraged. The workaround for issue #3397 from GitHub is being addressed in the section Know Issues Upgrading. Signed-off-by: Christian Kugler --- charts/ceph-csi-cephfs/README.md | 30 ++++++++++++++++++++++++++++++ charts/ceph-csi-rbd/README.md | 30 ++++++++++++++++++++++++++++++ 2 files changed, 60 insertions(+) diff --git a/charts/ceph-csi-cephfs/README.md b/charts/ceph-csi-cephfs/README.md index cd0696b6c..21b508cf2 100644 --- a/charts/ceph-csi-cephfs/README.md +++ b/charts/ceph-csi-cephfs/README.md @@ -50,6 +50,36 @@ After installation succeeds, you can get a status of Chart helm status "ceph-csi-cephfs" ``` +### Upgrade Chart + +If you want to upgrade your Chart, use the following commands. + +```bash +helm repo update ceph-csi +helm upgrade --namespace ceph-csi-cephfs ceph-csi-cephfs ceph-csi/ceph-csi-cephfs +``` + +For upgrading to a specific version, provide the flag `--version` and the +version. + +**Do not forget to include your values**, if they differ from the default values. +We recommend not to use `--reuse-values` in case there are new defaults AND +compare your currently used values with the new default values. + +#### Known Issues Upgrading + +- When upgrading to version >=3.7.0, you might encounter an error that the + CephFS CSI Driver cannot be updated. Please refer to + [issue](https://github.com/ceph/ceph-csi/issues/3397) for more details. + This is due to the CSIDriver resource not being updatable. To work around this + you can delete the CSIDriver object by running: + + ```bash + kubectl delete csidriver cephfs.csi.ceph.com + ``` + + Then rerun your `helm upgrade` command. + ### Delete Chart If you want to delete your Chart, use this command diff --git a/charts/ceph-csi-rbd/README.md b/charts/ceph-csi-rbd/README.md index d7bc3de92..1066c5dc7 100644 --- a/charts/ceph-csi-rbd/README.md +++ b/charts/ceph-csi-rbd/README.md @@ -50,6 +50,36 @@ After installation succeeds, you can get a status of Chart helm status "ceph-csi-rbd" ``` +### Upgrade Chart + +If you want to upgrade your Chart, use the following commands. + +```bash +helm repo update ceph-csi +helm upgrade --namespace ceph-csi-rbd ceph-csi-rbd ceph-csi/ceph-csi-rbd +``` + +For upgrading to a specific version, provide the flag `--version` and the +version. + +**Do not forget to include your values**, if they differ from the default values. +We recommend not to use `--reuse-values` in case there are new defaults AND +compare your currently used values with the new default values. + +#### Known Issues Upgrading + +- When upgrading to version >=3.7.0, you might encounter an error that the + RBD CSI Driver cannot be updated. Please refer to + [issue](https://github.com/ceph/ceph-csi/issues/3397) for more details. + This is due to the CSIDriver resource not being updatable. To work around this + you can delete the CSIDriver object by running: + + ```bash + kubectl delete csidriver rbd.csi.ceph.com + ``` + + Then rerun your `helm upgrade` command. + ### Delete Chart If you want to delete your Chart, use this command