Update documentation

* Add upgrade how-to
* Adjust parameters docs

Author: simu

docs/modules/ROOT/pages/how-tos/upgrade-v8-v9.adoc

@@ -0,0 +1,19 @@
+= Upgrade `component-argocd` from `v8.x` to `v9.x`
+
+TIP: On clusters which use SSH to fetch the cluster catalogs no manual actions are necessary.
+
+The component version `v9.x` defaults to ArgoCD v3 which only supports https://argo-cd.readthedocs.io/en/stable/operator-manual/declarative-setup/#repositories[declarative configuration of repositories^].
+
+The switch to declarative repository configuration is a breaking change for clusters which use HTTPS cluster catalogs.
+
+Operators of such clusters must update the HTTPS credentials secret to be picked up as a repo credentials secret by ArgoCD v3:
+
+[source,bash]
+----
+SECRET_NAME=the-credentials-secret <1>
+kubectl -n syn patch secret "$SECRET_NAME" --type=merge \
+  -p '{"stringData":{"url":"'"$CATALOG_URL"'"}}'
+kubectl -n syn label secret "$SECRET_NAME" \
+  argocd.argoproj.io/secret-type=repo-creds
+----
+<1> Replace with the name of the secret

docs/modules/ROOT/pages/references/parameters.adoc

@@ -128,11 +128,16 @@ Override specs of the ProjectSyn ArgoCD instance.
 type:: string
 default:: `catalog-https-credentials`
 
-The name of the externally managed secret which holds the username and password for fetching the catalog repo over HTTPS in fields `username` and `password`.
+The name of the externally managed secret which holds the username and password for fetching the catalog repo over HTTPS.
+
+The secret must be labeled with `argocd.argoproj.io/secret-type=repo-creds`.
+The secret must have the credentials in fields `username` and `password` and must have the catalog repo HTTPS URL (or a prefix thereof) in field `url`.
+
+NOTE: The `url` field must contain the catalog URL (or prefix) including the leading `https://`.
 
 This parameter is only used when the cluster's catalog repo URL starts with `https://`.
 
-IMPORTANT: Users must ensure that this secret is in place before this component is synced.
+IMPORTANT: Users must ensure that this secret is correctly configured and present before this component is synced.
 
 == `images`
 

docs/modules/ROOT/partials/nav.adoc

@@ -4,6 +4,7 @@
 * xref:how-tos/upgrade-v3-v4.adoc[Upgrade from `v3.x` to `v4.x`]
 * xref:how-tos/upgrade-v5-v6.adoc[Upgrade from `v5.5.x` to `v6.x`]
 * xref:how-tos/upgrade-v7-v8.adoc[Upgrade from `v7.x` to `v8.x`]
+* xref:how-tos/upgrade-v8-v9.adoc[]
 
 .References
 * xref:references/parameters.adoc[Parameters]