Skip to content

Commit 681ca60

Browse files
gman0ntnn
gman0
authored and
ntnn
committed
Document Provider bootstrap
Adds docs for concepts, how-to-guides and references. On-behalf-of: @SAP robert.vasek@sap.com Signed-off-by: Robert Vasek <rvasek01@gmail.com>
1 parent 0c4ece8 commit 681ca60

11 files changed

Lines changed: 438 additions & 4 deletions

File tree

‎concepts/index.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,9 +9,10 @@ Use this section when you want to understand why Platform Mesh exists, how its p
99
3. [Personas](./personas/) - the role guide for platform owners, service providers, and service consumers.
1010
4. [Account model](./account-model.md) - how organizations and accounts map to isolated control planes.
1111
5. [Control planes and workspaces](./control-planes.md) - how Platform Mesh uses kcp workspaces without duplicating the full kcp docs.
12-
6. [API sharing](./api-sharing.md) - how provider APIs become available in consumer workspaces.
13-
7. [Identity and authorization](./identity-and-authorization.md) - how identity, authorization data, and kcp enforcement relate.
14-
8. [Integration paths](./integration-paths.md) - when providers should use api-syncagent, multicluster-runtime, or related mechanisms.
15-
9. [Interaction patterns](./interaction-patterns/provider-to-consumer.md) - common provider-consumer, provider-provider, and cross-consumption flows.
12+
6. [Provider bootstrap](./provider-bootstrap.md) - how Platform Mesh provisions a dedicated workspace and kubeconfig for each service provider.
13+
7. [API sharing](./api-sharing.md) - how provider APIs become available in consumer workspaces.
14+
8. [Identity and authorization](./identity-and-authorization.md) - how identity, authorization data, and kcp enforcement relate.
15+
9. [Integration paths](./integration-paths.md) - when providers should use api-syncagent, multicluster-runtime, or related mechanisms.
16+
10. [Interaction patterns](./interaction-patterns/provider-to-consumer.md) - common provider-consumer, provider-provider, and cross-consumption flows.
1617

1718
For factual lookup, use [Reference](/reference/). For guided local setup, start with [Tutorials](/tutorials/).

‎concepts/provider-bootstrap.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Provider bootstrap
2+
3+
Platform Mesh provisions a dedicated kcp workspace for each service provider. Creating a `Provider` resource triggers that provisioning; the workspace becomes the provider's domain on the platform, holding their kcp resources (`APIExport`, `APIResourceSchema`) and Platform Mesh resources (`ContentConfiguration`, `ProviderMetadata`, and RBAC). When provisioning completes, Platform Mesh issues a scoped kubeconfig; the provider is then responsible for bootstrapping everything else.
4+
5+
`Provider` is the core primitive — any service provider can create one. `ManagedProvider` is a separate convenience layer for platform admins that builds on top of `Provider` to automate the full onboarding lifecycle for platform-owned services.
6+
7+
## The provider workspace
8+
9+
Each provider workspace lives under `root:providers` and is identified by the `Provider` name combined with a unique identifier for that particular `Provider` object. The identifier is stable for the lifetime of the resource and prevents name collisions across tenants or after deletion and recreation.
10+
11+
The workspace is the provider's exclusive domain. Platform Mesh creates it and issues credentials but does not manage the resources inside it.
12+
13+
## Provider
14+
15+
`Provider` is a kcp-level resource, reconciled by the Provider controller. Creating one provisions a dedicated workspace and a scoped admin kubeconfig for it. It has no effect on the runtime cluster — it operates entirely within kcp.
16+
17+
Once the workspace is ready, the provider is responsible for:
18+
19+
- Bootstrapping their workspace resources — for example, `APIExport`, `APIResourceSchema`, `ContentConfiguration`, `ProviderMetadata`, and RBAC.
20+
- Wiring the kubeconfig into their service controllers so those controllers can manage resources in the provider workspace.
21+
22+
With the workspace bootstrapped, service controllers use the kubeconfig to watch their `APIExport` virtual workspace and reconcile service consumers.
23+
24+
## ManagedProvider
25+
26+
`ManagedProvider` is a Platform Mesh runtime resource, reconciled by the platform-mesh controller. Platform admins use it as a convenience API to onboard platform-owned services: a single resource handles workspace provisioning, kubeconfig distribution, and operator deployment end-to-end.
27+
28+
On the kcp side, a `ManagedProvider` creates a `Provider` in `root:providers:system` and waits for it to be ready. On the runtime side, it copies the resulting kubeconfig into Platform Mesh's runtime cluster and deploys the service operator components.
29+
30+
The split between `Provider` and `ManagedProvider` reflects the split between kcp-level and runtime-level effects: a `Provider` can only affect kcp, while a `ManagedProvider` is owned and operated by the platform admin on Platform Mesh's runtime cluster.
31+
32+
By default, deleting a `ManagedProvider` removes the runtime deployments and the copied kubeconfig but leaves the kcp `Provider` and its workspace intact — giving platform admins room to handle service deprecation, migration, or handoff before committing to full removal. Alternatively, platform admins can opt into full cleanup, which also removes the `Provider` and cascades to the workspace.
33+
34+
## Related
35+
36+
- [Service provider persona](./personas/service-provider.md)
37+
- [Control planes and workspaces](./control-planes.md)
38+
- [API sharing](./api-sharing.md)
39+
- [Integration paths](./integration-paths.md)
40+
- [Platform Mesh operator](/reference/components/platform-mesh-operator.md)
41+
- [Provider resource](/reference/resources/provider-resource.md)
42+
- [ManagedProvider resource](/reference/resources/managed-provider-resource.md)

