diff --git a/docs/developers/platformprovider/03-develop.mdx b/docs/developers/platformprovider/03-develop.mdx deleted file mode 100644 index 8d8012dd..00000000 --- a/docs/developers/platformprovider/03-develop.mdx +++ /dev/null @@ -1,16 +0,0 @@ ---- -sidebar_position: 3 -id: develop ---- - -# Develop - -:::info Coming Soon -A comprehensive guide for developing Platform Providers from scratch is coming soon. -::: - -Platform Providers deliver complete platform capabilities and services within the OpenControlPlane ecosystem. They follow the same general patterns as Service Providers and Cluster Providers. - -For now, you can: -- Refer to the [Deploy Guide](./01-deployment.mdx) for the common deployment contract -- Check the [Service Provider Develop Guide](../serviceprovider/02-develop.mdx) for general patterns that apply to all provider types diff --git a/docs/developers/platformprovider/04-examples.mdx b/docs/developers/platformprovider/04-examples.mdx deleted file mode 100644 index af2c5969..00000000 --- a/docs/developers/platformprovider/04-examples.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -sidebar_position: 4 -id: examples ---- - -# Examples - -:::info Coming Soon -Platform Provider examples and templates are coming soon. -::: - -Platform Providers deliver complete platform capabilities within OpenControlPlane. Stay tuned for official examples and reference implementations. diff --git a/docs/developers/platformprovider/05-design.mdx b/docs/developers/platformprovider/05-design.mdx deleted file mode 100644 index 819a6b14..00000000 --- a/docs/developers/platformprovider/05-design.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -sidebar_position: 5 -id: design ---- - -# Design - -:::info Coming Soon -Detailed design documentation for Platform Providers is coming soon. -::: - -Platform Providers deliver complete platform capabilities within the OpenControlPlane ecosystem. They follow similar architectural patterns to Service Providers and Cluster Providers. - -For reference, you can review the [Service Provider Design Documentation](../serviceprovider/01-design.mdx) which outlines concepts that apply to all provider types in the OpenControlPlane ecosystem. diff --git a/docs/developers/platformprovider/_category_.json b/docs/developers/platformprovider/_category_.json deleted file mode 100644 index f66f842c..00000000 --- a/docs/developers/platformprovider/_category_.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "label": "Platform Providers", - "position": 4 -} diff --git a/docs/developers/platformservice/01-design.mdx b/docs/developers/platformservice/01-design.mdx new file mode 100644 index 00000000..01a3ceb1 --- /dev/null +++ b/docs/developers/platformservice/01-design.mdx @@ -0,0 +1,103 @@ +--- +sidebar_position: 1 +id: design +--- + +# Design + +This document defines the terminology for Platform Services within the OpenControlPlane project and clarifies their scope, responsibilities and boundaries. In particular, it distinguishes Platform Services and Service Providers. + +## Domain + +Platform services deliver platform capabilities within the OpenControlPlane ecosystem. They follow similar architectural patterns to [Service Providers](../serviceprovider/01-design.mdx) and [Cluster Providers](../clusterprovider/04-design.mdx). + +When mapped to a layered architecture using the personas of **Platform Owner**, **Service Provider** and **User**, Platform Services operate in the **Platform Owner** layer. Together with [Cluster Providers](../clusterprovider/04-design.mdx) they build the foundation of OpenControlPlane: + +| Persona | OpenControlPlane Concept | Responsibility | +| :------ | :--------------- | :------------------- | +| Platform Owner | Platform Service and [Cluster Provider](../clusterprovider/04-design.mdx) | Provide platform capabilities consumed by the layers below | +| Service Provider | [Service Providers](../serviceprovider/01-design.mdx) | Provide managed services consumed by the layer below | +| User | Not an OpenControlPlane concept but a human end user | Generate value from the services provided by Platform Owners and Service Providers | + +Some Platform Services are required to operate OpenControlPlane, such as those included in the [openmcp-operator](https://github.com/openmcp-project/openmcp-operator). Others are optional and extend the platform's capabilities to support specific use cases. + +:::info +For more details on platform personas, see [Why Kubernetes Is Inappropriate for Platforms, and How to Make It Better](https://www.youtube.com/watch?v=7op_r9R0fCo). +::: + +### API + +A Platform Service defines one or more `APIs` that consumers use to interact with its functionality. + +```mermaid +graph LR + CON[Consumer] + API[API] + CON -->|manages instances|API +``` + +A consumer may be a human or another system. + +:::info +A Platform Service may introduce a user-facing `API` but is not required to do so. Most Platform Services operate without exposing user-facing APIs and provide their capabilities internally to the Platform Owner and Service Provider layers (see [Domain](#domain) and [Service Provider Comparison](#comparison-to-service-providers)). +::: + +### Config + +A Platform Service defines a `Config` resource that contains service-specific settings. This allows platform owners to configure the service for different deployment scenarios and to enable or disable features. + +```mermaid +graph LR + %% Platform Owner + OP[Platform Owner] + PS[PlatformService] + PSC[Config] + OP -->|manages instances|PS + OP -->|manages instances|PSC +``` + +### Deployment Model + +A Platform Service runs on the platform cluster and reconciles its platform cluster `API` and/or onboarding cluster `EndUserAPI`. It creates and manages resources on the platform cluster. + +```mermaid +graph TD + %% Onboarding Cluster + subgraph OnboardingCluster + USRAPI[EndUserAPI] + end + + %% Platform Cluster + subgraph PlatformCluster + OP[openmcp-operator] + PS[PlatformService] + PSC[Config] + API[API] + end + + %% edges + PS -->|reconciles|API + PS -->|reconciles|USRAPI + PS -->|uses|PSC + OP-->|reconciles|PS +``` + +For more details on cluster types, see [Clusters and Namespaces](../clusters-and-namespaces.md). + +## Comparison to Service Providers + +The following table distinguishes Platform Services and Service Providers based on where they introduce new APIs. + +| Cluster | Platform Service | Service Provider | +| :------ | :--------------- | :--------------- | +| Platform cluster | ✳️ | ❌ | +| Onboarding cluster | ✳️ | ✅ | +| Control Plane | ❌ | ✅ | + +✅ MUST introduce API on that cluster type. +✳️ MAY introduce API on that cluster type. +❌ MUST NOT introduce API on that cluster type. + +:::info +Note that the Service Provider [Config](../serviceprovider/01-design.mdx#config) is not considered a service. +::: \ No newline at end of file diff --git a/docs/developers/platformservice/02-develop.mdx b/docs/developers/platformservice/02-develop.mdx new file mode 100644 index 00000000..1a4b50c5 --- /dev/null +++ b/docs/developers/platformservice/02-develop.mdx @@ -0,0 +1,16 @@ +--- +sidebar_position: 2 +id: develop +--- + +# Develop + +:::info Coming Soon +A comprehensive guide for developing Platform Services from scratch is coming soon. +::: + +Platform Services deliver complete platform capabilities and services within the OpenControlPlane ecosystem. They follow the same general patterns as Service Providers and Cluster Providers. + +For now, you can: +- Refer to the [Deploy Guide](./03-deployment.mdx) for the common deployment contract +- Check the [Service Provider Develop Guide](../serviceprovider/02-develop.mdx) for general patterns that apply to all provider types diff --git a/docs/developers/platformprovider/01-deployment.mdx b/docs/developers/platformservice/03-deployment.mdx similarity index 55% rename from docs/developers/platformprovider/01-deployment.mdx rename to docs/developers/platformservice/03-deployment.mdx index b30757ea..b9441cb0 100644 --- a/docs/developers/platformprovider/01-deployment.mdx +++ b/docs/developers/platformservice/03-deployment.mdx @@ -1,12 +1,12 @@ --- -sidebar_position: 1 +sidebar_position: 3 id: deploy --- # Deploy :::info Coming Soon -Documentation for deploying Platform Providers is coming soon. Platform Providers follow the same deployment contract as Service Providers and Cluster Providers. +Documentation for deploying Platform Services is coming soon. Platform Services follow the same deployment contract as Service Providers and Cluster Providers. ::: For now, please refer to the [Service Provider Deploy Guide](../serviceprovider/05-deployment.mdx) for the common deployment contract that applies to all provider types. diff --git a/docs/developers/platformservice/04-examples.mdx b/docs/developers/platformservice/04-examples.mdx new file mode 100644 index 00000000..b879f3a4 --- /dev/null +++ b/docs/developers/platformservice/04-examples.mdx @@ -0,0 +1,12 @@ +--- +sidebar_position: 4 +id: examples +--- + +# Examples + +:::info Coming Soon +Platform Services examples and templates are coming soon. +::: + +Platform Services deliver complete platform capabilities within OpenControlPlane. Stay tuned for official examples and reference implementations. diff --git a/docs/developers/platformservice/_category_.json b/docs/developers/platformservice/_category_.json new file mode 100644 index 00000000..89e687cc --- /dev/null +++ b/docs/developers/platformservice/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Platform Services", + "position": 4 +} diff --git a/docs/developers/serviceprovider/04-testing.mdx b/docs/developers/serviceprovider/04-testing.mdx index c690ccf1..fd36c51e 100644 --- a/docs/developers/serviceprovider/04-testing.mdx +++ b/docs/developers/serviceprovider/04-testing.mdx @@ -12,7 +12,7 @@ id: testing ```mermaid flowchart LR subgraph kind["Platform cluster (created by the framework)"] - P["openmcp-operator,
cluster/service/platform providers"] + P["openmcp-operator,
platform services,
cluster/service providers"] end P -->|"creates (via operator)"| O["Onboarding cluster
(consumer applies CRs here)"] P -->|"creates per tenant (via operator)"| M["ControlPlane cluster
(per-tenant control plane)"]