Appendix A

Appendix A — Architectural Decision Framework

How to Use This Appendix

Each decision is identified by a chapter-prefixed ID (e.g., Ch7-D-03 ) that matches exactly the ID used in that chapter's Key Decisions Addressed section. To read the full decision record, navigate to the referenced chapter and section number.

Decisions are organised by chapter in document order:

  • Section 1 — The Platform and Portainer: Chapter 2
  • Section 2 — Upstream Dependencies: Chapters 3–6
  • Section 3 — Downstream Dependencies: Chapters 7–12

Deployment Scenarios

The five reference deployment topologies for Portainer — from a single-cluster starter to a fully air-gapped enterprise fleet — are documented in Chapter 2, section 2.11 . Each scenario is labelled with a Platform Maturity Framework level (L1–L5).

Chapter 2 — Portainer Deployment Reference

  • Ch2-D-01 — Server Placement — see section 2.2
  • Ch2-D-02 — Agent Mode Selection — see section 2.3
  • Ch2-D-03 — Portainer Server Replica Count — see section 2.4
  • Ch2-D-04 — Data Persistence and Backup — see section 2.6
  • Ch2-D-05 — Off-Cluster Backup Storage — see section 2.6
  • Ch2-D-06 — Ingress and WebSocket Support — see section 2.4
  • Ch2-D-07 — Certificate Management — see section 2.7
  • Ch2-D-08 — Certificate Expiry Alerting — see section 2.7
  • Ch2-D-09 — Terraform Provider Adoption — see section 2.8
  • Ch2-D-10 — Release Track — see section 2.9
  • Ch2-D-11 — Audit Log Forwarding — see section 2.10
  • Ch2-D-12 — Database Encryption at Rest — see section 2.10
  • Ch2-D-13 — Identity-Based Access Control Only — see Chapter 4
  • Ch2-D-14 — External Alert Routing — see section 2.10
  • Ch2-D-15 — Mutual TLS for Agent–Server Communication — see section 2.7

Chapter 3 — Cluster Creation and Configuration

  • Ch3-D-01 — Kubernetes Distribution — see section 3.2
  • Ch3-D-02 — Node Operating System — see section 3.2
  • Ch3-D-03 — CNI Selection — see section 3.3
  • Ch3-D-04 — Traffic Routing Model — see section 3.4
  • Ch3-D-05 — Storage Tiers and CSI — see section 3.5
  • Ch3-D-06 — Cluster Profiles — see section 3.6
  • Ch3-D-07 — Cluster Provisioning Tooling — see section 3.7
  • Ch3-D-08 — Existing Cluster Onboarding — see section 3.8
  • Ch3-D-09 — Profile Orchestration Tooling — see section 3.7
  • Ch3-D-10 — Control Plane HA Topology — see section 3.2.3
  • Ch3-D-11 — CIDR and Subnet Planning — see section 3.3
  • Ch3-D-12 — Cluster Upgrade Strategy — see section 3.7
  • Ch3-D-13 — cert-manager Is a Mandatory Baseline Component — see section 3.5
  • Ch3-D-14 — DNS-01 Challenge Solver Required for Production Certificates — see section 3.5
  • Ch3-D-15 — Internal CA Issuer for Air-Gapped and Regulated Environments — see sections 3.5 and 8.2
  • Ch3-D-16 — ExternalDNS Ownership ID Must Be Unique Per Cluster — see section 3.5

Chapter 4 — Identity and Access Management

  • Ch4-D-01 — Namespace Isolation and Tenancy — see section 4.5
  • Ch4-D-02 — Team-Level Multi-Tenancy (Capsule) — see section 4.5
  • Ch4-D-03 — Authentication Provider — see section 4.2
  • Ch4-D-04 — Group Search as the Default Team Membership Mechanism — see sections 4.2 and 4.4
  • Ch4-D-05 — Kubernetes Secret Visibility (RestrictSecrets) — see section 4.3
  • Ch4-D-06 — SSO Enforcement and Internal Auth Suppression — see sections 4.2 and 4.9
  • Ch4-D-07 — MFA Enforcement at the Identity Provider — see section 4.7
  • Ch4-D-08 — Break-Glass Access Procedure — see section 4.9
  • Ch4-D-09 — Cluster Separation for Hard Compliance Isolation — see section 4.5

