Skip to content

Instantly share code, notes, and snippets.

@xrstf
Created September 21, 2026 14:58
Show Gist options
  • Select an option

  • Save xrstf/8877335bed3406b703a6412dbc018357 to your computer and use it in GitHub Desktop.

Select an option

Save xrstf/8877335bed3406b703a6412dbc018357 to your computer and use it in GitHub Desktop.
PM arch

Platform Mesh Operator Findings

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.


Executive summary

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.


Controllers in the operator

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

Main PlatformMesh reconciliation flow

The PlatformMeshReconciler runs these subroutines in order:

  1. DeploymentSubroutine
  2. KcpsetupSubroutine
  3. ProviderSecretSubroutine
  4. FeatureToggleSubroutine
  5. WaitSubroutine

That ordering is meaningful.


1. DeploymentSubroutine

This is the biggest piece of logic.

1.1 Reads and merges the PM config surface

It reads:

  • the PlatformMesh CR
  • the profile ConfigMap (spec.profileConfigMap or default <pm-name>-profile)
  • spec.values
  • spec.ocm
  • exposure settings (baseDomain, port, protocol)

It then builds merged template variables.

Merge behavior

It merges:

  • profile infra
  • profile components
  • operator flags
  • PlatformMesh.spec.values
  • PlatformMesh.spec.ocm
  • exposure-derived variables

Also renders templates inside values

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.


1.2 Renders and applies fixed infra deployment templates

From gotemplates/infra/..., it renders deployment resources for built-in infra components such as:

  • cert-manager
  • traefik
  • traefikCRDs
  • gateway-api
  • etcd-druid
  • prometheus-operator-crds
  • opentelemetry-operator
  • Argo-only AppProject (platform-mesh-runtime)

Depending on deployment technology, it renders:

  • Flux objects:
    • HelmRelease
    • sometimes Kustomization
  • or Argo objects:
    • Application
    • AppProject

Cluster placement

  • deployment CRs go to the infra client
  • related OCM Resource objects go to the runtime client

So even built-in infra components are split into:

  • runtime-side artifact descriptors
  • infra-side rollout objects

1.3 Renders and applies generic PM service deployment templates

From gotemplates/components/..., it renders service deployment resources driven by the profile.

For each enabled service, it can create:

Runtime-side OCM objects

  • chart Resource like <service>-chart
  • image Resource like <service>-image or a custom name

Infra-side deployment objects

  • one Flux HelmRelease
  • or one Argo Application

This is the operator chunk responsible for generating the rollout resources for most PM services.


1.4 Computes ordering and dependency behavior

Auto-calculates Argo sync waves

If ArgoCD is used, it computes syncWave from dependsOn unless the user already set one.

Prunes dependencies on disabled components

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.

Resolves deployment namespaces

It distinguishes:

  • releaseNamespace
  • deploymentNamespace
  • helmReleaseNamespace

This allows the deployment CR to live in one namespace while the workload goes to another.


1.5 Avoids fighting with ResourceReconciler

The operator has explicit anti-conflict logic between:

  • DeploymentSubroutine (renders base HelmReleases / Applications)
  • ResourceReconciler (patches repo URLs, chart versions, image tags, etc. from OCM Resource.status)

For Argo Applications, it preserves:

  • spec.source.repoURL
  • spec.source.targetRevision
  • image versions injected into spec.source.helm.values

For Flux HelmReleases, it preserves:

  • image values injected by ResourceReconciler
  • spec.suspend=false if ResourceReconciler unsuspended the release

This uses the in-memory ImageVersionStore.

So the operator contains explicit logic to prevent its own controllers from overwriting each other.


1.6 Manages rebac-authz webhook cert/bootstrap glue

The operator applies the following manifests from manifests/k8s/rebac-auth-webhook/:

  1. Issuer
    • rebac-authz-webhook-issuer
  2. Certificate
    • rebac-authz-webhook-cert
  3. Secret stub
    • kcp-webhook-secret

What kcp-webhook-secret contains

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.

Then it updates that kubeconfig CA bundle

