docs: add ADR for autonomous platform clusters

adrs/2026-04-29-autonomous-clusters.md

@@ -0,0 +1,236 @@
+---
+authors:
+  - ValentinGerlach # Change to your own handle. Add yourself to "authors.yml" if necessary.
+  - MoritzMarby
+---
+
+# Autonomous Platform Clusters
+
+The goal of this ADR is to streamline and simplify the bootstrapping and lifecycle management of the OpenControlPlane platform for platform operators and contributors.
+
+## Current state
+
+To bootstrap the platform
+
+- #bootstrapper
+  - templated yaml files similar to helm (#gitops-templates)
+- requirements like
+  - git
+  - flux
+
+### Problems
+
+- not humanly readable and maintanable gitops repositories
+  - templated and generated by bootstrapper
+  - source of truth are large single-file configuration yamls
+- hard to maintain
+- not scalable when operating multiple landscapes
+- difficult local setup
+  - caused the creation of different local setup bootstrapping scripts (see #ocptl #kind-cluster-provider)
+- operation responsibility currently is split up between cluster and git repository
+  - bootstrapper (templating logic before lifecycle management is taking over)
+  - flux (managing lifecycle of base operators and infrastructure)
+  - openmcp operators (managing lifecycle of service providers and platform services, cluster providers)
+- a lot of configuration needed for simple setup
+  - preventing easy local setup
+  - demo landscapes
+  - not applicable and maintainable for small/medium businesses
+  - too much things are required to be configured and installed
+- deployment description / configuration is currently decoupled from the release artifacts
+  - results in operation guides needed to be provided beside the normal artifact shipment
+
+## Desired state
+
+- configuration and landscape description in done in-cluster and stored in-cluster
+  - cluster can be **autonomous** even air-gapped and when there is network disruptions
+  - platform can detect drifts in configuration and repair itself
+- in-cluster configuration should be agnostic towards configuration sources
+  - flux should not be a requirement, just one option to bring configuration into cluster
+- easy to understand / proper default configuration
+  - should not be too implicit, more declarative
+- deployment description / configurtion should be shipped inside and with the release artifacts
+  - e.g. OpenControlPlane vX.X.X should contain the deployment configuration and technical install instructions for the autonomous cluster to understand and use.
+- scalability when operating multiple OpenControlPlane platforms in different environments/landscapes should be given and not a hassle which demands a whole team of engineers
+- reporting of configuration status should be clear and technical usable
+  - the OpenControlPlane platform should have a way to communicate overall platform health
+  - report of individual component status
+- local setup should be similar / identical to production setup
+
+## Solution Proposal
+
+platform cluster has a configuration Resource:
+
+```yaml
+apiVersion: delivery.ocm.software/v1alpha1
+kind: Component
+metadata:
+  name: open-control-plane
+spec:
+  repositoryRef:
+    name: default
+  component: github.com/openmcp-project/openmcp
+  semver: 1.0.0
+  interval: 1m
+---
+apiVersion: configuration.open-control-plane.io
+kind: PlatformConfiguration
+metadata:
+  name: default
+spec:
+  environmentName: dev
+  componentRef:
+    name: open-control-plane
+    namespace: open-control-plane-system
+---
+apiVersion: configuration.open-control-plane.io
+kind: DNSConfiguration
+metadata:
+  name: default
+spec:
+  baseDomain: dev.open-control-plane.io
+---
+apiVersion: configuration.open-control-plane.io
+kind: ClusterProviderConfiguration
+metadata:
+  name: default
+spec:
+  component: github.com/openmcp-project/cluster-provider-gardener
+  configuration:
+    component: company.io/xxx/gardener-cluster-configuration
+    resource: dev-landscape # must be a RGD resource
+    config:
+      gardenerProject:
+      credentialsBindingName:
+      ...
+```
+
+```yaml
+apiVersion: kro.run/v1alpha1
+kind: ResourceGraphDefinition
+metadata:
+  name: gardener-cluster-dev-landscape
+spec:
+  schema:
+    apiVersion: v1alpha1
+    # The name of the CRD that is created by this ResourceGraphDefinition when applied
+    kind: Simple
+    spec:
+      mcpProject:
+      mcpsProject:
+      mcpCredentialsBindingName:
+      ...
+  resources:
+    - id: landscape1
+      apiVersion: gardener.clusters.openmcp.cloud/v1alpha1
+      kind: Landscape
+      metadata:
+        name: gardener-landscape-mcp
+      spec:
+        access:
+          secretRef:
+            name: gardener-landscape-mcp-kubeconfig
+            namespace: openmcp-system
+    - id:
+      apiVersion: gardener.clusters.openmcp.cloud/v1alpha1
+      kind: ProviderConfig
+      metadata:
+        name: mcp-shoot-large-ha
+        labels:
+          deployment.openmcp.cloud/shoot-type: workers
+          deployment.openmcp.cloud/shoot-size: large
+          deployment.openmcp.cloud/gardener-project-type: mcp
+      spec:
+        landscapeRef:
+          name: gardener-landscape-mcp
+        project: "<project-placeholder>"
+        providerRef:
+          name: gardener
+        shootTemplate:
+          ...
+    - id:
+      apiVersion: gardener.clusters.openmcp.cloud/v1alpha1
+      kind: ProviderConfig
+      metadata:
+        name: mcp-shoot-large
+        labels:
+          deployment.openmcp.cloud/shoot-type: workers
+          deployment.openmcp.cloud/shoot-size: large
+          deployment.openmcp.cloud/gardener-project-type: mcp
+      spec:
+        landscapeRef:
+          name: gardener-landscape-mcp
+        project: <project-placeholder>
+        providerRef:
+          name: gardener
+        shootTemplate:
+          ...
+```
+
+OCM based deployment way:
+
+![RGD based shipment](./rgd_based_autonomous_clusters.excalidraw.svg)
+
+```yaml
+apiVersion: delivery.ocm.software/v1alpha1
+kind: Component
+metadata:
+  name: open-control-plane
+spec:
+  repositoryRef:
+    name: default
+  component: github.com/openmcp-project/openmcp
+  semver: 1.0.0
+  interval: 1m
+---
+apiVersion: delivery.ocm.software/v1alpha1
+kind: Component
+metadata:
+  name: cluster-provider-gardener
+spec:
+  repositoryRef:
+    name: default
+  component: github.com/openmcp-project/openmcp
+  semver: 1.0.0
+  interval: 1m
+---
+apiVersion: delivery.ocm.software/v1alpha1
+kind: Resource
+metadata:
+  name: cluster-provider-gardener-rgd
+spec:
+  componentRef:
+    name: cluster-provider-gardener
+  resource:
+    byReference:
+      resource: rgd
+---
+apiVersion: delivery.ocm.software/v1alpha1
+kind: Deployer
+metadata:
+  name: cluster-provider-gardener
+spec:
+  resourceRef: cluster-provider-gardener-rgd
+---
+apiVersion: kro.run/v1alpha1
+kind: ResourceGraphDefinition
+metadata:
+  name: cluster-provider-gardener
+spec:
+  schema:
+    apiVersion: v1alpha1
+    # The name of the CRD that is created by this ResourceGraphDefinition when applied
+    kind: ClusterProviderGardener
+    spec:
+      # This spec defines values that can be referenced in the ResourceGraphDefinition and that can be set in the
+      # instances of this ResourceGraphDefinition.
+      # We will use it to pass a value to the Helm chart and configure the message the application shows
+      # (see resource HelmRelease).
+      message: string | default="foo"
+  resources: ...
+---
+apiVersion: kro.run/v1alpha1
+kind: ClusterProviderGardener
+metadata:
+  name: default
+spec:
+```

adrs/2026-04-29-immutable-infrastructure.md

@@ -0,0 +1,9 @@
+---
+authors:
+  - ValentinGerlach # Change to your own handle. Add yourself to "authors.yml" if necessary.
+  - MoritzMarby
+---
+
+# Immutable Infrastructure
+
+- horizontal scaling of workload clusters add additional complexity

adrs/authors.yml

@@ -5,6 +5,13 @@ ValentinGerlach:
   image_url: /img/authors/ValentinGerlach.png
   socials:
     github: ValentinGerlach
+MoritzMarby:
+  name: Moritz Marby
+  title: openMCP Contributor
+  url: https://github.com/n3rdc4ptn
+  image_url: /img/authors/MoritzMarby.png
+  socials:
+    github: n3rdc4ptn
 ReneSchuenemann:
   name: Rene Schünemann
   title: openMCP Contributor