neunexus architecture supplement
neunexus는 OpenStack 위에 K8s 클러스터를 프로비저닝하고, 그 위에 goquest(티켓·작업 관리 서비스), brain(RAG 검색 + 온톨로지 기반 지식 그래프 서비스), lymphhub(IAM — 세션 계정 인증과 tokenhub 단기 자격증명 발급 서비스) 등 TOJI 전 서비스가 올라가는 기반 인프라를 코드로 관리하는 레포입니다. OpenTofu가 OpenStack Nova VM(control-plane/worker)과 베어메탈(work/ai-worker) 노드·네트워킹·LB를 프로비저닝하면 Ansible이 kubeadm으로 K8s 자체를 부트스트랩하고, 그 위에 CCM·Cinder CSI·Traefik·cert-manager·Vault 같은 클러스터 인프라 계층을 Helm으로 설치합니다. 마지막으로 Makefile의 Phase별 타겟이 taxon(저장소)부터 각 서비스 네임스페이스까지 순서대로 설치합니다.
왜 필요한가
docker compose처럼 서비스들을 수작업으로 관리하다 보니 인프라 이슈를 복구하는 데 비용이 너무 크게 발생했습니다(Kubernetes·로드밸런서·인증서·시크릿·cron·systemctl 등 관련 기능이 너무 많아서). 그래서 IaC 기반으로 인프라를 관리하고 설치할 수 있도록 셋팅한 프로젝트입니다.
00
IaC란 무엇이고, neunexus에서 어떤 역할을 하는가
concept
IaC(Infrastructure as Code)는 서버·네트워크·클러스터 같은 인프라를 사람이 콘솔을 클릭해 수동으로 만드는 대신, 선언적 코드로 정의하고 그 코드를 실행해 인프라 상태를 만들고·바꾸고·해체하는 방식입니다. 같은 코드를 다시 실행하면 같은 결과가 나오는 재현성과, 코드가 곧 "지금 인프라가 어떤 상태여야 하는가"의 단일 진실 공급원이 된다는 점이 핵심입니다. neunexus는 이 방식으로 OpenStack부터 서비스 배포까지 전체 스택을 관리합니다 — 프로비저닝(OpenTofu), 클러스터 부트스트랩(Ansible), 클러스터 인프라 계층 설치(OpenTofu+Helm), 서비스 라이프사이클 관리(Makefile Phase, 재현 가능한 설치/제거), 시크릿 관리(Vault+VSO)가 각각 역할을 나눠 맡습니다.
neunexus / (개념 설명, 다이어그램 없음)
01
물리 계층은 어떻게 나뉘고, 트래픽은 어떤 경로로 들어오는가
openstack/*.tf + kubernetes/{ccm,traefik}.tf
외부 트래픽은 Cloudflare DNS로 먼저 조회된 뒤, ipTIME 공유기가 포트포워딩(ipTIME API로 자동 관리)으로 내부 Octavia LB에 연결합니다. master/worker는 OpenStack Dalmatian 위의 Nova VM이고, neunexus-work/neunexus-ai-worker는 OpenStack을 거치지 않고 K8s에 직접 조인된 베어메탈입니다 — 둘 다 같은 Calico VXLAN 오버레이라 애플리케이션 레벨에서는 이 경계가 보이지 않습니다.
neunexus / network.yaml
02
OpenTofu 모듈은 어떻게 나뉘고, 서로 어떻게 연결되는가
openstack/*.tf + kubernetes/*.tf
openstack/(9개 .tf)와 kubernetes/(8개 .tf) 두 개의 독립된 OpenTofu 루트 모듈이 있고, 그 위에 Tofu가 관리하지 않는 3번째 계층 services/가 있습니다. 각 .tf 파일을 실제 노드로 하나씩 그려 무엇을 프로비저닝하는지 보여주며, 의존 관계는 실제 output→input 배선(ext_net_id, k8s_subnet_id)으로 확인했습니다.
neunexus / modules.yaml
03
부트스트랩이란 무엇이고, 실제로 어떤 순서로 실행되는가
Makefile (install-steps + Phase 0-7)
"부트스트랩"은 빈 서버(VM·베어메탈)에서 시작해 완전히 동작하는 K8s 클러스터+전 서비스가 뜬 상태까지 끌어올리는 초기화 과정입니다. neunexus의 핵심 기능이 바로 이것 — OpenTofu로 서버를 초기화하고, Ansible로 K8s를 부트스트랩한 뒤, Makefile Phase로 각 서비스를 OpenTofu로 설치·관리합니다. architecture.md가 빠뜨린 install-k8s(Ansible kubeadm) 단계를 보정했고, Phase 5(metaflow)는 Makefile과 architecture.md가 서로 다른 내용을 주장해 두 후보를 병기했습니다.
neunexus / bootstrap.yaml
04
Vault는 어떻게 초기화되고, 시크릿은 어떻게 각 서비스로 흘러가는가
scripts/vault/vault-init.sh + kubernetes/vault.tf + runbooks
Vault 초기화·unseal은 수동·최초 1회입니다. 시크릿이 각 서비스로 흘러가는 실제 경로는 VSO이고, Agent Injector는 2026-06-03 인시던트 이후 레거시로 단계적 폐지 중입니다 — architecture.md는 Injector만 설명하고 VSO를 언급하지 않습니다.
neunexus / vault-bootstrap.yaml
rendered via archview · d2lang/d2 · ELK layout