Merge pull request #125 from vshn/add/sli-control-plane-splitting

Add docs about SLI Prober with split control plane

docs/modules/ROOT/pages/reference/control-plane-architecture.adoc → docs/modules/ROOT/pages/reference/control-plane-pitfalls.adoc

@@ -1,4 +1,4 @@
-= Separate Control Plane from Service Clusters
+= Pitfalls
 
 This page shows the pitfalls and gotchas that we need to keep in mind if we develop for a split architecture.
 

docs/modules/ROOT/pages/reference/sli-prober-architecture.adoc

@@ -0,0 +1,36 @@
+= SLI Prober
+
+The SLI-Prober connects to each instance and will report on its SLI.
+For that it needs to reconcile the composites of each instance, to get the connection details.
+This way we ensure that the prober probes exactly what the customer gets.
+
+To avoid issues with potentially checking thousands of instances with a single prober, we deploy the prober to each service cluster.
+
+In order for the prober to work correctly it needs to reconcile two types of resources:
+
+* The composites
+* `UpgradeJobs`
+
+The composites are reconciled to detect all the actual instances and their connection details.
+They are matched against the local service cluster and if the instnace namespace exists, then it will start to probe the given instance.
+`UpgradeJobs` on the other hand will track the state of maintenance on the service cluster where the prober and thus the instances run.
+
+By default, it assumes that it's running in converged mode
+To enable the split configuration a `KUBECONFIG` environment variable has to be set on the prober pod.
+With that all reconcilers that check the composites will connect to that cluster.
+An exception is the reconciler for the `UpgradeJobs` it will connect to the local cluster in either way.
+It's possible to override the kubeconfig for the `UpgradeJob` reconciler for debug purposes.
+
+[mermaid,diagram,png]
+....
+architecture-beta
+    group cp(cloud)[Control Plane]
+    group sc(cloud)[Service Cluster]
+
+    service sli(server)[SLI Prober] in sc
+    service cr(disk)[Composites] in cp
+    service uj(disk)[UpgradeJobs] in sc
+
+    sli:B --> T:cr
+    sli:L --> R:uj
+....

docs/modules/ROOT/partials/nav.adoc

@@ -11,7 +11,9 @@
 ** xref:app-catalog:ROOT:reference/service-maturity.adoc[]
 ** xref:app-catalog:ROOT:reference/framework-requirements.adoc[]
 ** xref:app-catalog:ROOT:reference/slareports.adoc[]
-** xref:app-catalog:ROOT:reference/control-plane-architecture.adoc[]
+** Separate Control Plane from Service Clusters
+*** xref:app-catalog:ROOT:reference/control-plane-pitfalls.adoc[]
+*** xref:app-catalog:ROOT:reference/sli-prober-architecture.adoc[]
 ** xref:app-catalog:ROOT:reference/ci-cd.adoc[]
 ** xref:app-catalog:ROOT:reference/quality-requirements.adoc[Quality Requirements]
 *** xref:app-catalog:ROOT:reference/quality-requirements/maintainability/readiness-standards.adoc[Maintainability]