# AEGIS — Deployment Architecture

- **Document ID:** ARCH-25
- **Phase:** D — Deployment & Long View
- **Status:** Draft for review (post four-reviewer discipline)
- **Version:** 0.1
- **Date:** 2026-07-10
- **Owner:** Chief Security Architect

---

## 1. Purpose

Specify the framework for deploying AEGIS across every supported topology while preserving all Phase A–C properties. This document is topology-agnostic; specific topologies live in ARCH-26 (Reference Deployment Models).

## 2. Deployment Principles

1. **Self-hosted first.** Every capability must run on customer-owned infrastructure. Hosted mode (future) is additive, never replacing.
2. **Air-gap first-class.** Zero runtime egress path must be a supported topology (per ARCH-02 D-02-2).
3. **Trust boundaries are structural, not procedural.** Recovery Domain (ARCH-18) and Kernel separation are enforced by network + identity + storage, not just policy.
4. **Cloud-optional.** No capability requires cloud egress; providers are pluggable.
5. **Reproducible from source.** Every deployment is reproducible from a signed release bundle + a signed configuration bundle (ARCH-22).
6. **Cloud-off integration test.** Every release must pass an integration test with no external network egress (per NF-8.8).

## 3. Deployment Concerns (Universal)

Every topology addresses these regardless of scale:

### 3.1 Identity Chain
- Z0 root (offline HSM or software-emulated HSM for dev/small VPS).
- Kernel intermediate CA operated by the Kernel process.
- Engine SVIDs issued on attestation (ARCH-09).
- Workload identity provider: SPIFFE-compatible; in K8s uses SPIRE or equivalent; on VPS uses TPM-quote where available or enrollment tokens.

### 3.2 Network Zones
- **Public** (ingress from tenants + log sources).
- **Runtime** (engines, control plane, event plane).
- **Recovery Domain** (isolated per ARCH-18; separate namespace/segment/account).
- **Ceremony** (bastion/console access for privileged operations).
- No lateral movement between zones without Kernel-mediated policy.

### 3.3 Data Substrates
- **Control plane:** PostgreSQL (Prisma).
- **Event plane:** ClickHouse.
- **Control bus:** NATS (mTLS + subject-ACL).
- **Event bus:** Kafka or Redpanda (per ARCH-07 D-03).
- **Object store:** S3-compatible (self-hosted MinIO, or cloud-native).
- **KMS / HSM:** cloud-KMS in cloud; PKCS#11 device or YubiHSM for VPS; software HSM for dev only.

### 3.4 Admission Control
- Cluster-level policies (Kyverno / OPA Gatekeeper on K8s) enforce:
  - Signed image digests.
  - SLSA-3+ provenance.
  - Container base image allow-list.
  - Network policy defaults (deny all except explicit).
- Documented default policy bundles ship with each topology.

### 3.5 DNS / TLS
- External TLS: TLS 1.3 with hardened cipher profile; ACME or admin-managed cert (per topology).
- Internal mTLS: mandatory (ARCH-09).
- HSTS + secure headers where applicable.

### 3.6 Cloud-off Integration Test
- Every deployment topology has a variant of the release CI where all external network egress is blocked at the sandbox level.
- Test corpus exercises v0 capabilities end-to-end.
- Failure blocks release.

## 4. Scaling Patterns

- **Vertical (single-node) — small deployments.** Kernel + Engines colocated under one supervisor; PostgreSQL + ClickHouse on same host with separate volumes.
- **Horizontal (K8s) — multi-node.** Each engine as its own Deployment/StatefulSet; Kernel replica set; per-tenant partitioning of Kafka topics + ClickHouse tables.
- **Multi-region (future hosted).** Per-region Kernel cluster; per-tenant region pinning; cross-region only under explicit policy.

## 5. Upgrade Path

