net-kingdom/docs/adr/ADR-0007-security-orchestration-boundary.md

ADR-0007 - Security Orchestration Boundary

Status: Accepted Date: 2026-05-18 Refined: 2026-05-21 (meta-orchestration layer — see below) Deciders: Bernd Worsch, Codex

Context

The recursive platform security architecture needs careful sequencing: host trust, cluster trust, bootstrap secrets, runtime secret authority, runtime identity, runtime authorization, tenant onboarding, and readiness verification.

That sequencing crosses NetKingdom and Railiance ownership boundaries. NetKingdom owns the canonical security architecture, IAM Profile, credential/bootstrap standards, and authorization semantics. Railiance owns deployment layering for infrastructure, clusters, platform services, and applications. OpenBao adds an important runtime-secret authority to the platform control plane, but it does not change those ownership boundaries.

Creating a dedicated orchestration repo too early would risk encoding temporary bootstrap order and accidental stack assumptions as a permanent interface. Leaving every sequence implicit would also be risky: platform root actions, OpenBao initialization, policy import, and tenant onboarding must be auditable and repeatable.

Decision

Security orchestration will stay in Railiance playbooks for now.

NetKingdom will define the trust-state model, readiness checks, policy semantics, OpenBao boundaries, and tenant/control-plane rules. Railiance playbooks will own the concrete deployment sequencing across railiance-infra, railiance-cluster, railiance-platform, and railiance-apps.

A dedicated orchestration repo is deferred until the sequencing surface is stable enough to justify its own product boundary. If created later, it must coordinate safe sequencing and readiness reporting; it must not own security policy semantics or bypass Railiance stack ownership.

Consequences

• NK-WP-0006 is implemented as architecture, standards, ADRs, and workplan constraints rather than a new repo.
• OpenBao bootstrap, unseal/recovery, audit, backup, and workload-secret delivery belong in Railiance platform playbooks, governed by NetKingdom standards.
• Cross-repo readiness should be reported as checks against explicit trust states, not as a hidden imperative script.
• A future orchestration repo needs a new ADR before creation.

Future Repo Trigger

Revisit a dedicated orchestration repo only if at least two of these are true:

• multiple Railiance deployments need the same security sequencing interface;
• readiness reporting becomes a reusable artifact consumed by operators, agents, or CI;
• rollback and recovery workflows need a cross-repo state machine that no single Railiance layer can own cleanly;
• tenant onboarding becomes a repeatable workflow spanning identity, flex-auth, Topaz, OpenBao, object storage, and application repos.

Alternatives Considered

Create A Dedicated Orchestration Repo Now

This would give sequencing a visible home, but it would probably encode unstable details before OpenBao runtime operations, flex-auth/Topaz policy import, and tenant onboarding have enough implementation feedback.

Put Orchestration In NetKingdom

NetKingdom owns the security model, but it should not become the deployment repo for every stack layer. This would blur architecture ownership with platform deployment ownership.

Leave Sequencing Entirely Informal

This avoids premature structure but leaves bootstrap and runtime trust transitions too dependent on operator memory. The accepted approach keeps the sequence explicit while leaving concrete deployment in the Railiance stack.

Refinement (2026-05-21): Meta-Orchestration Layer

The original decision left "what NetKingdom does about orchestration" defined only negatively (it does not own deployment mechanics). This refinement names the positive role. It sharpens, and does not overturn, the accepted decision: execution stays in Railiance.

There are two distinct layers:

• Railiance — execution orchestration (the "how"). A library of scenario playbooks plus the tools that run them. Each playbook provisions a slice of the landscape, ships sensible defaults, and exposes parameters for tuning. Multiple playbooks exist for multiple scenarios.
• NetKingdom — meta-orchestration (the "what" and "who"). NetKingdom does not re-implement deployment mechanics. It (1) selects the services and playbooks a given scenario requires, (2) decides parametrization where tuning is warranted and otherwise relies on playbook defaults, and (3) holds the responsibility map — which element (a Railiance layer, an external provider, a tenant-owned piece) owns what across the whole IT landscape.

The relationship is architect ↔ contractor (or conductor ↔ players): NetKingdom composes the score and assigns parts; Railiance executes them. This is the same discipline used elsewhere — the IAM Profile is the contract while key-cape/Keycloak are implementations, and the State Hub is a read model over execution. Meta-orchestration is a decide/compose layer over Railiance's execute layer.

This binds directly to the capability ladder (docs/platform-identity-security-architecture.md → Capability Progression): the ladder is the menu, a scenario selects a subset of tiers, and meta-orchestration is the act of binding that subset to playbooks + parameters + a responsibility map, producing a turn-key landscape.

New Dependency — Playbook / Capability Contract

For NetKingdom to select and parametrize reliably, Railiance playbooks must publish a declared interface: the capability each playbook provisions, its parameters (with defaults and constraints), and the responsibility it claims. This catalog is the orchestration-layer analog of the IAM Profile. Without it, meta-orchestration composes against implicit behavior and breaks when a playbook changes. Establishing this contract is the prerequisite for any concrete meta-orchestration work.

Effect on the Future Repo Trigger

Meta-orchestration logic now has a clear home (NetKingdom) regardless of whether a dedicated execution-orchestration repo is later created under the Future Repo Trigger above. A future repo, if created, would host reusable execution sequencing — not the scenario-composition and responsibility-mapping role, which remains NetKingdom's.