2. Requirements and Invariants
2. Requirements and Invariants
← Previous: Introduction | Index | Next: Architecture →
This section defines the constraints and invariants that shape all subsequent architectural and implementation decisions. No design presented in later sections MAY violate the principles established here.
2.1 Core Problem Restatement
The platform REQUIRES a secrets management system that:
- scales with organizational and infrastructure growth,
- eliminates human-driven operational workflows,
- enforces correctness through system guarantees rather than conventions,
- remains reproducible and auditable over time,
- and operates independently of any single operator, workstation, or external SaaS UI.
The system MUST work under the assumption that:
- clusters MAY be destroyed and rebuilt,
- teams and operators will change,
- and failures will occur.
The architecture MUST therefore be resilient by construction, not by discipline.
2.2 Design Goals
2.2.1 Secrets as First-Class Platform Resources
Secrets MUST be treated as:
- explicit entities,
- with defined ownership,
- lifecycle stages,
- and documented relationships to consuming systems.
A secret's existence, scope, and purpose MUST be observable and auditable, not implicit.
2.2.2 Git as the Source of Intent, Not Runtime State
Git MUST define:
- which secrets exist,
- why they exist,
- where they are consumed,
- and how they are initially introduced.
Git MUST NOT define:
- the current runtime value of rotating secrets,
- short-lived credentials,
- or secrets whose lifecycle is managed dynamically.
This distinction is foundational.
2.2.3 Vault as the Runtime Authority
All non-bootstrap secrets MUST ultimately be owned by a runtime secrets system.
That system MUST:
- enforce access control,
- track metadata and expiry,
- support rotation,
- and act as the single runtime source of truth.
Kubernetes MUST NOT be the system of record for secrets.
2.2.4 Zero Human-In-The-Loop for Steady-State Operations
After initial bootstrap, the system MUST operate without requiring humans to:
- remember rotation schedules,
- re-run scripts,
- apply secrets manually,
- or restart workloads explicitly.
Human involvement is permitted only for:
- initial trust establishment,
- policy changes,
- and exceptional recovery scenarios.
2.2.5 Deterministic Bootstrap
Given:
- a Git repository,
- a cryptographic root of trust,
- and a Kubernetes cluster,
the system MUST be able to reach a fully operational state deterministically.
Bootstrap MUST NOT depend on:
- undocumented steps,
- local machine state,
- or operator-specific knowledge.
2.2.6 Cloud and Provider Agnosticism
The architecture MUST:
- function on-premises,
- avoid hard dependencies on cloud-managed services,
- and remain portable across environments.
Cloud integrations MAY exist but MUST NOT be required for correctness.
2.2.7 High Availability by Design
Wherever feasible, the system SHOULD:
- avoid single points of failure,
- degrade gracefully,
- and recover automatically.
Where HA is not immediately possible, the design MUST allow it without re-architecture.
2.3 Non-Goals
The following are explicitly out of scope for this architecture:
2.3.1 Application-Level Secret Reload Logic
How applications reload secrets (hot reload vs restart) is an application concern.
The platform guarantees secret propagation, not application behavior.
2.3.2 CI/CD as a Control Plane
CI/CD systems MAY exist, but:
- they MUST NOT be required for cluster correctness,
- they MUST NOT be the source of truth for secrets,
- and they MUST NOT hold exclusive authority over secret state.
The platform MUST remain operational without CI/CD.
2.3.3 Human-Friendly Secret Editing Interfaces
This architecture prioritizes correctness and automation over interactive UX.
Any UI is a convenience layer, not a dependency.
2.3.4 Cross-System IAM Design
User identity, RBAC, and organizational IAM models are intentionally excluded.
This system focuses solely on machine-consumed secrets.
2.4 Architectural Invariants
The following rules are non-negotiable invariants. Violating any of these invalidates the design.
Invariant 1 — Git MUST Be Sufficient for Reconstruction
Given Git and the platform itself, a cluster MUST be rebuildable.
No external UI state, dashboards, or undocumented secrets MAY be required.
Invariant 2 — Bootstrap Secrets Are Temporary Scaffolding
Secrets required before the runtime system exists:
- MUST be explicitly classified as bootstrap secrets,
- MUST be encrypted at rest in Git,
- and MUST NOT be reused by applications.
They MUST be retired once runtime authority is established.
Invariant 3 — Rotation MUST NOT Require Git Changes
Rotating a secret MUST NOT require:
- committing to Git,
- re-encrypting files,
- or reapplying manifests manually.
Rotation is a runtime concern.
Invariant 4 — Authority Transfers MUST Be Explicit
Any transition of ownership (e.g., bootstrap → runtime) MUST be:
- intentional,
- observable,
- and auditable.
Implicit or accidental duplication of authority is forbidden.
Invariant 5 — Kubernetes Is a Consumer, Not an Authority
Kubernetes Secrets exist only to satisfy application consumption requirements.
They are derived artifacts, not sources of truth.
Invariant 6 — No Hidden Control Planes
Any system capable of mutating secret state is a control plane.
All such systems MUST be:
- visible,
- documented,
- and intentionally introduced.
Scripts, workstations, and dashboards MUST NOT silently function as control planes.
Invariant 7 — Internal Secrets MUST Traverse Vault (v1.1)
Secrets generated by in-cluster operators that require cross-namespace distribution:
- MUST be pushed to Vault via PushSecret,
- MUST be pulled from Vault via ExternalSecret,
- and MUST NOT be directly copied between namespaces.
This ensures:
- audit trail for all cross-namespace secret access,
- rotation coordination through a single authority,
- and policy enforcement at the Vault layer.
Direct namespace-to-namespace secret copying violates the single-authority principle and creates hidden data flows.
See Section 5a for the complete framework.
Invariant 8 — Configuration Data MAY Use Secret Distribution (v1.1)
Non-sensitive configuration data (endpoints, ports, connection parameters) that requires cross-namespace distribution:
- MAY use the same PushSecret/ExternalSecret pattern,
- MUST use separate Vault paths from secrets (
platform-config/vsplatform-data/), - and MUST NOT be treated as a security boundary.
Configuration distribution is a convenience mechanism for centralized discovery and management, not a security control.
See Section 5a.5 for path conventions.
2.5 Operational Philosophy
The system is designed around the following operational beliefs:
- Automation is not optional — it is a correctness requirement.
- Human memory is not a dependency.
- Failures will happen; recovery MUST be routine.
- Security comes from structure, not secrecy.
- Convenience is achieved by removing repetition, not by adding shortcuts.
This philosophy informs every tradeoff made later in the design.
2.6 Success Criteria
This architecture is considered successful if:
- Secrets rotate without human intervention.
- Clusters can be rebuilt without manual secret recreation.
- Auditors can trace secret provenance and lifecycle.
- Platform engineers are not required to remember operational rituals.
- The system remains understandable years after its creation.
Document Navigation
| Previous | Index | Next |
|---|---|---|
| ← 1. Introduction | Table of Contents | 3. Architecture → |
End of Section 2