- Signed release bundle contains: images (digest-pinned), SBOM, SLSA provenance, config bundle skeleton, verifier CLI.
- Blue/green for engines that support it; canary tenant subset first.
- Kernel rotation follows ARCH-13 §7 ceremony.
- Rollback: previous signed bundle retained; automated on failure signals.

## 6. Observability Baseline (from ARCH-20)

- Prometheus for metrics; OpenTelemetry for traces.
- AEGIS's own self-monitoring runs on a separate observability pool (independent of tenant-facing metrics).
- Alerting integrates with the on-call rotation (ARCH-21).

## 7. Independent Architecture Review

- **F-1.** *Topology-agnostic framework may miss topology-specific pitfalls.* Concrete topologies in ARCH-26 exercise the framework; drift detected by cloud-off + canary integration tests.
- **F-2.** *K8s attestation alone is insufficient.* Complemented by Identity Engine fleet directory + Kernel-side heuristics (per ARCH-06).
- **F-3.** *Air-gap adds release-engineering complexity.* Accepted; per D-02-2 cost.

## 8. Adversarial Architect Review

- **A-1.** *Attacker exploits topology drift between doc and running deployment.* Config Management (ARCH-22) drift monitor catches; deployment config is a signed artifact.
- **A-2.** *Compromised admission controller lets a bad image in.* Admission policies signed; image-signature verification independent of admission controller; RIV verifies at runtime (ARCH-13).
- **A-3.** *Cloud account compromise reads runtime data.* Envelope encryption; Recovery Domain separate account; KMS in customer-owned tenancy where offered.

## 9. Operational Reliability Review

- **O-1.** Reference topologies drilled at least biannually (ARCH-23).
- **O-2.** Upgrade playbook per topology; canary metrics gate promotion.
- **O-3.** Documented sizing + capacity signals; auto-scale where safe.
- **O-4.** Multi-tenant fairness in shared substrates (Kafka partitions, ClickHouse resource pools).

## 10. Self-Critique

- **S-1.** *"Cloud-off" tests may not exercise the full matrix (Kafka, ClickHouse, NATS mixed states).* Added: cloud-off harness matrix documented per topology; regression tests grow with topology count.
- **S-2.** *KMS choice per topology could become inconsistent.* ARCH-11 crypto strategy pins choices; documented per ARCH-26.
- **S-3.** *Air-gap release-engineering discipline decays without drilling.* Air-gap release drill scheduled — every release channel runs its air-gap variant before shipping.

Revising in place: added air-gap release drill as a release gate (feeds into ARCH-28).

## 11. First-Target Analysis and Redesign

**Target: admission control configuration.** If admission policies are misconfigured or bypassed, unsigned/malicious images could reach production. Response: admission policies are signed configuration (ARCH-22 C-A class); drift monitor detects; canary integration test verifies admission enforcement each release; **admission bypass is itself a SEV-1 alarm**.

**Second target:** identity chain bootstrap in single-node/VPS deployments (weaker HSM). Response: documented as a **lower assurance level** (per ARCH-27); software-HSM only for dev; VPS uses PKCS#11 device baseline.

## 12. Decisions

### D-25-1. Topology-agnostic framework + specific ARCH-26 topologies

- **Advantages.** Framework stability + concrete guidance.
- **Disadvantages.** Two docs to maintain.
- **Alternatives.** *Single omnibus doc.* Rejected — unfocused.
- **Reason.** Layering keeps each doc reviewable.

### D-25-2. Cloud-off integration test as release gate

- **Advantages.** Enforces provider-independence structurally.
- **Reason.** Constitutional principle.

## 13. Open Questions

- Q-25-1. Exact admission-policy set per K8s distribution (Kyverno vs. OPA Gatekeeper defaults). Resolved in ARCH-26.
- Q-25-2. Sizing per NF-3.1 (10M events/day baseline). Resolved in ARCH-26.

## 14. Change Log

- **0.1 (2026-07-10)** — Initial draft after four-reviewer discipline.