Architecture Overview
Petra is built as four independent layers, each with its own update mechanism, verification chain, and operational lifecycle.
Layered Design
+------------------------------------------------------------------+
| Layer 4: Applications |
| Customer workloads deployed via Flux from bundled manifests |
+------------------------------------------------------------------+
| Layer 3: Platform Addons |
| Cilium, Flux, Gatekeeper, Tetragon, cert-manager, Velero, |
| external-dns, external-secrets, kube-bench |
+------------------------------------------------------------------+
| Layer 2: Kubernetes Runtime |
| k3s v1.35.3 FIPS (Go 1.24 native FIPS), embedded etcd, single binary |
+------------------------------------------------------------------+
| Layer 1: Operating System |
| Flatcar Container Linux (immutable root, A/B partitions) |
+------------------------------------------------------------------+
Layer 1: Operating System
Flatcar Container Linux provides an immutable root filesystem with automatic A/B partition updates. The root filesystem is read-only at runtime -- no packages can be installed, no system files can be modified. All mutable state lives on a separate data partition.
Updates are applied atomically: the new OS image is written to the inactive partition, and the system reboots into it. If the new image fails health checks, the system automatically rolls back.
Layer 2: Kubernetes Runtime
k3s is a lightweight, CNCF-certified Kubernetes distribution compiled as a single binary with embedded etcd. Petra uses the FIPS-validated build with Go 1.24 native FIPS crypto (CAVP A6650). k3s installs to /opt/bin on Flatcar and is managed by systemd.
Updates are orchestrated by the k3s System Upgrade Controller with rolling, node-by-node upgrades.
Layer 3: Platform Addons
All platform components beyond k3s and Cilium are managed by Flux v2 GitOps controllers. Each addon is defined as a HelmRelease with version pinning and image overrides pointing to cgr.dev/shebash.io.
| Component | Function |
|---|---|
| Cilium | eBPF networking, network policy, service mesh |
| Flux v2 | GitOps reconciliation |
| OPA Gatekeeper | Policy enforcement (admission control) |
| Tetragon | eBPF runtime security, syscall monitoring |
| cert-manager | X.509 certificate lifecycle |
| Velero | Backup and disaster recovery |
| external-dns | DNS record management |
| External Secrets | Secret synchronization from external stores |
| Sigstore Policy Controller | Image signature admission control |
| Reloader | ConfigMap/Secret change detection |
| kube-bench | CIS Kubernetes Benchmark scanning |
Cilium is installed directly via Helm during bootstrap (not through Flux) because it provides the CNI -- without it, no pods can schedule.
Layer 4: Applications
Customer workloads are deployed through Flux from bundled Kubernetes manifests or HelmReleases. Applications inherit all platform security controls.
Provisioning Models
Petra supports two paths that share the same hardened base:
Standalone Mode (petra up) provisions infrastructure directly using the AWS SDK. Designed for single clusters and development environments.
CAPI Mode (petra capi init + petra capi create) uses the Kubernetes Cluster API for fleet management. A management cluster runs CAPI controllers and a Petra ClusterClass. Workload clusters are created by applying a Cluster custom resource.
Both paths produce identical clusters.