TradingChassis Infrastructure GitOps Kubernetes Stack (MicroK8s + Argo CD)

Single-node infrastructure for quantitative research and backtesting on OCI.

Architecture generations

Generation	Role today	Path
Version 2	Current architecture — Terraform → Ansible → Argo CD clean-room deploy	`docs/V2_CLEAN_ROOM_DEPLOYMENT.md`
Version 1	Historical record — not an executable repository path	`VERSION_1_BASELINE.md`

V2 ownership:

Terraform → OCI network, compute, scratch volume, instance-principal IAM
Ansible → host baseline, scratch filesystem, MicroK8s, Argo CD bootstrap,
optional private runtime materialization
Argo CD → long-lived Kubernetes desired state (apps + oci-secrets)
GitHub Actions → static validation only

Start here for a fresh environment:docs/V2_CLEAN_ROOM_DEPLOYMENT.md.

That runbook is the canonical operator contract:

tools/bootstrap-cloud-shell → tools/deploy-clean-room → tools/verify-clean-room

The canonical V2 clean-room path has been live-proven through:

deploy → verify / idempotency → reboot → post-reboot convergence
→ destroy → empty Terraform state → fresh create/add-only plan

The external Object Storage state bucket and Vault foundation were preserved. The path is resumable from actual Terraform / Ansible / Kubernetes state, including after the live-discovered PR #75 system-pip fix. GitHub Actions static validation is not live rebuild proof. Historical V1 executable paths are retired. This is not a claim that Version 2 is multi-node, managed Kubernetes, or production-grade.

The historical in-place SecretProviderClass handoff document (docs/RUNTIME_SPC_OWNERSHIP_CUTOVER.md) is a fallback procedure, not the primary V2 path.

What This Repository Provides

Terraform-managed OCI reference infrastructure (network, compute, scratch storage, IAM)
Ansible-managed host bootstrap (baseline, scratch mount, MicroK8s, Argo CD)
GitOps-driven application reconciliation from manifests in this repository
OCI Vault-backed secret delivery through Secrets Store CSI + OCI provider
Predefined workloads: PostgreSQL, MLflow, monitoring stack, Argo Workflows, and scratch PVC overlays

Architecture Overview

Version 2 path (current architecture)

See docs/V2_CLEAN_ROOM_DEPLOYMENT.md for the canonical operator sequence (tools/bootstrap-cloud-shell → tools/deploy-clean-room → tools/verify-clean-room).

Version 1 (historical record only)

Version 1 Bash bootstrap and runtime-injection scripts are retired from this repository. The historical generation is recorded in VERSION_1_BASELINE.md. It is not an executable deployment path.

Canonical operator automation:

tools/bootstrap-cloud-shell → tools/deploy-clean-room → tools/verify-clean-room

GitOps application layer (`apps/` and `argocd/`)

Argo CD reconciles component manifests and Helm-based Kustomizations from:

apps/
argocd/

Repository Layout

.
├── apps/ # Component manifests and Kustomize overlays
│ ├── argo/ # Argo Workflows Helm chart config
│ ├── mlflow/ # MLflow deployment + service + secrets bundle
│ ├── monitoring/ # kube-prometheus-stack Helm config + pushgateway
│ ├── postgres/ # PostgreSQL deployment/pvc/service + DB init job
│ └── scratch/ # scratch PVC overlays for dev/prod
├── argocd/ # Argo CD Application definitions
├── VERSION_1_BASELINE.md # Historical Version 1 ownership and limits
├── CONTRIBUTING.md
├── SECURITY.md
└── README.md

Prerequisites

Canonical V2 deploy provisions the Ubuntu host with Terraform and configures it with Ansible. Do not treat an already-prepared VM plus .env bootstrap as the primary path. Operator procedure: docs/V2_CLEAN_ROOM_DEPLOYMENT.md.

Platform requirements:

Ubuntu host with sudo and snap (V2: Terraform-provisioned reference VM)
Outbound network access from the VM to pull snap packages, Helm charts, container images, and remote CRD/manifests
Dedicated OCI scratch block volume (V2: Terraform-attached; Ansible discovers the host device; kernel paths such as /dev/oracleoci/oraclevds are not a stable contract)
OCI Vault containing all required secret names (see Required OCI Vault secrets)
OCI IAM configured so the instance principal can read those vault secrets

Configuration

