Rework providers docs for ManagedProviders (#236)

Signed-off-by: Mangirdas Judeikis <mangirdas@judeikis.lt>

Author: mjudeikis

concepts/provider-bootstrap.md

@@ -6,9 +6,9 @@ Platform Mesh provisions a dedicated kcp workspace for each service provider. Cr
 
 ## 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.
+Each provider workspace lives under `root:providers` and is identified by the `Provider` name combined with the logical cluster ID of the workspace where the `Provider` object was created. The name is deterministic: two tenants can create a `Provider` with the same name without colliding, and deleting and recreating a `Provider` in the same workspace maps back to the same provider workspace.
 
-The workspace is the provider's exclusive domain. Platform Mesh creates it and issues credentials but does not manage the resources inside it.
+The workspace is the provider's exclusive domain. Platform Mesh creates it and provisions the access credentials inside it — a ServiceAccount, its RBAC binding, and a token, from which the kubeconfig is generated — but manages nothing else there; the provider owns the contents.
 
 ## Provider
 
@@ -23,9 +23,9 @@ With the workspace bootstrapped, service controllers use the kubeconfig to watch
 
 ## 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.
+`ManagedProvider` is a Platform Mesh runtime resource, reconciled by the Platform Mesh operator. 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.
+On the kcp side, a `ManagedProvider` creates a `Provider` and waits for it to be ready — by default named after the `ManagedProvider` in `root:providers:system`, or created/adopted at an explicit path via a provider reference. On the runtime side, it copies the resulting kubeconfig into Platform Mesh's runtime cluster and deploys the service operator components, declared as Helm charts delivered either directly via Flux or resolved from an OCM component.
 
 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.
 

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

@@ -15,11 +15,11 @@ Use `ManagedProvider` when the platform team owns and operates the service. For
 
 - 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
+- The service operator published as a Helm chart in an accessible OCI registry or Helm repository — or, if you deploy via OCM, published as an OCM component (this additionally requires the ocm-controller in the runtime cluster)
 
 ## 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`:
+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`. Each entry sets exactly one of `flux` (Helm chart fetched directly from an OCI registry or Helm repository) or `ocm` (chart resolved from an OCM component descriptor):
 
 ```yaml
 apiVersion: providers.platform-mesh.io/v1alpha1
@@ -31,10 +31,21 @@ spec:
   platformMeshRef:
     name: platform-mesh
   runtimeDeployments:
+  - flux:
+      registry: ghcr.io/my-org/charts
+      chart: my-service-operator
+      version: "1.0.0"
+```
+
+To deploy from an OCM component instead, replace the `flux` entry with:
+
+```yaml
+  runtimeDeployments:
   - ocm:
-      componentName: my-service-operator
-      registry: ghcr.io/my-org/ocm
+      registry: ghcr.io/my-org
+      component: github.com/my-org/my-service
       version: "1.0.0"
+      resourceName: chart
 ```
 
 ```bash
@@ -99,7 +110,7 @@ kubectl get pods -n platform-mesh-system -l app.kubernetes.io/name=my-service-op
 | 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 |
+| Stuck at `Deploying` | The chart or OCM component version does not exist in the registry, FluxCD is not reconciling, or (for `ocm` entries) the ocm-controller is not installed — check HelmRelease and OCM resource 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

reference/resources/managed-provider-resource.md

@@ -8,7 +8,7 @@ For the conceptual overview, see [Provider bootstrap](/concepts/provider-bootstr
 
 ## Schema
 
-A minimal `ManagedProvider` requires a `platformMeshRef` and at least one `runtimeDeployments` entry:
+A minimal `ManagedProvider` requires a `platformMeshRef` and at least one `runtimeDeployments` entry. Each entry deploys one Helm chart and sets exactly one of `flux` (chart fetched directly from an OCI registry or Helm repository) or `ocm` (chart resolved from an OCM component descriptor):
 
 ```yaml
 apiVersion: providers.platform-mesh.io/v1alpha1
@@ -20,22 +20,43 @@ spec:
   platformMeshRef:
     name: platform-mesh
   runtimeDeployments:
+  - flux:
+      registry: ghcr.io/my-org/charts
+      chart: my-service-operator
+      version: "1.0.0"
+```
+
+The same deployment resolved from an OCM component instead:
+
+```yaml
+  runtimeDeployments:
   - ocm:
-      componentName: my-service-operator
-      registry: ghcr.io/platform-mesh/ocm
+      registry: ghcr.io/my-org
+      component: github.com/my-org/my-service
       version: "1.0.0"
+      resourceName: chart
 ```
 
 ### 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. |
+| `runtimeDeployments` | Yes | — | List of components to deploy on the runtime cluster. Each entry sets exactly one of `flux` or `ocm`. |
+| `runtimeDeployments[].flux.type` | No | `oci` | How the chart is fetched: `oci` (OCI artifact via a Flux `OCIRepository`) or `helm` (HTTP(S) Helm repository via a Flux `HelmRepository`). |
+| `runtimeDeployments[].flux.registry` | Yes | — | Chart source: for `type: oci`, the OCI registry host and base path (e.g. `ghcr.io/my-org/charts`); for `type: helm`, the Helm repository URL. |
+| `runtimeDeployments[].flux.chart` | Yes | — | Chart name: the OCI repository path under the registry, or the chart name within the Helm repository. |
+| `runtimeDeployments[].flux.version` | Yes | — | Chart version to deploy (the OCI tag for `type: oci`). |
+| `runtimeDeployments[].flux.values` | No | — | Helm values passed to the deployed chart. |
+| `runtimeDeployments[].flux.insecure` | No | `false` | Allow plain-HTTP access to the OCI repository. |
+| `runtimeDeployments[].ocm.registry` | Yes | — | OCM/OCI registry root that holds the component (e.g. `ghcr.io/my-org`). |
+| `runtimeDeployments[].ocm.component` | Yes | — | Fully qualified OCM component name (e.g. `github.com/my-org/my-service`). |
+| `runtimeDeployments[].ocm.version` | Yes | — | OCM component version (semver). |
+| `runtimeDeployments[].ocm.resourceName` | No | `chart` | OCM resource name within the component to deploy. |
+| `runtimeDeployments[].ocm.referencePath` | No | — | List of `{name: ...}` elements navigating nested component references to reach the resource. |
+| `runtimeDeployments[].ocm.name` | No | Derived from `resourceName`, `referencePath`, or the component name | Name for the generated deployment objects. Set it explicitly when several entries share the same component name. |
+| `runtimeDeployments[].ocm.values` | No | — | Helm values passed to the resolved chart. |
+| `runtimeDeployments[].ocm.insecure` | No | `false` | Allow plain-HTTP access to the registry. |
 | `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. |
@@ -70,7 +91,7 @@ The **ManagedProvider controller**, part of the [Platform Mesh operator](/refere
 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.
+5. It deploys each component listed in `runtimeDeployments`: `flux` entries go straight to Flux (`OCIRepository`/`HelmRepository` + `HelmRelease`); `ocm` entries first have their component descriptor resolved by the ocm-controller (which must be installed in the runtime cluster), and the resolved chart is then deployed via Flux.
 
 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.
 

reference/resources/provider-resource.md

@@ -54,7 +54,7 @@ The **Provider controller**, part of the [Platform Mesh operator](/reference/com
 ## What happens when you apply one
 
 1. Finalizers are added for ordered cleanup.
-2. A workspace (WorkspaceType **`root:provider`**) is created under `root:providers`. Its name is `<Provider.name>-<random-suffix>`.
+2. A workspace (WorkspaceType **`provider`**, declared in `root`) is created under `root:providers`. Its name is `<Provider.name>-<cluster-id>`, where `<cluster-id>` is the logical cluster ID (the `kcp.io/cluster` annotation) of the workspace holding the `Provider`. The name is deterministic: recreating the same `Provider` in the same workspace maps back to the same provider workspace, while equal names created by different tenants do not collide.
 3. Inside that workspace, a ServiceAccount, ClusterRoleBinding, and token Secret are created.
 4. A kubeconfig is generated from those credentials and written to the Secret specified by `providerKubeconfigSecret` (or the default location). The Secret is placed in the workspace where the `Provider` object lives, not in the provider workspace itself.
 5. `status.phase` transitions to `Ready` once provisioning completes.