# OCI Kubernetes disaster-recovery architecture

## Purpose and evidence boundary

This diagram explains the public-safe architecture behind the
`oci-k3s-dr` case study. It shows only components supported by Terraform,
Kubernetes manifests, automation, tests, and sanitized execution reports in
the project repository.

The validated recovery claim is deliberately narrow: one encrypted backup of
a controlled PostgreSQL workload and selected non-secret Kubernetes resources
was uploaded to private OCI Object Storage, then restored into a separate
namespace and fresh persistent volume. This is not evidence of cluster-wide,
Secret, volume-snapshot, or production recovery.

## Status key

- **Validated:** supported by an execution report or live allow/deny evidence.
- **Implemented:** present in the applied foundation or repository, without a
  separate completed operational outcome where one is still required.
- **Planned:** designed or statically validated, but not operationally enabled.
- **Externally blocked:** requires operator custody, an approved destination,
  or ownership in another system.
- **Current source validation:** the earlier report records a converged apply;
  the current public repository also passes provider-backed
  `terraform validate` and its safety suite after the duplicate region
  declaration was reconciled.

These statuses appear in each diagram node as text and do not rely on colour.

## Data path

The backup Job reads an allowlisted workload scope, exports selected resources,
creates a PostgreSQL custom-format dump, validates the dump catalogue and
controlled data, writes versioned metadata, and verifies SHA-256 checksums. It
then builds a deterministic archive, encrypts it locally with an age recipient,
removes the plaintext archive, uploads only ciphertext under a unique name,
and confirms non-zero object presence.

The uploader can create and inspect the intended objects. Download, overwrite,
delete, key-management, IAM, and unrelated-resource access are denied by
omission and were tested separately.

## Recovery path

Recovery uses separate administrator authority. The archive validator rejects
unexpected members, traversal, links, devices, duplicates, missing checksums,
corruption, and invalid metadata before extraction. The completed drill used a
different namespace and a new persistent volume, restored into an empty
database, verified the expected schema and controlled data, checked that the
source workload was unchanged, and removed the drill environment.

## Governance and incomplete controls

Terraform separates the private storage, default software-key Vault, restricted
network, notification topic, and uploader identity into modules. Feature gates
keep recovery compute and OKE out of scope. Repository tests reject prohibited
resource classes and unsafe policy or container changes.

The design targets OCI Always Free resource classes; no measured zero-cost
billing result is claimed. Budgets are warning mechanisms. A hard quota policy
proposal is syntax-checked but not applied. Notification delivery, independent
offline key custody, clean Flux ownership, and recurring restore execution
remain incomplete.

## Sanitization

The source and SVG omit tenancy and user identifiers, bucket and namespace
values, object names, addresses and ranges, internal domains, API fingerprints,
configuration files, state, plans, keys, tokens, Kubernetes Secrets, backup
contents, and private command output.

Source: `docs/architecture/sources/oci-k3s-dr.mmd`  
Generated output: `docs/architecture/generated/oci-k3s-dr.svg`  
Public copy: `assets/diagrams/oci-k3s-dr.svg`