Skip to content
Documentation

ADR-028: Platform Foundations

Decision

Kubernetes is the default orchestration platform and Terraform is the default infrastructure-as-code tool. Prefer managed, in-cluster services over self-managed equivalents, and retain persistent storage by default.

Key rules

  • Kubernetes is the default orchestration platform — no bare Docker Compose in production.
  • Terraform manages infrastructure as code — no manual console clicks for persistent resources.
  • Prefer managed in-cluster services (CloudNativePG, Valkey, SeaweedFS) over self-managed equivalents when available.
  • Persistent storage must carry the "helm.sh/resource-policy": keep annotation so it survives a Helm uninstall.
  • Platform infrastructure lives in p3-* namespaces — never generic names like monitoring or logging.
  • Kubernetes CRDs are installed as a separate kubectl apply task before any Helm release that depends on them — never via Helm CRD hooks, installCRDs, crds.enabled, or app-of-apps sync. Helm may install controllers and namespaced resources only after the CRDs exist.

Code patterns

# Retain a PersistentVolumeClaim across a Helm uninstall.
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: app-data
  namespace: p3-app
  annotations:
    "helm.sh/resource-policy": keep

Why

A single managed-Kubernetes platform with Terraform-owned infrastructure keeps environments reproducible, auditable, and free of console drift. The keep resource policy prevents accidental data loss when a release is removed. Namespaced p3-* prefixes keep platform components discoverable and collision-free across tenants. The CRD-as-separate-kubectl-task rule reconciles this record with current dmwd-io practice: the global hard rules require CRDs to be applied directly before Helm-managed controllers, so Helm never owns CRD lifecycle even though it provisions the dependent resources.

Applies when

You are setting up CI/CD or infrastructure, writing Helm charts, applying Kubernetes CRDs, or making namespace or persistent-storage decisions.

  • ADR-027 — default tech stack (Kubernetes platform stack details).
  • ADR-029 — multi-tenancy by default.