It reads:

  • rebac-authz-webhook-cert secret
  • takes ca.crt
  • rewrites certificate-authority-data inside kcp-webhook-secret

Then it restarts kcp pods

If the kubeconfig CA changed, it deletes kcp pods so they reload the new webhook kubeconfig.

This is a major cross-component integration responsibility.


1.7 Gates on cert-manager CRDs before webhook cert work

Before managing those webhook cert resources, it explicitly waits for CRDs such as:

  • issuers.cert-manager.io
  • certificates.cert-manager.io

So cert-manager readiness is part of the operator's orchestration logic.


1.8 Optionally enforces Istio sidecar presence on itself

If Istio integration is enabled:

  • it waits for istio-istiod deployment 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.


1.9 Waits for kcp control-plane primitives

Still inside deployment, it requires runtime-side:

  • RootShard Available=True
  • FrontProxy Available=True

before finishing successfully.


2. KcpsetupSubroutine

This subroutine owns most kcp bootstrap work.

2.1 Builds kcp admin access

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.


2.2 Collects identity hashes and CA bundles for template injection

Before applying kcp manifests, it gathers:

APIExport identity hashes from root kcp

  • tenancy.kcp.io
  • shards.core.kcp.io
  • topology.kcp.io

CA bundles from runtime-cluster secrets

  • 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.


2.3 Applies the kcp manifest tree recursively

From manifests/kcp/, it bootstraps workspaces and API surface.

Top-level workspaces/types

It creates/applies things like:

  • workspace platform-mesh-system
  • workspace providers
  • workspace orgs

Workspace types:

  • security
  • providers
  • orgs
  • org
  • account
  • provider

In root:platform-mesh-system

It applies:

  • APIExports:
    • core.platform-mesh.io
    • system.platform-mesh.io
    • providers.platform-mesh.io
  • APIBindings:
    • core
    • system
  • APIExportEndpointSlice
  • APIResourceSchemas for:
    • accounts
    • accountinfos
    • authorizationmodels
    • identityproviderconfigurations
    • invites
    • stores
    • providers
    • providerpermissions
    • UI content/provider metadata
  • KCP init CRDs
  • ContentConfigurations
  • kcp-side admission webhook configs
  • welcome IdentityProviderConfiguration

In root:orgs

It applies:

  • Store named orgs

In root:providers

It applies:

  • workspace system

2.4 Wires kcp admission webhooks

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

2.5 Wires WorkspaceAuthenticationConfiguration

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 welcome IdentityProviderConfiguration.status.managedClients
  • alternate username/email handling when feature-disable-email-verification is enabled

Important coupling

  • welcome IPC status -> kcp auth audiences

So the operator uses one CR's observed status to drive another part of the auth system.


2.6 Applies extra workspaces and extra default API bindings

From the PlatformMesh spec it also handles:

  • spec.kcp.extraWorkspaces
  • spec.kcp.extraDefaultAPIBindings

This lets the PM installation extend the default kcp topology.


2.7 Special retry behavior for IdentityProviderConfiguration

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.


3. ProviderSecretSubroutine

This subroutine creates kubeconfig secrets consumed by PM services so they can talk to kcp or virtual workspaces.

3.1 Chooses provider connections

It builds the final provider connection list from:

  • default provider connections
  • spec.kcp.providerConnections
  • spec.kcp.extraProviderConnections
  • feature-specific additions

If terminal-controller-manager is enabled, it additionally creates:

  • terminal-controller-manager-kubeconfig

3.2 Default kubeconfig secrets it creates

By default it manages these secrets:

  • account-operator-kubeconfig
  • rebac-authz-webhook-kubeconfig
  • security-operator-kubeconfig
  • kubernetes-graphql-gateway-kubeconfig
  • virtual-workspace-clusteraccess-kubeconfig
  • extension-manager-operator-kubeconfig
  • iam-service-kubeconfig
  • portal-kubeconfig
  • security-initializer-kubeconfig
  • security-terminator-kubeconfig
  • virtual-workspaces-kubeconfig
  • init-agent-kubeconfig

