docs(kaas): azDomains config

docs/paas/kaas/installation/initial-setup.md

@@ -0,0 +1,44 @@
+# Initial setup
+
+For the *Kubernetes as a service* system to function, you need to pick and configure 2 DNS entries on your DNS server
+for each AZ and set those entries in your configuration file. You need to define those domains for every AZ that your
+*superphenix-api* deployment controlls.
+
+```yaml
+management:
+  systemConfiguration:
+    apps:
+      superphenix-api:
+        values:
+          config:
+            productsConfig:
+              argoApp:
+                kubernetes:
+                  azDomains:
+                    # add domains for all AZs which are controlled
+                    # by this superphenix-api instance
+                    local:
+                      external: "%s.kaas.local.example.org"
+                      internal: "azs.my-region.example.org"
+```
+
+## External domain
+
+This *wildcard* domain serves to build the URLs used to talk to KaaS controlplanes. For each new cluster an ingress is created where the `%s` part is replaced by the cluster's ID.
+The DNS record needs to point to the public IP of your AZ.
+
+!!! tip "No DNS?"
+    Use **[nip.io](https://nip.io)** against your AZ's public IP, for example `%s.1.2.3.4.nip.io`.
+
+    If you only want to access controlplanes locally, you can use a local node IP, but beware of [current limitations](../../../operations/limitations.md#nat-gateway-traffic-to-its-host-node).
+
+## Internal domain
+
+This domain is used by the kubernetes nodes to find their controlplane, even if the cluster was migrated to another AZ (in case of disaster recovery). The DNS record consists of a list containing
+the public IPs of all AZs in your region. The internal proxy running on each KaaS node will check all listed AZs and forward requests to the one listening for the corresponding *external domain*.
+
+!!! tip "No DNS?"
+    You can use **[nip.io](https://nip.io)** against your AZ's public IP, for example `local.1.2.3.4.nip.io`.  
+    Using a local node IP is also possible, but beware of [current limitations](../../../operations/limitations.md#nat-gateway-traffic-to-its-host-node).
+
+    If you have multiple AZ's, keep in mind that the disaster recovery function will not work in these configurations.

docs/paas/kaas/advanced-configuration.md → docs/paas/kaas/user-guides/advanced-configuration.md

@@ -80,3 +80,18 @@ To accomplish this follow these steps:
     ```
 
     Full chart values: [sfs-kaas](https://github.com/super-phenix/superphenix/blob/main/components/dependencies/sfs-kaas/values.yaml).
+
+For example, this feature can be leveraged to automatically enroll the cluster to an ArgoCD instance. A custom chart deploys a job that sets up the service account,
+ArgoCD connection and git repository. To assist in such endeavours, KaaS clusters contain a configmap which presents details about the cluster.
+
+This configmap is called `spx-cluster-info` and can be found in the `kube-system` namespace. It provides the following information under a `cluster` key:
+
+- **clusterID**: The unique SPXID of the cluster.
+- **friendlyName**: User-defined, human-readable name.
+- **kubeVersion**: Kubernetes release version.
+- **name**: Name of the cluster, used to generate its ID. Either UUIDv4 for console deployment or same as *friendlyName* for GitOps clusters.
+- **organizationID**: SPXID of the organization.
+- **projectID**: SPXID of the project.
+- **location**: AZ in which the cluster is deployed.
+
+You can also find those values here: [kaas-essentials](https://github.com/super-phenix/superphenix/blob/main/components/dependencies/kaas-essentials/values.yaml).

zensical.toml

@@ -67,10 +67,15 @@ nav = [
     { "PaaS" = [
       { "KaaS" = [
         { "Overview" = "paas/kaas/index.md" },
-        { "Basic operations" = "paas/kaas/basic-operations.md" },
-        { "Advanced configuration" = "paas/kaas/advanced-configuration.md" },
-        { "Disaster recovery" = "paas/kaas/disaster-recovery.md" },
-        { "Network configuration" = "paas/kaas/network-configuration.md" }
+        { "Installation" = [
+          { "Initial setup" = "paas/kaas/installation/initial-setup.md" },
+        ]},
+        { "User Guides" = [
+          { "Basic operations" = "paas/kaas/user-guides/basic-operations.md" },
+          { "Advanced configuration" = "paas/kaas/user-guides/advanced-configuration.md" },
+          { "Disaster recovery" = "paas/kaas/user-guides/disaster-recovery.md" },
+          { "Network configuration" = "paas/kaas/user-guides/network-configuration.md" },
+        ]},
       ]}
     ]},
     { "Multi-tenancy" = [
@@ -182,6 +187,10 @@ authors_profiles = true
 
 [project.plugins.redirects.redirect_maps]
 "index.md" = "home.md"
+"paas/kaas/basic-operations.md" = "paas/kaas/user-guides/basic-operations.md"
+"paas/kaas/advanced-configuration.md" = "paas/kaas/user-guides/advanced-configuration.md"
+"paas/kaas/disaster-recovery.md" = "paas/kaas/user-guides/disaster-recovery.md"
+"paas/kaas/network-configuration.md" = "paas/kaas/user-guides/network-configuration.md"
 
 # SEO and meta tags
 [[project.extra.meta]]