‎how-to-guides/bootstrap-provider.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
---
2+
title: Bootstrap a provider
3+
personas: [service-provider]
4+
---
5+
6+
# Bootstrap a provider
7+
8+
Use this how-to to provision a dedicated kcp workspace for your service by creating a `Provider` resource. The workspace is your provider's domain on the platform — once it is ready, you use the issued kubeconfig to bootstrap your service APIs, register your provider in the marketplace, and wire your controllers into the workspace.
9+
10+
## When to use this
11+
12+
Use this guide when your team operates a service independently and manages its own provider workspace. If the platform team owns the service end-to-end, use [Onboard a managed service](./onboard-managed-service.md) instead.
13+
14+
## Prerequisites
15+
16+
- `kubectl` access to a kcp workspace that has an `APIBinding` to the `providers.platform-mesh.io` export from `root:platform-mesh-system`
17+
18+
::: warning
19+
The workflow for obtaining this binding — the provider onboarding path — is not yet documented. For now, a platform owner must create the binding manually in the target workspace. This guide will be updated when the onboarding workflow is defined.
20+
:::
21+
22+
## Step 1: Create the Provider resource
23+
24+
Apply a `Provider` in the workspace where you have the `providers.platform-mesh.io` binding. All spec fields are optional — a minimal resource has an empty spec:
25+
26+
```yaml
27+
apiVersion: providers.platform-mesh.io/v1alpha1
28+
kind: Provider
29+
metadata:
30+
name: my-service
31+
spec: {}
32+
```
33+
34+
```bash
35+
kubectl apply -f provider.yaml
36+
```
37+
38+
## Step 2: Wait for the workspace to be ready
39+
40+
The Provider controller provisions a workspace and kubeconfig. Watch the phase:
41+
42+
```bash
43+
kubectl get provider my-service -w
44+
```
45+
46+
Expected output once provisioning completes:
47+
48+
```
49+
NAME PHASE READY
50+
my-service Ready True
51+
```
52+
53+
## Step 3: Retrieve the kubeconfig
54+
55+
The controller writes a kubeconfig Secret into the workspace where the `Provider` lives. Retrieve it:
56+
57+
```bash
58+
kubectl get secret my-service-provider-kubeconfig -o jsonpath='{.data.kubeconfig}' | base64 -d > provider-kubeconfig.yaml
59+
```
60+
61+
Use this kubeconfig to authenticate against the provider workspace in kcp.
62+
63+
## Step 4: Bootstrap workspace resources
64+
65+
Use the kubeconfig to seed the provider workspace with the resources your service needs to run and expose itself — for example, `APIExport`, `APIResourceSchema`, `ContentConfiguration`, `ProviderMetadata`, and RBAC. The kubeconfig can be passed to any mechanism that applies Kubernetes resources: an init container in the operator deployment, a dedicated setup controller, a GitOps pipeline, or similar.
66+
67+
Applying resources manually is possible but not the intended long-term approach:
68+
69+
```bash
70+
export PROVIDER_KUBECONFIG=provider-kubeconfig.yaml
71+
kubectl --kubeconfig $PROVIDER_KUBECONFIG apply -f <your-workspace-resources>
72+
```
73+
74+
## Step 5: Wire the kubeconfig into your service controllers
75+
76+
Configure your service controllers to use the provider kubeconfig to watch the `APIExport` virtual workspace and reconcile service consumers. See [Integration paths](/concepts/integration-paths.md) to choose the right mechanism and find the corresponding tutorial.
77+
78+
## Related
79+
80+
- [Provider resource](/reference/resources/provider-resource.md)
81+
- [Provider bootstrap](/concepts/provider-bootstrap.md)
82+
- [Integration paths](/concepts/integration-paths.md)
83+
- [Service provider persona](/concepts/personas/service-provider.md)

