Skip to content

docs: add CMK product vision and tenancy model#14

Open
isanmaz wants to merge 6 commits into
mainfrom
feature/cmk-product-vision
Open

docs: add CMK product vision and tenancy model#14
isanmaz wants to merge 6 commits into
mainfrom
feature/cmk-product-vision

Conversation

@isanmaz

@isanmaz isanmaz commented Jun 16, 2026

Copy link
Copy Markdown
Contributor

open questions are documented in the tenancy model with proposals. Review and alignment needed before these are considered final.

Comment thread product-vision/cmk-product-vision.md Outdated
- Role-based access control via OIDC / RBAC
- Full CMK UI — own web interface, not embedded in any platform portal

**Key hierarchy:**

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The whole Key hierarchy is always in the scope of the tenant!

Below each level were set in different scopes! From the Krypton perspective, all of the levels are in Tenant Scope.
From the Platform Mesh perspective, it may be in different scopes.

Comment thread product-vision/cmk-product-vision.md Outdated
| L1 | Root Key | Tenant | Customer — registered via OpenKCM CMK |
| L2 | Domain Key | Workspace | OpenKCM CMK — internal |
| L3 | Service Key | Service | Krypton — internal |
| L4 | Data Encryption Key | Workload | Krypton — internal |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

L4 is not a Krypton internal. Krypton doesn't have anything internal, what is telling to it will do.
Something from external should tell to Krypton to create a L4 key !

Comment thread product-vision/cmk-product-vision.md Outdated
|---|---|---|---|
| L1 | Root Key | Tenant | Customer — registered via OpenKCM CMK |
| L2 | Domain Key | Workspace | OpenKCM CMK — internal |
| L3 | Service Key | Service | Krypton — internal |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

L3 is not a Krypton internal. Krypton doesn't have anything internal, what is telling to it will do.
Something from external should tell to Krypton to create a L4 key !

Comment thread product-vision/cmk-product-vision.md Outdated
| Level | Name | Scope | Managed by |
|---|---|---|---|
| L1 | Root Key | Tenant | Customer — registered via OpenKCM CMK |
| L2 | Domain Key | Workspace | OpenKCM CMK — internal |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

L2 is not a CMK internal.
OpenKCM CMK - should have the capabilities over the CMK UI, admin to create and manage the L2 , same for L3 and L4.

L1 & L2 - should be sent to Krypton as well.

Comment thread product-vision/cmk-product-vision.md Outdated
| L3 | Service Key | Service | Krypton — internal |
| L4 | Data Encryption Key | Workload | Krypton — internal |

The customer only ever registers and manages the L1 key. Everything below is derived and managed internally by OpenKCM CMK and Krypton.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The customer should manage the whole chain from L1 to L4!

Comment thread product-vision/cmk-product-vision.md Outdated
| L1 Root Key | Customer (via OpenKCM CMK) | Register, bind to L2, rotate, revoke, kill switch |
| L2 Domain Key | Platform Mesh (automatic) | View, bind L1 to L2 — cannot create or delete |
| L3 Service Key | Krypton (automatic) | View status — see open question below |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Missing the L4.

L4 is not a Krypton internal. Krypton doesn't have anything internal, what is telling to it will do.
Something from external should tell to Krypton to create a L4 key !

Comment thread product-vision/cmk-product-vision.md Outdated
|---|---|---|
| L1 Root Key | Customer (via OpenKCM CMK) | Register, bind to L2, rotate, revoke, kill switch |
| L2 Domain Key | Platform Mesh (automatic) | View, bind L1 to L2 — cannot create or delete |
| L3 Service Key | Krypton (automatic) | View status — see open question below |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

L3 is not a Krypton internal. Krypton doesn't have anything internal, what is telling to, it will do.
Something from external should tell to Krypton to create a L3 key !

Comment thread product-vision/cmk-tenancy-model.md Outdated

## Overview

This document defines the tenancy model for OpenKCM CMK Platform Mesh. It describes the entities, their relationships, and the key binding model that governs how customer-owned encryption keys are applied across a Platform Mesh deployment.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unfortunately, I don't see here described the tenant modeling!

@dweidenfeld dweidenfeld left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Realign the key hierarchy with the Platform Mesh / OpenBao tenancy boundary

Reviewed against what we aligned on in the Apeiro service-layer sync (2026-06-17) with the OpenBao team. Picking up Nicolai's point that the tenant model isn't spelled out yet (cmk-tenancy-model.md:11) — here's the boundary I think it should use.

What we learned about OpenBao. OpenBao runs as a single instance deployed together with the Platform Mesh / Showroom installation. It does not tenant at account level only — it exposes a nested tenancy that starts at organization level (one OpenBao tenant per organization), with account-level nesting below, mirroring the KCP workspace hierarchy. Every organization gets its own OpenBao tenant.

OpenBao is our priority keystore backend and L1 material lives there, so OpenKCM's key placement should follow the same boundary instead of diverging:

  • L1 Root Key → organization level. One L1 per organization (= the org workspace in Platform Mesh), not per account.
  • L2 Domain Key → account level. Each account derives its own L2 from the org's registered L1; the account owner requests it — they don't handle root key material.
  • L3 / below → namespace / service, shifting down accordingly.

Net: a one-level shift up of the current diagram (L1 account→org, L2 namespace→account).

On the current Showroom instance. It does today place "organizations" at account level — but that's a demo simplification, not the target model. We run a single organization with multiple accounts so we can show all the MSPs (services from different companies) side by side in one place. For a real deployment — shared Platform Mesh or air-gapped — the organization is always the first level, and each company is its own org. The doc should describe the target (org-first), not the demo shortcut.

Permission concept (missing today). The doc models one account-level "Security Admin" that both registers L1 and binds keys. With L1 at org level this needs a split:

  • L1 is org-scoped and privileged — only OpenKCM operators / org-level security admins register, rotate, reattach or revoke L1. A regular account user must not be able to touch or reattach L1.
  • L2 is account-scoped — the account owner requests and manages an L2 bound to the org's L1, within their account only.

Inline comments mark the specific spots.

⚠️ To be clear: these are my own current thoughts on the structure, not settled review requests. Think of them as notes-to-self capturing the changes I assume we'll want — written down so I (and we) remember them. The right place to actually decide this is the placement follow-up I'm organizing (PM + OpenKCM + OpenBao), so let's treat these as input to that meeting rather than as final direction.

Comment thread product-vision/cmk-tenancy-model.md Outdated
## Entities

### Account
The top-level administrative boundary. Represents one customer organization. One account has exactly one workspace. The account is the tenant — pressing the kill switch at account level locks the entire account.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The tenant boundary should be the organization, not the account. In Platform Mesh a customer organization maps to an org workspace (own Keycloak realm + OpenFGA store + kcp subtree); an account is a subdivision below it. OpenBao tenants per organization too (one instance, nested org→account, confirmed in the 2026-06-17 sync). The current Showroom instance does put orgs at account level — but only as a demo simplification (one org, many accounts = different companies' MSPs shown together); for any real shared or air-gapped deployment the org is the first level. Proposal: make the organization the tenant + L1 owner; keep the account as the L2 boundary below it.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for your comments @dweidenfeld .
Let's differenciate two use cases and get clear about which usecase we want to cover.

  1. air-gapped env: cloud infra provider/platform operator (showroom) and platform consumer/customer/account holder for all the account are the same Org: e.g. Company X have deployed Platform Mesh and have their different departments: Production, Test. For each department they have dedicated an Account (workspace). Here I agree with your tenant boundry model. Provider and consumer are same company. A role based permission on the key operations are enough here to control all keys from Org level.

  2. enterprise env: the cloud provider/operator/platform operator is different than the platform consumers/customers. Here we have company X as platform operator offering a cloud infra services. e.g. HSM/OpenBao to Account holders who are different companies. each company has an account and they want a key management and a HSM connection for their compony. They later define their departments into namespaces. So they need a key management cross namespaces.

Open Question: Should we cover the second usecase at all? or is the assumption of the Platform Mesh is always the air-gapped env where customer operates/owns/deploys the Platform.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @isanmaz, the two-use-case split is the right framing and I think it resolves cleanly once we separate three boundaries we keep collapsing into one: the identity boundary (Keycloak realm / IdP), the control-plane boundary (kcp workspace), and the crypto boundary (OpenKCM tenant / HSM). They don't have to coincide.

On UC1 (air-gapped, provider = consumer) we fully agree: org = tenant, L1 at org, departments = accounts, role-based perms enough.

On UC2 (enterprise, provider ≠ consumer) I'd push back on the implicit assumption that each customer company = an account under the operator's org. I'd model each customer as its own org (own realm + OpenFGA store + kcp subtree + OpenBao tenant). That dissolves the tension you described:

  • Single pane of glass is preserved: L1 at the customer's org gives them cross-account / cross-namespace management and a kill switch over their own org.
  • Sovereignty is preserved: because the org is the customer's, not a shared operator org, the operator isn't sitting in the customer's identity/key tree. No shared realm, no org-role cascade between distinct customers.
  • The residual "operator can technically reach everything" concern (kcp system:masters etc.) is a separate boundary, and is exactly what the standalone CMK outside Platform Mesh is for. That's where operator-proof sovereignty comes from, not from pushing customers down to account level.

This also fits @nnicora's points above (:72, :110, :111): if L2/L3/L4 aren't Krypton-internal and must be requested externally, then L2 is naturally an account-scoped, requestable key bound to the org's already-registered L1, not an auto-provisioned internal. Org-L1 → account-L2 → namespace-L3 makes that explicit.

So: should we cover UC2? Yes, that's the enterprise commercial case. The key point is what an "org" actually is in the real world: an org is SAP, Telekom, Siemens, each with their own IdP, so the L1 key lives at that org level. The Showroom is misleading here because we currently model the whole Showroom as a single org, purely as a demo convenience. Our accounts under it aren't customers, they're developer / demo accounts that showcase specific integrations, so they're effectively at department level already, i.e. L2. In other words the Showroom layout already maps to org→account = L1→L2; it just collapses many "companies" into one demo org. For a real shared deployment each of SAP / Telekom / Siemens is its own org with its own L1. Net proposal: customer = org, L1 at org, account = L2, namespace = L3, identical in both UC1 and UC2, with UC2 just adding the standalone-CMK option for operator-proof crypto sovereignty.

This lines up with the draft tenancy RFC (architecture#61) and the OpenBao single-instance nested org→account model. Probably worth settling in the joint alignment meeting.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Resolved for me. With the detailed tenancy model removed, the product vision no longer prescribes one hierarchy. Customers can choose organization or account level deployment.

Comment thread product-vision/cmk-tenancy-model.md Outdated
Comment on lines +60 to +70
+----------------------+
| L1 Root Key |
+----------------------+
| L1KeyID |
| AccountID |
| Name |
| Status |
| KeystoreType | ← OpenBao, AWS KMS, Azure KV, HSM...
| KeystoreRef | ← reference only, no key material stored
| RegisteredBy | ← Security Admin
+----------------------+

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

L1 keys off AccountID here. With L1 at org level this becomes OrganizationID (the org workspace), and the chain is Org · L1 → Account · L2 → Namespace · L3. Suggest redrawing the ER model one level up: Organization → Account → Namespace, with L1/L2/L3 attached respectively.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Landed for Model 1: the L1 row is now keyed OrgID/AccountID and placement is org-level. Ok to resolve.

Comment thread product-vision/cmk-tenancy-model.md Outdated
A Kubernetes namespace within the workspace. Each namespace has exactly one L2 Domain Key, provisioned automatically by Platform Mesh when OpenKCM CMK Platform Mesh is enabled.

### L1 Root Key
A customer-owned root encryption key. Registered by the security admin at account level. Key material never leaves the customer's external keystore — OpenKCM CMK holds only a reference. One account can have multiple L1 root keys. Each L1 key is backed by one external keystore.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Propose L1 at organization level. The org registers one or more L1 root keys; accounts below derive L2s from them. Single root-of-trust per organization, aligned with the OpenBao org tenant — instead of every account holding its own root.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Landed: L1 is now registered at org level in Model 1. Ok to resolve.

Comment thread product-vision/cmk-tenancy-model.md Outdated
Comment on lines +153 to +155
### L2 Domain Key
Provisioned automatically by Platform Mesh when OpenKCM CMK Platform Mesh is enabled — one per namespace. The security admin cannot create or delete L2 keys. The admin can bind an L1 key to an L2 key. All services in a namespace are encrypted under that namespace's L2 key.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

With L1 at org level, L2 belongs at account level: each account has its own L2, and the account owner requests an L2 bound to the org's already-registered L1 (self-service against an existing root — no root-key handling at account level). This also lines up with Nicolai's point on :72 that L2 shouldn't be a purely auto-provisioned internal — it's an account-scoped, manageable key. L3 then shifts down to namespace/service.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

L2-at-account landed. Retracting the 'account owner requests L2' part, I agree L2 is auto-provisioned. Ok to resolve.

Comment thread product-vision/cmk-tenancy-model.md Outdated
Comment on lines +132 to +134
### Security Admin
A user with account-level permissions in Platform Mesh. Responsible for registering L1 root keys, binding them to L2 domain keys, and triggering the kill switch. The security admin operates from the account-level OpenKCM CMK UI.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One account-level role isn't enough once L1 is org-scoped. Split into an org-level L1 administrator (OpenKCM operator / org security admin) who registers, rotates, reattaches and revokes L1 — and an account-level L2 owner who requests/manages the account's L2 against the org L1. A normal account user must not be able to reattach or change L1.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Addressed: Security Admin is now scoped per model and L2 is auto-provisioned, so a separate account-level L2-owner role isn't needed. Ok to resolve.

Comment thread product-vision/cmk-tenancy-model.md Outdated
Comment on lines +218 to +236
A customer organization (e.g. ACME Corp) runs workloads on a shared Platform Mesh installation operated by someone else. They are one of many tenants on the platform.

- OpenKCM CMK Platform Mesh is the right product
- UI sits at **account level** — the tenant manages their own keys within their account
- Kill switch scope: the account — does not affect other tenants
- CMK Controller is shared platform infrastructure, but key governance is per-tenant

```
Platform Mesh (shared installation)
├── Account: ACME Corp ← OpenKCM CMK UI here
│ └── Workspace → Namespaces → Services
├── Account: VW ← OpenKCM CMK UI here
│ └── Workspace → Namespaces → Services
└── Account: Siemens ← OpenKCM CMK UI here
└── Workspace → Namespaces → Services
```

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In a real shared Platform Mesh, ACME / VW / Siemens are distinct organizations (each its own realm + OpenFGA store + kcp subtree + OpenBao tenant), not accounts under one shared org. The account-level layout shown here matches our current Showroom demo — one org with several accounts so we can display multiple companies' MSPs together — but that's a demonstration shortcut, not the target. For both shared and air-gapped deployments the org is the first level; recommend drawing each customer as an organization with L1 at the org level.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This thread is outdated after the rewrite. I'm re-raising the substance as a fresh comment on the current Scenario 1 block, so this one can be resolved.

Comment thread product-vision/cmk-product-vision.md Outdated

**Key capabilities:**

- L1 Root Key registration at account level — one registration covers all namespaces in the account

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same placement point: org-level registration, covering all accounts (and their namespaces) under the organization.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Landed: org-level L1 registration covering all accounts is in. Ok to resolve.

Comment thread product-vision/cmk-product-vision.md Outdated
Comment on lines +98 to +100
The OpenKCM section appears at account level in the Platform Mesh portal — not inside a namespace. Each account has one workspace, and that workspace contains multiple namespaces. When OpenKCM is enabled, Platform Mesh automatically provisions one L2 Domain Key per namespace.

The security admin registers the organization's L1 root key at account level. She then binds that L1 key to the L2 Domain Keys that Platform Mesh has provisioned — one binding per namespace. Once bound, all workloads running in that namespace are encrypted under the L1→L2 key chain.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The text already calls it the organization's L1 root key but places it at account level — that's the contradiction to resolve. If it's the organization's root key, register it at organization level; accounts bind/derive L2 below.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Resolved in the rewrite: L1 is now explicitly org-level in Model 1, no longer the account-level contradiction. Ok to resolve.

Comment thread product-vision/cmk-product-vision.md Outdated
Comment on lines +104 to +112
All key levels (L1, L2, L3) are managed from a single account-level UI. What actions are available depends on the key level and the user's role:

| Key level | Generated by | Admin actions |
|---|---|---|
| L1 Root Key | Customer (via OpenKCM CMK) | Register, bind to L2, rotate, revoke, kill switch |
| L2 Domain Key | Platform Mesh (automatic) | View, bind L1 to L2 — cannot create or delete |
| L3 Service Key | Krypton (automatic) | View status — see open question below |

The security admin sees the full key chain for the account in one place. Actions are only available where the admin has authority — Platform Mesh-generated and Krypton-generated keys are visible but not creatable or deletable by the admin.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This table is the right place to encode the permission concept (and it's where Nicolai is already flagging L3/L4 on :110/:111). Add the scope/role split: L1 = org scope, OpenKCM operator / org security admin only (register, rotate, reattach, revoke); L2 = account scope, account owner (request L2 from org L1, manage within account). Make explicit that account-level users cannot register or reattach L1.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Addressed: the role table now encodes this (Security Admin registers L1, Workspace Admin view-only, Developer none). Ok to resolve.

@dweidenfeld

Copy link
Copy Markdown

Cross-linking for the tenancy alignment: I've opened a draft RFC on platform tenancy (organization-level vs account-level company placement, and where the IdP and the cryptographic/governance boundary live as a consequence). It overlaps directly with the tenancy model proposed here and is meant as a pre-read for the upcoming Platform Mesh / OpenKCM / OpenBao alignment meeting.

architecture#61 (SAP-internal): https://github.tools.sap/ApeiroRA/architecture/pull/61

The OpenBao boundary from my review above (single OpenBao instance, nested tenancy starting at organization level with account nesting below, mirroring the KCP workspace hierarchy) is captured there as well.

@isanmaz

isanmaz commented Jun 24, 2026

Copy link
Copy Markdown
Contributor Author

OpenKCM tenancy model tension:

  • Account-level OpenKCM → clean sovereignty, account holder fully in control, but you lose cross-workspace management (main value of our product). If the account holder has 10 workspaces, they need to manage keys per workspace. No single pane of glass across accounts.

    • Org-level OpenKCM → single pane of glass, cross-workspace kill switch, but the platform provider has org-level visibility into key configuration. Sovereignty is weaker.

    So the real question for your product vision is: who is the target customer?

    • If it's a Managed Service Provider offering sovereign cloud to their customers (e.g. Siemens offering Platform Mesh to their business units) → account-level is the only acceptable model. Each business unit must own their OpenKCM.
    • If it's a large enterprise running Platform Mesh for themselves (e.g. Siemens IT running Platform Mesh for Siemens internally) → org-level works because the platform provider and account holder are the same organization.

isanmaz added 2 commits June 24, 2026 18:45
Signed-off-by: isanmaz <aysan.mazlumi@gmail.com>
…-mesh-vision

Signed-off-by: isanmaz <aysan.mazlumi@gmail.com>
@isanmaz
isanmaz force-pushed the feature/cmk-product-vision branch from 0834bb4 to 51b3407 Compare June 24, 2026 16:47
… with dual deployment model

Signed-off-by: isanmaz <aysan.mazlumi@gmail.com>
@isanmaz
isanmaz marked this pull request as ready for review June 24, 2026 17:02
Comment thread product-vision/cmk-tenancy-model.md Outdated
The customer's own key management system where L1 key material lives. Supported backends: OpenBao, AWS KMS, Azure Key Vault, GCP KMS, HSM via PKCS#11. OpenKCM CMK never stores key material — it holds a pointer and calls the keystore at runtime via Krypton.

### Key Binding
The association between an L1 Root Key and an L2 Domain Key. Created by the security admin. One L2 Domain Key is bound to exactly one L1 Root Key. One L1 Root Key can be bound to multiple L2 Domain Keys (multiple accounts can share the same L1 key). Different accounts can be bound to different L1 keys — the admin decides.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agree L2 should be auto-provisioned (retracting my earlier "account owner requests L2" framing). One refinement on the mechanism: rather than the security admin manually binding L1 to L2, the L2 should be created by a kcp init-agent (https://github.com/kcp-dev/init-agent) that runs on account/workspace initialization and derives the L2 from the parent's L1 automatically. So the L1 to L2 binding is inherited from the parent, not a manual admin assignment, and no user ever actively creates or binds an L2. That also pins the hierarchy down: the parent holding the L1 must be the org, which is the natural place for the init-agent to read it from. (Matches Nicolai's point too: L2 isn't Krypton-internal, the init-agent is the external trigger.)

Trade-off to flag: auto-derive-from-parent drops the "different accounts bound to different L1 keys, the admin decides" flexibility. But that flexibility only matters if accounts are different companies (Model 2); with account = department, one org L1 auto-derived to all its accounts is the cleaner model.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the init-agent proposal — auto-provisioning L2 on workspace initialization makes sense and we're aligned on that. One thing worth flagging on the auto-derive-from-parent model though:

a Customer Management Key should explicitly supports attaching different tenants/accounts to different L1 keys — the security admin decides which L1 governs which account. This isn't just a Model 2 (different companies) concern. Consider a single org with data residency requirements:

Org: Siemens
├── Account: EU-prod → L1-EU (key material in Frankfurt)
├── Account: US-prod → L1-US (key material in Virginia)
└── Account: R&D → L1-RD (separate compliance boundary)

One org, one company, three L1 keys — each account bound to a different L1 for geographic or compliance reasons. Auto-derive from a single parent L1 breaks this completely.

The manual binding step is what gives the security admin the ability to say "this account falls under this L1." Without it, you're locked into one L1 per org, which doesn't satisfy data residency or multi-compliance-boundary requirements within a single organization.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Resolved for me. The L2 provisioning mechanism was an implementation detail of the deleted tenancy model and is no longer part of this PR.

Comment thread product-vision/cmk-tenancy-model.md Outdated
- OpenKCM CMK Platform Mesh is the right product
- CMK Controller scoped to that account — one L2 provisioned for that account
- Kill switch scope: that account only — does not affect other tenants
- Platform provider has no visibility into any account's key governance

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the one place I'd still push back. In Scenario 1 (Model 2), ACME / VW / Siemens are modelled as accounts under one shared operator org. For genuinely distinct companies on a shared Platform Mesh, each should be its own organization (own Keycloak realm + OpenFGA store + kcp subtree + OpenBao tenant), not an account under the operator. Two consequences:

  • This "no visibility" claim isn't what Platform Mesh enforces today: org roles cascade into child accounts via OpenFGA get/update from parent, and platform operators bypass workspace authz entirely (system:masters / adminAuth: true). HYOK protects key material in the keystore, but key bindings and operations live in the control plane and stay reachable from the org above. So account-level enablement under a shared org is soft isolation, not the sovereignty the scenario claims.
  • If each company is its own org instead, Scenario 1 and Scenario 2 converge: every company enables at its own org level (Model 1), gets the single pane of glass + kill switch over its own departments, and the operator holds nothing. The only case that genuinely needs "accounts as tenants" is the single-company one, where accounts = departments, which is exactly Scenario 2.

Net: account = department (subdivision of a company), org = company. Worth settling at the alignment meeting; ties directly into your open question on the two APIExports.

cc @aaronschweig, this is the org-vs-account placement question from the Platform Mesh side. Whether OpenKCM can enable at org level (and how the FGA cascade / operator authz actually scopes visibility) depends on Platform Mesh, so it'd be good to have you in on this one.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So the conclusion and to be confirmed in the meeting :

  • Account = department (subdivision within a company) — always
  • Org = company — always

So if ACME, VW, and Siemens are three different companies on a shared Platform Mesh, they should each be their own org, not accounts under one shared operator org. Putting them as
accounts under a shared org gives the platform operator visibility into all of them — which breaks sovereignty.

The only valid "accounts as tenants" case is something like:

Org: Siemens (one company)
├── Account: Siemens-Finance (department)
├── Account: Siemens-R&D (department)
└── Account: Siemens-Manufacturing (department)

Here accounts are departments of the same company. Siemens owns the org, Siemens owns all the accounts — no sovereignty problem because it's all one entity.

So Model 2 as documented — where ACME, VW, Siemens are separate companies each enabling OpenKCM at account level under a shared operator org — doesn't exist as a valid architecture.
This needs to be confirmed by security architects as well to garantee the sovereignty.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Resolved for me. The product vision leaves organization or account level deployment to the customer, and the prescriptive model was removed.

@isanmaz isanmaz self-assigned this Jul 7, 2026
@isanmaz isanmaz added documentation Improvements or additions to documentation help wanted Extra attention is needed pmcmk Platform Mesh CMK — delivery via Platform Mesh microfrontend labels Jul 7, 2026

@mjudeikis mjudeikis left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In general this document has one big blind spot - it builds ontop that system tracks account to organization and back. kcp does not do that (workspace tree is just visual representation). So this would need to come from platfrom-mesh layer, either in form of seaprate api or dedicated virtual-workspace.

Overall this required some different layer to be developed for providers to be able act as org level provider or account level provider. Only later exists now.

Comment on lines +59 to +61
**Model 1 (org-level enablement):** OpenKCM enabled at org level → CMK Controller provisions one L2 for every existing account in the org. Every new account created afterwards gets an L2 automatically.

**Model 2 (account-level enablement):** Each account enables OpenKCM independently → CMK Controller scoped to that account provisions one L2 for that account only.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How do you envision this happening? On the dataplane every account is one plain structure. This implies you need to maintain some relationship between entities from different account & organizations?

@isanmaz isanmaz Jul 8, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

By that I am assuming that there is no cross account concept yet for platform mesh and for Model 1 to be possible. and also the assumtion is that the company sits on the account level (to be verified)

We need to validate Platform Mesh requirements for key and policy goverance.

A platform operator needs to manage key policy, rotation, audit, and revocation across all tenant accounts from a single governance layer — without any tenant being able to see or affect another tenant's keys, and without the operator being able to read tenant data.

isanmaz added 2 commits July 9, 2026 13:14
Based on 2026-07-09 alignment meeting with Platform Mesh team. kcp does
not track account-to-organization relationships as a structural primitive —
the workspace tree is visual only. Model 1 (org-level OpenKCM) requires
Platform Mesh to build an org-level provider API first.

- Add platform dependency callout at top of both documents
- Mark Model 1 as future-state / blocked throughout
- Confirm Model 2 (account-level) as only currently deliverable model
- Correct role separation section: Platform Mesh is not opinionated about
  authorization — OpenKCM defines its own role model via provider permissions
- Update last_updated dates to 2026-07-09
@isanmaz
isanmaz force-pushed the feature/cmk-product-vision branch from 1b42238 to ffac5f6 Compare July 14, 2026 07:29
@isanmaz

isanmaz commented Jul 14, 2026

Copy link
Copy Markdown
Contributor Author

Update — 2026-07-14

Based on the Platform Mesh alignment meeting (2026-07-09) and review feedback, this PR has been updated:

What changed:

  • cmk-platform-mesh-vision.md and cmk-tenancy-model.md have been removed from this PR — these are deployment-specific documents and will be maintained separately.
  • cmk-product-vision.md and cmk-standalone-vision.md remain — these describe OpenKCM CMK as a product concept and are the right content for this repo.

On the review feedback:

  • @nnicora — the Platform Mesh-specific content you reviewed is no longer in scope for this PR.
  • dweidenfeld's point about L1 at org level vs account level has been resolved by the 2026-07-09 Platform Mesh meeting: account level is confirmed as the only currently deliverable model. The org-level model is blocked pending Platform Mesh building an org-level provider API.

This PR is now ready for re-review. Scope is minimal — two product vision docs for the OSS community.

@dweidenfeld

Copy link
Copy Markdown

Since the tenancy model has now been removed from this PR, should we update the title as well? It still says "add CMK product vision and tenancy model".

@dweidenfeld dweidenfeld left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

With the deployment-specific documents removed, my previous concerns are resolved. The important point for me is that OpenKCM does not prescribe organization or account level deployment. Customers can choose either model and define access through provider-specific roles. Current Platform Mesh limitations can be documented separately from the target product vision.

The PR title should still be updated to match the remaining scope.

@dweidenfeld

Copy link
Copy Markdown

@isanmaz all my remaining review comments are resolved from my side. I added notes to the three threads where this was not already explicit. GitHub does not let me resolve the threads myself because I do not have the required repository permission. Could you please close them?

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

Labels

documentation Improvements or additions to documentation help wanted Extra attention is needed pmcmk Platform Mesh CMK — delivery via Platform Mesh microfrontend

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants