move some stuff around to let it make more sense

docs/installation_instructions.md

@@ -348,31 +348,3 @@ Besides these applications, some other auxiliary components are installed:
   traffic to all applications running in the cluster;
 * [Flux](https://fluxcd.io) checks for application updates approved by the
   OpenAppStack team and installs them automatically.
-
-## Managing an existing cluster
-
-You can use `kubectl`, the Kubernetes control program, to find and manipulate
-your Kubernetes cluster. Once you have installed `kubectl`, to get access to your
-cluster with the OAS CLI:
-
-    $ python -m openappstack my-cluster info
-
-Look for these lines:
-
-    To use kubectl with this cluster, copy-paste this in your terminal:
-
-    export KUBECONFIG=/home/you/projects/openappstack/clusters/my-cluster/secrets/kube_config_cluster.yml
-
-Copy the whole `export` line into your terminal. In *the same terminal window*,
-kubectl will connect to your cluster.
-
-### SSH access
-
-Alternatively, you can SSH login to your VPS. Some programs that are
-available to the root user on the VPS:
-
-* `kubectl`, the Kubernetes control program. The root user is connected to the
-  cluster automatically.
-* `helm` is the "Kubernetes package manager". Use `helm ls` to see what apps are
-  installed in your cluster. You can also use it to perform manual upgrades;
-  see `helm --help`.

docs/troubleshooting.md

@@ -150,14 +150,16 @@ applications.
       behave -D nextcloud.url=https://files.ci-20410.ci.openappstack.net \
        -D nextcloud.admin.password=…
 
+## SSH access
 
-## Upgrading
-
-If you encounter problems when you upgrade your cluster, please make sure first
-to include all potential new values of `ansible/group_vars/all/settings.yml.example`
-to your `clusters/YOUR_CLUSTERNAME/group_vars/all/settings.yml`, and rerun the installation
-script.
+You can SSH login to your VPS. Some programs that are available to the root user
+on the VPS:
 
+* `kubectl`, the Kubernetes control program. The root user is connected to the
+  cluster automatically.
+* `helm` is the "Kubernetes package manager". Use `helm ls` to see what apps are
+  installed in your cluster. You can also use it to perform manual upgrades;
+  see `helm --help`.
 
 ## HTTPS Certificates
 
@@ -189,6 +191,22 @@ Show the logs of the main `cert-manager` pod:
 You can `grep` for your cluster domain or for any specific subdomain to narrow
 down results.
 
+## Using kubectl to debug your cluster
+
+You can use `kubectl`, the Kubernetes control program, to find and manipulate
+your Kubernetes cluster. Once you have installed `kubectl`, to get access to your
+cluster with the OAS CLI:
+
+    $ python -m openappstack my-cluster info
+
+Look for these lines:
+
+    To use kubectl with this cluster, copy-paste this in your terminal:
+
+    export KUBECONFIG=/home/you/projects/openappstack/clusters/my-cluster/secrets/kube_config_cluster.yml
+
+Copy the whole `export` line into your terminal. In *the same terminal window*,
+kubectl will connect to your cluster.
 
 ## Purge OAS and install from scratch
 

docs/upgrading.md

@@ -26,4 +26,10 @@ intervention.
     for these applications. Find all the pvcs by running `kubectl get pvc
     --namespace oas-apps` and `kubectl get pvc --namespace oas`
 
+## Troubleshooting
 
+If you encounter problems when you upgrade your cluster, please make sure first
+to include all potential new values of
+`ansible/group_vars/all/settings.yml.example` to your
+`clusters/YOUR_CLUSTERNAME/group_vars/all/settings.yml`, and rerun the
+installation script.