Chapter 5 — Container Registries

  • Ch5-D-01 — Approved Registry List — see section 5.2
  • Ch5-D-02 — Registry Selection by Deployment Model — see section 5.4
  • Ch5-D-03 — Three-Layer Image Scanning — see section 5.3
  • Ch5-D-04 — Image Signing for Production — see section 5.3
  • Ch5-D-05 — Kubernetes Registry Access at Namespace Level — see section 5.2
  • Ch5-D-06 — Acceptable Use Boundary for Public Registries — see section 5.4
  • Ch5-D-07 — Vulnerability Severity Thresholds — see section 5.3
  • Ch5-D-08 — Service Credentials for Registry Integrations — see section 5.4
  • Ch5-D-09 — SBOM Generation and Ongoing CVE Correlation — see section 5.3

Chapter 6 — Git Repositories

  • Ch6-D-01 — Production GitOps Mandate — see section 6.1
  • Ch6-D-02 — Production Git Reference Model — see section 6.4
  • Ch6-D-03 — Kubernetes Manifest Format — see section 6.3
  • Ch6-D-04 — Service Account Credentials for Git Integration — see sections 6.2 and 6.5
  • Ch6-D-05 — CI/CD to GitOps Integration Pattern — see section 6.2

Chapter 7 — Policy Enforcement

  • Ch7-D-01 — Policy Engine Selection — see section 7.2
  • Ch7-D-02 — Enforcing Mode and Fail-Closed Configuration — see sections 7.2 and 7.3
  • Ch7-D-03 — Phased Policy Rollout — see section 7.3
  • Ch7-D-04 — Policy Authorship Separation — see section 7.3
  • Ch7-D-05 — Permanent Exemptions Prohibited — see section 7.3
  • Ch7-D-06 — Admission Enforcement at the API Server — see section 7.1
  • Ch7-D-07 — Defence-in-Depth Posture — see section 7.1
  • Ch7-D-08 — Just-in-Time Credentials for Policy Infrastructure — see section 7.1
  • Ch7-D-09 — Continuous Drift Remediation — see sections 7.1 and 7.6
  • Ch7-D-10 — Webhook Scope and Latency Governance — see section 7.6

Chapter 8 — Secret Management

  • Ch8-D-01 — Secrets Never Touch Git — see section 8.1
  • Ch8-D-02 — Native Kubernetes Secrets Are Insufficient as a Standalone Enterprise Solution — see section 8.2
  • Ch8-D-03 — KMS-Based Encryption at Rest for Any Native Kubernetes Secret Usage — see section 8.2
  • Ch8-D-04 — Vault Secrets Operator as Recommended Vault Integration Pattern — see section 8.2
  • Ch8-D-05 — Kubernetes Auth Method for In-Cluster Vault Authentication — see section 8.2
  • Ch8-D-06 — Namespace-Scoped SecretStore Over ClusterSecretStore — see section 8.2
  • Ch8-D-07 — Volume-Mount Consumption for Zero-Downtime Rotation — see section 8.4
  • Ch8-D-08 — Audit Logging Tier Must Match Compliance Requirement — see section 8.4
  • Ch8-D-09 — Portainer Application Credentials Have No External-Reference Mechanism — see section 8.3
  • Ch8-D-10 — Portainer Database Encryption Key Must Be Managed via the Enterprise Secret Store — see section 8.3
  • Ch8-D-11 — Secret Management Pattern Selected by Environment Tier — see sections 8.2 and 8.4

