Catalog Admission for Existing OpenBao Lanes

Catalog admission and infrastructure ownership are separate decisions. A lane may already exist on a shared OpenBao mount and already reach its workload through External Secrets Operator or Kubernetes auth. Adding that lane to the secrets-engine catalog must not imply that secrets-engine may create the mount, replace workload delivery, or broaden an existing role.

Admission dimensions

Mount management

mount_management describes only who creates the OpenBao secrets-engine mount.

Value	Plan and apply behavior
`engine`	The guarded plan may include a `kv-mount` action; apply ensures the mount exists. This is the compatibility default for existing catalog entries.
`existing`	The plan emits a non-mutating `kv-mount-check`; apply never calls mount creation. Provisioning may still update the exact cataloged KV path after approval.

Shared production mounts such as platform must use existing unless a separate infrastructure decision explicitly delegates mount administration.

Native delivery authentication

delivery_auth describes how secrets-engine itself obtains a scoped token for positive verification and exec-time delivery. It does not describe or replace workload authentication.

delivery_auth:
  method: approle
  management: engine
  # Optional safe overrides when the catalog id contains an admin-like term.
  policy_name: se-prod-forgejo-operator-token
  role_name: se-prod-forgejo-operator-token

Management	Meaning
`engine`	A reviewed apply may create/update the exact read policy and AppRole for this lane.
`existing`	Policy and AppRole are externally managed. `role_name` is mandatory; plan/apply emit checks only and never mutate either object.
`none`	No native verification or exec delivery is available. Use only for catalog-only metadata without native delivery modes.

The current native implementation supports AppRole. An entry that declares exec-env, exec-file, npm-config, read-check, or wrapped must therefore declare delivery auth. exec-file and wrapped remain reserved schema modes; they are not implemented by secrets-engine exec yet.

Engine-managed AppRoles may bound token_ttl, token_max_ttl, secret_id_ttl, secret_id_num_uses, and token_num_uses. The admitted high-risk drafts use 15-minute tokens, a 30-minute maximum, single-use secret_id values, and eight token uses.

Existing workload delivery

workload_delivery records non-secret facts about delivery already operated by another repository. Every item names both the mechanism and its owner.

workload_delivery:
  - mode: external-secrets
    owner: rapp-example

This metadata is evidence and review context. apply, provision, verify, and exec do not change ESO objects, Kubernetes auth roles, deployments, or provider accounts.

Example: existing production mount plus native exec adapter

id: example-runtime-api-key
kind: kv
org: coulomb
repo: example-service
stage: prod
mount: platform
path: workloads/example-service/runtime
mount_management: existing
fields: [EXAMPLE_API_KEY]

consumers:
  - name: example-service-runtime
    auth: kubernetes
    claim: system:serviceaccount:example:example-service
    purpose: production runtime access through ESO

workload_delivery:
  - mode: external-secrets
    owner: rapp-example-service

delivery_modes: [exec-env, read-check]
delivery_auth:
  method: approle
  management: engine

# approval, verification, rotation, deactivation, and audit remain required.

The guarded plan may propose a new exact-path delivery policy and AppRole after approval, but it emits only a check for the shared platform mount. The existing Kubernetes/ESO delivery remains untouched.

Admission checklist

Before accepting an existing production lane:

Confirm exact mount, path, and field names from the current owner.
Set mount_management: existing for shared or pre-provisioned mounts.
Record existing workload delivery and its repository owner.
Decide separately whether native delivery auth is engine-managed, existing, or absent.
Use exact policy/role overrides when the catalog id would trip broad-admin name guards; never weaken path or capability guards to accommodate a name.
Mark high-risk lanes explicitly; they require named rotation and deactivation owners and cannot use bootstrap-only approval.
Link a resolved approval before live apply, provisioning, verification, rotation, revoke, or exec. Every privileged live command fails closed when that approval cannot be resolved.
Preserve the interim route until native positive and negative verification passes without exposing a value.

4.7 KiB Raw Blame History