Namespace model

An Enclavr namespace is the complete configuration boundary for a fleet. OpenBao stores its canonical documents; the Go control plane materializes, validates, and consumes them without merging a second provider.

Open the namespace model full size

Canonical documents

OpenBao namespace
├── assets.<namespace>             required: hosts, sites, templates, features
├── secrets.<namespace>            required: scalar runtime fields
├── users.<namespace>              required: managed-user personal details
├── aws-vpc-bastion.<namespace>    optional when referenced
├── forgejo.<namespace>            optional when enabled
├── malcolm.<namespace>            optional when enabled
├── tailnet.<namespace>            optional for tailnet policy operations
└── referenced Caddy documents     optional; titles are selected by assets

OpenBao's KV payload uses document for the stored envelope. Materialization exposes JSON/text document components and named scalar fields; runtime settings in secrets.<namespace> are read by field name. The internal item representation still understands legacy notesPlain metadata, but it is not an external authentication or seal-custody source.

There is no data.<namespace>, confidential.<namespace>, or standalone sites.<namespace> source. All scalar runtime fields live in secrets.<namespace>; whether a field is ordinary or concealed is metadata, not a second hierarchy.

Four representations, four responsibilities

1. Stored document: OpenBao KV v2 holds the typed sparse envelope and version history.
2. Materialized document: the repository restores the complete compatibility representation without losing identity, metadata, field order, or unowned content.
3. Effective assets: named host templates are expanded into a complete host configuration and validated against the embedded Draft 2020-12 schema.
4. Resolved action input: only the selected deployment action resolves the protected templates it needs, in memory.

This separation prevents a partial Go struct from reconstructing an assets document and prevents plans or logs from becoming secret-bearing.

Assets hierarchy

assets.<namespace>/document contains:

• namespace-wide settings and the schema version;
• one host_sites registry, including mobile, with canonical network CIDRs;
• a default host template;
• platform templates for operating-system and architecture policy;
• execution templates for physical, virtual, EC2, or WSL shape;
• ordered role templates for reusable capabilities;
• sparse host instances that own identity, placement, selected templates, and exceptional overrides.

host_site is placement only. It never selects an operating-system execution profile. A host may name only a site in this one registry.

Host selection and planning

Local deployment compares the operating system's exact hostname with hosts[].hostname. A unique match is planned; no match is a successful no-op; duplicates are invalid. Enclavr does not select by alias, IP address, site, operating system, or a command-line hostname override.

The Go planner owns feature policy, defaults, ordering, and protected-input selection. Shell adapters receive complete, validated action envelopes and perform operating-system mutation only.

Logical references after migration

References retain the form op://<namespace>/<item>/<field> after OpenBao migration. This is Enclavr's stable logical namespace syntax. With configr_secret_store_provider=openbao, the OpenBao repository resolves the reference directly; the op:// prefix does not invoke the 1Password CLI.

Inspect without displaying values

./enclavr namespace inspect --namespace <namespace>
./enclavr config validate

Inspection verifies required and referenced documents through the selected provider and reports value-free issues. To change a document, use Edit private data safely; never patch a generated host artifact as a substitute for its source.

On the exact declared namespace writer, inspection uses that host's existing writer connection from openbao_roles, after verifying the namespace, cluster and AppRole identity. The report labels the selected inspection identity. This lets the management host inspect service documents that its ordinary deployment consumer does not need. Browse config and Edit config use the same verified management identity before loading their initial snapshots. Other hosts retain their accepted consumer scope. An inaccessible or rejected declared writer connection stops inspection; Enclavr does not fall back, expand permissions, or change the runtime .env connection. When no writer has been declared yet, inspection remains within the accepted host connection's scope.

Manage OpenBao host access

Launch ./enclavr → Config → OpenBao access on the declared namespace writer. The tables show host role assignments and live permission state. Select a row and press e to edit permissions, Space to enable or disable its role, a to create a role, or d to remove it. Forms require review with r and explicit confirmation with y. New resources require recorded approval; disabled roles retain their credentials. Other hosts are denied with the writer's hostname and IP address. AppRole presence is reported separately from unverified host-side enrollment acceptance.

Before opening a role form, Enclavr refreshes the writer's repository assets.<namespace> from the complete validated OpenBao document. Differing local content is preserved in a private, content-addressed backup under logs_enclavr_local/openbao-access/assets-backups/. Identical JSON is left untouched, including formatting and modification time. A failed read or backup stops before the form opens. Browsing the tables does not refresh files, and opening a form does not publish namespace data or change permissions.

Save still checks for changes made after the form opened, so another editor cannot silently overwrite a newer local or authoritative document. Reopen the form when a concurrent change is reported; interrupted confirmed changes keep their protected retry checkpoint.