‎how-to-guides/index.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,14 @@ How-to guides are task-focused. Use them when you already know what you want to
88
- [Set up remote deployment](./set-up-remote-deployment.md)
99
- [Speed up local rebuilds](./speed-up-local-rebuilds.md)
1010

11+
## Platform operators
12+
13+
- [Onboard a managed service](./onboard-managed-service.md)
14+
15+
## Service providers
16+
17+
- [Bootstrap a provider](./bootstrap-provider.md)
18+
1119
## Access local services
1220

1321
- [Access the Keycloak admin console](./access-keycloak.md)

‎how-to-guides/onboard-managed-service.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
---
2+
title: Onboard a managed service
3+
personas: [platform-owner]
4+
---
5+
6+
# Onboard a managed service
7+
8+
Use this how-to to onboard a platform-owned service into Platform Mesh using a `ManagedProvider`. The resource handles the full lifecycle: provisioning a kcp workspace for the provider, distributing the resulting kubeconfig, and deploying the service operator on the runtime cluster.
9+
10+
## When to use this
11+
12+
Use `ManagedProvider` when the platform team owns and operates the service. For services operated by *external teams* who manage their own provider onboarding, use a `Provider` directly instead.
13+
14+
## Prerequisites
15+
16+
- A running Platform Mesh environment with a `PlatformMesh` resource in the `Ready` state
17+
- `kubectl` access to the Platform Mesh runtime cluster
18+
- The service operator published as an OCM component in an accessible registry
19+
20+
## Step 1: Create the ManagedProvider resource
21+
22+
Apply a `ManagedProvider` in the same namespace as the `PlatformMesh` instance. Set `platformMeshRef.name` to the name of your `PlatformMesh` resource and list each operator component under `runtimeDeployments`:
23+
24+
```yaml
25+
apiVersion: providers.platform-mesh.io/v1alpha1
26+
kind: ManagedProvider
27+
metadata:
28+
name: my-service
29+
namespace: platform-mesh-system
30+
spec:
31+
platformMeshRef:
32+
name: platform-mesh
33+
runtimeDeployments:
34+
- ocm:
35+
componentName: my-service-operator
36+
registry: ghcr.io/my-org/ocm
37+
version: "1.0.0"
38+
```
39+
40+
```bash
41+
kubectl apply -f managed-provider.yaml
42+
```
43+
44+
## Step 2: Watch the phase progress
45+
46+
The controller moves through several phases as it provisions the workspace and deploys the operator:
47+
48+
```bash
49+
kubectl get managedprovider my-service -n platform-mesh-system -w
50+
```
51+
52+
Expected progression:
53+
54+
```
55+
NAME PHASE READY
56+
my-service WaitingForProvider False
57+
my-service CopyingKubeconfig False
58+
my-service Deploying False
59+
my-service Deployed True
60+
```
61+
62+
If the phase stalls, check the `conditions` field on the resource:
63+
64+
```bash
65+
kubectl describe managedprovider my-service -n platform-mesh-system
66+
```
67+
68+
And the controller logs:
69+
70+
```bash
71+
kubectl logs -n platform-mesh-system -l app=platform-mesh-operator --tail=50
72+
```
73+
74+
## Step 3: Verify the kubeconfig Secret
75+
76+
Once `Deployed`, the controller writes a kubeconfig Secret into the runtime cluster. Verify it exists:
77+
78+
```bash
79+
kubectl get secret my-service-provider-kubeconfig -n platform-mesh-system
80+
```
81+
82+
Service operator components reference this Secret to reach the provider workspace in kcp.
83+
84+
## Step 4: Verify the operator deployment
85+
86+
Confirm the operator components are running:
87+
88+
```bash
89+
kubectl get pods -n platform-mesh-system -l app.kubernetes.io/name=my-service-operator
90+
```
91+
92+
## Troubleshooting
93+
94+
| Symptom | Likely cause |
95+
| --- | --- |
96+
| Stuck at `WaitingForProvider` | The `Provider` has not yet reached `Ready` — check the Provider controller logs for workspace or kubeconfig provisioning errors |
97+
| Stuck at `CopyingKubeconfig` | The Provider workspace is ready but the kubeconfig copy failed — check the ManagedProvider controller logs for Secret write errors |
98+
| Stuck at `Deploying` | The OCM component version does not exist in the registry, or FluxCD is not reconciling — check HelmRelease status in the namespace |
99+
| `Deployed` but pods not running | The operator chart values may be misconfigured — check the HelmRelease events and operator pod logs |
100+
101+
## Related
102+
103+
- [ManagedProvider resource](/reference/resources/managed-provider-resource.md)
104+
- [Provider bootstrap](/concepts/provider-bootstrap.md)
105+
- [Platform Mesh operator reference](/reference/components/platform-mesh-operator.md)