Chapter 9 — Platform Observability

  • Ch9-D-01 — OneUptime Is the Recommended Observability Backend — see sections 9.2, 9.3, 9.4, 9.5
  • Ch9-D-02 — Observability Is Centralised; Collection Is Distributed — see section 9.1
  • Ch9-D-03 — Portainer Is the RBAC Enforcement Layer for Observability Access — see section 9.1
  • Ch9-D-04 — The Observability Policy Manages Fleet Collector Deployment — see section 9.2
  • Ch9-D-05 — OneUptime Backend Deployment via Helm — see section 9.2
  • Ch9-D-06 — Out-of-Band Alerting Is Mandatory — see section 9.1
  • Ch9-D-07 — Symptom-Based Alerting Over Cause-Based — see section 9.5
  • Ch9-D-08 — Every Alert Must Have a Defined Owner and Runbook Link — see section 9.5
  • Ch9-D-09 — Severity Taxonomy Applied Uniformly Across All Alert Sources — see section 9.5
  • Ch9-D-10 — TLS on All Cross-Network Forwarding Paths — see section 9.7
  • Ch9-D-11 — Dual-Stream Forwarding for SIEM and Operational Backends — see section 9.7
  • Ch9-D-12 — Cardinality Discipline Is a Platform-Level Requirement — see section 9.4
  • Ch9-D-13 — Prometheus Remote Write for Existing Investments — see section 9.4

Chapter 10 — Security Audit and SIEM Integration

  • Ch10-D-01 — Two Primary Audit Streams Are Required; Falco Is Optional — see section 10.2
  • Ch10-D-02 — SIEM Forwarding Is Non-Optional for Regulated Environments — see section 10.2
  • Ch10-D-03 — SIEM Platform Selection — see section 10.3
  • Ch10-D-04 — Dedicated Index or Table per SIEM — see section 10.3
  • Ch10-D-05 — Immutable Log Storage Outside the Administrative Boundary — see section 10.6
  • Ch10-D-06 — At-Least-Once Delivery with Persistent Buffer — see section 10.6
  • Ch10-D-07 — TLS and mTLS on All Forwarding Paths — see section 10.3
  • Ch10-D-08 — MITRE ATT&CK Technique Mapping on All Detection Rules — see section 10.4
  • Ch10-D-09 — PAM Events Route to SOC, Not Platform Engineering — see sections 10.2 and 10.4
  • Ch10-D-10 — Falco Is an Optional Component for Advanced Runtime Security — see section 10.2

Chapter 11 — Data Protection

  • Ch11-D-01 — Backup Tooling Selection — see section 11.2
  • Ch11-D-02 — Kubernetes-Native Backup Required — see section 11.1
  • Ch11-D-03 — RPO and RTO Must Be Defined Per Workload Tier Before Tooling Is Selected — see section 11.1
  • Ch11-D-04 — Application-Consistent Backup for Stateful Workloads — see section 11.2
  • Ch11-D-05 — Backup Data Must Be Stored Off-Cluster with Write-Once Semantics — see sections 11.1 and 11.7
  • Ch11-D-06 — Backup Storage Credentials Are Separate from Cluster Credentials — see section 11.7
  • Ch11-D-07 — Independent-Cluster DR Topology — see sections 11.5 and Chapter 3, section 3.11
  • Ch11-D-08 — Restore Testing Is Mandatory Before a Backup Is Operationally Valid — see section 11.1
  • Ch11-D-09 — Backup Tooling Deployed via GitOps as Part of Cluster Profile — see section 11.6
  • Ch11-D-10 — Backup Solution Must Be Independent of the Clusters It Protects — see sections 11.5 and 11.7
  • Ch11-D-11 — Air-Gapped Clusters Use Local MinIO with Synchronisation During Connectivity Windows — see Scenario E and section 11.7

Chapter 12 — Developer and Operator Interaction

  • Ch12-D-01 — Each Persona Has a Primary Interface — see sections 12.1 and 12.9
  • Ch12-D-02 — Application Templates Are the Primary Developer Delivery Mechanism — see section 12.5
  • Ch12-D-03 — Self-Service Does Not Bypass Governance — see section 12.6
  • Ch12-D-04 — Shell Access Is Privileged and Audit-Logged — see section 12.7
  • Ch12-D-05 — Portainer Is the First Stop for Operational Triage — see section 12.8
  • Ch12-D-06 — Direct Manifest Deployment Is Restricted in Production — see sections 12.3 and 12.9
  • Ch12-D-07 — OT Operators Require a Dedicated Simplified Interface — see sections 12.1 and 12.11