Version 2 operator inputs are gitignored files completed after tools/bootstrap-cloud-shell:

terraform/backend.hcl
terraform/terraform.tfvars
ansible/extra-vars/private-runtime.yml

.env.example remains a public reminder of Vault secret names and of VAULT_ID / OCI_REGION as operator values. Ansible does not read .env. Do not commit secret values or the gitignored input files.

Environment variables

Variable	Required	Purpose	Used by
`VAULT_ID`	Yes	OCI Vault OCID used when materializing SecretProviderClass resources	`.env.example`, Ansible `private_runtime_config` extra-vars
`OCI_REGION`	Yes	Region value stored in `tradingchassis-runtime-config` / `OCI_REGION` for MLflow	`.env.example`, Ansible `private_runtime_config` extra-vars

Required OCI Vault Secrets

The following secret names must exist in OCI Vault before private-runtime materialization. Ansible renders them into SecretProviderClass resources; they are not stored as secret values in Git.

Secret name	Used by	Purpose / expected value type	Source contract
`postgresdb-naming`	PostgreSQL	PostgreSQL database name (string)	`ansible/roles/private_runtime_config/defaults/main.yml`
`postgres-user`	PostgreSQL	PostgreSQL username (string)	`ansible/roles/private_runtime_config/defaults/main.yml`
`postgres-password`	PostgreSQL	PostgreSQL password (secret string)	`ansible/roles/private_runtime_config/defaults/main.yml`
`mlflowdb-naming`	PostgreSQL init job	MLflow database name in PostgreSQL (string)	`ansible/roles/private_runtime_config/defaults/main.yml`
`mlflow-user`	PostgreSQL init job	MLflow DB user (string)	`ansible/roles/private_runtime_config/defaults/main.yml`
`mlflow-password`	PostgreSQL init job	MLflow DB user password (secret string)	`ansible/roles/private_runtime_config/defaults/main.yml`
`mlflow-db-uri`	MLflow	Full backend store URI (secret string/URI)	`ansible/roles/private_runtime_config/defaults/main.yml`
`grafana-login-user`	Monitoring / Grafana	Grafana admin username (string)	`ansible/roles/private_runtime_config/defaults/main.yml`
`grafana-login-password`	Monitoring / Grafana	Grafana admin password (secret string)	`ansible/roles/private_runtime_config/defaults/main.yml`

Do not commit secret values to Git.

OCI Instance Principal and IAM note

All SecretProviderClass resources in this repository use authType: instance. The OCI provider DaemonSet also sets OCI_RESOURCE_PRINCIPAL_VERSION, indicating instance principal authentication.

Version 2 Terraform owns the instance-principal Dynamic Group and the compartment-scoped read secret-bundles policy for the reference compute instance. Vault lifecycle, secret values, and any broader tenancy IAM remain external.

V1 historical record

For new V2 deployments, use the canonical clean-room runbook:

docs/V2_CLEAN_ROOM_DEPLOYMENT.md

Canonical operator automation:

tools/bootstrap-cloud-shell → tools/deploy-clean-room → tools/verify-clean-room

The historical Version 1 Bash bootstrap is retired from this repository. See VERSION_1_BASELINE.md for that generation's ownership and limits. It is not an executable fallback path.

GitOps Source of Truth

