Document Provider bootstrap

concepts/index.md

@@ -9,9 +9,10 @@ Use this section when you want to understand why Platform Mesh exists, how its p
 3. [Personas](./personas/) - the role guide for platform owners, service providers, and service consumers.
 4. [Account model](./account-model.md) - how organizations and accounts map to isolated control planes.
 5. [Control planes and workspaces](./control-planes.md) - how Platform Mesh uses kcp workspaces without duplicating the full kcp docs.
-6. [API sharing](./api-sharing.md) - how provider APIs become available in consumer workspaces.
-7. [Identity and authorization](./identity-and-authorization.md) - how identity, authorization data, and kcp enforcement relate.
-8. [Integration paths](./integration-paths.md) - when providers should use api-syncagent, multicluster-runtime, or related mechanisms.
-9. [Interaction patterns](./interaction-patterns/provider-to-consumer.md) - common provider-consumer, provider-provider, and cross-consumption flows.
+6. [Provider bootstrap](./provider-bootstrap.md) - how Platform Mesh provisions a dedicated workspace and kubeconfig for each service provider.
+7. [API sharing](./api-sharing.md) - how provider APIs become available in consumer workspaces.
+8. [Identity and authorization](./identity-and-authorization.md) - how identity, authorization data, and kcp enforcement relate.
+9. [Integration paths](./integration-paths.md) - when providers should use api-syncagent, multicluster-runtime, or related mechanisms.
+10. [Interaction patterns](./interaction-patterns/provider-to-consumer.md) - common provider-consumer, provider-provider, and cross-consumption flows.
 
 For factual lookup, use [Reference](/reference/). For guided local setup, start with [Tutorials](/tutorials/).

concepts/provider-bootstrap.md