‎reference/components/platform-mesh-operator.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,8 @@ The operator runs two independent controllers:
9393
|------------|---------|---------|
9494
| `PlatformMeshReconciler` | `PlatformMesh` (`core.platform-mesh.io/v1alpha1`) | Bootstraps and maintains the environment via subroutines |
9595
| `ResourceReconciler` | `Resource` (`delivery.ocm.software/v1alpha1`) | Syncs OCM-resolved artifacts into FluxCD sources / ArgoCD Applications |
96+
| `ProviderReconciler` | `Provider` (`providers.platform-mesh.io/v1alpha1`) | Provisions kcp workspaces and kubeconfig Secrets for service providers |
97+
| `ManagedProviderReconciler` | `ManagedProvider` (`providers.platform-mesh.io/v1alpha1`) | Orchestrates end-to-end onboarding of platform-owned services |
9698

9799
## PlatformMesh subroutines
98100

‎reference/resources/index.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,4 +7,6 @@ For conceptual explanations of accounts, control planes, API sharing, identity,
77
- [Account resource](./account-resource.md) — the central Platform Mesh tenancy object.
88
- [IAM Store resource](./iamstore-resource.md) — OpenFGA authorization store per account.
99
- [ContentConfiguration](./content-configuration.md) — register UI extensions with the Portal.
10+
- [Provider resource](./provider-resource.md) — provisions a dedicated kcp workspace and kubeconfig for a service provider.
11+
- [ManagedProvider resource](./managed-provider-resource.md) — automates end-to-end onboarding of platform-owned services.
1012
- [Metadata catalog](./metadata-catalog.md) — Platform Mesh API groups, labels, and finalizers.

