Overview

Architecture

How the platform fits together: from Terraform provisioning to GitOps delivery to the namespaces where the workloads and agents run.

component provisioningGitOps sync

The flow, top to bottom

Two Git repositories are the source of truth. tf-modules holds reusable Terraform, and k8s-gitops holds the Argo CD manifests. Nothing is applied by hand from a laptop; the repos drive everything.

Provisioning: a terraform apply using the modules in tf-modules creates the Civo K3s cluster, its network, and the base namespaces and RBAC.
Delivery: Argo CD is bootstrapped onto the cluster and then manages itself and everything else. It watches k8s-gitops and syncs the desired state in. Adding a component means adding a manifest, not running kubectl.
Runtime: workloads land in one of three namespaces, each with a clear purpose.

Namespace strategy

platform holds the shared infrastructure everything depends on: Argo CD, the Istio service mesh, and the Prometheus / Grafana observability stack.
agents runs the AI workloads: the Anthropic-SDK agent, later the kagent-managed agent, and its MCP tools.
sandbox holds experiments and the chaos demo workload (crashdummy), plus gVisor-isolated execution for agent code.

Why GitOps first

Bootstrapping Argo CD before anything else means every later component, the mesh, the observability stack, the agents, arrives the same way: a pull request into k8s-gitops. The cluster's real state is always the Git state, which keeps the whole thing reproducible and auditable.

Design principles

Reproducible: the cluster can be recreated from scratch with terraform apply in minutes; no snowflake state.
Observable by default: every component deployed from Phase 2 onward ships a ServiceMonitorand metrics; if it runs, it's on a dashboard.
Least privilege: agents get scoped RBAC, never cluster-admin, and untrusted execution is sandboxed.