generated from coulomb/repo-seed
tegwick
88a30e3c0a
- ADR-0007: refine (not overturn) the orchestration boundary with the two-layer model — Railiance executes parametrized playbooks, NetKingdom does meta-orchestration (scenario->playbook selection, parametrization, responsibility map). Add the playbook/capability-contract dependency as the prerequisite, analogous to the IAM Profile. - INTENT.md: add "Why NetKingdom" (the kingdom metaphor: governed, defended, living/evolving, tended by its people); Principle 7 (Meta-Orchestration over Re-Implementation); an Operating Model section (kaizen-agent workforce for recurring duties + change/improvement); and matching Direction-of-Evolution entries. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
143 lines
6.3 KiB
Markdown
143 lines
6.3 KiB
Markdown
# 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.
|