@@ -0,0 +1,42 @@
+# Provider bootstrap
+
+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.
+
+`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.
+
+## The provider workspace
+
+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.
+
+The workspace is the provider's exclusive domain. Platform Mesh creates it and issues credentials but does not manage the resources inside it.
+
+## Provider
+
+`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.
+
+Once the workspace is ready, the provider is responsible for:
+
+- Bootstrapping their workspace resources — for example, `APIExport`, `APIResourceSchema`, `ContentConfiguration`, `ProviderMetadata`, and RBAC.
+- Wiring the kubeconfig into their service controllers so those controllers can manage resources in the provider workspace.
+
+With the workspace bootstrapped, service controllers use the kubeconfig to watch their `APIExport` virtual workspace and reconcile service consumers.
+
+## ManagedProvider
+
+`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.
+
+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.
+
+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.
+
+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.
+
+## Related
+
+- [Service provider persona](./personas/service-provider.md)
+- [Control planes and workspaces](./control-planes.md)
+- [API sharing](./api-sharing.md)
+- [Integration paths](./integration-paths.md)
+- [Platform Mesh operator](/reference/components/platform-mesh-operator.md)
+- [Provider resource](/reference/resources/provider-resource.md)
+- [ManagedProvider resource](/reference/resources/managed-provider-resource.md)

how-to-guides/bootstrap-provider.md

@@ -0,0 +1,83 @@
+---
+title: Bootstrap a provider
+personas: [service-provider]
+---
+
+# Bootstrap a provider
+
+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.
+
+## When to use this
+
+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.
+
+## Prerequisites
+
+- `kubectl` access to a kcp workspace that has an `APIBinding` to the `providers.platform-mesh.io` export from `root:platform-mesh-system`
+
+::: warning
+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.
+:::
+
+## Step 1: Create the Provider resource
+
+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:
+
+```yaml
+apiVersion: providers.platform-mesh.io/v1alpha1
+kind: Provider
+metadata:
+  name: my-service
+spec: {}
+```
+
+```bash
+kubectl apply -f provider.yaml
+```
+
+## Step 2: Wait for the workspace to be ready
+
+The Provider controller provisions a workspace and kubeconfig. Watch the phase:
+
+```bash
+kubectl get provider my-service -w
+```
+
+Expected output once provisioning completes:
+
+```
+NAME         PHASE   READY
+my-service   Ready   True
+```
+
+## Step 3: Retrieve the kubeconfig
+
+The controller writes a kubeconfig Secret into the workspace where the `Provider` lives. Retrieve it:
+
+```bash
+kubectl get secret my-service-provider-kubeconfig -n default -o jsonpath='{.data.kubeconfig}' | base64 -d > provider-kubeconfig.yaml
+```
+
+Use this kubeconfig to authenticate against the provider workspace in kcp.
+
+## Step 4: Bootstrap workspace resources
+
+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.
+
+Applying resources manually is possible but not the intended long-term approach:
+
+```bash
+export PROVIDER_KUBECONFIG=provider-kubeconfig.yaml
+kubectl --kubeconfig $PROVIDER_KUBECONFIG apply -f <your-workspace-resources>
+```
+
+## Step 5: Wire the kubeconfig into your service controllers
+
+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.
+
+## Related
+
+- [Provider resource](/reference/resources/provider-resource.md)
+- [Provider bootstrap](/concepts/provider-bootstrap.md)
+- [Integration paths](/concepts/integration-paths.md)
+- [Service provider persona](/concepts/personas/service-provider.md)

how-to-guides/index.md

@@ -8,6 +8,14 @@ How-to guides are task-focused. Use them when you already know what you want to
 - [Set up remote deployment](./set-up-remote-deployment.md)
 - [Speed up local rebuilds](./speed-up-local-rebuilds.md)
 
+## Platform operators
+
+- [Onboard a managed service](./onboard-managed-service.md)
+
+## Service providers
+
+- [Bootstrap a provider](./bootstrap-provider.md)
+
 ## Access local services
 
 - [Access the Keycloak admin console](./access-keycloak.md)

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

@@ -0,0 +1,109 @@
+---
+title: Onboard a managed service
+personas: [platform-owner]
+---
+
+# Onboard a managed service
+
+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.
+
+## When to use this
+
+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.
+
+## Prerequisites
+
+- A running Platform Mesh environment with a `PlatformMesh` resource in the `Ready` state
+- `kubectl` access to the Platform Mesh runtime cluster
+- The service operator published as an OCM component in an accessible registry
+
+## Step 1: Create the ManagedProvider resource
+
+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`:
+
+```yaml
+apiVersion: providers.platform-mesh.io/v1alpha1
+kind: ManagedProvider
+metadata:
+  name: my-service
+  namespace: platform-mesh-system
+spec:
+  platformMeshRef:
+    name: platform-mesh
+  runtimeDeployments:
+  - ocm:
+      componentName: my-service-operator
+      registry: ghcr.io/my-org/ocm
+      version: "1.0.0"
+```
+
+```bash
+kubectl apply -f managed-provider.yaml
+```
+
+## Step 2: Watch the phase progress
+
+The controller moves through several phases as it provisions the workspace and deploys the operator:
+
+```bash
+kubectl get managedprovider my-service -n platform-mesh-system -w
+```
+
+Expected progression:
+
+```
+NAME         PHASE                    READY
+my-service   Pending                  False
+my-service   WaitingForPlatformMesh   False
+my-service   WaitingForProvider       False
+my-service   CopyingKubeconfig        False
+my-service   Deploying                False
+my-service   Ready                    True
+```
+
+If the phase stalls, check the `conditions` field on the resource:
+
+```bash
+kubectl describe managedprovider my-service -n platform-mesh-system
+```
+
+And the controller logs:
+
+```bash
+kubectl logs -n platform-mesh-system -l app=platform-mesh-operator --tail=50
+```
+
+## Step 3: Verify the kubeconfig Secret
+
+The controller writes the kubeconfig Secret during the `CopyingKubeconfig` phase. Once the resource is `Ready`, verify it exists:
+
+```bash
+kubectl get secret my-service-provider-kubeconfig -n platform-mesh-system
+```
+
+Service operator components reference this Secret to reach the provider workspace in kcp.
+
+## Step 4: Verify the operator deployment
+
+Confirm the operator components are running:
+
+```bash
+kubectl get pods -n platform-mesh-system -l app.kubernetes.io/name=my-service-operator
+```
+
+## Troubleshooting
+
+| Symptom | Likely cause |
+| --- | --- |
+| Stuck at `WaitingForPlatformMesh` | The referenced `PlatformMesh` resource is not yet `Ready` — check the platform-mesh-operator logs and the `PlatformMesh` conditions |
+| Stuck at `WaitingForProvider` | The associated `Provider` has not yet reached `Ready` — check the Provider controller logs for workspace or kubeconfig provisioning errors |
+| Stuck at `CopyingKubeconfig` | The Provider controller has not yet populated the kubeconfig Secret — check the Provider controller logs |
+| Stuck at `CopyingKubeconfigFailed` | The `providerKubeconfigSecret` spec on the `Provider` does not match what the `ManagedProvider` expects — ensure the `providerKubeconfigSecret` fields are aligned between both resources |
+| Stuck at `Deploying` | The OCM component version does not exist in the registry, or FluxCD is not reconciling — check HelmRelease status in the namespace |
+| `Ready` but pods not running | The operator chart values may be misconfigured — check the HelmRelease events and operator pod logs |
+
+## Related
+
+- [ManagedProvider resource](/reference/resources/managed-provider-resource.md)
+- [Provider bootstrap](/concepts/provider-bootstrap.md)
+- [Platform Mesh operator reference](/reference/components/platform-mesh-operator.md)

