Polish 0.7 upgrade notes

docs/upgrading.rst

@@ -6,22 +6,25 @@ Upgrading to 0.7.0
 
 Because of `problems with Helm and secret management
 <https://open.greenhost.net/openappstack/openappstack/-/issues/891>`__
-we had to move away from using a helm chart for secrets, and now use scripts
-that run during installation to manage secrets. Because we have removed the
-``oas-secrets`` helm chart, Flux will remove the secrets that it has
+we had to move away from using a helm chart for application secrets, and now use
+scripts that run during installation to manage secrets. Because we have removed
+the ``oas-secrets`` helm chart, Flux will remove the secrets that it has
 generated. **It is important that you back up these secrets before switching
-from ``v0.6`` to ``v0.7``!**
+from v0.6 to v0.7!**
 
-Before you start, please ensure that you have the right ``yq`` tool installed,
-because you will need it later.  There are two very different versions of
-``yq``. The one you need is the go based [yq from Mike
-Farah](http://mikefarah.github.io/yq/), which installs the same binary name ``yq``
-as the [python-yq](https://github.com/kislyuk/yq), while both have different
-command sets.
+.. note::
+  Before you start, please ensure that you have the right ``yq`` tool installed,
+  because you will need it later.  There are two very different versions of
+  ``yq``. The one you need is the go based `yq from Mike Farah
+  <http://mikefarah.github.io/yq>`_, which installs the same binary name ``yq``
+  as the `python-yq <https://github.com/kislyuk/yq>`_, while both have different
+  command sets.
+  The yq needed here can be installed by running ``sudo snap install yq``,
+  ``brew install yq`` or with other methods from the `yq installation
+  instructions <http://mikefarah.github.io/yq/#install>`_.
 
-The yq needed here can be installed by running ``sudo snap install yq``,
-``brew install yq`` or with other methods from the [``yq`` installation
-instructions](http://mikefarah.github.io/yq/#install).
+  If you're unsure which ``yq`` you have installed, look at the output of
+  ``yq --help`` and make sure ``eval`` shows up under ``Available Commands:``.
 
 
 To back-up your secrets, run the following script:
@@ -57,15 +60,17 @@ lines under "data:", rename the field to ``wekan_oauth_client_secret`` and enter
 a different random password. Make sure to base64 encode it (``echo "<your random
 password>" | base64``).
 
-If you get the error several times, that means ther
-
 This script creates a directory called ``secrets-backup`` and places the secrets
 that have been generated by Helm in it as ``yaml`` files.
 
-Now you can upgrade your cluster by running ``kubectl edit gitrepository -n
-flux-system openappstack`` and setting ``spec.ref.branch`` to ``v0.7``
+Now you can upgrade your cluster by running
+``kubectl -n flux-system patch gitrepository openappstack --type merge
+-p '{"spec":{"ref":{"branch":"v0.7"}}}'``
+or by editing the ``gitrepository`` object manually with
+``kubectl -n flux-system edit gitrepository openappstack`` and setting
+``spec.ref.branch`` to ``v0.7``.
 
-Flux will now start updating your cluster to version 0.7. This process will fail,
+Flux will now start updating your cluster to version ``0.7``. This process will fail,
 because it will remove the secrets that you just backed up. Make
 sure that the ``oas-secrets`` helmrelease has been removed by running ``flux get
 hr -A``. You might also see that some helmreleases start failing to be installed
@@ -79,16 +84,15 @@ the following code:
    #!/usr/bin/env bash
 
    # Again: make sure you use https://github.com/mikefarah/yq -- install with `snap install yq`
-   yq eval 'del(.metadata.annotations,.metadata.labels,.metadata.creationTimestamp,.metadata.resourceVersion,.metadata.uid)' secrets-backup/oas-cluster-variables.yaml | kubectl apply -f - -n flux-system
-   yq eval 'del(.metadata.annotations,.metadata.labels,.metadata.creationTimestamp,.metadata.resourceVersion,.metadata.uid)' secrets-backup/oas-wordpress-variables.yaml | kubectl apply -f - -n flux-system
-   yq eval 'del(.metadata.annotations,.metadata.labels,.metadata.creationTimestamp,.metadata.resourceVersion,.metadata.uid)' secrets-backup/oas-wekan-variables.yaml | kubectl apply -f - -n flux-system
-   yq eval 'del(.metadata.annotations,.metadata.labels,.metadata.creationTimestamp,.metadata.resourceVersion,.metadata.uid)' secrets-backup/oas-single-sign-on-variables.yaml | kubectl apply -f - -n flux-system
-   yq eval 'del(.metadata.annotations,.metadata.labels,.metadata.creationTimestamp,.metadata.resourceVersion,.metadata.uid)' secrets-backup/oas-rocketchat-variables.yaml | kubectl apply -f - -n flux-system
-   yq eval 'del(.metadata.annotations,.metadata.labels,.metadata.creationTimestamp,.metadata.resourceVersion,.metadata.uid)' secrets-backup/oas-kube-prometheus-stack-variables.yaml | kubectl apply -f - -n flux-system
-   yq eval 'del(.metadata.annotations,.metadata.labels,.metadata.creationTimestamp,.metadata.resourceVersion,.metadata.uid)' secrets-backup/oas-prometheus-basic-auth.yaml | kubectl apply -f - -n flux-system
-   yq eval 'del(.metadata.annotations,.metadata.labels,.metadata.creationTimestamp,.metadata.resourceVersion,.metadata.uid)' secrets-backup/oas-alertmanager-basic-auth.yaml | kubectl apply -f - -n flux-system
-   yq eval 'del(.metadata.annotations,.metadata.labels,.metadata.creationTimestamp,.metadata.resourceVersion,.metadata.uid)' secrets-backup/oas-oauth-variables.yaml | kubectl apply -f - -n flux-system
-   yq eval 'del(.metadata.annotations,.metadata.labels,.metadata.creationTimestamp,.metadata.resourceVersion,.metadata.uid)' secrets-backup/oas-nextcloud-variables.yaml | kubectl apply -f - -n flux-system
+   yq eval 'del(.metadata.annotations,.metadata.labels,.metadata.creationTimestamp,.metadata.resourceVersion,.metadata.uid)' secrets-backup/oas-wordpress-variables.yaml | kubectl apply -f -
+   yq eval 'del(.metadata.annotations,.metadata.labels,.metadata.creationTimestamp,.metadata.resourceVersion,.metadata.uid)' secrets-backup/oas-wekan-variables.yaml | kubectl apply -f -
+   yq eval 'del(.metadata.annotations,.metadata.labels,.metadata.creationTimestamp,.metadata.resourceVersion,.metadata.uid)' secrets-backup/oas-single-sign-on-variables.yaml | kubectl apply -f -
+   yq eval 'del(.metadata.annotations,.metadata.labels,.metadata.creationTimestamp,.metadata.resourceVersion,.metadata.uid)' secrets-backup/oas-rocketchat-variables.yaml | kubectl apply -f -
+   yq eval 'del(.metadata.annotations,.metadata.labels,.metadata.creationTimestamp,.metadata.resourceVersion,.metadata.uid)' secrets-backup/oas-kube-prometheus-stack-variables.yaml | kubectl apply -f -
+   yq eval 'del(.metadata.annotations,.metadata.labels,.metadata.creationTimestamp,.metadata.resourceVersion,.metadata.uid)' secrets-backup/oas-prometheus-basic-auth.yaml | kubectl apply -f -
+   yq eval 'del(.metadata.annotations,.metadata.labels,.metadata.creationTimestamp,.metadata.resourceVersion,.metadata.uid)' secrets-backup/oas-alertmanager-basic-auth.yaml | kubectl apply -f -
+   yq eval 'del(.metadata.annotations,.metadata.labels,.metadata.creationTimestamp,.metadata.resourceVersion,.metadata.uid)' secrets-backup/oas-oauth-variables.yaml | kubectl apply -f -
+   yq eval 'del(.metadata.annotations,.metadata.labels,.metadata.creationTimestamp,.metadata.resourceVersion,.metadata.uid)' secrets-backup/oas-nextcloud-variables.yaml | kubectl apply -f -
 
 Again this script assumes you have all applications installed. If you get the
 following error, you can ignore it:
@@ -104,8 +108,10 @@ failed, you can retrigger reconciliation of a kustomization using the commands
 can take quite a while (over an hour some times), because Flux waits for some
 long timeouts before giving up and re-starting a reconciliation.
 
-Some errors we've seen during our own upgrade process, and how to solve them
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Potential upgrade issues
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Some errors we've seen during our own upgrade process, and how to solve them:
 
 SSO helm upgrade failed
 '''''''''''''''''''''''