After bootstrap, Argo CD reconciles from the repoURL, targetRevision, and path in argocd/*.yaml, not from uncommitted local files.

Current repository values in all Argo CD Application manifests:

repoURL: https://github.com/TradingChassis/infrastructure
targetRevision: main

If you operate from a fork or a different repository, update argocd/*.yaml before relying on Argo CD reconciliation.

Also verify repoURL matches the repository you intend to deploy in your environment.

Deployed Applications and Services

Argo CD Applications

Application	Source path	Destination namespace	Purpose
`postgres`	`apps/postgres`	`postgres`	PostgreSQL backend and MLflow DB init job
`mlflow`	`apps/mlflow`	`mlflow`	MLflow tracking server
`monitoring`	`apps/monitoring`	`monitoring`	kube-prometheus-stack + pushgateway
`argo`	`apps/argo`	`argo`	Argo Workflows
`scratch-storage`	`apps/scratch/platform`	`kube-system` (cluster-scoped)	Scratch StorageClass + static PVs for `/mnt/scratch`
`scratch-dev`	`apps/scratch/dev`	`dev`	Scratch PVC overlay for dev namespace
`scratch-prod`	`apps/scratch/prod`	`prod`	Scratch PVC overlay for prod namespace
`oci-secrets`	Oracle chart / Argo Helm values	`kube-system`	Secrets Store CSI Driver + OCI provider

NodePort services configured in manifests

Component	NodePort	Source
Grafana	`30007`	`apps/monitoring/base/helm-values.yaml`
Argo Workflows server	`32120`	`apps/argo/helm-values.yaml`
Prometheus	`30090`	`apps/monitoring/base/helm-values.yaml`
MLflow	`30500`	`apps/mlflow/base/service.yaml`

Access is typically done through SSH local port forwarding. Cloud firewall exposure is configured outside this repository, so verify your OCI NSG/Security List settings.

Argo CD UI access (debugging)

V2 (Ansible bootstrap): Argo CD and Application CRs live in namespace argocd (ansible/roles/argocd_bootstrap, argocd/*.yaml).

V1 (historical Bash bootstrap): Application objects were commonly managed in namespace default. See VERSION_1_BASELINE.md.

Check where argocd-server service exists:

sudo microk8s kubectl get svc -A | rg argocd-server

V2 port-forward example:

sudo microk8s kubectl -n argocd port-forward svc/argocd-server 8080:443

Historical V1 example if the server is still in default:

sudo microk8s kubectl -n default port-forward svc/argocd-server 8080:443

Open https://localhost:8080 while the port-forward is active.

Scratch Storage Model

V2 contract

Terraform → OCI scratch block volume (default 150 GB) + attachment
Ansible → mount at /mnt/scratch; create /mnt/scratch/dev and /mnt/scratch/prod
Argo CD → StorageClass tradingchassis-scratch + static hostPath PVs + namespace PVCs

Application scratch-storage owns cluster-scoped StorageClass/PersistentVolume objects under apps/scratch/platform
Applications scratch-dev / scratch-prod own namespaced scratch-pvc claims only
PVCs use storageClassName: tradingchassis-scratch with deterministic volumeName binding
Requests are 70Gi + 70Gi accounting capacity with headroom on the shared filesystem (not a quota)
PostgreSQL remains on microk8s-hostpath and is intentionally out of this contract

V1 historical note

Legacy V1 Bash storage bootstrap mounted /mnt/scratch while scratch PVCs used microk8s-hostpath. That gap is closed in the V2 Git manifests above. Operator verification of the mount and PVC binding is part of the canonical clean-room tools, not a hardcoded host device path.

Post-Install Verification

Canonical proof is tools/verify-clean-room. The commands below are host-side debugging only and are not a substitute for that tool.

sudo microk8s status
sudo microk8s kubectl get applications -A
sudo microk8s kubectl get pods -A
sudo microk8s kubectl get svc -A
sudo microk8s kubectl get pvc -A

What to verify:

MicroK8s reports ready status
Argo CD Application resources exist for the Applications listed above
Pods are created in namespaces including argocd, postgres, mlflow, monitoring, argo, dev, and prod
Expected NodePorts are present (30007, 32120, 30090, 30500)
PVCs exist for postgres-pvc and scratch-pvc (dev/prod)

Common Operations and Reset Notes

Apply changes after bootstrap

Edit manifests under apps/ or argocd/
Commit and push to the repository/branch referenced by Argo CD Applications
Argo CD reconciles automatically (automated.prune=true, selfHeal=true)

Full reset (destructive)

sudo snap remove microk8s --purge
sudo rm -rf /var/snap/microk8s/
sudo rm -rf ~/.kube/

After reset, also review manually:

/etc/fstab UUID entries for /mnt/scratch (Ansible owns persistent mounting; kernel names such as /dev/oracleoci/oraclevds are not a stable contract)
whether /mnt/scratch should be unmounted/cleaned
whether attached block volume data should be preserved or re-formatted

Development and Validation

From CONTRIBUTING.md:

kustomize build should succeed
YAML should be valid

Repository-specific build examples:

kustomize build apps/postgres
kustomize build apps/mlflow
kustomize build --enable-helm apps/monitoring
kustomize build --enable-helm apps/argo
kustomize build apps/scratch/dev
kustomize build apps/scratch/prod

--enable-helm is required for components that use helmCharts in Kustomization.

Security Notes

No secrets are stored in Git
Secret retrieval is done via OCI Vault + CSI provider
Instance principal authentication is expected by current manifests
Public network exposure rules are configured in OCI, not in this repository
CI Security validation scans for credential leaks and operator/live metadata hygiene; see docs/REPOSITORY_SECURITY.md

For vulnerability reporting and security policy, see SECURITY.md.

Out of Scope / Limitations

Live Greenfield acceptance does not remove these architecture limits:

Single-node MicroK8s (not a multi-node or highly available cluster)
No managed Kubernetes provider
Public service exposure configuration (cloud firewall / NSG remains external)
Application business logic and trade execution systems
Vault lifecycle and Vault secret values (referenced by Terraform / consumed via CSI; not provisioned as secret contents here)
External Object Storage Terraform state-bucket lifecycle (operator-managed foundation; not owned by this Terraform root)

Additional Version 1 limitations and evidence gaps are listed in VERSION_1_BASELINE.md. The V2 clean-room operator procedure is docs/V2_CLEAN_ROOM_DEPLOYMENT.md.

AI-Assisted Development

This repository includes Cursor and agent guardrails for AI-assisted work. Start at AGENTS.md. The human-facing workflow is docs/AI_AGENT_WORKFLOW.md. These guardrails are an additional protection layer; they do not replace OS sandboxing, operating-system permissions, manual confirmation, or Git review.

Additional Documentation

docs/V2_CLEAN_ROOM_DEPLOYMENT.md — canonical V2 clean-room operator runbook
docs/REPOSITORY_SECURITY.md — repository security CI and metadata hygiene
docs/RUNTIME_SPC_OWNERSHIP_CUTOVER.md — historical in-place SPC handoff (fallback only)
terraform/README.md / ansible/README.md / argocd/README.md — layer ownership
VERSION_1_BASELINE.md for historical Version 1 ownership and limitations
AGENTS.md for the cross-agent safety entry point
docs/AI_AGENT_WORKFLOW.md for the Cursor/AI-assisted implementation and review workflow
CONTRIBUTING.md for contribution workflow
SECURITY.md for vulnerability reporting and security model
CHANGELOG.md for tracked changes

Navigation Menu

Uh oh!

Repository files navigation

TradingChassis Infrastructure GitOps Kubernetes Stack (MicroK8s + Argo CD)

Architecture generations

What This Repository Provides

Architecture Overview

Version 2 path (current architecture)

Version 1 (historical record only)

GitOps application layer (`apps/` and `argocd/`)

Repository Layout

Prerequisites

Configuration

Environment variables

Required OCI Vault Secrets

OCI Instance Principal and IAM note

V1 historical record

GitOps Source of Truth

Deployed Applications and Services

Argo CD Applications

NodePort services configured in manifests

Argo CD UI access (debugging)

Scratch Storage Model

V2 contract

V1 historical note

Post-Install Verification

Common Operations and Reset Notes

Apply changes after bootstrap

Full reset (destructive)

Development and Validation

Security Notes

Out of Scope / Limitations

AI-Assisted Development

Additional Documentation

About

Releases

Contributors

Languages

Name		Name	Last commit message	Last commit date
.cursor		.cursor
.github		.github
ansible		ansible
apps		apps
argocd		argocd
docs		docs
terraform		terraform
tests/unit		tests/unit
tools		tools
.cursorignore		.cursorignore
.env.example		.env.example
.gitignore		.gitignore
.gitleaks.toml		.gitleaks.toml
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
VERSION_1_BASELINE.md		VERSION_1_BASELINE.md

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

TradingChassis Infrastructure GitOps Kubernetes Stack (MicroK8s + Argo CD)

Architecture generations

What This Repository Provides

Architecture Overview

Version 2 path (current architecture)

Version 1 (historical record only)

GitOps application layer (apps/ and argocd/)

Repository Layout

Prerequisites

Configuration

Environment variables

Required OCI Vault Secrets

OCI Instance Principal and IAM note

V1 historical record

GitOps Source of Truth

Deployed Applications and Services

Argo CD Applications

NodePort services configured in manifests

Argo CD UI access (debugging)

Scratch Storage Model

V2 contract

V1 historical note

Post-Install Verification

Common Operations and Reset Notes

Apply changes after bootstrap

Full reset (destructive)

Development and Validation

Security Notes

Out of Scope / Limitations

AI-Assisted Development

Additional Documentation

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Contributors

Languages

GitOps application layer (`apps/` and `argocd/`)