Merge branch '880-document-yamltojson-error' into 'master'

add troubleshooting instructions for #880 and some small fixes

Closes #880

See merge request openappstack/openappstack!502

docs/installation/install_oas.rst

@@ -65,6 +65,9 @@ values. The rest are optional.
 - ``admin_email``: a valid email address for the system administrator of your
   cluster.
 
+Make sure not to put any quotes around your values, because that can make the
+resulting yaml files invalid.
+
 Outgoing email
 --------------
 

docs/installation/overview.rst

@@ -42,7 +42,7 @@ Clone the OpenAppStack git repository
 -------------------------------------
 
 On your **provisioning machine**, clone the OpenAppStack git repository
-and checkout the latest release branch (currently ``v0.6``):
+and checkout the latest release branch (currently ``v0.7``):
 
 ::
 

docs/troubleshooting.rst

@@ -138,10 +138,10 @@ You can also only run a Taiko test for a specific application, i.e.:
    python -m openappstack CLUSTERNAME test --taiko-tags nextcloud
 
 Advanced usage
---------------
+~~~~~~~~~~~~~~
 
 Testinfra tests
-~~~~~~~~~~~~~~~
+'''''''''''''''
 
 Specify host manually:
 
@@ -191,12 +191,10 @@ then:
     gitlab-runner exec docker --env CI_REGISTRY_IMAGE="$CI_REGISTRY_IMAGE" --env SSH_PRIVATE_KEY="$SSH_PRIVATE_KEY" --env COSMOS_API_TOKEN="$COSMOS_API_TOKEN" bootstrap
 
 Taiko tests
-~~~~~~~~~~~
+'''''''''''
 
-Using Taiko without the OpenAppStack CLI
-''''''''''''''''''''''''''''''''''''''''
-
-Go to the ``test/taiko`` directory and run:
+If you want to use Taiko without invoking the openappstack CLI, go to the
+``test/taiko`` directory and run:
 
 For nextcloud & onlyoffice tests:
 
@@ -396,6 +394,34 @@ by telling Flux to *reconcile* them:
 Will make sure that the Nextcloud ``helmrelease`` gets brought into a state that
 our OpenAppStack wants it to be in.
 
+
+Common installation failures
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+var substitution failed
+'''''''''''''''''''''''
+
+When you execute ``flux get kustomization`` and you see this error:
+
+.. code::
+
+   var substitution failed for 'kube-prometheus-stack': YAMLToJSON: yaml: line 32: found character that cannot start any token
+
+That can mean that one of your values contains a double quote (``"``) or that
+you quoted a value in ``.flux.env`` during the :ref:`flux_config`. Make sure
+that ``.flux.env`` does not contain any values that are quoted.
+
+If you need to change ``.flux.env``, run the following commands: 
+
+.. code:: bash
+
+   $ kubectl apply -k $CLUSTER_DIR
+
+Afterwards, you can speed up the process that fixes your ``kustomization``, by
+running ``flux reconcile kustomization kube-prometheus-stack`` (replace
+``kube-prometheus-stack`` with the kustomization is mentioned in the error
+message).
+
 Purge OAS and install from scratch
 ----------------------------------
 

install/.flux.env.example

+# This file contains variables that will be used in Kubernetes manifests.
+# Replace the values to make sense for your setup. The values should not be
+# quoted (correct: a=b, incorrect: a="b").
+
 # IP address of the cluster
 ip_address=1.2.3.4
 # FQDN of the cluster