Workspaces

kcp workspaces are isolated Kubernetes-shaped API endpoints sharing a single process. Platform Mesh maps the account model directly onto the workspace tree: organizations, accounts, providers, and the platform-mesh-system workspace are all kcp Workspace objects.

The account-operator creates and reconciles them.

Primitives

Primitive	Platform Mesh role	Upstream
Workspace (tenancy.kcp.io/v1alpha1)	One per organization, account, or provider.	Workspaces
WorkspaceType	Defines API surface, default bindings, and parent/child constraints. Platform Mesh ships orgs, org, account.	Workspace types
LogicalCluster (core.kcp.io/v1alpha1)	Singleton cluster object inside each workspace. The kcp.io/path annotation is what Platform Mesh controllers route on.	Logical clusters

Workspace types Platform Mesh ships

The orgs workspace type — the parent of every organization — extends universal, default-binds the Platform Mesh core APIs, and references a WorkspaceAuthenticationConfiguration (see Identity and authorization):

# platform-mesh-operator/manifests/kcp/workspace-type-orgs.yaml
apiVersion: tenancy.kcp.io/v1alpha1
kind: WorkspaceType
metadata:
  name: orgs
spec:
  defaultAPIBindings:
    - export: core.platform-mesh.io
      path: root:platform-mesh-system
    - export: system.platform-mesh.io
      path: root:platform-mesh-system
  defaultChildWorkspaceType:
    name: org
    path: root
  extend:
    with:
      - name: universal
        path: root
  limitAllowedChildren:
    types:
      - name: org
        path: root
  authenticationConfigurations:
  - name: orgs-authentication

The account type composes the security extension (which contributes the IAM Store reconciliation), restricts parents to org or account, and default-binds the workspace-type APIs needed for nesting:

# platform-mesh-operator/manifests/kcp/workspace-type-account.yaml
apiVersion: tenancy.kcp.io/v1alpha1
kind: WorkspaceType
metadata:
  name: account
spec:
  defaultAPIBindings:
    - export: core.platform-mesh.io
      path: root:platform-mesh-system
    - export: tenancy.kcp.io
      path: root
    - export: topology.kcp.io
      path: root
  defaultChildWorkspaceType:
    name: account
    path: root
  limitAllowedChildren:
    types: [{ name: account, path: root }]
  limitAllowedParents:
    types:
      - { name: org, path: root }
      - { name: account, path: root }
  extend:
    with:
      - { name: universal, path: root }
      - { name: security, path: root }

Workspace instances

The :root:orgs workspace is the root of every organization tree:

# platform-mesh-operator/manifests/kcp/workspace-orgs.yaml
apiVersion: tenancy.kcp.io/v1alpha1
kind: Workspace
metadata:
  name: orgs
spec:
  type:
    name: orgs
    path: root

Org and account workspaces below it are created by the account-operator from Account CRs. See Watch and sync for the controller pattern.

Hierarchical paths

Workspace paths use : as the separator. The Platform Mesh tree looks like:

root
├── platform-mesh-system     # core APIExports, IAM stores, marketplace
├── orgs
│   └── <org-name>
│       └── <account>
│           └── <sub-account> ...
└── providers
    └── <provider-name>      # provider workspaces with APIExports

Controllers reference workspaces by path in Workspace.spec.type.path, in APIBinding.spec.reference.export.path, and in APIExport.spec.permissionClaims[*].identityHash lookups.

Lifecycle hooks

WorkspaceType supports spec.initializer and spec.terminator flags. When set, kcp delays the Ready / Removed phase until the workspace is processed by an external controller. The endpoints those controllers consume are documented in Virtual workspaces. The security-operator implements the terminating phase for accounts.

Related

• Account model — the design rationale for the workspace tree
• API sharing — how defaultAPIBindings resolve
• Watch and sync — how controllers create and reconcile workspaces
• Virtual workspaces — initializer/terminator endpoints