This document summarizes what the platform-mesh-operator currently does, based on a careful read-through of the code in:
/home/xrstf/gospace/src/github.com/platform-mesh/platform-mesh/main/operators/platform-mesh-operator
The focus is on the operator's actual responsibilities today, especially the glue it provides between installed charts/components.
The platform-mesh-operator is not only the thing that creates Flux HelmRelease / source objects or ArgoCD Applications.
Today it acts as all of these at once:
- deployment compiler
- GitOps object generator
- OCM-to-GitOps translator
- KCP bootstrapper
- webhook/CA propagator
- kubeconfig/credential distributor
- feature manifest applier
- provider workspace/bootstrap manager
So any attempt to remove only the HelmRelease/Application generation part must still account for a lot of non-obvious orchestration logic.
The operator binary currently wires up these controllers/subsystems:
| Piece | Watches | Main purpose |
|---|---|---|
PlatformMeshReconciler |
PlatformMesh |
Main Platform Mesh installation/bootstrap/reconciliation |
ResourceReconciler |
OCM Resource |
Translate resolved OCM artifacts into Flux/Argo deployment inputs |
ManagedProviderReconciler |
ManagedProvider |
Runtime-side lifecycle for platform-owned providers |
ProviderReconciler |
Provider in kcp via APIExport provider |
Provider workspace and scoped kubeconfig bootstrap |
delayed provider bootstrap (startProvidersOperator) |
waits for kcp admin access | Adds APIExport provider and starts the Provider controller |
The PlatformMeshReconciler runs these subroutines in order:
DeploymentSubroutineKcpsetupSubroutineProviderSecretSubroutineFeatureToggleSubroutineWaitSubroutine
That ordering is meaningful.
This is the biggest piece of logic.
It reads:
- the
PlatformMeshCR - the profile ConfigMap (
spec.profileConfigMapor default<pm-name>-profile) spec.valuesspec.ocm- exposure settings (
baseDomain,port,protocol)
It then builds merged template variables.
It merges:
- profile
infra - profile
components - operator flags
PlatformMesh.spec.valuesPlatformMesh.spec.ocm- exposure-derived variables
It does not only render template files. It also renders Go-template expressions inside values where needed.
This means the operator currently acts as a configuration compiler.
From gotemplates/infra/..., it renders deployment resources for built-in infra components such as:
cert-managertraefiktraefikCRDsgateway-apietcd-druidprometheus-operator-crdsopentelemetry-operator- Argo-only
AppProject(platform-mesh-runtime)
Depending on deployment technology, it renders:
- Flux objects:
HelmRelease- sometimes
Kustomization
- or Argo objects:
ApplicationAppProject
- deployment CRs go to the infra client
- related OCM
Resourceobjects go to the runtime client
So even built-in infra components are split into:
- runtime-side artifact descriptors
- infra-side rollout objects
From gotemplates/components/..., it renders service deployment resources driven by the profile.
For each enabled service, it can create:
- chart
Resourcelike<service>-chart - image
Resourcelike<service>-imageor a custom name
- one Flux
HelmRelease - or one Argo
Application
This is the operator chunk responsible for generating the rollout resources for most PM services.
If ArgoCD is used, it computes syncWave from dependsOn unless the user already set one.
If a service depends on another component/release that is disabled and therefore not rendered, it removes that dependsOn entry so Flux does not block forever.
It distinguishes:
releaseNamespacedeploymentNamespacehelmReleaseNamespace
This allows the deployment CR to live in one namespace while the workload goes to another.
The operator has explicit anti-conflict logic between:
DeploymentSubroutine(renders base HelmReleases / Applications)ResourceReconciler(patches repo URLs, chart versions, image tags, etc. from OCMResource.status)
spec.source.repoURLspec.source.targetRevision- image versions injected into
spec.source.helm.values
- image values injected by
ResourceReconciler spec.suspend=falseifResourceReconcilerunsuspended the release
This uses the in-memory ImageVersionStore.
So the operator contains explicit logic to prevent its own controllers from overwriting each other.
The operator applies the following manifests from manifests/k8s/rebac-auth-webhook/:
Issuerrebac-authz-webhook-issuer
Certificaterebac-authz-webhook-cert
Secretstubkcp-webhook-secret
It contains a kubeconfig pointing to:
https://rebac-authz-webhook.platform-mesh-system.svc.cluster.local:9443/authz
So the operator explicitly wires kcp to call the rebac authorization webhook via kubeconfig.
It reads:
rebac-authz-webhook-certsecret- takes
ca.crt - rewrites
certificate-authority-datainsidekcp-webhook-secret
If the kubeconfig CA changed, it deletes kcp pods so they reload the new webhook kubeconfig.
This is a major cross-component integration responsibility.
Before managing those webhook cert resources, it explicitly waits for CRDs such as:
issuers.cert-manager.iocertificates.cert-manager.io
So cert-manager readiness is part of the operator's orchestration logic.
If Istio integration is enabled:
- it waits for
istio-istioddeployment resource readiness - checks whether the operator pod has an
istio-proxy - if not, and not in local mode, it deletes/restarts itself
So the operator also self-manages its own expected pod shape.
Still inside deployment, it requires runtime-side:
RootShardAvailable=TrueFrontProxyAvailable=True
before finishing successfully.
This subroutine owns most kcp bootstrap work.
It builds a kcp admin kubeconfig from the configured cluster-admin secret, using:
- a prebuilt kubeconfig secret if present
- otherwise cert/key/ca data
This is then used to apply kcp-side manifests.
Before applying kcp manifests, it gathers:
tenancy.kcp.ioshards.core.kcp.iotopology.kcp.io
- account-operator webhook CA
- account-operator validating webhook CA
- security-operator webhook CA
- domain certificate CA
These values are fed into templated kcp manifests.
So the operator bridges runtime-side secret material into kcp-side objects.
From manifests/kcp/, it bootstraps workspaces and API surface.
It creates/applies things like:
- workspace
platform-mesh-system - workspace
providers - workspace
orgs
Workspace types:
securityprovidersorgsorgaccountprovider
It applies:
APIExports:core.platform-mesh.iosystem.platform-mesh.ioproviders.platform-mesh.io
APIBindings:- core
- system
APIExportEndpointSliceAPIResourceSchemas for:accountsaccountinfosauthorizationmodelsidentityproviderconfigurationsinvitesstoresprovidersproviderpermissions- UI content/provider metadata
- KCP init CRDs
ContentConfigurations- kcp-side admission webhook configs
welcomeIdentityProviderConfiguration
It applies:
Storenamedorgs
It applies:
- workspace
system
It applies these kcp-side webhook configs:
account-operator.webhooks.core.platform-mesh.io(mutating)organization-validator.webhooks.core.platform-mesh.io(validating)identityproviderconfiguration-validator.webhooks.core.platform-mesh.io(validating)
The CA bundles for those are templated from runtime-side secrets.
So the operator explicitly wires:
- account-operator webhook CA secret -> kcp webhook config CA
- security-operator webhook CA secret -> kcp webhook config CA
It applies orgs-authentication and fills in:
- issuer URL based on exposure/base domain
- certificate authority from the domain CA secret
- audience list derived from
welcomeIdentityProviderConfiguration.status.managedClients - alternate username/email handling when
feature-disable-email-verificationis enabled
welcomeIPC status -> kcp auth audiences
So the operator uses one CR's observed status to drive another part of the auth system.
From the PlatformMesh spec it also handles:
spec.kcp.extraWorkspacesspec.kcp.extraDefaultAPIBindings
This lets the PM installation extend the default kcp topology.
If applying an IdentityProviderConfiguration fails, it tolerates this and retries later, because the validating webhook may not yet be ready.
This is another orchestration responsibility.
This subroutine creates kubeconfig secrets consumed by PM services so they can talk to kcp or virtual workspaces.
It builds the final provider connection list from:
- default provider connections
spec.kcp.providerConnectionsspec.kcp.extraProviderConnections- feature-specific additions
If terminal-controller-manager is enabled, it additionally creates:
terminal-controller-manager-kubeconfig
By default it manages these secrets:
account-operator-kubeconfigrebac-authz-webhook-kubeconfigsecurity-operator-kubeconfigkubernetes-graphql-gateway-kubeconfigvirtual-workspace-clusteraccess-kubeconfigextension-manager-operator-kubeconfigiam-service-kubeconfigportal-kubeconfigsecurity-initializer-kubeconfigsecurity-terminator-kubeconfigvirtual-workspaces-kubeconfiginit-agent-kubeconfig
And optionally:
terminal-controller-manager-kubeconfig
These are direct cross-component integration artifacts.
For AdminAuth=true connections, it:
- reads
kubeconfig-kcp-admin - builds a trust bundle from:
- kubeconfig CA data
- root shard CA secret
<rootShardName>-ca
- rewrites the server URL to the desired cluster path / raw path / endpoint path
- writes a secret with the resulting kubeconfig
For AdminAuth=false, it:
- resolves an APIExport or APIExportEndpointSlice
- generates RBAC rules from exported resources + permission claims
- creates a ServiceAccount in the kcp workspace
- creates ClusterRoles/Bindings
- creates a workspace-access ClusterRoleBinding
- creates a token for the ServiceAccount
- builds a token-based kubeconfig
- writes the kubeconfig secret back to the runtime cluster
So this subroutine handles security scoping, not just secret copying.
For scoped kubeconfigs using endpoint slices, it rewrites the published virtual workspace URL to the front-proxy base or external exposure URL, preserving path/query.
So it normalizes connectivity for clients.
This applies optional kcp feature manifests.
Known feature toggles include:
feature-enable-getting-startedfeature-enable-marketplace-accountfeature-enable-marketplace-orgfeature-accounts-in-accountsfeature-enable-account-iam-uifeature-enable-terminal-controller-managerfeature-enable-provider-permissionsfeature-disable-email-verification
What it applies from manifests/features/... includes:
- extra
ContentConfigurations - APIBinding for
providers.platform-mesh.io ProviderPermissions- terminal
APIExport - terminal
APIResourceSchema
So the operator also owns optional kcp API/UI feature surface extension.
This is the reconciliation barrier.
By default it checks operator-created deployment resources for readiness via WaitConfig.
The exact set is configurable, but the shipped default targets operator-created Flux HelmReleases.
It explicitly checks that:
orgs-authentication.spec.jwt[0].issuer.audiences- is not empty
- and is not still
"<placeholder>"
This is effectively a guard that auth bootstrap finished.
This controller watches OCM Resource objects and mutates deployment objects based on resolved artifact status.
This is a major glue layer.
Depending on repo:
repo=oci-> creates/updatesOCIRepositoryrepo=git-> creates/updatesGitRepositoryrepo=helm-> creates/updatesHelmRepository, then patchesHelmReleasechart version
It patches target HelmRelease.spec.values to inject:
- image tag
- sometimes registry/repository/digest siblings
It also supports:
- combined image reference mode
- unsuspending a HelmRelease once image resolution is ready
It patches Application.spec.source:
repoURLtargetRevision
based on whether the OCM resource resolved to:
- helm repo
- git repo
- OCI chart
It patches Application.spec.source.helm.values with the resolved image tag.
It interprets annotations/labels such as:
repoartifactforpathversion-pathimage-refunsuspend
These drive how a resolved OCM Resource maps onto a target HelmRelease/Application field.
So the operator has an internal metadata contract / mini-DSL here.
It looks up from the runtime-side profile ConfigMap:
deploymentTechnologydeploymentNamespace
This tells it whether it should patch:
- Flux objects
- or Argo objects
- and in which namespace
These are separate from PM core installation, but they are part of the same operator today.
Watches Provider objects via kcp APIExport/multicluster provider.
- creates dedicated provider workspace under
root:providers:<name>-<cluster> - waits for it to become
Ready - deletes it on finalization
Inside that provider workspace it:
- creates namespace
- creates ServiceAccount
- creates cluster-admin ClusterRoleBinding
- creates static token Secret
- builds kubeconfig
- writes kubeconfig Secret into the user workspace
- cleans this up on delete
So the operator contains a full provider bootstrap subsystem.
This is the runtime-side convenience API.
It runs these steps:
- wait for referenced
PlatformMeshto be Ready - create/adopt a
Providerin kcp - wait for
Providerto become Ready - copy provider kubeconfig Secret from kcp workspace into runtime cluster
- deploy runtime components for that provider
- Flux
OCIRepository - Flux
HelmRepository - Flux
HelmRelease - or inline OCM
Repository/Component/Resourcethat eventually feed a Flux release
It also supports deploying to an alternate runtime cluster via runtimeKubeconfigSecretName.
This is the most important practical summary.
rebac-authz-webhook-cert->kcp-webhook-secretCA datakcp-webhook-secret-> kcp authz webhook client kubeconfig- account-operator webhook CA secret -> kcp account admission webhook configs
- security-operator webhook CA secret -> kcp IdP validating webhook config
- domain certificate CA secret -> kcp
WorkspaceAuthenticationConfiguration
welcomeIdentityProviderConfiguration.status.managedClients-> JWT audiences inorgs-authentication- exposure/base domain -> welcome IPC redirect URIs + kcp auth issuer URL
- runtime-side OCM
Resource.status.*-> infra-side Flux sources / versions - runtime-side OCM image
Resourcestatus -> HelmRelease/Application image values - profile
deploymentTechnology-> whether HelmRelease or Application templates are rendered - profile
deploymentNamespace-> where deployment CRs live - profile service
dependsOn-> Flux dependencies or Argo sync waves
- cluster-admin / root shard CA / APIExportEndpointSlice / APIExport definitions -> service-specific kubeconfig secrets for PM components
istio-istiodreadiness -> operator pod self-restart if missing sidecar- webhook CA rotation -> kcp pod restart
The operator is currently responsible for much more than chart rollout generation. It also owns:
- config merging and templating
- dependency pruning
- Argo sync-wave calculation
- OCM
Resource-> deployment object translation - image version field patching
- webhook certificate and CA propagation
- kcp admission webhook object creation
- kcp APIExports / APIBindings / APIResourceSchemas / workspace topology bootstrap
- service kubeconfig secret generation
- auth audience propagation from IdP status into kcp auth config
- provider bootstrap and provider runtime deployment workflows
If the HelmRelease/Application generation part is removed from the operator, a replacement still has to cover a large amount of non-obvious glue, especially:
- OCM-to-deployment translation
- auth/webhook CA propagation
- kcp bootstrap and manifest application
- kubeconfig distribution
- profile/value merge and template rendering behavior
- provider bootstrap lifecycle
In short: the operator today is both a deployer and a substantial integration/orchestration layer for Platform Mesh.