‎reference/resources/managed-provider-resource.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# ManagedProvider resource
2+
3+
## Definition
4+
5+
`ManagedProvider` is a namespace-scoped custom resource in the `providers.platform-mesh.io/v1alpha1` API group. It is a convenience API for platform admins to onboard platform-owned services end-to-end: it creates and manages a `Provider` on the kcp side, then copies the resulting kubeconfig and deploys service operator components on the runtime side.
6+
7+
For the conceptual overview, see [Provider bootstrap](/concepts/provider-bootstrap.md).
8+
9+
## Schema
10+
11+
A minimal `ManagedProvider` requires a `platformMeshRef` and at least one `runtimeDeployments` entry:
12+
13+
```yaml
14+
apiVersion: providers.platform-mesh.io/v1alpha1
15+
kind: ManagedProvider
16+
metadata:
17+
name: my-service
18+
namespace: platform-mesh-system
19+
spec:
20+
platformMeshRef:
21+
name: platform-mesh
22+
runtimeDeployments:
23+
- ocm:
24+
componentName: my-service-operator
25+
registry: ghcr.io/platform-mesh/ocm
26+
version: "1.0.0"
27+
```
28+
29+
### Spec fields
30+
31+
| Field | Required | Default | Description |
32+
| --- | --- | --- | --- |
33+
| `platformMeshRef.name` | Yes | — | Name of the `PlatformMesh` instance this `ManagedProvider` belongs to. |
34+
| `runtimeDeployments` | Yes | — | List of OCM components to deploy on the runtime cluster. |
35+
| `runtimeDeployments[].ocm.componentName` | Yes | — | Fully qualified OCM component name. |
36+
| `runtimeDeployments[].ocm.registry` | Yes | — | OCM registry host. |
37+
| `runtimeDeployments[].ocm.version` | Yes | — | Component version to deploy. |
38+
| `runtimeDeployments[].ocm.values` | No | — | Helm values passed to the deployed chart. |
39+
| `provider.path` | No | `root:providers:system` | kcp workspace path where the `Provider` is created or adopted. |
40+
| `provider.name` | No | `<ManagedProvider.name>` | Name of the `Provider` to create or adopt at `provider.path`. |
41+
| `providerKubeconfigSecret.name` | No | `<ManagedProvider.name>-provider-kubeconfig` | Name of the Secret to store the copied kubeconfig in the runtime cluster. |
42+
| `providerKubeconfigSecret.key` | No | `kubeconfig` | Key in the Secret's data map. |
43+
| `runtimeKubeconfigSecretName` | No | Hosting cluster | Name of the Secret containing the kubeconfig for the target runtime cluster. |
44+
| `providerHostOverride` | No | Operator-configured front-proxy URL | Overrides the kcp front-proxy host in the generated kubeconfig. |
45+
| `cleanupOnDelete` | No | `false` | When `true`, also deletes the `Provider` on the kcp side when this resource is deleted, cascading to workspace deletion. |
46+
47+
### Status fields
48+
49+
| Field | Description |
50+
| --- | --- |
51+
| `phase` | Current lifecycle phase. See [Lifecycle](#lifecycle). |
52+
| `providerKubeconfigSecretRef` | Reference to the Secret in the runtime cluster containing the copied kubeconfig. |
53+
| `conditions` | Standard Kubernetes conditions, including `Ready`. |
54+
55+
## Who creates it
56+
57+
Platform admins create `ManagedProvider` resources to onboard platform-owned services.
58+
59+
::: tip
60+
For service providers managing their own onboarding, see [`Provider`](./provider-resource.md).
61+
:::
62+
63+
## Who reconciles it
64+
65+
The **ManagedProvider controller**, part of the [Platform Mesh operator](/reference/components/platform-mesh-operator.md), orchestrates the full provider lifecycle — from platform readiness checks through `Provider` creation, kubeconfig distribution, and operator deployment.
66+
67+
## What happens when you apply one
68+
69+
1. Finalizers are added for ordered cleanup.
70+
2. The controller waits for the referenced `PlatformMesh` to be ready.
71+
3. It creates (or adopts) a `Provider` at the target kcp path, defaulting to `root:providers:system`.
72+
4. Once the `Provider` is ready, it copies the resulting kubeconfig into a Secret on the runtime cluster.
73+
5. It deploys each component listed in `runtimeDeployments` via OCM and FluxCD.
74+
75+
By default, deleting a `ManagedProvider` removes the runtime deployments and the copied kubeconfig but leaves the kcp `Provider` and its workspace intact. Set `cleanupOnDelete: true` to also remove the `Provider` and cascade to the workspace.
76+
77+
## Lifecycle
78+
79+
```mermaid
80+
stateDiagram-v2
81+
[*] --> Pending
82+
Pending --> WaitingForPlatformMesh
83+
WaitingForPlatformMesh --> WaitingForProvider
84+
WaitingForProvider --> CopyingKubeconfig
85+
CopyingKubeconfig --> CopyingKubeconfigFailed : spec mismatch
86+
CopyingKubeconfigFailed --> CopyingKubeconfig
87+
CopyingKubeconfig --> Deploying
88+
Deploying --> Ready
89+
Ready --> Deploying : spec change
90+
Ready --> Deleting
91+
CopyingKubeconfigFailed --> Deleting
92+
Deleting --> [*]
93+
```
94+
95+
## Related
96+
97+
- [Provider bootstrap](/concepts/provider-bootstrap.md)
98+
- [Provider resource](./provider-resource.md)
99+
- [Platform Mesh operator](/reference/components/platform-mesh-operator.md)
100+
- [Platform owner persona](/concepts/personas/platform-owner.md)

0 commit comments

Comments
 (0)