reference/components/platform-mesh-operator.md

@@ -87,12 +87,14 @@ The operator reports per-subroutine conditions on the status subresource:
 
 ## Controllers
 
-The operator runs two independent controllers:
+The operator binary provides the following controllers:
 
 | Controller | Watches | Purpose |
 |------------|---------|---------|
 | `PlatformMeshReconciler` | `PlatformMesh` (`core.platform-mesh.io/v1alpha1`) | Bootstraps and maintains the environment via subroutines |
 | `ResourceReconciler` | `Resource` (`delivery.ocm.software/v1alpha1`) | Syncs OCM-resolved artifacts into FluxCD sources / ArgoCD Applications |
+| `ProviderReconciler` | `Provider` (`providers.platform-mesh.io/v1alpha1`) | Provisions kcp workspaces and kubeconfig Secrets for service providers |
+| `ManagedProviderReconciler` | `ManagedProvider` (`providers.platform-mesh.io/v1alpha1`) | Orchestrates end-to-end onboarding of platform-owned services |
 
 ## PlatformMesh subroutines
 

reference/resources/index.md

@@ -7,4 +7,6 @@ For conceptual explanations of accounts, control planes, API sharing, identity,
 - [Account resource](./account-resource.md) — the central Platform Mesh tenancy object.
 - [IAM Store resource](./iamstore-resource.md) — OpenFGA authorization store per account.
 - [ContentConfiguration](./content-configuration.md) — register UI extensions with the Portal.
+- [Provider resource](./provider-resource.md) — provisions a dedicated kcp workspace and kubeconfig for a service provider.
+- [ManagedProvider resource](./managed-provider-resource.md) — automates end-to-end onboarding of platform-owned services.
 - [Metadata catalog](./metadata-catalog.md) — Platform Mesh API groups, labels, and finalizers.

reference/resources/managed-provider-resource.md

@@ -0,0 +1,100 @@
+# ManagedProvider resource
+
+## Definition
+
+`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.
+
+For the conceptual overview, see [Provider bootstrap](/concepts/provider-bootstrap.md).
+
+## Schema
+
+A minimal `ManagedProvider` requires a `platformMeshRef` and at least one `runtimeDeployments` entry:
+
+```yaml
+apiVersion: providers.platform-mesh.io/v1alpha1
+kind: ManagedProvider
+metadata:
+  name: my-service
+  namespace: platform-mesh-system
+spec:
+  platformMeshRef:
+    name: platform-mesh
+  runtimeDeployments:
+  - ocm:
+      componentName: my-service-operator
+      registry: ghcr.io/platform-mesh/ocm
+      version: "1.0.0"
+```
+
+### Spec fields
+
+| Field | Required | Default | Description |
+| --- | --- | --- | --- |
+| `platformMeshRef.name` | Yes | — | Name of the `PlatformMesh` instance this `ManagedProvider` belongs to. |
+| `runtimeDeployments` | Yes | — | List of OCM components to deploy on the runtime cluster. |
+| `runtimeDeployments[].ocm.componentName` | Yes | — | Fully qualified OCM component name. |
+| `runtimeDeployments[].ocm.registry` | Yes | — | OCM registry host. |
+| `runtimeDeployments[].ocm.version` | Yes | — | Component version to deploy. |
+| `runtimeDeployments[].ocm.values` | No | — | Helm values passed to the deployed chart. |
+| `provider.path` | No | `root:providers:system` | kcp workspace path where the `Provider` is created or adopted. |
+| `provider.name` | No | `<ManagedProvider.name>` | Name of the `Provider` to create or adopt at `provider.path`. |
+| `providerKubeconfigSecret.name` | No | `<ManagedProvider.name>-provider-kubeconfig` | Name of the Secret to store the copied kubeconfig in the runtime cluster. |
+| `providerKubeconfigSecret.key` | No | `kubeconfig` | Key in the Secret's data map. |
+| `runtimeKubeconfigSecretName` | No | Hosting cluster | Name of the Secret containing the kubeconfig for the target runtime cluster. |
+| `providerHostOverride` | No | Operator-configured front-proxy URL | Overrides the kcp front-proxy host in the generated kubeconfig. |
+| `cleanupOnDelete` | No | `false` | When `true`, also deletes the `Provider` on the kcp side when this resource is deleted, cascading to workspace deletion. |
+
+### Status fields
+
+| Field | Description |
+| --- | --- |
+| `phase` | Current lifecycle phase. See [Lifecycle](#lifecycle). |
+| `providerKubeconfigSecretRef` | Reference to the Secret in the runtime cluster containing the copied kubeconfig. |
+| `conditions` | Standard Kubernetes conditions, including `Ready`. |
+
+## Who creates it
+
+Platform admins create `ManagedProvider` resources to onboard platform-owned services.
+
+::: tip
+For service providers managing their own onboarding, see [`Provider`](./provider-resource.md).
+:::
+
+## Who reconciles it
+
+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.
+
+## What happens when you apply one
+
+1. Finalizers are added for ordered cleanup.
+2. The controller waits for the referenced `PlatformMesh` to be ready.
+3. It creates (or adopts) a `Provider` at the target kcp path, defaulting to `root:providers:system`.
+4. Once the `Provider` is ready, it copies the resulting kubeconfig into a Secret on the runtime cluster.
+5. It deploys each component listed in `runtimeDeployments` via OCM and FluxCD.
+
+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.
+
+## Lifecycle
+
+```mermaid
+stateDiagram-v2
+    [*] --> Pending
+    Pending --> WaitingForPlatformMesh
+    WaitingForPlatformMesh --> WaitingForProvider
+    WaitingForProvider --> CopyingKubeconfig
+    CopyingKubeconfig --> CopyingKubeconfigFailed : spec mismatch
+    CopyingKubeconfigFailed --> CopyingKubeconfig
+    CopyingKubeconfig --> Deploying
+    Deploying --> Ready
+    Ready --> Deploying : spec change
+    Ready --> Deleting
+    CopyingKubeconfigFailed --> Deleting
+    Deleting --> [*]
+```
+
+## Related
+
+- [Provider bootstrap](/concepts/provider-bootstrap.md)
+- [Provider resource](./provider-resource.md)
+- [Platform Mesh operator](/reference/components/platform-mesh-operator.md)
+- [Platform owner persona](/concepts/personas/platform-owner.md)