Release 2.0.13

Co-authored-by: Maximilian Lenkeit <maximilian.lenkeit@sap.com>

Author: apeirora-service-user[bot]

.vitepress/config.mts

@@ -20,7 +20,11 @@ export default withMermaid(defineConfig({
   description: "Apeiro Reference Architecture - Documentation",
   base: BASE,
   srcDir: '.',
-  srcExclude: ['./node_modules/**/*'],
+  srcExclude: [
+    './node_modules/**/*',
+    'README.md',
+    'RELEASE.md'
+  ],
   // assetsDir: './static',
   cleanUrls: true,
   appearance: false, // disable dark mode
@@ -133,5 +137,5 @@ export default withMermaid(defineConfig({
       }
     ]
   },
-  ignoreDeadLinks: true // TODO: set to false
+  ignoreDeadLinks: false
 }))

blog/2025-03-05-lcm-configuration-installation-reconsidered.md

@@ -5,7 +5,7 @@ authors:
   - uwe-krueger
 ---
 
-<!-- index.mdx -->
+<!-- index.md -->
 Software configuration and procedures, practices, and tools for (first time) installation, patching, or updating are at the heart of software lifecycle management.
 
 Generally, lifecycle management
@@ -28,7 +28,7 @@ While complex initial installations may be covered by the approach, we conclude
 
 <!-- truncate -->
 
-<!-- challenge.mdx -->
+<!-- challenge.md -->
 ## The Challenge, Day 0, 1, and 2
 
 Lifecycle management involves distinct phases - Day 0, Day 1, and Day 2. Each presenting unique challenges:
@@ -48,7 +48,7 @@ The term *installation* will be used in the following as a synonym for both *set
 
 [^1]: Popular data migration tools for example are [Wikipedia: Flyway](https://en.wikipedia.org/wiki/Flyway_(software)), [Wikipedia: Liquibase](https://en.wikipedia.org/wiki/Liquibase), and programming languages offer libraries, such as [github: go-migrate](https://github.com/golang-migrate/migrate).
 
-<!-- layout.mdx -->
+<!-- layout.md -->
 ## General Installation Layout
 
 In consequence, all approaches follow the same general layout:
@@ -68,7 +68,7 @@ Let us next consider the configuration description.
 
 
 
-<!-- configurations.mdx -->
+<!-- configurations.md -->
 ## Configurations Reconsidered
 
 In the simplest case, configuration is described by some general, possibly structured, data definition format, like [YAML](https://yaml.org), [JSON](https://www.json.org), [XML](https://www.w3.org/TR/xml) or [INI](https://docs.fileformat.com/system/ini). The installation code looks for dedicated fields in the configuration to assign a particular meaning. This could be single parameters or complete structures.
@@ -86,7 +86,7 @@ Values of particular attributes should either follow some rules (or constraints)
 
 Let us therefore consider templating engines next.
 
-<!-- templating.mdx -->
+<!-- templating.md -->
 ## Templating Engines
 
 
@@ -142,7 +142,7 @@ An often-cited example for integrated configuration DSL allowing for feedback fr
 
 With this last scenario we leave the pure configuration description. Let us consider and take a closer look at the installation procedure itself next.
 
-<!-- installations.mdx -->
+<!-- installations.md -->
 ## Installations Reconsidered
 
 The installer coding is responsible to map a configuration (utilizing a DSL) to an appropriate set of elements in the target environment and execute the concrete installation.
@@ -234,7 +234,7 @@ All approaches to circumvent those problems are typically
 
 In summary, while Day 1 installation can be handled with multi-purpose, generic frameworks, Day 2 updates with structural changes, even requiring migrations, can't be handled by typical generic frameworks. All approaches to fix updates within generic frameworks become very complicated, confusing and error-prone.
 
-<!-- target.mdx -->
+<!-- target.md -->
 ## Target Environment Reconsidered
 
 A new quality can be achieved with the configuration (the DSL-based composition) not treated as static input to the complete installation procedure. A first step towards this direction is to refer to information from the target environment by using special (static) expressions in the configuration description. The next iteration is to incorporate feedback loops that are generalized for all element configuration descriptions.
@@ -252,7 +252,7 @@ This feature is tightly coupled with the decomposition of the overall installer
 increase the expressive power of the overall system as well as the abstraction available for the installer implementation. It can asynchronously decompose into other configuration elements and
 combine this with its own synchronization and ordering logic.
 
-<!-- gitops.mdx -->
+<!-- gitops.md -->
 ## GitOps Operational Model
 
 A popular practice to handle installations is [*GitOps*](https://opengitops.dev/) with *Kubernetes* as runtime. Whereas, *GitOps* is not necessarily part of the technical installation procedure itself but only augments it with a [DevOps](https://en.wikipedia.org/wiki/DevOps) operational model. Its task is to handle the synchronization process of bringing together static configurations stored in (versioned) repositories (of course Git, but also OCI) with the execution of the installation.
@@ -294,7 +294,7 @@ GitOps Principles v1.0.0 [^5]
 [^5]: GitOps principles according to [opengitops.dev/#principles](https://opengitops.dev/#principles)
 
 
-<!-- conclusion.mdx -->
+<!-- conclusion.md -->
 ## Conclusion
 
 First of all, we see that DSLs are present everywhere, where configuration is interpreted. Even with simple data formats it is possible to express rules, commonalities and derived values. The expressive power comes from the evaluation logic as part of the installation code. Explicit specialized DSL can be seen as syntactical sugar to improve the readability.

blog/2025-03-25-kcp-multi-tenant-control-planes.md

@@ -81,16 +81,16 @@ The paradigm shift is clear: **move from managing fleets of clusters to managing
 
 [^5]: [Horizontally Scalable Control Plane for Kubernetes APIs - kcp.io](https://kcp.io/#:~:text=Building%20Block%2C%20Not%20Walled%20Garden)
 
-[^6]: [Multi-Plane Controller](https://documentation.apeirora.eu/control-planes/crt) and [Baremetal Operating System (BOS)](https://apeirora.eu/content/about/#:~:text=infrastructure%20to%20independently%20operate%20compute%2C,for%20non) in ApeiroRA
+[^6]: [Multi-Plane Controller](./../docs/best-practices/control-planes/crt.md) and [Baremetal Operating System (BOS)](https://apeirora.eu/content/about/#:~:text=infrastructure%20to%20independently%20operate%20compute%2C,for%20non) in ApeiroRA
 
-[^7]: [How to apply Apeiro-Reference-Architecture?](https://apeirora.eu/content/about/#:~:text=The%20%E2%80%9Creference%E2%80%9D%20in%20ApeiroRA%20and,are%20truly%20general) and [Documentation](https://documentation.apeirora.eu/) of ApeiroRA
+[^7]: [How to apply Apeiro-Reference-Architecture?](https://apeirora.eu/content/about/#:~:text=The%20%E2%80%9Creference%E2%80%9D%20in%20ApeiroRA%20and,are%20truly%20general) and [Documentation](/) of ApeiroRA
 
-[^8]: [How to apply Apeiro-Reference-Architecture?](https://apeirora.eu/content/about/#:~:text=compatible%20underlays%20at%20every%20participating,of%20uniformity%20required%20for%20the) and [Kubernetes Implementation Design](https://documentation.apeirora.eu/control-planes/kid) in ApeiroRA
+[^8]: [How to apply Apeiro-Reference-Architecture?](https://apeirora.eu/content/about/#:~:text=compatible%20underlays%20at%20every%20participating,of%20uniformity%20required%20for%20the) and [Kubernetes Implementation Design](./../docs/best-practices//control-planes/kid.md) in ApeiroRA
 
 [^9]: [Building Europe's Platform Mesh: Cloud-Native APIs for Multi-Provider Integration and Digital Sovereignty](https://fosdem.org/2025/schedule/event/fosdem-2025-5746-building-europe-s-platform-mesh-cloud-native-apis-for-multi-provider-integration-and-digital-sovereignty/) at FOSDEM 2025
 
 [^10]: [How Standards Proliferate](https://xkcd.com/927/) (xkcd comic)
 
-[^11]: [Digital Twins | Apeiro Reference Architecture - Documentation](https://documentation.apeirora.eu/digital-twins)
+[^11]: [Digital Twins | Apeiro Reference Architecture - Documentation](./../docs/best-practices/digital-twins/index.md)
 
-[^12]: [ApeiroRA Platform Mesh | Apeiro Reference Architecture - Documentation](https://documentation.apeirora.eu/platform-mesh)
+[^12]: [ApeiroRA Platform Mesh | Apeiro Reference Architecture - Documentation](./../docs/best-practices//platform-mesh/index.md)

docs/architecture/index.md

@@ -19,11 +19,11 @@ Apeiro conceptually pursues a _declarative approach_ across its components, just
 
 ## Layers Top to Bottom
 
-- **[Platform Mesh](./../best-practices/platform-mesh/index.mdx)** is a core component of Apeiro that allows service providers to offer services of any kind and service consumers to discover those services, order capabilities, and control their lifecycle.
+- **[Platform Mesh](./../best-practices/platform-mesh/index.md)** is a core component of Apeiro that allows service providers to offer services of any kind and service consumers to discover those services, order capabilities, and control their lifecycle.
 
     Other layers of Apeiro usually act as both service provider and service consumers: they provide their functionality as capability and consume capabilities of other layers through the Platform Mesh. The Platform Mesh also acts as a single point of contact for integrating non-Apeiro services (not depicted) and making them available via the same cloud-native mechanisms.
 
-- **[Data Fabric](./../best-practices/data-fabric/index.mdx)** provides standards and tooling for decentralized self-describing of application resources leading to a mesh architecture.
+- **[Data Fabric](./../best-practices/data-fabric/index.md)** provides standards and tooling for decentralized self-describing of application resources leading to a mesh architecture.
 
 - **Konfidence** is the software development and release framework of Apeiro for microservice-based SaaS applications. It comes with support for ring deployments, feature toggle management and a delivery process, all based on best practices from the CNCF landscape[^cncf-landscape].
 
@@ -46,13 +46,13 @@ Apeiro conceptually pursues a _declarative approach_ across its components, just
 
 ## Cross Cutting Concerns
 
-- **[Lifecycle Tooling](./../best-practices/lcm/index.mdx)** based on cloud native principles is considered essential by Apeiro in order to managing software lifecycle at scale.
+- **[Lifecycle Tooling](./../best-practices/lcm/index.md)** based on cloud native principles is considered essential by Apeiro in order to managing software lifecycle at scale.
 
-- **[Security & Compliance](./../best-practices/security/index.mdx)** are built into Apeiro across the different layers.
+- **[Security & Compliance](./../best-practices/security/index.md)** are built into Apeiro across the different layers.
 
 - **Zero-Trust** is a security paradigm in Apeiro to improve the overall security posture.
 
-- **[Observability](./../best-practices/observability/index.mdx)** is available in Apeiro through its layers.
+- **[Observability](./../best-practices/observability/index.md)** is available in Apeiro through its layers.
 
 [^cncf-landscape]: CNCF Cloud Native Landscape, see https://landscape.cncf.io
-[^kubeception]: see [Hosted Control Planes](./../best-practices/multi-cluster-federation/hosted-control-planes.mdx)
+[^kubeception]: see [Hosted Control Planes](./../best-practices/multi-cluster-federation/hosted-control-planes.md)

docs/best-practices/control-planes/crt.md

@@ -3,17 +3,17 @@ sidebar_position: 3
 title: Multi-Plane Controller
 ---
 
-In the [Controller Pattern section](./../digital-twins/controller.mdx), we discussed the general responsibilities of a <Term>controller</Term> and in the [Kubernetes Implementation Design section](./kid.mdx), we seem to
+In the [Controller Pattern section](./../digital-twins/controller.md), we discussed the general responsibilities of a <Term>controller</Term> and in the [Kubernetes Implementation Design section](./kid.md), we seem to
 assume that the context for a controller always has to be a single Kubernetes cluster (assembled with the three planes).
 However, a reconciling controller can be executed anywhere suitable and be implemented to be multi-plane aware - or more precisely multi-control-plane aware.
 This becomes self-explanatory during the development of a controller. Typically, development occurs on a laptop, where the controller is run outside the cluster
 (the laptop serving as work plane) and debugged against different clusters (for example, connected to a local cluster on the laptop first, then a cluster in the cloud).
 
 By designing a multi-plane aware controller, we achieve two primary objectives:
 1. establish the necessary isolation boundaries required by cloud services
-2. enable the design for [Multi-Cluster Federation](./../multi-cluster-federation/index.mdx)
+2. enable the design for [Multi-Cluster Federation](./../multi-cluster-federation/index.md)
 
-For clarity throughout this document, the term "<Term>control plane</Term>" refers to any platform[^4] capable of serving [Kubernetes Resource Model](./../digital-twins/krm/index.mdx) (KRM) APIs.
+For clarity throughout this document, the term "<Term>control plane</Term>" refers to any platform[^4] capable of serving [Kubernetes Resource Model](./../digital-twins/krm/index.md) (KRM) APIs.
 
 ## Multi-Plane Architecture Components
 
@@ -27,7 +27,7 @@ For clarity throughout this document, the term "<Term>control plane</Term>" refe
    Business users interact and declare their intent with a dedicated API hosted on a separate <Term>data plane</Term>. This plane serves as the source of truth (for the external business contract), hosting the digital twins and their respective desired states. This layer is _intentionally separated_ from the data and control plane of the Runtime Cluster. This design enforces a critical isolation boundary by decoupling the user-facing API from internal implementation concerns. Note that this layer may be composed of multiple <Term>data planes</Term>.
 
 3. **Multiple Targets**:
-   The multi-plane controller model encourages the use of separate Kubernetes clusters (or control planes) as scale-out targets for workloads. It accomplishes this by utilizing available resource primitives (see [Multi-Cluster Federation](./../multi-cluster-federation/index.mdx) for a detailed discussion) or by orchestrating the desired outcome on any API-enabled platform[^1]. This practice isolates the controller's runtime concerns from the workload's concerns, thereby enhancing the overall security posture. In the case of simpler [clusterlet](./../multi-cluster-federation#federation-with-agents-decentralizing-control) or [servicelet](./../multi-cluster-federation/multi-cloud-service-provider.mdx) controllers, the Runtime Cluster may pragmatically be used as the work plane.
+   The multi-plane controller model encourages the use of separate Kubernetes clusters (or control planes) as scale-out targets for workloads. It accomplishes this by utilizing available resource primitives (see [Multi-Cluster Federation](./../multi-cluster-federation/index.md) for a detailed discussion) or by orchestrating the desired outcome on any API-enabled platform[^1]. This practice isolates the controller's runtime concerns from the workload's concerns, thereby enhancing the overall security posture. In the case of simpler [clusterlet](./../multi-cluster-federation/index.md#federation-with-agents-decentralizing-control) or [servicelet](./../multi-cluster-federation/multi-cloud-service-provider.md) controllers, the Runtime Cluster may pragmatically be used as the work plane.
 
 <ApeiroFigure src="/control-planes/img/crt2.svg"
     alt="Multi-plane aware controller"
@@ -92,8 +92,8 @@ These Fan-In and Fan-Out patterns can be implemented within a single controller.
 - **Scalability**: Leverage `multicluster-runtime` for dynamic cluster/multi-plane handling. It allows more efficient scaling and management of multiple clusters by reusing internal components like clients, queues and caches.
 - **Isolation**: Maintain clear separation between data plane (source for contract), Runtime Cluster (for the multi-plane aware controller), and target clusters (for the workloads), to ensure security and operational integrity. Only open or cross these boundaries when needed.
 - **Dynamic Discovery**: Use `MultiCluster`[`Manager`](https://github.com/kubernetes-sigs/multicluster-runtime/blob/main/pkg/manager/manager.go) to dynamically discover and manage clusters/control planes. Allow controllers to dynamically adapt to changing environments without manual intervention.
-- **Consistency**: Use level-based reconciliation for accurate state management. Make sure that you always set appropriate conditions and states to manage state transitions. Use consistent states across resources. Consistency is established by adhering to the two important basics: 1) well designed [KRM Extension APIs](./../digital-twins/krm/index.mdx) and 2) properly coded [reconciliation loops](./../digital-twins/controller.mdx#edge-and-level-triggering)
-- **Error Handling**: Implement exponential backoff and retries for robust multi-plane interactions. When implementing any retriable error handling, always consider possible hot spots - same resources being retried without random delays and the ensuing [Thundering herd problem](https://en.wikipedia.org/wiki/Thundering_herd_problem). See further information in the [Controller Pattern](./../digital-twins/controller.mdx#proportional-integral-derivative) chapter.
+- **Consistency**: Use level-based reconciliation for accurate state management. Make sure that you always set appropriate conditions and states to manage state transitions. Use consistent states across resources. Consistency is established by adhering to the two important basics: 1) well designed [KRM Extension APIs](./../digital-twins/krm/index.md) and 2) properly coded [reconciliation loops](./../digital-twins/controller.md#edge-and-level-triggering)
+- **Error Handling**: Implement exponential backoff and retries for robust multi-plane interactions. When implementing any retriable error handling, always consider possible hot spots - same resources being retried without random delays and the ensuing [Thundering herd problem](https://en.wikipedia.org/wiki/Thundering_herd_problem). See further information in the [Controller Pattern](./../digital-twins/controller.md#proportional-integral-derivative) chapter.
 
 By using [multicluster-runtime](https://github.com/kubernetes-sigs/multicluster-runtime) with providers like [kcp](https://kcp.io) and [Gardener](https://gardener.cloud) for **Fan-In** and [`Cluster`](https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/cluster) for **Fan-Out**, both integrated with `MultiCluster`[`Manager`](https://github.com/kubernetes-sigs/multicluster-runtime/blob/main/pkg/manager/manager.go), developers can build scalable multi-plane aware controllers within the controller-runtime framework.
 

docs/best-practices/control-planes/kid.md

@@ -3,7 +3,7 @@ sidebar_position: 1
 title: Kubernetes Implementation Design
 ---
 
-Kubernetes is said to be composed of microservices which form the [aforementioned three planes](./index.mdx).
+Kubernetes is said to be composed of microservices which form the [aforementioned three planes](./index.md).
 But an important distinction needs to be made: microservices manage and encapsulate their state with their own API protocol, whereas Kubernetes fully defines a common API framework and manages the state for all its components in the <Term>data plane</Term>.
 
 There is ample external [documentation](https://kubernetes.io/docs/concepts/architecture/) available, which describes the architecture and detailed implementation of Kubernetes (primarily as container orchestrator).
@@ -34,7 +34,7 @@ width="100%"/>
 ### Components of the Control Plane
 
 If we conceptually attribute the API server to the <Term>data plane</Term>, then the <Term>control plane</Term> contains
-a) all needed **[API Extensions](./../digital-twins/extensibility.mdx)**.
+a) all needed **[API Extensions](./../digital-twins/extensibility.md)**.
 The Kubernetes core design pattern includes b) [**scheduler**](https://kubernetes.io/docs/concepts/architecture/#kube-scheduler), and
 c) [**controller manager**](https://kubernetes.io/docs/concepts/architecture/#kube-controller-manager) which bundles various Kubernetes internal controllers.
 Furthermore, a typical cluster minimally requires d) [**cloud controller manager**](https://kubernetes.io/docs/concepts/architecture/cloud-controller/) which bundles controllers necessary for dealing with resources from external cloud providers.