26M26a
500~1000대 노드의 대규모 멀티클러스터, 그리고 폐쇄망(On-premise Air-gapped) 환경에서의 Cloud Native Data Lakehouse 운영은 단순한 자동화를 넘어 'Platform Engineering' 관점의 정교한 설계가 필요합니다.
Harness(Platform) Engineering의 핵심은 재사용성, 격리, 그리고 가시성입니다. Bitbucket에서 GitOps와 AIOps를 동시에 수용할 수 있는 전형적인 디렉토리 구조를 제안해 드립니다.
📂 Cloud Native Platform Unified Repository 구조
/ (Root)
├── .harness/ # CI/CD 파이프라인 정의 (Harness 전용)
├── apps/ # 서비스별 애플리케이션 소스 (Data Lakehouse 관련)
├── infrastructure/ # 플랫폼 기반 인프라 관리 (IaC)
│ ├── terraform/ # 노드 및 네트워크 프로비저닝 (RHEL 10, VM 등)
│ └── kubevirt/ # 가상화 리소스 관리 (VMI, DataVolume)
├── platform/ # 플랫폼 서비스 설정 (GitOps/Helm/Kustomize)
│ ├── core/ # 핵심 계층 (Cilium, OpenEBS, CNPG, Kyverno, OPA)
│ ├── storage/ # 데이터 계층 (MinIO AIStor)
│ ├── security/ # 인증/인가 (Keycloak)
│ ├── registry/ # 이미지/패키지 관리 (Nexus, Harbor)
│ ├── cicd/ # 배포 도구 (ArgoCD, Jenkins)
│ └── observability/ # 모니터링 (Prometheus, Grafana, OpenSearch)
├── clusters/ # 멀티클러스터별 타겟 설정 (ArgoCD App-of-Apps 패턴)
│ ├── cluster-prod-01/ # 운영 클러스터 01 설정
│ └── cluster-dev-01/ # 개발 클러스터 01 설정
├── operations/ # AIOps 및 운영 데이터 관리 (중요)
│ ├── docs/ # SOP, 작업계획서, 장애관리 (Markdown 기반)
│ ├── knowledge-base/ # RAG용 원천 데이터 (BM25/LLM 인덱싱 타겟)
│ ├── ai-ops/ # LangChain 프롬프트, LLM 파이프라인, 모델 메타데이터
│ └── reports/ # 성능/운영 결과 (iperf3, fio, health-check 로그 저장)
├── policies/ # 거버넌스 관리 (Kyverno, OPA 정책)
└── scripts/ # 관리용 유틸리티 (Nexus 업로드, EE 빌드 스크립트)1. 핵심 설계 원칙 및 고려사항
① GitOps 중심의 형상 관리 (ArgoCD 연계)
platform/vsclusters/분리: 플랫폼 서비스의 공통 템플릿(Helm/Kustomize)은platform/에 두고, 각 클러스터별 특화 변수(Value 파일)는clusters/하위에서 관리합니다. 500대 이상의 노드를 관리할 때는 App-of-Apps 또는 ApplicationSet 패턴이 필수적입니다.
② 폐쇄망(Air-gapped) 최적화
scripts/내 Proxy 관리: 외부 이미지를 내부 Nexus/Harbor로 미러링하는 스크립트와 EE(Execution Environment) 빌드 정의서를 이곳에서 관리합니다.- 로컬 경로 참조:
platform/내의 모든 차트와 이미지는 인터넷 주소가 아닌 내부 Nexus 주소를 참조하도록 하드코딩하거나 템플릿화합니다.
③ AIOps를 위한 데이터 구조 (operations/)
- 문서의 자산화: SOP와 장애관리 문서를 Markdown(
.md)으로 관리하면 Git Diff를 통해 변경 이력을 추적할 수 있을 뿐만 아니라, LangChain의 Loader가 즉시 읽어 들여 벡터 DB(OpenSearch)에 인덱싱하기 매우 유리합니다. - RAG 피드백 루프: 운영 중 발생한
reports/내의 성능 점검 결과(fio, iperf3 로그)를 LLM이 분석하여 "현재 네트워크 대역폭 저하로 인한 MinIO 성능 저하 발생 가능성" 등을 추론하게 합니다.
④ 보안 및 정책 거버넌스 (policies/)
- Kyverno/OPA: 멀티클러스터 환경에서 모든 Pod과 네트워크 설정을 검증합니다. 예를 들어, "모든 MinIO Pod은 반드시 지정된 DirectPV 스토리지 클래스를 사용해야 함" 같은 정책을 소스코드로 관리합니다.
2. AIOps 연동 시나리오
- 데이터 수집:
operations/reports/에 Ansible로 수행한 노드 점검 결과(JSON)가 저장됩니다. - 임베딩:
operations/docs/의 작업계획서와 최신 보고서를 LangChain이 읽어 벡터화합니다. - AIOps 질의: 운영자가 "최근 Cluster-A의 MinIO Latency 증가 원인이 뭐야?"라고 물으면, LLM이
fio결과와Cilium네트워크 로그를 교차 분석하여 SOP에 기반한 해결책을 제시합니다.
3. 요약된 기술 사양 (Technical Specs)
[Slide 가이드 적용]
클라우드 네이티브 플랫폼 저장소 전략
- GitOps 기반 멀티클러스터 통합 제어
- Markdown 중심 운영 문서 자산화 및 RAG 최적화
- 폐쇄망 인프라 도구(Nexus/Harbor) 내장 설계
- AIOps 연동을 위한 성능 리포트 데이터 레이크화
다음 단계로 무엇을 도와드릴까요?
- "위 구조를 바탕으로 실제
operations/docs/에 들어갈 장애 대응 SOP의 Markdown 템플릿을 만들어 드릴까요?" - "ArgoCD가
clusters/폴더를 읽어 들여 플랫폼을 배포하는 ApplicationSet 예시 코드가 필요하신가요?" - "LangChain이
reports/폴더의 JSON을 읽기 위한 Python 로더 스크립트를 짜 드릴까요?"
===
규모와 요구사항을 보니 프로젝트 단위 Poly-Repo 전략이 적합합니다. Bitbucket Project 아래 역할별로 repo를 분리하되, ArgoCD App-of-Apps로 GitOps를 연결하는 구조로 설계했습니다.
전체 구조부터 보여드리고, 각 repo의 상세 디렉토리를 아래에 설명합니다.각 repo를 클릭하면 해당 상세 구조를 볼 수 있습니다. 이제 각 repo의 상세 디렉토리 구조를 보여드리겠습니다.탭을 눌러 각 repo의 디렉토리 구조를 확인할 수 있습니다. 이 설계의 핵심 의사결정 사항을 정리합니다.
설계 원칙 요약
Poly-Repo 채택 이유: 규모(500~1000 노드, 멀티클러스터)와 팀 분리(인프라팀 / 데이터팀 / 보안팀 / AIOps팀) 고려 시, 모노레포는 ArgoCD RBAC와 Kyverno 정책 범위가 섞여 리스크가 커집니다. 대신 lh-gitops를 App-of-Apps 진입점으로 두고 나머지 repo를 소스로 연결합니다.
Air-gap 대응 포인트:
lh-infra/scripts/airgap-image-sync.sh에서 Nexus(proxy) → Harbor(internal) 이미지 동기화를 Jenkins로 트리거lh-apps/base/nexus/repos-config.json에 proxy 레포 목록 선언 (pypi, npm, maven 등도 포함)lh-apps/base/harbor/replication-rules.yaml에서 Harbor ↔ Nexus replication rule 관리lh-aiops/models/에는 실제 모델 파일 대신 MinIO 경로만 기록, 실 파일은 MinIO에 보관
문서→RAG 연결: lh-docs/_meta/doc-registry.yaml에 문서 목록과 태그를 관리하고, ingestion-trigger.yaml(ArgoCD PostSync Hook)이 신규 커밋 감지 시 lh-aiops의 ingestion CronJob을 즉시 트리거합니다.
운영 결과 추적: lh-ops-results는 Jenkins 파이프라인이 Prometheus 쿼리 결과를 CSV/JSON으로 커밋하고, Grafana 리포트를 MD로 변환해 PR 없이 직접 push하는 자동화 전용 repo로 운영합니다. 사람이 직접 쓰는 변경계획서/장애분석은 lh-docs에 관리합니다.
Kyverno + OPA 역할 분리: Kyverno는 워크로드 admission 제어(이미지 레지스트리 제한, resource limit 강제 등 일반 정책), OPA Gatekeeper는 조직 컴플라이언스 제약(외부 서비스 금지, 필수 어노테이션 등 감사 목적 정책)으로 역할을 구분합니다.
추가로 특정 repo의 상세 구조나 ArgoCD ApplicationSet 예시 YAML, Jenkins air-gap 동기화 파이프라인 등이 필요하시면 말씀해 주세요.
===
위 탭 위젯에서 기본 구조는 보셨을 테니, 여기서는 각 디렉토리의 실제 파일 내용과 운영 맥락을 상세히 풀어드립니다.각 탭을 눌러 세부 구조를 확인하실 수 있습니다. 설계상 주요 판단 포인트를 추가로 설명합니다.
핵심 설계 결정 사항
base/overlays 분리 원칙: HelmRelease 본체(버전, 기본값)는 base/에 두고 클러스터별 차이(BGP 피어 IP, DiskPool 노드명, 리소스 튜닝값)만 overlays/의 strategic merge patch로 관리합니다. 클러스터가 늘어도 base는 건드리지 않습니다.
air-gap 이미지 동기화 흐름: scripts/image-list.txt에 버전을 명시적으로 고정하고, Jenkins nightly 파이프라인이 skopeo copy로 Nexus proxy → Harbor로 미러링합니다. Cilium, OpenEBS, cert-manager 모두 values.yaml의 image.repository를 harbor.internal/...로 오버라이드해서 외부 인터넷 접근 없이 동작합니다.
network/policies 번호 prefix: 00-default-deny-all → 05-allow-harbor-pull 순서로 번호를 붙이면 ArgoCD Sync 시 적용 순서가 보장되고, 감사(audit) 시 "어떤 정책이 기본으로 깔려 있는지"를 파일 목록만으로 파악할 수 있습니다.
bootstrap/ vs base/ 경계: bootstrap/은 kubeadm init과 OS 준비처럼 쿠버네티스가 아직 없는 상태에서 실행하는 1회성 작업입니다. 쿠버네티스가 기동된 이후의 모든 변경은 반드시 base/overlays/를 통해 GitOps로 관리합니다.
upgrade/ 별도 분리: 업그레이드 매니페스트는 ArgoCD가 관리하면 안 됩니다. 자동 Sync가 걸리면 의도치 않게 업그레이드가 트리거될 수 있기 때문입니다. upgrade/는 ArgoCD Application 범위 밖에 두고, 변경 이력 추적 용도로만 Git에서 관리합니다.
===
각 탭에서 컴포넌트별 상세 구조를 확인할 수 있습니다. 핵심 설계 판단 사항을 정리합니다.
핵심 설계 결정 사항
Medallion 아키텍처를 버킷 단위로 분리: bronze-layer, silver-layer, gold-layer 버킷을 별도로 선언하고 IAM 정책도 레이어별로 분리합니다. 수집 파이프라인은 bronze에만 쓰고, 정제 잡은 silver read/write, 분석 쿼리 엔진은 gold read-only만 부여합니다. 실수로 raw 데이터를 덮어쓰는 사고를 구조적으로 차단합니다.
CNPG Cross-Cluster HA: data-cluster-01이 meta-db Primary 역할을 담당하고, data-cluster-02는 externalClusters로 cluster-01을 참조하는 Streaming Replica로 구성합니다. 두 클러스터가 물리적으로 분리되어 있어도 CNPG의 Barman을 통해 WAL 스트리밍이 이어집니다. Pooler는 cluster-01에만 배포하고, 재해 시 kubectl cnpg promote로 cluster-02 전환 후 Pooler를 재배포하는 DR 절차를 scripts/restore-cnpg-backup.sh에 문서화합니다.
aiops-db에 pgvector 활성화: Milvus가 주 벡터 DB이지만, 자주 조회되는 문서 임베딩은 PostgreSQL pgvector에 캐시해두어 Milvus 호출 없이 빠르게 응답합니다. 인덱싱 비용이 낮은 운영 문서(SOP, 매뉴얼)는 pgvector에, 대용량 로그/메트릭 임베딩은 Milvus로 역할을 나눕니다.
lifecycle/ 집중 관리: MinIO ILM 규칙과 CNPG retentionPolicy를 같은 디렉토리에 두어 "DB 백업 30일 / MinIO 백업 버킷 30일" 정책이 서로 불일치하는 사고를 예방합니다. 정책 변경 PR에서 두 파일을 함께 수정하도록 PR 템플릿에 체크리스트를 넣는 것을 권장합니다.
schemas/migrations/ Flyway 스타일: 스키마 변경을 v001__init.sql 형식으로 번호 관리하면, Jenkins가 PR 머지 시 schema-migrate.sh를 호출해 Hive Metastore DB에 자동 적용하고 실패 시 파이프라인을 중단합니다. 이력이 Git blame으로 추적되어 "이 컬럼은 언제 누가 추가했는가"가 항상 명확합니다.
===
