neunexus architecture supplement
neunexus provisions a K8s cluster on top of OpenStack and manages, as code, the base infrastructure every other TOJI service — goquest (ticket/work management), brain (RAG search + ontology-based knowledge graph), lymphhub (IAM — session-account auth and short-lived tokenhub credential issuance) — runs on. OpenTofu provisions OpenStack Nova VMs (control-plane/worker) and bare-metal nodes (work/ai-worker) plus networking and load balancing; Ansible then bootstraps K8s itself via kubeadm; on top of that, cluster infrastructure — CCM, Cinder CSI, Traefik, cert-manager, Vault — is installed via Helm. Finally, phased Makefile targets install everything from taxon (storage) through each service namespace, in order.
Why
Managing services by hand, the way docker compose does, made recovering from infra issues far too costly — there were simply too many moving pieces to track (Kubernetes, load balancers, certificates, secrets, cron, systemctl, and more). So this project set up infrastructure to be managed and installed on an IaC basis instead.
00
What IaC is, and what role it plays in neunexus
concept
IaC (Infrastructure as Code) means defining infrastructure — servers, networks, clusters — as declarative code and running that code to create, change, or tear it down, instead of clicking through a console by hand. The core ideas are reproducibility (running the same code again produces the same result) and the code being the single source of truth for what state the infrastructure should be in. neunexus manages its entire stack this way, from OpenStack up through service deployment — provisioning (OpenTofu), cluster bootstrap (Ansible), cluster infrastructure install (OpenTofu + Helm), service lifecycle management (phased Makefile targets, reproducible install/teardown), and secrets management (Vault + VSO) each own a distinct role.
neunexus / (개념 설명, 다이어그램 없음)
01
How the physical layer is split, and which path traffic takes in
openstack/*.tf + kubernetes/{ccm,traefik}.tf
Inbound traffic resolves via Cloudflare DNS first, then an ipTIME router port-forwards it (auto-managed via the ipTIME API) to the internal Octavia LB. master/worker are OpenStack Nova VMs on Dalmatian; neunexus-work/neunexus-ai-worker are bare metal joined directly to K8s, bypassing OpenStack entirely — both share the same Calico VXLAN overlay, so this boundary is invisible at the application level.
neunexus / network.yaml
02
How the OpenTofu modules are split, and how they connect
openstack/*.tf + kubernetes/*.tf
Two independent OpenTofu root modules — openstack/ (9 .tf files) and kubernetes/ (8 .tf files) — plus a third layer, services/, that Tofu does not manage. Each .tf file is drawn as its own node showing exactly what it provisions; the dependency was confirmed as a real output→input wiring (ext_net_id, k8s_subnet_id), not just convention.
neunexus / modules.yaml
03
What "bootstrap" means here, and what order a fresh install runs in
Makefile (install-steps + Phase 0-7)
"Bootstrap" means the full initialization path from a bare server (VM or bare metal) to a fully running K8s cluster with every service up. This is neunexus's core capability — OpenTofu initializes the servers, Ansible bootstraps K8s itself, and phased Makefile targets then install and manage each service via OpenTofu. This corrects a gap in architecture.md's own bootstrap diagram, which omits the install-k8s (Ansible kubeadm) step entirely. Phase 5 (metaflow) is shown with both disputed candidates side by side, since the Makefile and architecture.md disagree and this pass couldn't resolve which is current.
neunexus / bootstrap.yaml
04
How Vault is initialized, and how secrets reach each service
scripts/vault/vault-init.sh + kubernetes/vault.tf + runbooks
Vault init/unseal is manual, done once. The real path secrets take to each service is VSO — the legacy Agent Injector is being phased out following a 2026-06-03 incident. architecture.md only documents the Injector pattern and never mentions VSO.
neunexus / vault-bootstrap.yaml
rendered via archview · d2lang/d2 · ELK layout