And optionally:

  • terminal-controller-manager-kubeconfig

These are direct cross-component integration artifacts.


3.3 Creates two kinds of kubeconfigs

A. Admin-auth kubeconfigs

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

B. Scoped kubeconfigs

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.


3.4 Rewrites virtual workspace URLs

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.


4. FeatureToggleSubroutine

This applies optional kcp feature manifests.

Known feature toggles include:

  • feature-enable-getting-started
  • feature-enable-marketplace-account
  • feature-enable-marketplace-org
  • feature-accounts-in-accounts
  • feature-enable-account-iam-ui
  • feature-enable-terminal-controller-manager
  • feature-enable-provider-permissions
  • feature-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.


5. WaitSubroutine

This is the reconciliation barrier.

5.1 Waits for deployment resources

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.

5.2 Verifies WorkspaceAuthenticationConfiguration

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.


6. ResourceReconciler

This controller watches OCM Resource objects and mutates deployment objects based on resolved artifact status.

This is a major glue layer.

6.1 For FluxCD

For chart resources (artifact=chart)

Depending on repo:

  • repo=oci -> creates/updates OCIRepository
  • repo=git -> creates/updates GitRepository
  • repo=helm -> creates/updates HelmRepository, then patches HelmRelease chart version

For image resources (artifact=image)

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

6.2 For ArgoCD

Chart resources

It patches Application.spec.source:

  • repoURL
  • targetRevision

based on whether the OCM resource resolved to:

  • helm repo
  • git repo
  • OCI chart

Image resources

It patches Application.spec.source.helm.values with the resolved image tag.


6.3 Uses metadata conventions on Resources

It interprets annotations/labels such as:

  • repo
  • artifact
  • for
  • path
  • version-path
  • image-ref
  • unsuspend

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.


6.4 Reads runtime profile to locate deployment CRs

It looks up from the runtime-side profile ConfigMap:

  • deploymentTechnology
  • deploymentNamespace

This tells it whether it should patch:

  • Flux objects
  • or Argo objects
  • and in which namespace

7. Provider-related controllers in the same binary

These are separate from PM core installation, but they are part of the same operator today.


7.1 ProviderReconciler

Watches Provider objects via kcp APIExport/multicluster provider.

ProviderWorkspaceSubroutine

  • creates dedicated provider workspace under root:providers:<name>-<cluster>
  • waits for it to become Ready
  • deletes it on finalization

ScopedKubeconfigSubroutine

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.


7.2 ManagedProviderReconciler

This is the runtime-side convenience API.

It runs these steps:

  1. wait for referenced PlatformMesh to be Ready
  2. create/adopt a Provider in kcp
  3. wait for Provider to become Ready
  4. copy provider kubeconfig Secret from kcp workspace into runtime cluster
  5. deploy runtime components for that provider

Runtime deployments it can create

  • Flux OCIRepository
  • Flux HelmRepository
  • Flux HelmRelease
  • or inline OCM Repository / Component / Resource that eventually feed a Flux release

It also supports deploying to an alternate runtime cluster via runtimeKubeconfigSecretName.


8. Concrete strings/connections the operator ties between components

This is the most important practical summary.

Auth / webhook wiring

  • rebac-authz-webhook-cert -> kcp-webhook-secret CA data
  • kcp-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

KCP / IdP wiring

  • welcome IdentityProviderConfiguration.status.managedClients -> JWT audiences in orgs-authentication
  • exposure/base domain -> welcome IPC redirect URIs + kcp auth issuer URL

OCM / deployment wiring

  • runtime-side OCM Resource.status.* -> infra-side Flux sources / versions
  • runtime-side OCM image Resource status -> 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

Kubeconfig distribution

  • cluster-admin / root shard CA / APIExportEndpointSlice / APIExport definitions -> service-specific kubeconfig secrets for PM components

Self-management

  • istio-istiod readiness -> operator pod self-restart if missing sidecar
  • webhook CA rotation -> kcp pod restart

9. What the operator is doing beyond "installing charts"

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

10. Bottom line

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment