Claims and Service Offerings

Claims and Service Offerings provide a self-service API above the concrete OpenBaoCluster lifecycle API.

Design status

This design note describes the current same-cluster Claims and Service Offerings direction. The feature is in integration and remains subject to API review, documentation review, security review, and release validation.

Summary

OpenBaoClusterClaim is the planned tenant-facing service request API for OpenBao clusters.

It gives a tenant one place to request an OpenBao service instance without requiring direct access to the full OpenBaoCluster workload specification. Platform operators define approved service shapes. The claim resolves that service intent into the concrete lifecycle resources the operator already knows how to manage.

OpenBaoCluster still exists. It remains the concrete workload API, the direct advanced path, and the object same-cluster claims materialize into.

Problem statement

Without a claim layer, tenants must interact with the concrete workload API too early. That leaks low-level lifecycle knobs into a self-service workflow and makes it harder for platform operators to offer curated, repeatable service classes.

Claims separate:

• tenant-facing service intent
• platform-owned offerings and profiles
• internal approved service contracts
• rendered execution contracts
• concrete runtime materialization

User-facing model

The claim model keeps the tenant surface small. A tenant selects an approved offering or service profile and provides only the parameters that the platform chose to expose.

Diagram

Claim resolution model

Claims express service intent. The platform catalog and internal contracts render that intent into a concrete lifecycle object.

The important rule is that the claim path does not bypass the core lifecycle contract. If the direct OpenBaoCluster API cannot represent a rendered service shape honestly, the claim path blocks instead of silently weakening that shape.

Technical model

The same-cluster path resolves service intent through a bounded pipeline:

1. Validate the claim, tenant reference, and selected service offering or profile.
2. Load immutable platform-owned catalog inputs.
3. Bind an approved service contract.
4. Render same-cluster execution inputs.
5. Materialize or patch the deterministic claim-managed OpenBaoCluster.
6. Publish claim-facing status and connection output.

The concrete workload remains visible and owned. Claim-managed clusters are machine-distinguishable from directly managed clusters through ownership labels and admission protection.

Current implementation status

The same-cluster path is in integration. The implementation branch is integration/claims-service.

Current same-cluster work includes:

• tenant and service selection
• immutable catalog inputs
• approved and rendered internal contracts
• claim-managed OpenBaoCluster materialization
• Development and bounded Hardened service shapes
• SelfInit bootstrap as the supported claim-managed bootstrap posture
• cluster-internal, Gateway, and Ingress exposure projection where supported
• bootstrap dependency projection through ConfigMaps or Secrets where supported
• storage, read replica, upgrade strategy, and first-wave backup projection
• claim-facing status and connection publication
• admission guardrails for claim-managed child objects
• workflow events and claim-native status for supported operations

Security and ownership model

The claim path is intentionally fail-closed.

Security and ownership boundaries include:

• tenant namespace access still flows through explicit tenant onboarding
• claim-managed child objects carry ownership markers
• non-controller identities cannot spoof or mutate claim ownership markers
• claim-managed child deletion is guarded
• connection output custody is bound to the claim
• unsupported shapes remain blocked until the concrete lifecycle API can carry them honestly
• secret values stay out of CRDs, status, logs, and events

The claim controller does not need broad tenant object discovery for arbitrary ConfigMap, Secret, or Gateway objects. Dependencies stay explicit so the controller can remain narrow in multi-tenant environments.

Rollout and upgrade posture

The first public model is deliberately conservative after materialization.

Fields that change the service contract, tenant binding, or backup partitioning are treated as rollout-sensitive. Ordinary claim edits should not trigger hidden migration, adoption, or replacement behavior.

Supported rollout and upgrade workflows should be explicit. When a requested change cannot be classified safely, the operator should block the change and surface status instead of guessing.

Non-goals

The initial Claims and Service Offerings surface does not include:

• generic import of unmanaged OpenBao clusters
• ordinary claim-reconcile adoption of directly managed OpenBaoCluster objects
• arbitrary mutation of low-level workload fields through the claim API
• broad bootstrap modes beyond the supported claim-managed posture
• ongoing in-band management of auth methods, policies, secret engines, or audit devices after bootstrap
• secret-value movement between clusters

Open questions

Open design questions include:

• how much of the Service Offering alias layer should be exposed in the first public API
• which claim upgrade classes should be tenant-facing and which should remain platform-admin workflows
• how adoption of existing direct OpenBaoCluster objects should be handled without weakening ownership safety

Related work

This design note connects to:

• Roadmap
• Operator invariants
• Known limitations