신규 구축 및 확장: 지역별 클러스터 및 AIStor 구축/업그레이드 계획.

기술 고도화: KubeVirt 도입, AI 기반 오류 분석 자동화, K8sGPT, Agentic AI 도입 검토.

보안 및 표준화: Vault를 통한 키 관리, CI/CD 보안 강화, 운영 SOP(장애/변경/보안/자동화) 템플릿 표준화.

성능 최적화: Core Component(Runtime, etcd, Scheduler, Network, DNS) 튜닝 및 리소스 최적화.

==

작년에 성공적으로 구축하신 클라우드 네이티브 데이터 레이크하우스 환경을 기반으로, 이제 본격적인 'Day 2 운영(안정화, 최적화, 확장성 확보)' 및 SRE(Site Reliability Engineering) 체계로 전환하시려는 명확하고 훌륭한 목표입니다.

제시해주신 목표(정/부 페어 운영, GitOps/문서 기반 SSOT, HA 및 템플릿화)를 달성하기 위해, 인력 할당 및 과제 수행 체계를 세우기 전 가장 중점을 두어 준비하고 합의해야 할 5가지 핵심 영역을 정리해 드립니다.

1. 정/부(Pair) 체계의 실질적 정착 (프로세스 강제화)

단순히 역할만 나누는 것을 넘어, '부담당자'가 '정담당자' 부재 시 완벽히 백업할 수 있는 제도적 강제성이 필요합니다.

• GitOps PR(Pull Request) 리뷰 의무화: 모든 인프라/설정 변경(Git push) 시, 반드시 부담당자의 Approve를 거쳐야만 Merge 및 Deploy(ArgoCD 등)가 되도록 파이프라인 정책을 설정해야 합니다.
• Runbook 공동 작성 및 교차 검증: 정담당자가 Runbook(장애 대처, 확장 스크립트 등)을 작성하면, 부담당자가 해당 문서만 보고 실제 테스트 환경에서 그대로 실행해보는 검증 단계를 거쳐야 합니다.
• 모의 장애 훈련 (Game Day) 주도: 정기적인 장애 대응 훈련 시, 의도적으로 정담당자를 배제하고 부담당자가 작성된 Runbook과 대시보드만을 활용해 장애를 해결하는 문화를 정착시켜야 합니다.

2. SSOT(Single Source of Truth) 확립: 문서와 코드의 유기적 결합

'Git 기반 운영'과 'Confluence 문서 기반 운영'이 파편화되지 않도록 연결 고리를 만들어야 합니다.

• 수동 개입(ClickOps/수동 kubectl) 원천 차단: 긴급 장애(Emergency) 상황을 제외한 모든 클러스터 변경은 Git을 통해서만 이루어지도록 클러스터 권한(RBAC)을 엄격히 통제해야 합니다. 긴급 수동 변경 시, 사후 Git 동기화 프로세스(SOP)를 엄수해야 합니다.
• Jira - Confluence - Git Commit 규칙 연동: 작업 내역의 추적성을 위해 규칙을 정립해야 합니다.
• 예: Git Commit 메시지에 반드시 Jira 티켓 번호 포함 (feat: [INFRA-123] Update Keycloak HA config)
• Confluence 작업 계획서에 해당 Git PR 링크 및 관련 SOP 링크 첨부

3. '자산 재활용'을 위한 철저한 모듈화 및 템플릿화 (IaC)

향후 타 사이트 유사 클러스터 구축 시 공수를 최소화하려면, 현재 환경이 특정 환경에 종속되지 않게 분리되어야 합니다.

• 설정(Config)과 뼈대(Template)의 분리: Helm Chart, Kustomize, Ansible Playbook 작성 시 환경 변수(dev, stg, prd, 지역 등)를 철저히 Value 파일로 분리하여 관리해야 합니다.
• 표준 파이프라인 자산화: Jenkins Shared Library를 활용하여, 개발팀이 가져다 쓸 수 있는 선언적(Declarative) 파이프라인 템플릿을 구축하고 문서화하는 것을 최우선 과제로 두어야 합니다.

4. Actionable Alert (실행 가능한 알람) 및 Runbook 맵핑

1,000여 개의 노드와 거대한 시스템에서 발생하는 알람 피로도(Alert Fatigue)를 줄이고, 즉각적인 대응 체계를 만들어야 합니다.

• 알람과 Runbook의 1:1 매칭: Alert Manager에서 Slack/Teams 등으로 알람을 쏠 때, 알람 내용 하단에 반드시 해당 장애를 해결할 수 있는 Confluence Runbook 링크가 포함되도록 템플릿을 구성해야 합니다.
• 노이즈 감소 및 알람 등급화: 치명적 장애(Call-out)와 단순 경고(업무시간 내 확인)를 분리하고, CPU 일시적 스파이크 등 불필요한 로깅과 알람을 제거하는 'Observability 최적화'를 초기에 집중적으로 수행해야 합니다.

5. 핵심 컴포넌트의 단일 장애점(SPOF) 제거 및 한계 테스트

운영 안정성의 핵심은 주요 모듈의 완벽한 HA 구성과 성능 한계치를 명확히 아는 것입니다.

• 상태 저장(Stateful) 서비스의 HA 우선 확보: Keycloak, Vault, Nexus, AIStor 등 데이터와 세션을 관리하는 서비스의 이중화/다중화를 우선 검증해야 합니다. (단순한 Pod 레플리카 증가가 아닌, DB/토큰/세션 클러스터링 동기화 확인)
• 부하 테스트(Load Test) 기반 튜닝: eBPF(Cilium), CoreDNS, Ingress 등의 커널/네트워크 튜닝은 단순 값 설정으로 끝나지 않고, 실제 예상 트래픽 이상의 부하를 발생시켜(LoadTest) 병목이 해소되었는지 수치화하여 Confluence에 기록해야 합니다.

💡 다음 단계 제안: 인력 할당 및 운영 체계(운영 vs 프로젝트 병행) 구축

위의 중점 사항들을 바탕으로, 팀원들이 '일상적인 운영/장애 대응(Toil)'과 '고도화 과제(Project)'를 동시에 원활히 수행하기 위한 인력 할당 체계(예: 7:3 업무 분할, 혹은 스프린트 별 운영 담당자 로테이션 제도 등)를 설계하는 것이 좋습니다.

다음 단계로, 올해 진행할 전체 Task들을 정/부 담당자 역할에 맞게 어떻게 배분하고 스프린트(Sprint) 주기로 운영할지 구체적인 워크플로우나 체계 설계를 도와드릴까요?

==

리드 1명, 시니어(책임/수석) 7명, 주니어 4명으로 구성된 총 12명의 조직은 '기술 고도화 과제(Project)'와 '안정적 운영(Daily Ops)'을 병행하기에 매우 이상적인 구조입니다. 특히 K8s와 Cilium에 대한 운영 가용성을 높이기 위해 '매트릭스형 전담 조직'과 '운영 로테이션(On-call)' 제도를 결합한 배분 방안을 제안합니다.

1. 전담 분야별 기술 필러(Technical Pillar) 구성

단순히 일을 나누는 것이 아니라, 11명의 엔지니어를 4개의 핵심 필러로 나누어 정/부 담당자 체제를 구축합니다. 모든 필러에는 시니어와 주니어를 혼합 배치하여 기술 전수와 운영 안정성을 동시에 꾀합니다.

| 기술 필러 | 주요 담당 Task

| 인력 구성 (정/부) | | --- | --- | --- | | Pillar 1: Core Infra & K8s/Cilium | K8s/Cilium/etcd 튜닝 및 업그레이드, BGP/ECMP 구축, 커널 파라미터 튜닝 | 시니어 3명 + 주니어 1명 (Cilium 가용성 집중) | | Pillar 2: DevOps & Security | CI/CD 파이프라인 표준화, GitOps, Keycloak HA, Vault, Harbor 구축 | 시니어 2명 + 주니어 1명 | | Pillar 3: Storage & Observability | AIStor 확장, Local PV/Isilon 연동, 모니터링 체계 고도화, PIR 체계 | 시니어 1명 + 주니어 1명 | | Pillar 4: Innovation & MLOps | KubeVirt, K8sGPT, Agentic AI, GPU 서버 도입, Vibe Coding Zone | 시니어 1명 + 주니어 1명 |

2. '주간 운영 엔지니어(Duty Engineer)' 로테이션 도입

특정 인원이 운영에만 매몰되지 않도록, 매주 2명(시니어 1, 주니어 1)을 '주간 운영 엔지니어'로 지정합니다.

• 운영 엔지니어의 역할: 해당 주차의 모든 JIRA 티켓 응대, 모니터링 알람 1차 대응, 단순 변경 작업 수행.

• 프로젝트 엔지니어의 역할: 운영 엔지니어를 제외한 나머지 인원은 본인 필러의 고도화 과제(Task) 수행에 집중.

• 효과: K8s와 Cilium은 모든 시니어가 로테이션에 참여함으로써 자연스럽게 운영 노하우가 상향 평준화됩니다.

3. 직급별 역할 및 과제 배분 가이드라인

Lead (1명)

• 전체 로드맵 관리 및 필러 간 기술적 의사결정 조율.

• Jira 기반 외부 요청 필터링 및 업무 우선순위 확정.

시니어 (책임/수석 7명)

• 정(Primary): 담당 분야 설계(Design Document), 고도화 과제(Task) 리딩, 핵심 Runbook 초안 작성.

• 부(Secondary): 다른 필러 시니어의 PR(Pull Request) 리뷰, 장애 시 2차 에스컬레이션 대상.

• Cilium 가용성: 시니어 3명을 핵심 필러에 배치하여, 1명 부재 시에도 나머지 2명이 상호 백업하도록 구성.

주니어 (4명)

• 실행 및 운영: 시니어가 설계한 IaC 코드 구현, 모니터링 대시보드 현행화, Runbook 검증.

• 기술 습득: 정/부 체계에서 '부' 담당자로서 시니어의 설계를 리뷰하고, 운영 로테이션을 통해 인프라 전반의 대응 능력 배양.

4. 운영 체계 가동 프로세스

Step 1: GitOps & PR 기반의 운영 (Peer Review)

• 모든 설정 변경(K8s Config, Cilium Policy 등)은 Git 저장소에 Commit 후 PR을 생성합니다.

• 반드시 담당 필러의 시니어 혹은 운영 파트너의 승인(Approve)이 있어야 반영 가능하도록 설정하여 인적 오류를 방지합니다.

Step 2: Confluence 기반 Runbook 중심 운영

• "문서가 없으면 작업도 없다"는 원칙을 적용합니다.

• 주니어는 모든 작업 후 결과 보고 대신 Runbook 업데이트를 수행하고, 시니어는 이를 검수합니다.

Step 3: 주간 스크럼 및 PIR(사후 분석) 공유

• 매주 스크럼 시, 운영 로테이션 엔지니어가 한 주간 발생한 주요 이슈와 해결 과정을 공유합니다.

• Cilium과 같은 고난도 컴포넌트 이슈 발생 시, 담당 필러가 상세 분석(RCA)을 진행하고 전체 인원이 학습하도록 세션을 운영합니다.

이 체계가 정착되면 Cilium 이탈과 같은 인력 변동에도 조직 전체가 유연하게 대응할 수 있는 지속 가능한 SRE 기반이 마련될 것입니다. 우선 4개 필러에 인원을 매칭하는 것부터 시작해 보시겠습니까? 구체적인 인원 성함이나 성향을 알려주시면 더 세부적인 매칭안을 제안해 드릴 수 있습니다.

==

제시해주신 인력 구성(L1, S1S7, J1J4)에 맞춰, 기술 필러(Pillar)별 정/부 담당 체계와 K8s/Cilium 운영 가용성 극대화를 위한 할당 안을 작성해 드립니다. 모든 인원은 본인의 중점 과제(Task)를 수행하면서, 로테이션을 통해 운영(Ops) 능력을 상향 평준화합니다.

1. 기술 필러별 인력 할당 (Task 중심)

각 시니어(S)는 특정 분야의 정 담당으로서 설계를 주도하고, 주니어(J) 및 타 시니어와 페어를 이뤄 기술을 자산화합니다.

| 필러 (Pillar) | 중점 Task

| 인력 할당 (정/부) | | --- | --- | --- | | P1. Core & Network | k8s/Cilium 업그레이드, 커널 튜닝, BGP/ECMP, 클러스터 헬스체크

| 정: S1, S2, S3

부: J1, S4 | | P2. DevOps & Security | Keycloak HA, Vault, CI/CD 표준화, GitOps, Harbor, 레지스트리 보안

| 정: S4, S5

부: J2, S1 | | P3. Storage & Obs | AIStor PB 확장, Isilon 연동, Observability 최적화, PIR 체계

| 정: S6

부: J3, S2 | | P4. Next Tech | KubeVirt, K8sGPT, Agentic AI, GPU 서버, Vibe Coding Zone

| 정: S7

부: J4, S5 |

• L1 (Lead): 전체 로드맵 관리, 필러 간 우선순위 조율, JIRA 티켓 최종 검토 및 의사결정.

• S1, S2, S3 (Cilium 집중): 기존 인력 이탈에 대응하여 시니어 3명을 전면 배치, 상호 백업 체계를 구축합니다.

2. K8s/Cilium 운영 체계 (Ops 중심)

모든 담당자가 대응 가능하도록 '주간 운영 당번(Duty)' 제도를 도입하여 실무 운영 능력을 배양합니다.

운영 로테이션 (Weekly Duty)

• 구성: 시니어 1명 + 주니어 1명 (매주 교대)

• 역할: 해당 주차의 모든 모니터링 알람 대응, JIRA를 통한 외부 기술지원 요청 처리, 일상적인 K8s/Cilium 운영.

• Cilium 가용성 확보: 운영 당번이 해결하지 못하는 Cilium 심화 이슈는 P1(S1~S3)이 즉시 투입되는 2차 에스컬레이션 구조를 가집니다.

3. 정/부 담당자(Pair) 실무 가이드

인력 변동 및 휴가 시에도 중단 없는 운영을 위해 아래 원칙을 준수합니다.

• 정(Primary) 담당자 (S1~S7):
• 담당 과제의 아키텍처 설계 및 IaC(Terraform, Ansible 등) 코드 작성.

• Confluence에 장애 대응 및 확장 Runbook 초안 작성.

• 주니어(J)의 기술 역량 강화를 위한 코드 리뷰 및 가이드.

• 부(Secondary) 담당자 (S, J 혼합):
• 정 담당자가 작성한 모든 코드의 Peer Review(PR 승인) 수행.

• 정 부재 시 Runbook에 기반하여 독자적인 장애 대응 수행.

• 주기적으로 정 담당자와 업무 싱크업(Sync-up) 미팅 진행.

4. GitOps 기반의 자동화 및 자산화

• Git 기반 SSOT: 모든 클러스터 설정 및 정책은 Git 저장소에 기록하며, 부 담당자의 승인 없이는 운영 환경 반영을 금지합니다.

• Runbook 현행화: 모든 작업 결과는 Confluence에 기록하며, 주니어(J)는 운영 당번 수행 시 발생한 신규 오류 패턴을 문서화하는 역할을 맡습니다.

이와 같은 구조로 시작하면, S1~S3를 통한 Cilium 운영 안정성을 확보함과 동시에 주니어 4명의 빠른 기술 습득과 전체 인원의 K8s 상향 평준화를 달성할 수 있습니다.

이 할당 안을 바탕으로 첫 번째 주간 운영 로테이션 순번을 정해볼까요?

중점 준비 사항부터 말씀드리면, 크게 세 가지 이유에서 우선순위가 갈립니다.

첫째, 운영 기반(SOP/문서/Git체계)이 없으면 정/부 페어 자체가 작동하지 않습니다. 부담당자가 정담당자 부재 시 주도적으로 대응하려면 절차가 명문화되어 있어야 하고, 설정과 소스가 Git에 있어야 합니다. 이게 없는 상태에서 과제를 아무리 많이 진행해도 인력 이탈 한 명에 흔들립니다.

둘째, 모니터링/알람 노이즈 정비를 먼저 해야 합니다. 지금 알람이 너무 많거나 의미 없는 알람이 섞여 있으면 스프린트 중 일상 운영이 계속 방해받고, 정작 중요한 이슈를 놓칩니다.

셋째, 인증(Keycloak) HA와 etcd 백업/컴팩션은 나머지 모든 서비스의 기반이라, 안정화가 늦어지면 다른 과제 리스크가 덩달아 올라갑니다.

아래는 이를 바탕으로 한 전체 운영 체계 설계입니다.---

핵심 요약을 텍스트로 정리하면 다음과 같습니다.

① 지금 당장 시작해야 할 것 (P0, Q1 내)은 SOP 4종·PIR 체계·Git 소스 관리 표준·오류 패턴 플레이북·알람 노이즈 정비입니다. 이것이 없으면 부담당자가 정담당자 없이 장애 대응을 할 수가 없고, 인력 변동 때마다 운영이 흔들립니다. 과제 진행보다 이게 먼저입니다.

② 스프린트 capacity는 BAU 40% / Sprint 과제 40% / 버퍼 20%로 잡는 걸 권장합니다. 처음에 과제 비중을 너무 높게 잡으면 일상 운영에서 불이 나고, 그 불을 끄다가 스프린트가 흐지부지됩니다.

③ 정/부 페어에서 가장 중요한 것은 부담당자가 단순히 "보조"가 아니라 "언제든 주도할 수 있는 사람"이 되는 것입니다. 이를 위해 문서 peer review와 복합 작업 공동 수행을 Sprint 내에 명시적으로 할당해야 합니다. 자연스럽게 두면 부담당자는 항상 뒷전이 됩니다.

다음 단계로 넘어갈 때 도움이 필요하시면 말씀해 주세요. 예를 들어 실제 인원 수를 알려주시면 도메인-인력 매핑을 더 구체적으로 설계해드릴 수 있고, Q1 Sprint 백로그를 직접 뽑아드릴 수도 있습니다.

==

1. 중점 준비 사항

==

2. 스프린트 운영 체계

==

3. 도메인 과제 배분

==

4. 변경 워크플로우

======

5. 팀 구성 배분

==

6. Q1 sprint backlog

==

7. Q2 sprint backlog

======

1. custom-columns를 사용하여 가독성 있게 확인하기

PV 이름과 NFS 경로를 열 형태로 출력한 뒤 grep으로 필터링하는 방식입니다. 경로가 정확히 무엇인지 확인하며 리스트업할 때 유용합니다.

kubectl get pv -o custom-columns="NAME:.metadata.name,NFS_PATH:.spec.nfs.path,NFS_SERVER:.spec.nfs.server" | grep "/your/specific/path"

2. jsonpath를 사용하여 이름만 추출하기

특정 경로와 정확히 일치하는 PV의 이름만 깔끔하게 뽑아내고 싶을 때 사용합니다.

kubectl get pv -o jsonpath='{range .items[?(@.spec.nfs.path=="/your/specific/path")]}{.metadata.name}{"\n"}{end}'

3. jq를 사용한 정교한 필터링 (추천)

경로의 일부만 포함되어 있거나, NFS 서버 주소까지 함께 체크해야 하는 대규모 클러스터 환경에서는 jq가 가장 강력합니다.

• 특정 경로가 포함된 모든 PV 이름 출력:

  kubectl get pv -o json | jq -r '.items[] | select(.spec.nfs.path | contains("/your/specific/path")) | .metadata.name'
  

• NFS 서버와 경로를 동시에 만족하는 경우:

  kubectl get pv -o json | jq -r '.items[] | select(.spec.nfs.path == "/your/path" and .spec.nfs.server == "10.0.0.1") | .metadata.name'
  

  4. 고성능 클러스터를 위한 팁

  만약 관리 중인 PV의 수가 수천 개 단위로 매우 많다면, 전체 리스트를 가져오는 과정에서 API 서버에 부하가 걸릴 수 있습니다. 이럴 때는 --go-template을 활용하여 클라이언트 사이드 부하를 줄일 수 있습니다.

  kubectl get pv -o go-template='{{range .items}}{{if .spec.nfs}}{{if eq .spec.nfs.path "/your/specific/path"}}{{.metadata.name}}{{"\n"}}{{end}}{{end}}{{end}}'
  

위 명령어 중 본인의 작업 환경(정확한 일치 여부, 시인성 등)에 가장 적합한 것을 골라 사용하시면 됩니다. 구체적으로 찾으시는 경로 형식이 있다면 그에 맞춰 필터를 더 세분화해 드릴 수 있습니다.

테스트용으로 빠르게 띄우는 방법과 방화벽 설정법을 정리해 드립니다.

1. 테스트용 포트 리스너 띄우기 (Linux)

가장 간단한 방법은 nc(netcat)를 사용하는 것입니다. 도구가 없다면 python을 활용할 수도 있습니다.

A. Netcat (nc) 사용

• TCP 포트 열기:

    # -l: Listen, -p: Port
    nc -l -p 8080

• UDP 포트 열기:

    # -u: UDP
    nc -lu -p 8080

  • 팁: ncat(nmap 패키지)을 쓰신다면 -k 옵션을 추가해 클라이언트가 접속을 끊어도 계속 대기하게 할 수 있습니다.

B. Python 사용 (별도 설치 없을 때)

• TCP (간이 웹서버):

    python3 -m http.server 8080

• UDP (스크립트 필요):

    # udp_server.py
    import socket
    sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
    sock.bind(("0.0.0.0", 8080))
    print("UDP server listening on 8080...")
    while True:
        data, addr = sock.recvfrom(1024)
        print(f"Received: {data} from {addr}")

2. OS 방화벽에서 포트 허용하기

리스너를 띄웠어도 방화벽에서 막히면 외부 접속이 안 됩니다. OS별 명령어가 다릅니다.

A. RHEL/CentOS/Rocky (firewalld)

# TCP 8080 허용
sudo firewall-cmd --permanent --add-port=8080/tcp
# UDP 8080 허용
sudo firewall-cmd --permanent --add-port=8080/udp
# 적용
sudo firewall-cmd --reload

B. Ubuntu/Debian (ufw)

sudo ufw allow 8080/tcp
sudo ufw allow 8080/udp

C. Windows (PowerShell)

# TCP 8080 인바운드 규칙 추가
New-NetFirewallRule -DisplayName "Test_TCP_8080" -Direction Inbound -LocalPort 8080 -Protocol TCP -Action Allow

# UDP 8080 인바운드 규칙 추가
New-NetFirewallRule -DisplayName "Test_UDP_8080" -Direction Inbound -LocalPort 8080 -Protocol UDP -Action Allow

3. 제대로 떴는지 확인하는 법

서버 내부에서 아래 명령어로 내 프로세스가 포트를 잘 잡고 있는지 확인하세요.

# TCP 리스닝 확인
ss -ntlp | grep 8080

# UDP 리스닝 확인
ss -nulp | grep 8080

• 0.0.0.0:8080: 모든 인터페이스에서 접속 허용 상태
• 127.0.0.1:8080: 서버 내부(Local)에서만 접속 가능 상태 (외부 접속 불가)

💡 전문가의 팁

대규모 인프라(K8s 등)를 운영하신다면, OS 방화벽 외에도 클라우드 보안 그룹(Security Group)이나 네트워크 ACL, 혹은 쿠버네티스의 NetworkPolicy가 가로막고 있지는 않은지 반드시 확인해야 합니다.

특히 UDP의 경우, 일부 클라우드 로드밸런서(LB)나 방화벽 장비에서 기본적으로 차단되어 있거나 세션 유지 시간이 매우 짧게 설정된 경우가 많으니 이 점 유의하세요!

==

서버 간 네트워크 통신 가능 여부를 확인하는 것은 인프라 트러블슈팅의 기본입니다. 특히 에어갭(Air-gapped) 환경이나 폐쇄망을 관리하신다면, 별도의 도구 설치 없이 기본 명령어로 확인하는 방법이 매우 중요합니다.

주요 도구별 사용법을 정리해 드립니다.

1. Linux 환경 (Netcat, Nmap, Bash)

A. nc (Netcat) - 가장 범용적인 도구

대부분의 리눅스 배포판에 설치되어 있으며, TCP와 UDP 모두 지원합니다.

• TCP 확인:

    # -z: 스캔 모드, -v: 상세 출력, -w: 타임아웃(초)
    nc -zv -w 3 <IP주소> <포트번호>

• UDP 확인:

    # -u: UDP 모드
    nc -zuv -w 3 <IP주소> <포트번호>

  주의: UDP는 비연결형 프로토콜이라 포트가 열려 있어도 응답을 보내지 않는 경우가 많습니다. succeeded!가 뜨지 않더라도 방화벽에서 거부(Refused 또는 Admin Prohibited) 메시지가 오는지 확인해야 합니다.

B. Nmap - 상세 스캔용

네트워크 보안 및 포트 스캔의 표준 도구입니다.

• TCP/UDP 동시 확인:

    # -sT: TCP 연결 스캔, -sU: UDP 스캔, -p: 포트 지정
    sudo nmap -sT -sU -p 80,443,53 <IP주소>

C. Bash 내장 기능 (도구가 전혀 없을 때)

nc나 telnet이 설치되지 않은 최소 설치(Minimal) 환경에서 유용합니다.

• TCP 확인:

    timeout 3 bash -c "cat < /dev/tcp/<IP주소>/<포트번호>" && echo "Open" || echo "Closed"

• UDP 확인:

    timeout 3 bash -c "cat < /dev/udp/<IP주소>/<포트번호>" && echo "Sent" || echo "Failed"

2. Windows 환경 (PowerShell)

Windows 서버 간 혹은 클라이언트에서 서버 접속 여부를 확인할 때 사용합니다.

A. Test-NetConnection (TNC)

가장 강력하고 권장되는 명령어입니다.

• TCP 확인:

    Test-NetConnection -ComputerName <IP주소> -Port <포트번호>

  • TcpTestSucceeded : True가 나오면 연결 성공입니다.

B. PowerShell을 이용한 UDP 확인

PowerShell 기본 명령어에는 UDP 전용 테스트가 없으므로 .NET 클래스를 활용해야 합니다.

$udpClient = New-Object System.Net.Sockets.UdpClient
$udpClient.Connect("<IP주소>", <포트번호>)
# UDP는 데이터 전송 후 에러가 없으면 열려있다고 가정하는 경우가 많음

3. 트러블슈팅 팁 (Checklist)

1. 방화벽(iptables/firewalld/Security Group): 대상 서버에서 포트를 허용했는지뿐만 아니라, 나가는(Outbound) 서버에서도 해당 포트가 막혀있지 않은지 확인하세요.
2. 리스닝(Listening) 상태: 접속이 안 된다면 대상 서버에서 실제 서비스가 해당 포트를 점유하고 있는지 먼저 확인해야 합니다.
   • netstat -tulnp | grep <포트번호>
   • ss -tulnp | grep <포트번호>
3. MTU 및 경로 이슈: ping은 가는데 특정 서비스만 안 된다면, 특히 쿠버네티스 CNI나 VPN 환경일 경우 패킷 파편화(Fragmentation) 문제일 수 있습니다.
4. UDP의 특성: UDP 테스트 시 "Open"이라고 떠도 실제 애플리케이션 응답이 없으면 방화벽에서 드랍(Drop) 중일 가능성이 큽니다. 이 경우 tcpdump로 패킷이 도달하는지 직접 찍어보는 것이 확실합니다.

어느 도구를 사용하는 것이 현재 환경에 가장 적합하신가요? 상황에 맞는 스크립트가 필요하시면 바로 작성해 드릴 수 있습니다.

흐름 요약

1단계 — 로컬 PC에서 빌드

프로젝트 루트에 .env.build 파일에 Nexus 주소와 인증정보를 설정한 뒤 ./build/build-all.sh v1.2를 실행하면 5개 이미지(extractor, processor, indexer, git-tools, api-server)가 한 번에 빌드됩니다.

2단계 — Nexus에 Push

./build/push-all.sh v1.2를 실행하면 Nexus Docker Registry에 버전 태그와 latest 태그가 함께 등록됩니다. Push 후 Nexus REST API로 등록 결과를 자동 확인합니다.

3단계 — K8s 배포

순서가 중요한데, nexus-pull-secret → ServiceAccount/RBAC → Secrets → PVC → Argo CronWorkflow 순으로 적용합니다. ServiceAccount에 imagePullSecret을 연결해두면 이후 모든 Pod가 자동으로 Nexus 인증을 사용합니다.

중요 포인트 두 가지:

첫째, 사내 Nexus가 자체 서명 인증서를 쓴다면 Docker daemon의 insecure-registries에 등록해야 빌드 머신에서 push가 됩니다. K8s 워커 노드의 containerd 설정에도 동일하게 추가해야 pull이 됩니다.

둘째, processor 이미지는 GPU(nvidia/cuda 베이스)를 쓰기 때문에 이미지 크기가 다른 것보다 훨씬 큽니다. 사내 빌드 머신에 GPU가 없어도 빌드는 가능하고, 실행 시에만 GPU 노드에 스케줄됩니다(nodeSelector: accelerator: nvidia-gpu).

===

AIOps Pipeline 컨테이너화 & Nexus 등록 전체 가이드

환경 가정: 사내 Nexus Repository Manager 3.x / Docker Registry 포함 / K8s 내부망(Airgapped)

1. 전체 디렉토리 구조

먼저 아래와 같이 소스 파일들을 배치합니다.

aiops-pipeline/                        ← 프로젝트 루트 (Git 저장소)
├── docker/
│   ├── extractor/
│   │   ├── Dockerfile
│   │   └── requirements.txt
│   ├── processor/
│   │   ├── Dockerfile
│   │   └── requirements.txt
│   ├── indexer/
│   │   ├── Dockerfile
│   │   └── requirements.txt
│   ├── git-tools/
│   │   └── Dockerfile
│   └── api-server/
│       ├── Dockerfile
│       └── requirements.txt
│
├── scripts/                           ← 앞서 작성한 Python 소스
│   ├── incremental_export.py
│   ├── processor.py
│   ├── lifecycle_manager.py
│   ├── indexer.py
│   ├── aiops_agent.py
│   ├── api_server.py
│   └── sync_to_git.sh
│
├── k8s/
│   ├── secrets.yaml
│   ├── pvc.yaml
│   ├── argo-pipeline.yaml
│   ├── api-server-deployment.yaml
│   └── nexus-pull-secret.yaml
│
├── build/
│   ├── build-all.sh                   ← 전체 이미지 한번에 빌드
│   └── push-all.sh                    ← 전체 이미지 Nexus에 Push
│
└── .env.build                         ← 빌드용 환경변수 (Git에 올리지 않음)

2. .env.build (빌드 환경 변수 설정)

# .env.build  ← .gitignore에 추가 필수
NEXUS_HOST=nexus.internal.company.com
NEXUS_REPO=docker-hosted          # Nexus Docker Hosted Repository 이름
NEXUS_PORT=8082                   # Nexus Docker Registry 포트
NEXUS_USER=deploy-user
NEXUS_PASS=your-nexus-password
IMAGE_TAG=v1.2                    # 배포 버전 태그

3. Dockerfile 작성

3-1. extractor (Confluence 추출기)

# docker/extractor/Dockerfile
FROM python:3.11-slim AS base

LABEL maintainer="platform-team@company.com"
LABEL version="1.2"
LABEL description="Confluence Incremental Exporter"

# 시스템 패키지 설치 (최소화)
RUN apt-get update && apt-get install -y --no-install-recommends \
    wget curl ca-certificates \
    && rm -rf /var/lib/apt/lists/*

# MinIO Client 설치
RUN wget -q https://dl.min.io/client/mc/release/linux-amd64/mc \
    -O /usr/local/bin/mc && chmod +x /usr/local/bin/mc

WORKDIR /app

# Python 의존성 먼저 복사 (캐시 레이어 활용)
COPY docker/extractor/requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 소스 복사
COPY scripts/incremental_export.py .

# 비루트 사용자로 실행 (보안)
RUN useradd -m -u 1000 appuser && chown -R appuser /app
USER appuser

ENTRYPOINT ["python", "incremental_export.py"]

# docker/extractor/requirements.txt
atlassian-python-api==3.41.11
html2text==2024.2.26
minio==7.2.7
requests==2.31.0
python-dotenv==1.0.0

3-2. processor (LLM 분류기 - GPU 포함)

# docker/processor/Dockerfile
# GPU 사용: CUDA 12.1 + Python 3.11 베이스 이미지
FROM nvidia/cuda:12.1.1-cudnn8-runtime-ubuntu22.04 AS base

LABEL description="LangChain LLM Document Processor"

ENV DEBIAN_FRONTEND=noninteractive
ENV PYTHONUNBUFFERED=1

RUN apt-get update && apt-get install -y --no-install-recommends \
    python3.11 python3.11-dev python3-pip \
    wget curl git \
    && rm -rf /var/lib/apt/lists/*

# python3.11을 기본 python으로 설정
RUN update-alternatives --install /usr/bin/python python /usr/bin/python3.11 1 \
    && update-alternatives --install /usr/bin/pip pip /usr/bin/pip3 1

# MinIO Client
RUN wget -q https://dl.min.io/client/mc/release/linux-amd64/mc \
    -O /usr/local/bin/mc && chmod +x /usr/local/bin/mc

WORKDIR /app

COPY docker/processor/requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 소스 복사
COPY scripts/processor.py .
COPY scripts/lifecycle_manager.py .

RUN useradd -m -u 1000 appuser && chown -R appuser /app
USER appuser

ENTRYPOINT ["python", "processor.py"]

# docker/processor/requirements.txt
langchain==0.2.16
langchain-openai==0.1.23
langchain-community==0.2.16
langchain-core==0.2.38
langchain-huggingface==0.0.3
minio==7.2.7
pydantic==1.10.21
pyyaml==6.0.2
requests==2.31.0
# 폐쇄망: transformers/sentence-transformers는 모델과 함께 /models에 미리 반입

3-3. indexer (Vector DB 인덱서)

# docker/indexer/Dockerfile
FROM python:3.11-slim AS base

LABEL description="Milvus Vector DB Indexer"

RUN apt-get update && apt-get install -y --no-install-recommends \
    git curl \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app

COPY docker/indexer/requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY scripts/indexer.py .

RUN useradd -m -u 1000 appuser && chown -R appuser /app
USER appuser

ENTRYPOINT ["python", "indexer.py"]

# docker/indexer/requirements.txt
langchain==0.2.16
langchain-community==0.2.16
langchain-huggingface==0.0.3
langchain-milvus==0.1.4
pymilvus==2.4.4
unstructured==0.14.10
pyyaml==6.0.2
sqlalchemy==2.0.34

3-4. git-tools (Git 동기화 도구)

# docker/git-tools/Dockerfile
FROM alpine:3.19 AS base

LABEL description="Git Sync Tool for Wiki Pipeline"

# git, bash, python3, mc 설치
RUN apk add --no-cache \
    git bash curl wget python3 py3-pip \
    openssh-client

# MinIO Client
RUN wget -q https://dl.min.io/client/mc/release/linux-amd64/mc \
    -O /usr/local/bin/mc && chmod +x /usr/local/bin/mc

# Python 패키지 (lifecycle_manager.py 의존성)
RUN pip3 install --no-cache-dir pyyaml requests

WORKDIR /app

COPY scripts/sync_to_git.sh .
COPY scripts/lifecycle_manager.py .
RUN chmod +x sync_to_git.sh

# git 설정 (컨테이너 내 기본값)
RUN git config --global http.sslVerify false && \
    git config --global core.compression 0

ENTRYPOINT ["/bin/bash", "sync_to_git.sh"]

3-5. api-server (AIOps FastAPI 서버)

# docker/api-server/Dockerfile
FROM python:3.11-slim AS base

LABEL description="AIOps LangGraph Agent API Server"

RUN apt-get update && apt-get install -y --no-install-recommends \
    curl \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app

COPY docker/api-server/requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# K8s Python Client (클러스터 내부에서 실행)
RUN pip install --no-cache-dir kubernetes==30.1.0

COPY scripts/aiops_agent.py .
COPY scripts/api_server.py .

RUN useradd -m -u 1000 appuser && chown -R appuser /app
USER appuser

EXPOSE 8080

# 헬스체크
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s \
    CMD curl -f http://localhost:8080/health || exit 1

ENTRYPOINT ["uvicorn", "api_server:app", "--host", "0.0.0.0", "--port", "8080", "--workers", "2"]

# docker/api-server/requirements.txt
fastapi==0.111.1
uvicorn==0.30.3
langchain==0.2.16
langchain-openai==0.1.23
langchain-community==0.2.16
langchain-huggingface==0.0.3
langchain-milvus==0.1.4
langgraph==0.1.19
pymilvus==2.4.4
httpx==0.27.0
pydantic==2.8.2
pyyaml==6.0.2

4. Nexus Docker Registry 설정

4-1. Nexus에서 Docker Hosted Repository 확인/생성

Nexus 관리 UI에서 확인합니다.

Nexus UI: http://nexus.internal.company.com:8081
메뉴: Repository → Repositories → Create repository
Type: docker (hosted)
이름: docker-hosted
HTTP Port: 8082        ← Docker push/pull에 사용할 포트
Allow anonymous: false  ← 인증 필수

4-2. 로컬 Docker daemon에 Nexus insecure registry 등록

사내 Nexus가 자체 서명 인증서를 쓰는 경우(내부망 흔한 상황):

// /etc/docker/daemon.json  (Linux) 또는
// Docker Desktop → Settings → Docker Engine (Windows/Mac)
{
  "insecure-registries": [
    "nexus.internal.company.com:8082"
  ],
  "registry-mirrors": [],
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "100m",
    "max-file": "3"
  }
}

# daemon.json 수정 후 Docker 재시작
sudo systemctl restart docker

# 확인
docker info | grep -A 5 "Insecure Registries"

5. 빌드 & Push 스크립트

5-1. 전체 빌드 스크립트 (build/build-all.sh)

#!/bin/bash
# build/build-all.sh
# 사용법: ./build/build-all.sh [optional-tag]
# 예시:   ./build/build-all.sh v1.3

set -euo pipefail

# .env.build 로드
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
source "$PROJECT_ROOT/.env.build"

# 태그 오버라이드 (인자가 있으면 사용)
TAG="${1:-$IMAGE_TAG}"
REGISTRY="${NEXUS_HOST}:${NEXUS_PORT}"

echo "=================================================="
echo " AIOps Pipeline 이미지 빌드 시작"
echo " Registry : ${REGISTRY}/${NEXUS_REPO}"
echo " Tag      : ${TAG}"
echo " Build Dir: ${PROJECT_ROOT}"
echo "=================================================="

# ── 이미지 목록 정의 ─────────────────────────────────────────
declare -A IMAGES=(
    ["extractor"]="docker/extractor"
    ["processor"]="docker/processor"
    ["indexer"]="docker/indexer"
    ["git-tools"]="docker/git-tools"
    ["api-server"]="docker/api-server"
)

# ── Nexus 로그인 ──────────────────────────────────────────────
echo ""
echo "▶ Nexus Docker Registry 로그인..."
echo "$NEXUS_PASS" | docker login "${REGISTRY}" \
    --username "$NEXUS_USER" \
    --password-stdin
echo "✅ 로그인 성공"

# ── 각 이미지 빌드 ────────────────────────────────────────────
for IMAGE_NAME in "${!IMAGES[@]}"; do
    DOCKERFILE_DIR="${PROJECT_ROOT}/${IMAGES[$IMAGE_NAME]}"
    FULL_TAG="${REGISTRY}/${NEXUS_REPO}/wiki-pipeline/${IMAGE_NAME}:${TAG}"
    LATEST_TAG="${REGISTRY}/${NEXUS_REPO}/wiki-pipeline/${IMAGE_NAME}:latest"

    echo ""
    echo "▶ Building: ${IMAGE_NAME} (${FULL_TAG})"
    echo "--------------------------------------------------"

    docker build \
        --no-cache \
        --build-arg BUILDTIME="$(date -u +"%Y-%m-%dT%H:%M:%SZ")" \
        --build-arg VERSION="${TAG}" \
        --label "build.version=${TAG}" \
        --label "build.date=$(date -u +"%Y-%m-%d")" \
        --file "${DOCKERFILE_DIR}/Dockerfile" \
        --tag "${FULL_TAG}" \
        --tag "${LATEST_TAG}" \
        "${PROJECT_ROOT}"   # 빌드 컨텍스트는 프로젝트 루트

    echo "✅ Built: ${IMAGE_NAME}:${TAG}"
done

echo ""
echo "=================================================="
echo " 빌드 완료! Push하려면: ./build/push-all.sh ${TAG}"
echo "=================================================="

5-2. 전체 Push 스크립트 (build/push-all.sh)

#!/bin/bash
# build/push-all.sh
# 사용법: ./build/push-all.sh [optional-tag]

set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
source "$PROJECT_ROOT/.env.build"

TAG="${1:-$IMAGE_TAG}"
REGISTRY="${NEXUS_HOST}:${NEXUS_PORT}"

declare -a IMAGE_NAMES=("extractor" "processor" "indexer" "git-tools" "api-server")

echo ""
echo "▶ Nexus에 이미지 Push 시작 (Tag: ${TAG})"

for IMAGE_NAME in "${IMAGE_NAMES[@]}"; do
    FULL_TAG="${REGISTRY}/${NEXUS_REPO}/wiki-pipeline/${IMAGE_NAME}:${TAG}"
    LATEST_TAG="${REGISTRY}/${NEXUS_REPO}/wiki-pipeline/${IMAGE_NAME}:latest"

    echo ""
    echo "▶ Pushing: ${IMAGE_NAME}..."
    docker push "${FULL_TAG}"
    docker push "${LATEST_TAG}"
    echo "✅ Pushed: ${FULL_TAG}"
done

echo ""
echo "=================================================="
echo " Push 완료!"
echo ""
echo " 등록된 이미지 확인:"
for NAME in "${IMAGE_NAMES[@]}"; do
    echo "  ${REGISTRY}/${NEXUS_REPO}/wiki-pipeline/${NAME}:${TAG}"
done
echo "=================================================="

# Nexus에서 이미지 목록 확인 (REST API)
echo ""
echo "▶ Nexus에서 등록된 이미지 목록 조회..."
curl -s -u "${NEXUS_USER}:${NEXUS_PASS}" \
    "http://${NEXUS_HOST}:8081/service/rest/v1/components?repository=${NEXUS_REPO}" \
    | python3 -c "
import json,sys
data = json.load(sys.stdin)
for item in data.get('items',[]):
    print(f\"  → {item.get('name')}:{item.get('version')}\")
" 2>/dev/null || echo "  (Nexus REST API 조회 실패 - UI에서 직접 확인하세요)"

5-3. 빌드 실행 방법

# 1. 스크립트 실행 권한 부여
chmod +x build/build-all.sh build/push-all.sh

# 2. 전체 이미지 빌드
./build/build-all.sh v1.2

# 3. Nexus에 Push
./build/push-all.sh v1.2

# ── 특정 이미지만 빌드/Push 하고 싶을 때 ──────────────────
REGISTRY="nexus.internal.company.com:8082"
REPO="docker-hosted"

# 단일 이미지 빌드
docker build \
  -f docker/processor/Dockerfile \
  -t ${REGISTRY}/${REPO}/wiki-pipeline/processor:v1.2 \
  .

# 단일 이미지 Push
docker push ${REGISTRY}/${REPO}/wiki-pipeline/processor:v1.2

6. K8s에서 Nexus 이미지 Pull 설정

K8s 클러스터에서 Nexus의 프라이빗 이미지를 Pull하려면 imagePullSecret이 필요합니다.

6-1. imagePullSecret 생성

# k8s 네임스페이스에 Nexus 인증 정보 등록
kubectl create secret docker-registry nexus-pull-secret \
  --namespace platform-ops \
  --docker-server=nexus.internal.company.com:8082 \
  --docker-username=deploy-user \
  --docker-password=your-nexus-password \
  --docker-email=platform@company.com

# 확인
kubectl get secret nexus-pull-secret -n platform-ops -o yaml

# k8s/nexus-pull-secret.yaml (선언형 방식)
apiVersion: v1
kind: Secret
metadata:
  name: nexus-pull-secret
  namespace: platform-ops
type: kubernetes.io/dockerconfigjson
data:
  # base64 인코딩된 docker config
  # 생성: cat ~/.docker/config.json | base64 -w 0
  .dockerconfigjson: <base64-encoded-docker-config>

6-2. ServiceAccount에 imagePullSecret 연결 (전역 설정)

매번 Pod에 imagePullSecrets를 붙이는 대신, ServiceAccount에 연결하면 네임스페이스 내 모든 Pod에 자동 적용됩니다.

# 기존 default ServiceAccount에 연결
kubectl patch serviceaccount argo-wiki-sa \
  -n platform-ops \
  -p '{"imagePullSecrets": [{"name": "nexus-pull-secret"}]}'

# 또는 새 ServiceAccount 생성 시 포함

# k8s/serviceaccount.yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  name: argo-wiki-sa
  namespace: platform-ops
imagePullSecrets:
- name: nexus-pull-secret
---
# Argo Workflows가 파이프라인 Pod를 생성할 수 있도록 권한 부여
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: argo-wiki-role
  namespace: platform-ops
rules:
- apiGroups: [""]
  resources: ["pods", "pods/log", "configmaps", "persistentvolumeclaims"]
  verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
- apiGroups: [""]
  resources: ["events", "nodes"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["apps"]
  resources: ["deployments", "daemonsets"]
  verbs: ["get", "list"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: argo-wiki-rolebinding
  namespace: platform-ops
subjects:
- kind: ServiceAccount
  name: argo-wiki-sa
  namespace: platform-ops
roleRef:
  kind: Role
  name: argo-wiki-role
  apiGroup: rbac.authorization.k8s.io

7. K8s 배포 순서 (처음 설치)

아래 순서대로 적용하면 됩니다.

# ── Step 0: 네임스페이스 및 기반 리소스 ──────────────────────
kubectl create namespace platform-ops

# Nexus Pull Secret
kubectl apply -f k8s/nexus-pull-secret.yaml

# ServiceAccount & RBAC
kubectl apply -f k8s/serviceaccount.yaml

# ── Step 1: Secret (인증 정보) 등록 ──────────────────────────
# 실제 값으로 수정 후 적용
kubectl apply -f k8s/secrets.yaml -n platform-ops

# ── Step 2: 공유 볼륨 (PVC) 생성 ─────────────────────────────
kubectl apply -f k8s/pvc.yaml -n platform-ops

# ── Step 3: Argo Workflows 설치 (미설치 시) ──────────────────
kubectl create namespace argo
kubectl apply -n argo -f https://github.com/argoproj/argo-workflows/releases/latest/download/install.yaml
# 또는 폐쇄망에서는 Helm chart를 내려받아 설치

# ── Step 4: AIOps API 서버 배포 ──────────────────────────────
kubectl apply -f k8s/api-server-deployment.yaml -n platform-ops

# ── Step 5: Argo Workflows CronWorkflow 등록 ─────────────────
kubectl apply -f k8s/argo-pipeline.yaml -n platform-ops

# ── Step 6: 첫 실행 (수동 트리거) ────────────────────────────
# Argo CLI 또는 UI에서 즉시 실행
argo submit --from=cronworkflow/llm-wiki-pipeline -n platform-ops

# 실행 상태 확인
argo list -n platform-ops
argo get <workflow-name> -n platform-ops
argo logs <workflow-name> -n platform-ops

8. K8s 리소스 YAML 전체

8-1. PVC 설정 (k8s/pvc.yaml)

# k8s/pvc.yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: wiki-pipeline-pvc
  namespace: platform-ops
spec:
  accessModes:
    - ReadWriteMany       # 여러 Pod가 동시 접근 가능 (NFS 또는 Ceph RBD 권장)
  storageClassName: ceph-rbd   # 사내 스토리지 클래스명으로 변경
  resources:
    requests:
      storage: 50Gi

8-2. AIOps API 서버 Deployment (k8s/api-server-deployment.yaml)

# k8s/api-server-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: aiops-api-server
  namespace: platform-ops
  labels:
    app: aiops-api
spec:
  replicas: 2
  selector:
    matchLabels:
      app: aiops-api
  template:
    metadata:
      labels:
        app: aiops-api
    spec:
      serviceAccountName: argo-wiki-sa
      imagePullSecrets:
      - name: nexus-pull-secret
      containers:
      - name: api-server
        image: nexus.internal.company.com:8082/docker-hosted/wiki-pipeline/api-server:v1.2
        ports:
        - containerPort: 8080
        envFrom:
        - secretRef:
            name: wiki-pipeline-secrets
        env:
        - name: EMBEDDING_MODEL_PATH
          value: "/models/bge-m3"
        - name: MILVUS_HOST
          value: "milvus.storage.svc.cluster.local"
        volumeMounts:
        - name: models
          mountPath: /models
          readOnly: true
        resources:
          requests:
            cpu: "500m"
            memory: "2Gi"
          limits:
            cpu: "2"
            memory: "4Gi"
        livenessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 10
          periodSeconds: 5
      volumes:
      - name: models
        hostPath:
          path: /data/models    # 워커 노드에 미리 모델 파일 배치
---
apiVersion: v1
kind: Service
metadata:
  name: aiops-api-svc
  namespace: platform-ops
spec:
  selector:
    app: aiops-api
  ports:
  - port: 8080
    targetPort: 8080
  type: ClusterIP
---
# 외부(Lens 로컬 PC)에서 접근할 수 있도록 NodePort 또는 Ingress 추가
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aiops-api-ingress
  namespace: platform-ops
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  rules:
  - host: aiops.internal.company.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: aiops-api-svc
            port:
              number: 8080

8-3. Argo CronWorkflow (이미지 주소 업데이트 포함)

# k8s/argo-pipeline.yaml (Nexus 이미지 주소 적용)
apiVersion: argoproj.io/v1alpha1
kind: CronWorkflow
metadata:
  name: llm-wiki-pipeline
  namespace: platform-ops
spec:
  schedule: "0 2 * * *"
  timezone: "Asia/Seoul"
  concurrencyPolicy: Forbid
  workflowSpec:
    serviceAccountName: argo-wiki-sa
    entrypoint: main-pipeline

    # 전역 imagePullSecrets 설정
    imagePullSecrets:
    - name: nexus-pull-secret

    volumes:
    - name: workspace
      persistentVolumeClaim:
        claimName: wiki-pipeline-pvc
    - name: models
      hostPath:
        path: /data/models

    templates:
    - name: main-pipeline
      dag:
        tasks:
        - name: step1-extract
          template: confluence-extractor
        - name: step2-process
          dependencies: [step1-extract]
          template: langchain-processor
        - name: step3-lifecycle
          dependencies: [step2-process]
          template: lifecycle-manager
        - name: step4-git-sync
          dependencies: [step3-lifecycle]
          template: git-syncer
        - name: step5-indexing
          dependencies: [step4-git-sync]
          template: vector-indexer
        - name: step6-notify
          dependencies: [step5-indexing]
          template: slack-notifier

    # ── Nexus 이미지 주소 적용 ────────────────────────────────
    - name: confluence-extractor
      container:
        image: nexus.internal.company.com:8082/docker-hosted/wiki-pipeline/extractor:v1.2
        command: ["python", "incremental_export.py"]
        resources:
          requests: {cpu: "500m", memory: "1Gi"}
          limits:   {cpu: "2",   memory: "2Gi"}
        envFrom:
        - secretRef:
            name: wiki-pipeline-secrets
        volumeMounts:
        - name: workspace
          mountPath: /workspace

    - name: langchain-processor
      container:
        image: nexus.internal.company.com:8082/docker-hosted/wiki-pipeline/processor:v1.2
        command: ["python", "processor.py"]
        resources:
          requests:
            cpu: "2"
            memory: "8Gi"
            nvidia.com/gpu: "1"
          limits:
            cpu: "8"
            memory: "16Gi"
            nvidia.com/gpu: "1"
        nodeSelector:
          accelerator: nvidia-gpu
        tolerations:
        - key: nvidia.com/gpu
          operator: Exists
          effect: NoSchedule
        envFrom:
        - secretRef:
            name: wiki-pipeline-secrets
        env:
        - name: LLM_ENDPOINT
          value: "http://vllm-service.ai-namespace.svc.cluster.local:8000/v1"
        volumeMounts:
        - name: workspace
          mountPath: /workspace
        - name: models
          mountPath: /models
          readOnly: true

    - name: lifecycle-manager
      container:
        image: nexus.internal.company.com:8082/docker-hosted/wiki-pipeline/processor:v1.2
        command: ["python", "lifecycle_manager.py", "--action", "archive",
                  "--clone-dir", "/workspace/llm-wiki"]
        resources:
          requests: {cpu: "200m", memory: "512Mi"}
          limits:   {cpu: "1",   memory: "1Gi"}
        envFrom:
        - secretRef:
            name: wiki-pipeline-secrets
        volumeMounts:
        - name: workspace
          mountPath: /workspace

    - name: git-syncer
      container:
        image: nexus.internal.company.com:8082/docker-hosted/wiki-pipeline/git-tools:v1.2
        command: ["/bin/bash", "sync_to_git.sh"]
        resources:
          requests: {cpu: "200m", memory: "256Mi"}
          limits:   {cpu: "1",   memory: "512Mi"}
        envFrom:
        - secretRef:
            name: wiki-pipeline-secrets
        volumeMounts:
        - name: workspace
          mountPath: /workspace

    - name: vector-indexer
      container:
        image: nexus.internal.company.com:8082/docker-hosted/wiki-pipeline/indexer:v1.2
        command: ["python", "indexer.py"]
        resources:
          requests: {cpu: "1",  memory: "4Gi"}
          limits:   {cpu: "4",  memory: "8Gi"}
        env:
        - name: WIKI_DIR
          value: "/workspace/llm-wiki/wiki/active"
        - name: EMBEDDING_MODEL_PATH
          value: "/models/bge-m3"
        envFrom:
        - secretRef:
            name: wiki-pipeline-secrets
        volumeMounts:
        - name: workspace
          mountPath: /workspace
        - name: models
          mountPath: /models
          readOnly: true

    - name: slack-notifier
      container:
        image: curlimages/curl:latest    # 이건 Nexus에 미러링 후 주소 변경 권장
        command: [sh, -c]
        args:
        - |
          DATE=$(date '+%Y-%m-%d %H:%M KST')
          curl -s -X POST "$SLACK_WEBHOOK_URL" \
            -H 'Content-type: application/json' \
            -d "{\"text\":\"✅ LLM Wiki 파이프라인 완료 (${DATE})\"}"
        envFrom:
        - secretRef:
            name: wiki-pipeline-secrets

9. 전체 실행 흐름 요약

[개발자 로컬 PC]
    1. 소스 수정 (scripts/*.py, docker/*/Dockerfile)
    2. ./build/build-all.sh v1.3      ← 이미지 빌드
    3. ./build/push-all.sh v1.3       ← Nexus에 Push

[Nexus Repository]
    4. 이미지 저장
       nexus.internal.company.com:8082/docker-hosted/wiki-pipeline/extractor:v1.3
       nexus.internal.company.com:8082/docker-hosted/wiki-pipeline/processor:v1.3
       ...

[K8s 클러스터]
    5. argo-pipeline.yaml의 image 주소를 v1.3으로 수정 후 apply
       kubectl apply -f k8s/argo-pipeline.yaml -n platform-ops

    6. Argo가 매일 새벽 2시에 자동 실행 (또는 수동 트리거)
       argo submit --from=cronworkflow/llm-wiki-pipeline -n platform-ops

    7. 각 Step Pod가 Nexus에서 이미지 Pull → 실행
       step1: Confluence 추출 → MinIO
       step2: LLM 분류 → MinIO wiki/
       step3: 생애주기 관리
       step4: Git Push
       step5: Milvus 인덱싱
       step6: Slack 알림

[AIOps API 서버] (24시간 상시 실행)
    - Alertmanager Webhook 수신
    - Lens에서 HTTP 호출: http://aiops.internal.company.com/analyze
    - 정기 리스크 스캔: GET /risk-scan

10. 트러블슈팅 체크리스트

# 이미지 Pull 실패 시
kubectl describe pod <pod-name> -n platform-ops | grep -A 10 "Events"
# → ImagePullBackOff: nexus-pull-secret 확인
kubectl get secret nexus-pull-secret -n platform-ops

# Nexus 연결 확인
curl -u deploy-user:password \
  http://nexus.internal.company.com:8082/v2/_catalog

# 이미지 목록 확인
curl -u deploy-user:password \
  http://nexus.internal.company.com:8082/v2/docker-hosted/wiki-pipeline/extractor/tags/list

# Argo 파이프라인 로그 확인
argo logs llm-wiki-pipeline-<hash> -n platform-ops --follow

# 특정 Step 로그만 확인
argo logs llm-wiki-pipeline-<hash> -n platform-ops -c langchain-processor

# Pod에 직접 접속하여 디버깅
kubectl run debug-pod --rm -it \
  --image=nexus.internal.company.com:8082/docker-hosted/wiki-pipeline/processor:v1.2 \
  --overrides='{"spec":{"imagePullSecrets":[{"name":"nexus-pull-secret"}]}}' \
  -n platform-ops -- /bin/bash

빌드 가이드 버전: v1.0 | 작성일: 2026-04-29

문서 구성 요약

8개 핵심 코드 모듈이 포함되어 있으며, 각각의 역할과 연결 구조는 다음과 같습니다.

데이터 수집 → 정제 → 저장 흐름:

• incremental_export.py — Confluence CQL 증분 추출, 파일 해시 비교로 중복 방지, MinIO raw/ 저장
• processor.py — LangChain + 로컬 LLM(vLLM)으로 분류·링크수정·YAML 메타데이터 자동 생성, 중복 문서 감지 및 deprecated 처리
• sync_to_git.sh — MinIO wiki/ → Git 동기화, lifecycle_manager 연계 호출
• lifecycle_manager.py — 180일 미검증 시 Slack 알림, 365일 경과 시 archive/ 자동 이동

인덱싱 및 검색:

• indexer.py — RecordManager로 증분 인덱싱(변경분만), 삭제된 문서 자동 정리, Milvus Hybrid Search

AIOps 모니터링:

• aiops_agent.py — LangGraph 6-Node 워크플로우. 신뢰도 낮으면 자동 재검색 루프, K8s 실시간 컨텍스트 수집, 근본 원인 분석 → 해결책 → 리스크 예측까지 순차 실행
• api_server.py — FastAPI 서버. Alertmanager Webhook 수신, Lens에서 HTTP 호출, 정기 리스크 스캔 엔드포인트 제공
• argo-pipeline.yaml — 전체 6단계 파이프라인을 CronWorkflow로 오케스트레이션

생애주기 관리는 YAML status 필드(draft → active → deprecated → archive)를 중심으로 전 단계에 걸쳐 반영했고, GitLab 전환 대비 .gitlab-ci.yml도 포함되어 있습니다.

===

AIOps Platform + LLM Wiki 전체 아키텍처 설계서

대상 환경: K8s 1,000노드 클러스터 / Cilium / MinIO AIStor / Airgapped / Bitbucket → GitLab 전환 예정
목표: Confluence 문서를 LLM Wiki로 자동 변환하고, 실시간 K8s 상태와 결합하여 장애 원인 분석·해결책 제시·리스크 예측이 가능한 완전 자동화 AIOps 시스템 구축

1. 전체 시스템 아키텍처 (High-Level Overview)

┌─────────────────────────────────────────────────────────────────────────┐
│                        DATA INGESTION LAYER                             │
│  Confluence  ──►  K8s CronJob(증분추출)  ──►  MinIO AIStor [raw/]      │
│  Web Vendor Docs ──► Firecrawl(Self-hosted) ──► MinIO AIStor [raw/]    │
└──────────────────────────────┬──────────────────────────────────────────┘
                               │ Argo Workflows (Event-Driven)
┌──────────────────────────────▼──────────────────────────────────────────┐
│                     INTELLIGENCE PROCESSING LAYER                       │
│  MinIO [raw/]  ──►  LangChain Processor                                │
│                     ├─ Link Resolver (Internal Links 수정)              │
│                     ├─ LLM Classifier (vLLM/Ollama - 폐쇄망)           │
│                     ├─ Metadata YAML 자동 생성                          │
│                     └─ Lifecycle Status 관리                            │
└──────────────────────────────┬──────────────────────────────────────────┘
                               │
┌──────────────────────────────▼──────────────────────────────────────────┐
│                        KNOWLEDGE STORAGE LAYER                          │
│  Git (Bitbucket/GitLab)                                                 │
│  ├─ /raw/         ← MinIO에서 가져온 원본 MD                            │
│  └─ /wiki/        ← LLM이 정제한 구조화 지식                            │
│      ├─ /active/Architecture, SOP, Library, Reports                    │
│      └─ /archive/ ← 폐기된 구버전 문서                                  │
└──────────┬──────────────────────────────────────────────────────────────┘
           │ GitHub Actions / GitLab CI  (wiki/** push trigger)
┌──────────▼──────────────────────────────────────────────────────────────┐
│                         VECTOR INDEX LAYER                              │
│  LangChain Indexing API + RecordManager ──► Milvus (K8s Operator)      │
│  ├─ Hybrid Search: BM25(Keyword) + Vector(Semantic)                     │
│  └─ Metadata Filter: status, category, tech_stack, last_verified       │
└──────────┬──────────────────────────────────────────────────────────────┘
           │
┌──────────▼──────────────────────────────────────────────────────────────┐
│                        AIOPS MONITORING LAYER                           │
│  K8s 실시간 이벤트 (Prometheus/Alertmanager/K8s API)                   │
│      ──► LangGraph Agent                                                │
│           ├─ Node 1: 이벤트 수집 & 증상 분석                            │
│           ├─ Node 2: RAG 검색 (Milvus - 관련 SOP/Library)              │
│           ├─ Node 3: 근본 원인 분석 (Root Cause Analysis)              │
│           ├─ Node 4: 해결책 생성 & 검증                                 │
│           └─ Node 5: 리스크 예측 (Proactive Risk Detection)            │
│      ──► Lens (로컬 PC) + 사내 LLM API 연동                            │
└─────────────────────────────────────────────────────────────────────────┘

2. 문서 생애주기 (Document Lifecycle) 설계

모든 문서는 아래 4단계 상태를 가지며, LLM과 자동화 파이프라인이 상태를 관리합니다.

draft ──► active ──► deprecated ──► archive
                         │
                   (180일 미검증 시 자동 알림)
                         │
                   (365일 후 archive 자동 이동)

표준 Metadata YAML 스키마

---
# === 식별 및 분류 ===
id: "SOP-CIL-001"                         # 문서 고유 ID (자동 생성)
title: "Cilium BGP Control Plane 장애 대응"
category: "SOP"                           # SOP | Library | Architecture | Reports
tech_stack: ["Cilium", "BGP", "K8s"]
sub_category: "Network"

# === 생애주기 관리 (Lifecycle) ===
status: "active"                          # draft | active | deprecated | archive
created_at: "2026-01-15"
last_verified_at: "2026-04-28"            # 기술 검증일 (180일 미갱신 시 알림)
verified_by: "platform-lead"
applies_to_version: "cilium>=1.15"        # 유효 버전 범위
expires_at: null                          # 명시적 만료일 (null이면 자동 관리)

# === 출처 및 추적 ===
source: "confluence"                      # confluence | web | manual | ai-generated
source_url: "https://confluence.internal/pages/12345"
auto_classified: true
pipeline_version: "v1.2"

# === 운영 맥락 (AIOps) ===
severity: "Critical"                      # Critical | High | Medium | Low
environment: ["production", "staging"]
target_audience: "platform-engineer"
contains_code: true
code_languages: ["yaml", "shell"]
related_docs: ["ARCH-NET-002", "LIB-CIL-005"]

# === 검색 최적화 ===
tags: ["bgp-peering", "network-failure", "cilium", "troubleshooting"]
summary: "Cilium BGP 피어링 실패 시 원인 진단 및 단계별 복구 절차"
---

3. 핵심 코드 구현

3-1. Confluence 증분 추출 스크립트 (incremental_export.py)

#!/usr/bin/env python3
"""
Confluence 24시간 증분 추출 → MinIO AIStor 저장
K8s CronJob에서 매일 새벽 02:00 실행
"""
import os
import datetime
import hashlib
import json
from atlassian import Confluence
import html2text
from minio import Minio

# ── 환경 변수 ──────────────────────────────────────────────
CONFLUENCE_URL  = os.getenv("CONFLUENCE_URL")
CONFLUENCE_USER = os.getenv("CONFLUENCE_USER")
CONFLUENCE_TOKEN= os.getenv("CONFLUENCE_TOKEN")
PARENT_PAGE_ID  = os.getenv("PARENT_PAGE_ID")
MINIO_URL       = os.getenv("MINIO_URL")
MINIO_ACCESS    = os.getenv("MINIO_ACCESS_KEY")
MINIO_SECRET    = os.getenv("MINIO_SECRET_KEY")
BUCKET_NAME     = "confluence-wiki"
EXPORT_DIR      = "/tmp/confluence_export"
HASH_STORE_PATH = "/tmp/hash_store.json"

confluence = Confluence(url=CONFLUENCE_URL, username=CONFLUENCE_USER, password=CONFLUENCE_TOKEN)
minio_client = Minio(MINIO_URL, access_key=MINIO_ACCESS, secret_key=MINIO_SECRET, secure=True)

h = html2text.HTML2Text()
h.ignore_links = False
h.body_width = 0  # 줄바꿈 없이 원형 유지

def load_hash_store():
    """이전 실행의 파일 해시값 로드 (중복 처리 방지)"""
    try:
        resp = minio_client.get_object(BUCKET_NAME, "metadata/hash_store.json")
        return json.loads(resp.read())
    except Exception:
        return {}

def save_hash_store(store: dict):
    data = json.dumps(store).encode()
    from io import BytesIO
    minio_client.put_object(BUCKET_NAME, "metadata/hash_store.json", BytesIO(data), len(data))

def extract_page(page_id: str, title: str) -> str:
    """Confluence 페이지 → Markdown 변환"""
    detail = confluence.get_page_by_id(page_id, expand='body.storage,version,ancestors')
    html_body = detail['body']['storage']['value']
    version = detail['version']['number']

    # 첨부 이미지 수집
    attachments = confluence.get_attachments_from_content(page_id)
    attachment_map = {}
    for att in attachments.get('results', []):
        att_title = att['title']
        att_url = f"{CONFLUENCE_URL}{att['_links']['download']}"
        attachment_map[att_title] = f"./assets/{att_title}"

    md_content = h.handle(html_body)

    # 첨부 이미지 경로를 상대 경로로 교체
    for original_url, relative_path in attachment_map.items():
        md_content = md_content.replace(original_url, relative_path)

    # YAML Frontmatter 초안 삽입 (LLM이 나중에 완성)
    safe_title = title.replace("/", "-").replace(" ", "-").lower()
    frontmatter = f"""---
id: "PENDING-{page_id}"
title: "{title}"
source: "confluence"
source_page_id: "{page_id}"
source_version: {version}
status: "draft"
auto_classified: false
created_at: "{datetime.date.today()}"
last_verified_at: "{datetime.date.today()}"
---

"""
    return frontmatter + md_content

def run_incremental_export():
    os.makedirs(EXPORT_DIR, exist_ok=True)
    hash_store = load_hash_store()

    # 24시간 이내 변경 페이지만 CQL로 추출
    cql = f'ancestor = {PARENT_PAGE_ID} AND lastModified >= now("-1d") ORDER BY lastModified DESC'
    results = confluence.cql(cql).get('results', [])
    print(f"[INFO] Found {len(results)} updated pages in last 24h")

    exported_count = 0
    for item in results:
        page = item.get('content', {})
        page_id = page.get('id')
        title = page.get('title', 'untitled').replace("/", "-")

        try:
            md_content = extract_page(page_id, title)
            content_hash = hashlib.sha256(md_content.encode()).hexdigest()

            # 해시 비교 → 변경된 파일만 처리
            if hash_store.get(page_id) == content_hash:
                print(f"[SKIP] No change: {title}")
                continue

            # MinIO raw/ 버킷에 저장 (날짜별 경로)
            date_prefix = datetime.date.today().strftime("%Y-%m-%d")
            minio_path = f"raw/{date_prefix}/{title}.md"
            data = md_content.encode('utf-8')
            from io import BytesIO
            minio_client.put_object(BUCKET_NAME, minio_path, BytesIO(data), len(data),
                                    content_type="text/markdown")

            hash_store[page_id] = content_hash
            exported_count += 1
            print(f"[OK] Exported: {title} → {minio_path}")

        except Exception as e:
            print(f"[ERROR] Failed to export {title}: {e}")

    save_hash_store(hash_store)
    print(f"[DONE] Exported {exported_count} pages to MinIO")

if __name__ == "__main__":
    run_incremental_export()

3-2. LangChain 지능형 분류 처리기 (processor.py)

#!/usr/bin/env python3
"""
MinIO raw/ → LLM 분류/링크수정/메타데이터 생성 → wiki/ 폴더 구조 출력
Argo Workflows langchain-processor Pod 내부에서 실행
"""
import os
import re
import json
import uuid
import datetime
from minio import Minio
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.pydantic_v1 import BaseModel, Field
from typing import List, Optional
import yaml

MINIO_URL    = os.getenv("MINIO_URL")
MINIO_ACCESS = os.getenv("MINIO_ACCESS_KEY")
MINIO_SECRET = os.getenv("MINIO_SECRET_KEY")
LLM_ENDPOINT = os.getenv("LLM_ENDPOINT", "http://vllm-service.ai:8000/v1")
BUCKET_NAME  = "confluence-wiki"

minio_client = Minio(MINIO_URL, access_key=MINIO_ACCESS, secret_key=MINIO_SECRET, secure=True)

# 폐쇄망: vLLM이 OpenAI 호환 API 제공
llm = ChatOpenAI(
    model="llama-3-70b-instruct",
    base_url=LLM_ENDPOINT,
    api_key="internal",
    temperature=0
)

# ── Pydantic 출력 스키마 ─────────────────────────────────────
class DocMetadata(BaseModel):
    id_suffix: str = Field(description="문서 고유 식별자 접미사 (영문 대문자 3자리, 예: NET, K8S, MIO)")
    category: str = Field(description="SOP | Library | Architecture | Reports")
    sub_category: str = Field(description="Network | Storage | Compute | Security | Monitoring")
    tech_stack: List[str] = Field(description="관련 기술 스택 리스트 (예: ['Cilium','BGP','K8s'])")
    severity: str = Field(description="Critical | High | Medium | Low")
    summary: str = Field(description="문서 핵심 내용 한 문장 요약 (한국어)")
    tags: List[str] = Field(description="검색용 핵심 키워드 리스트 (소문자, kebab-case)")
    applies_to_version: Optional[str] = Field(description="유효 버전 (예: 'cilium>=1.15'), 없으면 null")
    contains_code: bool = Field(description="코드 블록 포함 여부")
    code_languages: List[str] = Field(description="포함된 코드 언어 리스트")
    optimized_filename: str = Field(description="파일명 (영문 kebab-case, .md 제외)")
    related_concepts: List[str] = Field(description="관련 인프라 컴포넌트 또는 개념 리스트")

structured_llm = llm.with_structured_output(DocMetadata)

# ── 내부 링크 리졸버 ──────────────────────────────────────────
def resolve_internal_links(content: str, all_filenames: list) -> str:
    """[[WikiLink]] → [WikiLink](./WikiLink.md) 변환 (파일 존재 확인 포함)"""
    def replace_link(match):
        link_text = match.group(1)
        safe_name = link_text.replace(" ", "-").lower()
        # 파일 목록에서 존재 여부 확인
        matched = next((f for f in all_filenames if safe_name in f.lower()), None)
        if matched:
            return f"[{link_text}](./{matched})"
        return f"[{link_text}](./{safe_name}.md)"  # 미래 생성 파일 대비

    # [[Link|Alias]] 형식도 처리
    content = re.sub(r'\[\[([^|\]]+)\|([^\]]+)\]\]', 
                     lambda m: f"[{m.group(2)}](./{m.group(1).replace(' ','-').lower()}.md)", 
                     content)
    # [[Link]] 형식 처리
    content = re.sub(r'\[\[([^\]]+)\]\]', replace_link, content)
    return content

# ── 중복 문서 감지 ────────────────────────────────────────────
def check_duplicate_in_wiki(new_content: str, wiki_path: str) -> Optional[str]:
    """기존 wiki 파일과 의미적 유사도 체크 (간단 버전: 제목+핵심키워드 비교)"""
    try:
        objects = minio_client.list_objects(BUCKET_NAME, prefix="wiki/active/", recursive=True)
        new_words = set(re.findall(r'\b[A-Za-z]{4,}\b', new_content[:2000]))

        for obj in objects:
            if not obj.object_name.endswith('.md'):
                continue
            resp = minio_client.get_object(BUCKET_NAME, obj.object_name)
            existing = resp.read().decode('utf-8')
            existing_words = set(re.findall(r'\b[A-Za-z]{4,}\b', existing[:2000]))

            # 70% 이상 단어 겹침 → 중복 의심
            if len(new_words) > 0:
                overlap = len(new_words & existing_words) / len(new_words | existing_words)
                if overlap > 0.7:
                    return obj.object_name
    except Exception:
        pass
    return None

# ── 메인 분류 프로세서 ────────────────────────────────────────
def process_raw_documents():
    """MinIO raw/[today]/ 의 모든 MD 파일을 처리하여 wiki/active/ 로 저장"""
    today = datetime.date.today().strftime("%Y-%m-%d")
    prefix = f"raw/{today}/"

    objects = list(minio_client.list_objects(BUCKET_NAME, prefix=prefix, recursive=True))
    all_filenames = [os.path.basename(obj.object_name) for obj in objects]
    print(f"[INFO] Processing {len(objects)} files from {prefix}")

    category_counter = {"SOP": 0, "Library": 0, "Architecture": 0, "Reports": 0}

    for obj in objects:
        if not obj.object_name.endswith('.md'):
            continue

        try:
            # 1. 파일 읽기
            resp = minio_client.get_object(BUCKET_NAME, obj.object_name)
            raw_content = resp.read().decode('utf-8')

            # 기존 YAML Frontmatter 제거 (재생성 예정)
            body = re.sub(r'^---\n.*?\n---\n', '', raw_content, flags=re.DOTALL).strip()

            # 2. 내부 링크 수정
            refined = resolve_internal_links(body, all_filenames)

            # 3. LLM 메타데이터 분류
            prompt = ChatPromptTemplate.from_template("""
당신은 플랫폼 엔지니어링 지식 관리 전문가입니다.
다음 인프라 기술 문서를 분석하여 정확한 메타데이터를 추출하세요.
문서 컨텍스트: K8s 1,000노드 클러스터, Cilium CNI, MinIO AIStor 환경

문서 내용 (앞 2000자):
{content}
""")
            chain = prompt | structured_llm
            meta: DocMetadata = chain.invoke({"content": refined[:2000]})

            # 4. 카테고리별 ID 생성
            cat_short = {"SOP": "SOP", "Library": "LIB", "Architecture": "ARCH", "Reports": "RPT"}
            cat_key = cat_short.get(meta.category, "DOC")
            category_counter[meta.category] = category_counter.get(meta.category, 0) + 1
            doc_id = f"{cat_key}-{meta.id_suffix}-{category_counter.get(meta.category, 1):03d}"

            # 5. 완전한 YAML Frontmatter 생성
            frontmatter = {
                "id": doc_id,
                "title": meta.optimized_filename.replace("-", " ").title(),
                "category": meta.category,
                "sub_category": meta.sub_category,
                "tech_stack": meta.tech_stack,
                "status": "active",
                "severity": meta.severity,
                "summary": meta.summary,
                "tags": meta.tags,
                "applies_to_version": meta.applies_to_version,
                "contains_code": meta.contains_code,
                "code_languages": meta.code_languages,
                "related_docs": [],
                "related_concepts": meta.related_concepts,
                "source": "confluence",
                "auto_classified": True,
                "created_at": str(datetime.date.today()),
                "last_verified_at": str(datetime.date.today()),
                "verified_by": "auto-pipeline",
                "environment": ["production"],
                "expires_at": None,
                "pipeline_version": "v1.2"
            }

            final_content = f"---\n{yaml.dump(frontmatter, allow_unicode=True, default_flow_style=False)}---\n\n{refined}"

            # 6. 중복 체크
            duplicate_path = check_duplicate_in_wiki(refined, obj.object_name)
            if duplicate_path:
                # 기존 파일을 deprecated로 상태 변경
                print(f"[WARN] Duplicate detected: {duplicate_path} → marking as deprecated")
                _deprecate_document(duplicate_path)

            # 7. wiki/active/[Category]/[SubCat]/ 경로로 저장
            target_path = f"wiki/active/{meta.category}/{meta.sub_category}/{meta.optimized_filename}.md"
            data = final_content.encode('utf-8')
            from io import BytesIO
            minio_client.put_object(BUCKET_NAME, target_path, BytesIO(data), len(data),
                                    content_type="text/markdown")

            print(f"[OK] Classified: {obj.object_name} → {target_path} [{doc_id}]")

        except Exception as e:
            print(f"[ERROR] Failed to process {obj.object_name}: {e}")
            import traceback; traceback.print_exc()

def _deprecate_document(minio_path: str):
    """기존 문서의 status를 deprecated로 변경"""
    try:
        resp = minio_client.get_object(BUCKET_NAME, minio_path)
        content = resp.read().decode('utf-8')
        content = re.sub(r'status: "active"', 'status: "deprecated"', content)
        data = content.encode('utf-8')
        from io import BytesIO
        minio_client.put_object(BUCKET_NAME, minio_path, BytesIO(data), len(data))
    except Exception as e:
        print(f"[ERROR] Failed to deprecate {minio_path}: {e}")

if __name__ == "__main__":
    process_raw_documents()

3-3. Git 동기화 스크립트 (sync_to_git.sh)

#!/bin/bash
# MinIO wiki/ 내용을 Git 저장소에 동기화
# Argo Workflows git-sync Pod에서 실행

set -euo pipefail

GIT_REPO_URL="https://${GIT_TOKEN}@${GIT_HOST}/platform/llm-wiki.git"
CLONE_DIR="/workspace/llm-wiki"
BUCKET="confluence-wiki"

echo "[STEP 1] Git clone or pull"
if [ ! -d "$CLONE_DIR/.git" ]; then
    git clone "$GIT_REPO_URL" "$CLONE_DIR"
fi
cd "$CLONE_DIR"
git config user.email "aiops-bot@internal.com"
git config user.name "AIOps Pipeline Bot"
git pull origin main --rebase

echo "[STEP 2] Sync MinIO wiki/ → local"
mc alias set myminio "${MINIO_URL}" "${MINIO_ACCESS_KEY}" "${MINIO_SECRET_KEY}"
mc mirror myminio/confluence-wiki/wiki/ "$CLONE_DIR/wiki/" --overwrite

echo "[STEP 3] Archive lifecycle check (365일 초과 deprecated 문서 자동 이동)"
python3 /app/lifecycle_manager.py --action archive --clone-dir "$CLONE_DIR"

echo "[STEP 4] Git commit & push"
git add wiki/
CHANGED=$(git diff --cached --name-only | wc -l)
if [ "$CHANGED" -gt "0" ]; then
    COMMIT_MSG="Auto-sync: ${CHANGED} docs updated [$(date +%Y-%m-%d %H:%M)] via AIOps Pipeline"
    git commit -m "$COMMIT_MSG"
    git push origin main
    echo "[OK] Pushed $CHANGED changed files to Git"
else
    echo "[SKIP] No changes detected, nothing to push"
fi

echo "[DONE] Git sync completed"

3-4. 문서 생애주기 관리 (lifecycle_manager.py)

#!/usr/bin/env python3
"""
문서 생애주기 자동 관리
- 180일 미검증 → Slack 알림
- 365일 deprecated → archive 자동 이동
- Argo CronJob 또는 Git sync 후 호출
"""
import os
import re
import yaml
import datetime
import argparse
import requests
from pathlib import Path

SLACK_WEBHOOK = os.getenv("SLACK_WEBHOOK_URL")
ARCHIVE_DAYS  = 365
ALERT_DAYS    = 180

def parse_frontmatter(content: str) -> dict:
    match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
    if match:
        try:
            return yaml.safe_load(match.group(1)) or {}
        except Exception:
            return {}
    return {}

def update_frontmatter(content: str, updates: dict) -> str:
    match = re.match(r'^(---\n)(.*?)(\n---)', content, re.DOTALL)
    if not match:
        return content
    try:
        fm = yaml.safe_load(match.group(2)) or {}
        fm.update(updates)
        new_fm = yaml.dump(fm, allow_unicode=True, default_flow_style=False).strip()
        return f"---\n{new_fm}\n---{content[match.end():]}"
    except Exception:
        return content

def send_slack_alert(doc_id: str, title: str, last_verified: str, file_path: str):
    if not SLACK_WEBHOOK:
        print(f"[ALERT] {doc_id} ({title}): 검증 기간 초과 - {last_verified}")
        return
    msg = {
        "blocks": [
            {"type": "section", "text": {"type": "mrkdwn",
             "text": f":warning: *문서 검증 기간 초과 알림*\n"
                     f"*ID:* `{doc_id}`\n*제목:* {title}\n"
                     f"*마지막 검증:* {last_verified}\n*경로:* `{file_path}`"}},
            {"type": "actions", "elements": [
                {"type": "button", "text": {"type": "plain_text", "text": "검증 완료로 표시"},
                 "style": "primary", "value": doc_id},
                {"type": "button", "text": {"type": "plain_text", "text": "아카이브"},
                 "style": "danger", "value": f"archive:{doc_id}"}
            ]}
        ]
    }
    requests.post(SLACK_WEBHOOK, json=msg)

def run_lifecycle_check(clone_dir: str, action: str = "check"):
    today = datetime.date.today()
    wiki_path = Path(clone_dir) / "wiki" / "active"
    archived_count = 0
    alerted_count  = 0

    for md_file in wiki_path.rglob("*.md"):
        content = md_file.read_text(encoding='utf-8')
        fm = parse_frontmatter(content)
        if not fm:
            continue

        status = fm.get("status", "active")
        last_verified_str = str(fm.get("last_verified_at", ""))
        doc_id = fm.get("id", "UNKNOWN")
        title  = fm.get("title", str(md_file.name))

        try:
            last_verified = datetime.date.fromisoformat(last_verified_str)
        except (ValueError, TypeError):
            last_verified = today - datetime.timedelta(days=ALERT_DAYS + 1)

        age_days = (today - last_verified).days

        # 365일 초과 deprecated → archive 폴더로 자동 이동
        if status == "deprecated" and age_days >= ARCHIVE_DAYS and action == "archive":
            archive_target = Path(clone_dir) / "wiki" / "archive" / md_file.relative_to(wiki_path)
            archive_target.parent.mkdir(parents=True, exist_ok=True)

            updated = update_frontmatter(content, {
                "status": "archive",
                "archived_at": str(today),
                "archive_reason": f"Auto-archived after {age_days} days without verification"
            })
            archive_target.write_text(updated, encoding='utf-8')
            md_file.unlink()
            archived_count += 1
            print(f"[ARCHIVE] {doc_id}: {md_file.name} → archive/")

        # 180일 초과 active → Slack 경고
        elif status == "active" and age_days >= ALERT_DAYS:
            if action in ("check", "alert"):
                send_slack_alert(doc_id, title, last_verified_str, str(md_file))
                alerted_count += 1

    print(f"[LIFECYCLE] archived={archived_count}, alerted={alerted_count}")

if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("--action", choices=["check", "alert", "archive"], default="check")
    parser.add_argument("--clone-dir", default="/workspace/llm-wiki")
    args = parser.parse_args()
    run_lifecycle_check(args.clone_dir, args.action)

3-5. Vector DB 인덱싱 파이프라인 (indexer.py)

#!/usr/bin/env python3
"""
Git wiki/ → Milvus Vector DB 증분 인덱싱
LangChain RecordManager로 중복/삭제 자동 동기화
Hybrid Search: Dense(Embedding) + Sparse(BM25) 지원
"""
import os
import re
from pathlib import Path
from langchain_community.document_loaders import UnstructuredMarkdownLoader
from langchain_text_splitters import MarkdownHeaderTextSplitter
from langchain_huggingface import HuggingFaceEmbeddings  # 폐쇄망용
from langchain_community.vectorstores import Milvus
from langchain.indexes import SQLRecordManager, index
from langchain_core.documents import Document
import yaml

WIKI_DIR    = os.getenv("WIKI_DIR", "/workspace/llm-wiki/wiki/active")
MILVUS_HOST = os.getenv("MILVUS_HOST", "milvus-service.storage")
MILVUS_PORT = os.getenv("MILVUS_PORT", "19530")
MODEL_PATH  = os.getenv("EMBEDDING_MODEL_PATH", "/models/bge-m3")  # 폐쇄망 로컬 모델
COLLECTION  = "platform_ops_wiki"
DB_URL      = os.getenv("RECORD_MANAGER_DB", "sqlite:////data/record_manager.db")

# ── 임베딩 모델 (폐쇄망: HuggingFace 로컬 모델) ──────────────
embeddings = HuggingFaceEmbeddings(
    model_name=MODEL_PATH,
    model_kwargs={'device': 'cuda'},
    encode_kwargs={'normalize_embeddings': True}
)

# ── Vector Store ──────────────────────────────────────────────
vector_store = Milvus(
    embedding_function=embeddings,
    collection_name=COLLECTION,
    connection_args={"host": MILVUS_HOST, "port": MILVUS_PORT},
    index_params={"metric_type": "COSINE"},
)

# ── RecordManager: 중복/삭제 자동 동기화 ──────────────────────
record_manager = SQLRecordManager(namespace=f"milvus/{COLLECTION}", db_url=DB_URL)
record_manager.create_schema()

# ── 마크다운 헤더 기반 청킹 ────────────────────────────────────
HEADERS_TO_SPLIT = [("#", "h1"), ("##", "h2"), ("###", "h3")]
text_splitter = MarkdownHeaderTextSplitter(HEADERS_TO_SPLIT, strip_headers=False)

def parse_frontmatter(content: str) -> dict:
    match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
    if match:
        try:
            return yaml.safe_load(match.group(1)) or {}
        except Exception:
            return {}
    return {}

def load_documents(wiki_dir: str) -> list[Document]:
    """wiki/active/ 모든 MD 파일 → LangChain Document 리스트 (메타데이터 포함)"""
    docs = []
    for md_path in Path(wiki_dir).rglob("*.md"):
        content = md_path.read_text(encoding='utf-8')
        fm = parse_frontmatter(content)

        # status가 active인 문서만 인덱싱
        if fm.get("status") not in ("active", None):
            continue

        # YAML Frontmatter 제거 후 본문만 청킹
        body = re.sub(r'^---\n.*?\n---\n', '', content, flags=re.DOTALL).strip()
        chunks = text_splitter.split_text(body)

        for chunk in chunks:
            # 청킹된 각 조각에 문서 메타데이터 부착
            chunk.metadata.update({
                "doc_id":       fm.get("id", ""),
                "category":     fm.get("category", ""),
                "sub_category": fm.get("sub_category", ""),
                "tech_stack":   ",".join(fm.get("tech_stack", [])),
                "severity":     fm.get("severity", ""),
                "status":       fm.get("status", "active"),
                "tags":         ",".join(fm.get("tags", [])),
                "summary":      fm.get("summary", ""),
                "last_verified":str(fm.get("last_verified_at", "")),
                "file_path":    str(md_path.relative_to(wiki_dir)),
                "source":       fm.get("source", ""),
            })
            docs.append(chunk)

    return docs

def run_indexing():
    print(f"[INFO] Loading documents from {WIKI_DIR}")
    docs = load_documents(WIKI_DIR)
    print(f"[INFO] Total chunks to index: {len(docs)}")

    # cleanup="incremental": 변경된 문서만 업데이트, 삭제된 문서는 DB에서도 삭제
    result = index(
        docs,
        record_manager,
        vector_store,
        cleanup="incremental",
        source_id_key="doc_id"
    )
    print(f"[DONE] Indexing result: {result}")

if __name__ == "__main__":
    run_indexing()

3-6. LangGraph AIOps 모니터링 에이전트 (aiops_agent.py)

#!/usr/bin/env python3
"""
K8s 실시간 이벤트 + RAG(Wiki) 기반 AIOps 에이전트
기능:
  1. 이벤트 수집 & 증상 분석
  2. 관련 SOP/Library RAG 검색
  3. 근본 원인 분석 (Root Cause Analysis)
  4. 해결책 생성 & 실행 가능 명령어 제시
  5. 리스크 예측 (Proactive Risk Detection)
"""
import os
import json
from typing import TypedDict, Annotated, List, Optional
from langgraph.graph import StateGraph, END
from langgraph.graph.message import add_messages
from langchain_core.messages import HumanMessage, AIMessage, SystemMessage
from langchain_openai import ChatOpenAI
from langchain_huggingface import HuggingFaceEmbeddings
from langchain_community.vectorstores import Milvus
from kubernetes import client, config

LLM_ENDPOINT  = os.getenv("LLM_ENDPOINT", "http://vllm-service.ai:8000/v1")
MILVUS_HOST   = os.getenv("MILVUS_HOST", "milvus-service.storage")
MODEL_PATH    = os.getenv("EMBEDDING_MODEL_PATH", "/models/bge-m3")
COLLECTION    = "platform_ops_wiki"

llm = ChatOpenAI(model="llama-3-70b-instruct", base_url=LLM_ENDPOINT, api_key="internal", temperature=0)

embeddings = HuggingFaceEmbeddings(model_name=MODEL_PATH, model_kwargs={'device': 'cpu'})
vector_store = Milvus(
    embedding_function=embeddings,
    collection_name=COLLECTION,
    connection_args={"host": MILVUS_HOST, "port": MILVUS_PORT},
)

# ── K8s 클라이언트 초기화 ─────────────────────────────────────
try:
    config.load_incluster_config()
except Exception:
    config.load_kube_config()

k8s_core = client.CoreV1Api()
k8s_apps = client.AppsV1Api()

# ── 에이전트 상태 정의 ────────────────────────────────────────
class AIOpsState(TypedDict):
    messages: Annotated[list, add_messages]
    event_raw: str                    # 원본 K8s 이벤트/알람
    symptoms: str                     # 분석된 증상
    search_query: str                 # RAG 검색 쿼리
    retrieved_docs: List[dict]        # 검색된 관련 문서
    root_cause: str                   # 근본 원인 분석 결과
    solution: str                     # 제안된 해결책 + 명령어
    risk_prediction: str              # 예측된 리스크
    k8s_context: dict                 # K8s 클러스터 실시간 상태
    retry_count: int                  # 재시도 횟수 (루프 제어)
    confidence: float                 # 분석 신뢰도 (0~1)

# ── Node 1: K8s 컨텍스트 수집 ──────────────────────────────────
def collect_k8s_context(state: AIOpsState) -> AIOpsState:
    """이벤트와 관련된 K8s 실시간 상태 수집"""
    ctx = {}
    event_text = state["event_raw"]

    try:
        # 네임스페이스 추출 시도
        ns_match = __import__('re').search(r'namespace[=: ]+(\S+)', event_text, re.IGNORECASE)
        namespace = ns_match.group(1) if ns_match else "kube-system"

        # 최근 이벤트 수집
        events = k8s_core.list_namespaced_event(
            namespace=namespace,
            limit=20,
            field_selector="type=Warning"
        )
        ctx["recent_warnings"] = [
            {"reason": e.reason, "message": e.message, "object": e.involved_object.name}
            for e in events.items
        ]

        # 비정상 파드 수집
        pods = k8s_core.list_namespaced_pod(namespace=namespace)
        ctx["unhealthy_pods"] = [
            {"name": p.metadata.name, "phase": p.status.phase,
             "conditions": [c.type for c in (p.status.conditions or []) if not c.status == "True"]}
            for p in pods.items
            if p.status.phase not in ("Running", "Succeeded")
        ]

        # 노드 상태
        nodes = k8s_core.list_node()
        ctx["node_summary"] = {
            "total": len(nodes.items),
            "not_ready": [n.metadata.name for n in nodes.items
                          if not any(c.type == "Ready" and c.status == "True"
                                     for c in (n.status.conditions or []))]
        }

    except Exception as e:
        ctx["error"] = str(e)

    state["k8s_context"] = ctx
    return state

# ── Node 2: 증상 분석 ──────────────────────────────────────────
def analyze_symptoms(state: AIOpsState) -> AIOpsState:
    """이벤트 + K8s 컨텍스트 → 증상 구조화"""
    prompt = f"""
당신은 K8s 인프라 전문가입니다. 다음 이벤트와 클러스터 상태를 분석하여 정확한 증상을 파악하세요.

## 원본 이벤트/알람:
{state['event_raw']}

## 실시간 K8s 상태:
{json.dumps(state['k8s_context'], ensure_ascii=False, indent=2)}

다음 형식으로 분석하세요:
1. **주요 증상**: 가장 명확한 이상 현상
2. **영향 범위**: 영향받는 컴포넌트/네임스페이스/노드
3. **심각도**: Critical/High/Medium/Low
4. **검색 키워드**: 관련 문서 검색에 쓸 핵심 키워드 (3~5개)
"""
    response = llm.invoke([HumanMessage(content=prompt)])
    state["symptoms"] = response.content

    # 검색 쿼리 추출
    keywords = __import__('re').findall(r'\*\*검색 키워드\*\*:?\s*(.+)', response.content)
    state["search_query"] = keywords[0] if keywords else state["event_raw"][:200]

    return state

# ── Node 3: RAG 검색 (Hybrid Search) ─────────────────────────
def retrieve_knowledge(state: AIOpsState) -> AIOpsState:
    """Milvus Hybrid Search: 의미 검색 + 메타데이터 필터링"""
    query = state["search_query"]

    # 카테고리 필터: SOP 우선 검색
    sop_results = vector_store.similarity_search_with_score(
        query,
        k=3,
        expr='category == "SOP" and status == "active"'
    )

    # Library/Architecture도 추가 검색
    lib_results = vector_store.similarity_search_with_score(
        query,
        k=3,
        expr='(category == "Library" or category == "Architecture") and status == "active"'
    )

    all_results = sop_results + lib_results
    # 유사도 점수 기준 정렬 (낮을수록 유사)
    all_results.sort(key=lambda x: x[1])

    retrieved = []
    for doc, score in all_results[:5]:
        retrieved.append({
            "doc_id":   doc.metadata.get("doc_id"),
            "category": doc.metadata.get("category"),
            "severity": doc.metadata.get("severity"),
            "content":  doc.page_content,
            "score":    round(score, 4),
            "file_path":doc.metadata.get("file_path"),
        })

    state["retrieved_docs"] = retrieved
    return state

# ── Node 4: 근본 원인 분석 ────────────────────────────────────
def analyze_root_cause(state: AIOpsState) -> AIOpsState:
    """증상 + 검색 결과 → 근본 원인 분석 + 신뢰도 평가"""
    docs_context = "\n\n---\n".join([
        f"[{d['doc_id']}] (유사도: {d['score']})\n{d['content']}"
        for d in state["retrieved_docs"]
    ])

    prompt = f"""
당신은 1,000노드 K8s 클러스터 운영 전문가입니다.

## 분석된 증상:
{state['symptoms']}

## 참조 문서 (SOP/Library):
{docs_context}

## K8s 실시간 상태:
{json.dumps(state['k8s_context'], ensure_ascii=False)}

근본 원인을 분석하세요:

1. **근본 원인**: 가장 가능성 높은 원인 (1~2가지)
2. **원인 근거**: 증상과 참조 문서를 연결한 논리적 근거
3. **관련 컴포넌트**: 직접 관련된 K8s/Cilium/MinIO 컴포넌트
4. **분석 신뢰도**: 0.0~1.0 (참조 문서의 관련성이 낮으면 낮게 평가)
"""
    response = llm.invoke([HumanMessage(content=prompt)])
    state["root_cause"] = response.content

    # 신뢰도 추출
    conf_match = __import__('re').search(r'분석 신뢰도.*?([0-9]\.[0-9]+)', response.content)
    state["confidence"] = float(conf_match.group(1)) if conf_match else 0.5

    return state

# ── Node 5: 해결책 생성 ────────────────────────────────────────
def generate_solution(state: AIOpsState) -> AIOpsState:
    """근본 원인 → 단계별 해결책 + 실행 가능한 명령어 생성"""
    prompt = f"""
## 근본 원인 분석:
{state['root_cause']}

## 관련 SOP/Library 요약:
{chr(10).join([d['content'][:500] for d in state['retrieved_docs'][:2]])}

즉시 실행 가능한 해결책을 제시하세요:

1. **즉각 조치 (0~5분)**: 피해 최소화를 위한 긴급 조치
2. **단계별 복구 절차**: 순서대로 실행할 kubectl/cilium 명령어 포함
3. **검증 방법**: 복구 성공 여부를 확인하는 방법
4. **재발 방지**: 같은 이슈가 재발하지 않도록 하는 설정 변경

```bash
# 즉각 조치 명령어 예시
# (실제 리소스명으로 교체 필요)

주의사항: 이 명령어는 Production 환경에 적용 전 반드시 검토하세요. """ response = llm.invoke([HumanMessage(content=prompt)]) state["solution"] = response.content return state

── Node 6: 리스크 예측 ────────────────────────────────────────

def predict_risks(state: AIOpsState) -> AIOpsState: """현재 상태 기반 근시일 내 발생 가능한 리스크 예측""" prompt = f"""

현재 장애 상황:

{state['symptoms']}

K8s 클러스터 상태:

{json.dumps(state['k8s_context'], ensure_ascii=False)}

이미 수집된 운영 지식:

{chr(10).join([d['content'][:300] for d in state['retrieved_docs'][:3]])}

현재 상황을 방치하거나 부분 조치만 취했을 때 발생 가능한 리스크를 예측하세요:

1. 단기 리스크 (24시간 내): 연쇄 장애 가능성
2. 중기 리스크 (1주일 내): 성능 저하 또는 데이터 손실 위험
3. 선제 조치 권장: 리스크를 사전에 차단하기 위한 예방 조치

리스크별 확률(%)과 영향도(Critical/High/Medium)도 표시하세요. """ response = llm.invoke([HumanMessage(content=prompt)]) state["risk_prediction"] = response.content return state

── 조건부 엣지: 신뢰도 낮으면 재검색 ───────────────────────

def should_retry_search(state: AIOpsState) -> str: if state["confidence"] < 0.4 and state["retry_count"] < 2: state["retry_count"] += 1 state["search_query"] = state["symptoms"][:300] # 더 넓은 쿼리로 재시도 print(f"[RETRY] Low confidence ({state['confidence']}), retrying search...") return "retrieve_knowledge" return "generate_solution"

── LangGraph 워크플로우 구성 ─────────────────────────────────

def build_aiops_graph() -> StateGraph: graph = StateGraph(AIOpsState)

graph.add_node("collect_k8s_context", collect_k8s_context)
graph.add_node("analyze_symptoms",    analyze_symptoms)
graph.add_node("retrieve_knowledge",  retrieve_knowledge)
graph.add_node("analyze_root_cause",  analyze_root_cause)
graph.add_node("generate_solution",   generate_solution)
graph.add_node("predict_risks",       predict_risks)

graph.set_entry_point("collect_k8s_context")
graph.add_edge("collect_k8s_context", "analyze_symptoms")
graph.add_edge("analyze_symptoms",    "retrieve_knowledge")
graph.add_edge("retrieve_knowledge",  "analyze_root_cause")

# 조건부 엣지: 신뢰도 낮으면 재검색 루프
graph.add_conditional_edges("analyze_root_cause", should_retry_search,
                            {"retrieve_knowledge": "retrieve_knowledge",
                             "generate_solution": "generate_solution"})
graph.add_edge("generate_solution", "predict_risks")
graph.add_edge("predict_risks",     END)

return graph.compile()

def analyze_event(event_text: str) -> dict: """외부에서 호출하는 메인 분석 함수""" graph = build_aiops_graph() initial_state = AIOpsState( messages=[], event_raw=event_text, symptoms="", search_query="", retrieved_docs=[], root_cause="", solution="", risk_prediction="", k8s_context={}, retry_count=0, confidence=0.0, ) result = graph.invoke(initial_state) return { "symptoms": result["symptoms"], "root_cause": result["root_cause"], "solution": result["solution"], "risk_prediction": result["risk_prediction"], "confidence": result["confidence"], "referenced_docs": [d["doc_id"] for d in result["retrieved_docs"]], }

if name == "main": # 테스트 이벤트 test_event = """ ALERT: CiliumNetworkPolicy not enforced Namespace: production Node: k8s-worker-042 Message: BGP peer 10.0.0.1 connection lost, routes not propagated Timestamp: 2026-04-29T03:14:00Z """ result = analyze_event(test_event) import json print(json.dumps(result, ensure_ascii=False, indent=2))

---

### 3-7. Argo Workflows 전체 파이프라인 YAML

```yaml
# argo-pipeline.yaml
# kubectl apply -f argo-pipeline.yaml
apiVersion: argoproj.io/v1alpha1
kind: CronWorkflow
metadata:
  name: llm-wiki-pipeline
  namespace: platform-ops
spec:
  schedule: "0 2 * * *"     # 매일 새벽 2시
  timezone: "Asia/Seoul"
  concurrencyPolicy: Forbid  # 중복 실행 방지
  workflowSpec:
    serviceAccountName: argo-wiki-sa
    entrypoint: main-pipeline

    # 공유 볼륨 (파이프라인 단계 간 데이터 공유)
    volumes:
    - name: workspace
      persistentVolumeClaim:
        claimName: wiki-pipeline-pvc

    templates:
    # ── 메인 DAG ───────────────────────────────────────────────
    - name: main-pipeline
      dag:
        tasks:
        - name: step1-extract
          template: confluence-extractor

        - name: step2-process
          dependencies: [step1-extract]
          template: langchain-processor

        - name: step3-lifecycle
          dependencies: [step2-process]
          template: lifecycle-manager

        - name: step4-git-sync
          dependencies: [step3-lifecycle]
          template: git-syncer

        - name: step5-indexing
          dependencies: [step4-git-sync]
          template: vector-indexer

        - name: step6-notify
          dependencies: [step5-indexing]
          template: slack-notifier

    # ── Step 1: Confluence 증분 추출 ───────────────────────────
    - name: confluence-extractor
      container:
        image: internal-reg.com/wiki-pipeline/extractor:v1.2
        command: ["python", "incremental_export.py"]
        resources:
          requests: {cpu: "500m", memory: "1Gi"}
          limits:   {cpu: "2", memory: "2Gi"}
        envFrom:
        - secretRef:
            name: wiki-pipeline-secrets
        volumeMounts:
        - name: workspace
          mountPath: /workspace

    # ── Step 2: LLM 분류 처리 (GPU 활용) ──────────────────────
    - name: langchain-processor
      container:
        image: internal-reg.com/wiki-pipeline/processor:v1.2
        command: ["python", "processor.py"]
        resources:
          requests: {cpu: "2", memory: "8Gi", "nvidia.com/gpu": "1"}
          limits:   {cpu: "8", memory: "16Gi", "nvidia.com/gpu": "1"}
        nodeSelector:
          accelerator: nvidia-gpu
        envFrom:
        - secretRef:
            name: wiki-pipeline-secrets
        env:
        - name: LLM_ENDPOINT
          value: "http://vllm-service.ai-namespace:8000/v1"
        volumeMounts:
        - name: workspace
          mountPath: /workspace

    # ── Step 3: 생애주기 관리 ──────────────────────────────────
    - name: lifecycle-manager
      container:
        image: internal-reg.com/wiki-pipeline/processor:v1.2
        command: ["python", "lifecycle_manager.py", "--action", "archive",
                  "--clone-dir", "/workspace/llm-wiki"]
        resources:
          requests: {cpu: "200m", memory: "512Mi"}
          limits:   {cpu: "1", memory: "1Gi"}
        envFrom:
        - secretRef:
            name: wiki-pipeline-secrets
        volumeMounts:
        - name: workspace
          mountPath: /workspace

    # ── Step 4: Git 동기화 ─────────────────────────────────────
    - name: git-syncer
      container:
        image: internal-reg.com/wiki-pipeline/git-tools:v1.0
        command: ["/bin/bash", "/app/sync_to_git.sh"]
        resources:
          requests: {cpu: "200m", memory: "256Mi"}
        envFrom:
        - secretRef:
            name: wiki-pipeline-secrets
        volumeMounts:
        - name: workspace
          mountPath: /workspace

    # ── Step 5: Vector DB 인덱싱 ──────────────────────────────
    - name: vector-indexer
      container:
        image: internal-reg.com/wiki-pipeline/indexer:v1.2
        command: ["python", "indexer.py"]
        resources:
          requests: {cpu: "1", memory: "4Gi"}
          limits:   {cpu: "4", memory: "8Gi"}
        env:
        - name: WIKI_DIR
          value: "/workspace/llm-wiki/wiki/active"
        - name: EMBEDDING_MODEL_PATH
          value: "/models/bge-m3"
        envFrom:
        - secretRef:
            name: wiki-pipeline-secrets
        volumeMounts:
        - name: workspace
          mountPath: /workspace
        - name: models
          mountPath: /models
          readOnly: true
      volumes:
      - name: models
        hostPath:
          path: /data/models

    # ── Step 6: 완료 알림 ─────────────────────────────────────
    - name: slack-notifier
      container:
        image: curlimages/curl:latest
        command: [sh, -c]
        args:
        - |
          curl -X POST $SLACK_WEBHOOK_URL \
            -H 'Content-type: application/json' \
            -d '{"text":"✅ LLM Wiki 파이프라인 완료 ('"$(date '+%Y-%m-%d %H:%M')"')\n자세한 내용: Argo UI 확인"}'
        envFrom:
        - secretRef:
            name: wiki-pipeline-secrets
---
# K8s Secret (실제 배포 시 Vault 또는 Sealed Secrets 권장)
apiVersion: v1
kind: Secret
metadata:
  name: wiki-pipeline-secrets
  namespace: platform-ops
type: Opaque
stringData:
  CONFLUENCE_URL:   "https://your-domain.atlassian.net/wiki"
  CONFLUENCE_USER:  "admin@company.com"
  CONFLUENCE_TOKEN: "your-api-token"
  PARENT_PAGE_ID:   "12345678"
  MINIO_URL:        "minio.storage.svc.cluster.local:9000"
  MINIO_ACCESS_KEY: "minio-user"
  MINIO_SECRET_KEY: "minio-password"
  GIT_TOKEN:        "your-git-token"
  GIT_HOST:         "bitbucket.internal.com"
  MILVUS_HOST:      "milvus.storage.svc.cluster.local"
  SLACK_WEBHOOK_URL:"https://hooks.slack.com/services/..."

3-8. AIOps API 서버 (api_server.py)

Lens 로컬 PC 및 모니터링 시스템에서 에이전트를 호출하는 FastAPI 엔드포인트입니다.

#!/usr/bin/env python3
"""
AIOps Agent FastAPI 서버
- Lens(로컬 PC) 에서 HTTP 호출
- Alertmanager Webhook 수신
- 모니터링 시스템 연동
"""
from fastapi import FastAPI, BackgroundTasks
from pydantic import BaseModel
from typing import Optional
import asyncio
from aiops_agent import analyze_event  # 위의 LangGraph 에이전트 임포트
import uvicorn

app = FastAPI(title="AIOps Agent API", version="1.0.0")

class EventRequest(BaseModel):
    event_text: str
    source: str = "manual"        # manual | alertmanager | prometheus | lens
    namespace: Optional[str] = None
    severity: Optional[str] = None

class AlertmanagerWebhook(BaseModel):
    """Prometheus Alertmanager Webhook 형식"""
    alerts: list
    groupLabels: dict
    commonAnnotations: dict

# ── 즉시 분석 엔드포인트 ─────────────────────────────────────
@app.post("/analyze")
async def analyze(req: EventRequest):
    """이벤트 텍스트 즉시 분석 (Lens 또는 사내 모니터링 시스템에서 호출)"""
    result = await asyncio.get_event_loop().run_in_executor(
        None, analyze_event, req.event_text
    )
    return {
        "status": "ok",
        "source": req.source,
        "analysis": result
    }

# ── Alertmanager Webhook 수신 ─────────────────────────────────
@app.post("/webhook/alertmanager")
async def alertmanager_webhook(payload: AlertmanagerWebhook, background_tasks: BackgroundTasks):
    """Prometheus Alertmanager에서 실시간 알람 수신 → 백그라운드 분석"""
    for alert in payload.alerts:
        if alert.get("status") == "firing":
            event_text = (
                f"ALERT: {alert.get('labels', {}).get('alertname', 'Unknown')}\n"
                f"Namespace: {alert.get('labels', {}).get('namespace', 'unknown')}\n"
                f"Severity: {alert.get('labels', {}).get('severity', 'unknown')}\n"
                f"Summary: {alert.get('annotations', {}).get('summary', '')}\n"
                f"Description: {alert.get('annotations', {}).get('description', '')}"
            )
            background_tasks.add_task(_analyze_and_notify, event_text)
    return {"status": "received"}

async def _analyze_and_notify(event_text: str):
    """백그라운드: 분석 후 Slack으로 결과 전송"""
    import httpx, os
    result = await asyncio.get_event_loop().run_in_executor(None, analyze_event, event_text)

    slack_msg = {
        "blocks": [
            {"type": "header", "text": {"type": "plain_text",
             "text": f"🚨 AIOps 장애 분석 결과 (신뢰도: {result['confidence']:.0%})"}},
            {"type": "section", "text": {"type": "mrkdwn",
             "text": f"*📋 증상 요약*\n{result['symptoms'][:500]}"}},
            {"type": "divider"},
            {"type": "section", "text": {"type": "mrkdwn",
             "text": f"*🔍 근본 원인*\n{result['root_cause'][:600]}"}},
            {"type": "divider"},
            {"type": "section", "text": {"type": "mrkdwn",
             "text": f"*🛠 해결책*\n{result['solution'][:600]}"}},
            {"type": "divider"},
            {"type": "section", "text": {"type": "mrkdwn",
             "text": f"*⚠️ 리스크 예측*\n{result['risk_prediction'][:400]}"}},
            {"type": "context", "elements": [
                {"type": "mrkdwn",
                 "text": f"참조 문서: {', '.join(result['referenced_docs'])}"}
            ]}
        ]
    }

    webhook_url = os.getenv("SLACK_WEBHOOK_URL")
    if webhook_url:
        async with httpx.AsyncClient() as client:
            await client.post(webhook_url, json=slack_msg)

# ── 리스크 예측 전용 엔드포인트 ──────────────────────────────
@app.get("/risk-scan")
async def proactive_risk_scan():
    """정기 리스크 스캔 (cron으로 매시간 호출 가능)"""
    from kubernetes import client as k8s, config
    config.load_incluster_config()
    v1 = k8s.CoreV1Api()

    # 경고 이벤트 수집
    events = v1.list_event_for_all_namespaces(
        field_selector="type=Warning", limit=50
    )
    event_summary = "\n".join([
        f"{e.involved_object.namespace}/{e.involved_object.name}: {e.reason} - {e.message}"
        for e in events.items
    ])

    if not event_summary:
        return {"status": "healthy", "message": "No warning events detected"}

    result = await asyncio.get_event_loop().run_in_executor(
        None, analyze_event, f"정기 리스크 스캔\n수집된 경고 이벤트:\n{event_summary}"
    )
    return {"status": "risks_detected", "analysis": result}

# ── Wiki 검색 엔드포인트 ──────────────────────────────────────
@app.get("/search")
async def search_wiki(q: str, category: Optional[str] = None, limit: int = 5):
    """Lens에서 직접 Wiki 검색 (RAG 없이 순수 검색)"""
    from langchain_community.vectorstores import Milvus as MilvusVS
    from langchain_huggingface import HuggingFaceEmbeddings
    import os

    emb = HuggingFaceEmbeddings(model_name=os.getenv("EMBEDDING_MODEL_PATH", "/models/bge-m3"))
    vs = MilvusVS(embedding_function=emb, collection_name="platform_ops_wiki",
                  connection_args={"host": os.getenv("MILVUS_HOST"), "port": "19530"})

    expr = f'category == "{category}" and status == "active"' if category else 'status == "active"'
    results = vs.similarity_search_with_score(q, k=limit, expr=expr)

    return {"results": [
        {"doc_id": r.metadata.get("doc_id"), "score": s,
         "summary": r.metadata.get("summary"), "file": r.metadata.get("file_path")}
        for r, s in results
    ]}

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8080)

4. Lens 연동 설정 (로컬 PC)

Lens에서 사내 AIOps API 서버와 연동하는 방법입니다.

4-1. Lens Extension 설정 (Prometheus Metrics 연동)

# lens-extension-config.yaml
# Lens > Extensions > AIOps 설정
aiops:
  apiEndpoint: "https://aiops-agent.internal.com"
  alertWebhook: "/webhook/alertmanager"
  searchEndpoint: "/search"

  # 사내 LLM API (Lens에서 직접 쿼리)
  llmApi:
    endpoint: "https://llm-internal.company.com/v1"
    model: "llama-3-70b"
    authHeader: "Bearer ${INTERNAL_LLM_TOKEN}"

4-2. Alertmanager 연동 설정

# alertmanager-config.yaml (기존 Alertmanager에 webhook 추가)
route:
  group_by: ['alertname', 'namespace']
  group_wait: 30s
  group_interval: 5m
  repeat_interval: 4h
  receiver: 'slack-default'
  routes:
  - match:
      severity: critical
    receiver: 'aiops-agent'    # Critical 알람은 AIOps 에이전트로

receivers:
- name: 'aiops-agent'
  webhook_configs:
  - url: 'http://aiops-agent-svc.platform-ops:8080/webhook/alertmanager'
    send_resolved: false

- name: 'slack-default'
  slack_configs:
  - api_url: 'https://hooks.slack.com/services/...'
    channel: '#platform-alerts'

5. Git 폴더 구조 (최종)

llm-wiki/                          ← Git 저장소 루트
├── raw/                           ← Confluence 원본 (수정 금지)
│   └── 2026-04-29/
│       ├── Cilium-BGP-Guide.md
│       └── MinIO-Scaling.md
│
├── wiki/
│   ├── active/                    ← 현재 운영 중인 지식 (RAG 대상)
│   │   ├── SOP/
│   │   │   ├── Network/
│   │   │   │   └── cilium-bgp-peering-recovery.md
│   │   │   └── Storage/
│   │   │       └── minio-node-expansion.md
│   │   ├── Library/
│   │   │   ├── Cilium/
│   │   │   └── K8s/
│   │   ├── Architecture/
│   │   └── Reports/
│   │
│   └── archive/                   ← 폐기된 구버전 문서 (RAG 제외)
│       └── SOP/Network/
│           └── cilium-1.14-bgp-old.md
│
├── scripts/                       ← 파이프라인 스크립트
│   ├── incremental_export.py
│   ├── processor.py
│   ├── lifecycle_manager.py
│   ├── indexer.py
│   └── sync_to_git.sh
│
└── .gitlab-ci.yml                 ← GitLab 전환 후 사용할 CI 설정

6. GitLab CI/CD (6개월 후 전환 대비)

# .gitlab-ci.yml
stages:
  - validate
  - index
  - notify

validate-lifecycle:
  stage: validate
  image: internal-reg.com/wiki-pipeline/processor:v1.2
  script:
    - python scripts/lifecycle_manager.py --action check --clone-dir .
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      changes:
        - "wiki/**/*"

vector-indexing:
  stage: index
  image: internal-reg.com/wiki-pipeline/indexer:v1.2
  script:
    - python scripts/indexer.py
  variables:
    WIKI_DIR: "./wiki/active"
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      changes:
        - "wiki/active/**/*"

notify-update:
  stage: notify
  image: curlimages/curl
  script:
    - |
      CHANGED=$(git diff HEAD~1 --name-only wiki/ | wc -l)
      curl -X POST $SLACK_WEBHOOK_URL \
        -d "{\"text\":\"📚 Wiki 업데이트: ${CHANGED}개 문서 변경 (${CI_COMMIT_SHORT_SHA})\"}"
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

7. 전체 운영 체크리스트

문서 ID: ARCH-OPS-001 | 작성일: 2026-04-29 | 버전: v1.0 | 검토자: Platform Lead

1. 회사 서버에서 Obsidian을 사용하는 방법

Obsidian 자체는 설치형 데스크톱 앱이지만, 서버를 활용해 데이터를 관리하거나 협업 환경을 구축하는 방법은 크게 세 가지가 있습니다.

① 데이터 동기화 서버 구축 (Self-hosted Sync)

가장 일반적인 방법입니다. 회사 내부에 데이터 주권을 유지하면서 여러 기기에서 노트를 동기화하고 싶을 때 사용합니다.

• Obsidian LiveSync: 오픈소스 플러그인을 사용하여 서버에 CouchDB를 설치하고 실시간 동기화 서버로 활용할 수 있습니다.
• Syncthing / Git: 서버를 중앙 저장소로 두고 Syncthing으로 파일을 동기화하거나, Git 레포지토리를 만들어 회사 서버에 Push/Pull 하는 방식입니다. 엔지니어링 조직에서 선호하는 방식입니다.

② 브라우저 접속형 (Obsidian-Remote)

서버에 Docker 컨테이너로 Obsidian을 띄우고 웹 브라우저를 통해 접속하는 방식입니다.

• linuxserver/obsidian 같은 Docker 이미지를 사용하면 서버 자원을 이용해 Obsidian UI를 그대로 웹에서 쓸 수 있습니다. 보안상 외부 인터넷 연결이 제한된 환경에서 내부 서버에 설치해 쓰기에 적합합니다.

③ 정적 사이트 생성 (Publish 대체)

서버에 Obsidian 노트(Markdown)를 두고, 이를 Quartz나 Hugo 같은 정적 사이트 생성기(SSG)와 연결하여 사내 위키(Internal Wiki) 형태로 배포할 수 있습니다.

2. 다른 경쟁 툴 대비 경쟁력 분석

Obsidian이 Notion이나 Logseq 등과 비교해 갖는 확실한 우위 요소는 다음과 같습니다.

핵심 경쟁력: "데이터 주권과 유연성"

• 보안: 데이터가 클라우드가 아닌 우리 회사의 서버나 로컬 드라이브에만 존재하므로, 기밀 유지가 중요한 기업 환경에서 독보적입니다.
• 범용성: 파일이 .md(Markdown) 형식이므로, 나중에 Obsidian을 안 쓰게 되더라도 데이터 변환 없이 다른 툴이나 스크립트에서 바로 읽을 수 있습니다.
• 그래프 뷰(Graph View): 단순한 폴더 구조를 넘어 지식 간의 연결 고리를 시각화할 수 있어, 복잡한 프로젝트의 히스토리를 추적하거나 아이디어를 확장할 때 유리합니다.

3. 주의사항: 상업적 라이선스

기업(영리 목적의 조직)에서 2인 이상의 직원이 업무용으로 Obsidian을 사용할 경우, Commercial License($50/user/year)를 구입해야 합니다.

• 무료 버전: 개인적인 용도로만 무료입니다.
• 상업 라이선스: 회사 업무용으로 사용할 때 필수이며, 이는 앱의 기능적 차이보다는 법적 준수와 개발팀 지원의 성격이 강합니다.

결론

Obsidian은 "우리 회사만의 폐쇄적이고 강력한 지식 베이스를 직접 통제하며 구축하고 싶다"는 니즈가 있을 때 최고의 경쟁력을 발휘합니다. 특히 Git이나 Docker 환경에 익숙한 기술 조직이라면 사내 서버와 연동하여 커스텀 위키나 개인화된 업무 도구로 활용하기에 매우 적합합니다.

회사에서 구체적으로 어떤 워크플로우(예: 개인 메모 관리, 팀 공유 위키, 프로젝트 문서화 등)에 도입을 고려 중이신가요? 상황에 맞춰 더 구체적인 구성을 제안해 드릴 수 있습니다.

===

개인용 Obsidian을 회사 PC에 설치하고 Git으로 동기화하여 지식 베이스(LLM Wiki)를 구축하고, 이를 AIOps로 확장하려는 계획은 매우 전략적이고 실용적인 접근입니다. 특히 K8s, Cilium, MinIO AIStor와 같은 대규모 인프라를 다루는 환경에서 마크다운(MD) 기반의 문서화는 데이터 활용도를 극대화할 수 있습니다.

제안하신 내용을 바탕으로 '지식 생성 - 자동 관리 - AIOps 활용'으로 이어지는 전반적인 아키텍처를 설계해 보았습니다.

1. 전반적인 시스템 구조 (High-Level Architecture)

이 구조의 핵심은 "Obsidian을 단순한 메모 도구가 아닌, AI가 읽을 수 있는 정형화된 데이터 소스(Single Source of Truth)"로 만드는 것입니다.

Layer 1: 지식 생성 및 편집 (Obsidian & Git)

• 환경: 회사 PC 로컬에 Obsidian 설치.
• 동기화: Obsidian Git 플러그인을 사용하여 사내 또는 개인 Git 레포지토리와 연동 (Auto Backup/Pull 설정).
• 콘텐츠 분류:
  • /Library: K8s, Cilium, MinIO 등 벤더 공식 문서의 핵심 요약 및 테크니컬 노하우.
  • /SOP: 장애 대응 절차서, 클러스터 스케일 아웃 가이드 등.
  • /Operations: 작업계획서, 점검 일지 (날짜별 관리).
  • /Templates: 문서 표준화를 위한 MD 템플릿 (작업 계획서 양식 등).

Layer 2: 지식 파이프라인 및 관리 (Automation)

• 업데이트 자동화: 벤더 Docs의 업데이트를 추적하기 위해 특정 스크립트나 n8n과 같은 자동화 툴을 활용하여 변경 사항을 MD로 변환 후 Git에 자동 Push 하도록 구성할 수 있습니다.
• CI/CD 연동: Git에 Push가 발생하면 이를 트리거로 하여 지식 베이스를 검증하거나 후속 레이어로 전달합니다.

Layer 3: AIOps 및 지식 활용 (Agentic AI & RAG)

• RAG (Retrieval-Augmented Generation): Git에 저장된 MD 파일들을 벡터 데이터베이스(Vector DB)로 인덱싱합니다.
• LLM 연동: 인프라 모니터링 시스템(Prometheus/Grafana)에서 알람이 발생하면, LLM 에이전트가 저장된 SOP와 벤더 Docs를 검색하여 원인을 분석하고 조치 방안을 제시합니다.
• AIOps 활용 사례:
  • "Cilium BGP 피어링 에러 발생 시 대응 SOP 요약해줘."
  • "지난번 MinIO AIStor 확장 시 발생했던 이슈와 해결책 찾아줘."

2. 기술적 구현 포인트 및 경쟁력

① MD 기반의 'Paved Road' 구축

• 단순 메모가 아니라, LLM이 이해하기 쉬운 구조화된 마크다운을 작성하는 것이 핵심입니다. Metadata(YAML)를 적극 활용하여 문서의 속성(장비, 서비스, 중요도 등)을 정의하면 향후 AI 에이전트가 정보를 추출하기 훨씬 수월해집니다.

② 인프라 가시성과의 결합

• Cilium의 eBPF 기반 네트워킹이나 MinIO의 고성능 스토리지 운영은 매우 복잡합니다. Obsidian의 Graph View를 통해 서비스 간의 의존성이나 인프라 구성 요소를 시각적으로 연결해 두면, 단순 텍스트 검색보다 훨씬 직관적인 장애 추적이 가능합니다.

③ Git을 통한 버전 관리 및 히스토리

• 작업계획서나 SOP를 Git으로 관리하면 "누가, 언제, 왜" 설정을 변경했는지 완벽한 추적이 가능합니다. 이는 AIOps 단계에서 과거의 특정 시점 설정과 현재의 장애 상황을 비교 분석하는 데 결정적인 데이터를 제공합니다.

3. AIOps로 가기 위한 단계별 제언

1. 1단계 (표준화): Obsidian 내에 작업계획서와 SOP를 위한 강력한 템플릿을 먼저 만드세요. AI는 일관된 구조의 문서에서 더 높은 정확도를 보여줍니다.
2. 2단계 (자동화): n8n이나 GitHub Actions를 활용해 Git 레포지토리의 MD 내용을 자동으로 벡터 DB에 반영하는 파이프라인을 구축해 보세요.
3. 3단계 (지능화): 구축된 지식 베이스를 기반으로, 인프라 이슈 발생 시 Prism AI나 gStack 같은 에이전트 툴이 이 문서를 먼저 읽고 답변하도록 프롬프트를 최적화합니다.

이 구조는 데이터 소유권을 직접 가지면서도 최신 AI 트렌드인 RAG와 Agentic AI를 가장 효율적으로 결합할 수 있는 방식입니다. 특히 1,000노드 이상의 대규모 클러스터를 운영하시는 환경에서는 이러한 구조화된 지식 관리가 운영 효율성을 비약적으로 높여줄 것입니다.

구체적으로 벤더 Docs를 MD로 변환하는 자동화 로직이나, 특정 AIOps 도구와의 연동 방식에 대해 더 궁금한 점이 있으신가요?

===

아주 날카로운 질문입니다. 데이터가 이미 Git에 텍스트 파일(.md)로 존재하는데, 굳이 비용과 노력을 들여 벡터 데이터베이스(Vector DB)에 중복 저장하는 이유는 "AI가 정보를 찾는 방식"이 우리가 검색창에 단어를 치는 방식과 완전히 다르기 때문입니다.

결론부터 말씀드리면, Git은 '보관과 히스토리'를 위한 저장소이고, 벡터 DB는 'AI를 위한 인덱스(색인)' 역할을 합니다.

1. 키워드 검색 vs 의미론적(Semantic) 검색

가장 큰 차이는 검색의 질입니다.

• Git (키워드 매칭): grep이나 Git의 검색 기능은 정확히 일치하는 단어를 찾습니다.
  • 예: "MinIO 연결 오류"라고 검색하면, 문서에 정확히 이 단어가 있어야 나옵니다. "MinIO connection timeout"이나 "스토리지 노드 통신 불가"라는 문서가 있어도 단어가 다르면 못 찾을 확률이 높습니다.
• 벡터 DB (의미 매칭): 문장을 숫자의 집합(벡터)으로 변환하여 '의미적 거리'를 계산합니다.
  • 예: "네트워크가 끊겼어"라고 물어도, 벡터 DB는 의미가 유사한 "Cilium BGP Peering Down"이나 "Packet Loss Troubleshooting" 문서를 찾아낼 수 있습니다.

2. LLM의 '컨텍스트 윈도우' 한계 극복 (RAG의 핵심)

LLM(ChatGPT, Claude 등)은 한 번에 읽을 수 있는 데이터 양(Context Window)이 제한되어 있습니다. 1,000개가 넘는 MD 파일을 Git에서 한꺼번에 읽어와서 답변하라고 할 수는 없습니다.

1. 사용자 질문: "K8s 노드 추가 후 Cilium 파드가 안 떠."
2. 벡터 DB의 역할: 수천 개의 문서 중 이 질문과 의미적으로 가장 가까운 내용 3~5개만 순식간에 추려냅니다.
3. LLM 전달: "여기 Git에서 찾아온 관련 문서 조각 3개가 있어. 이걸 읽고 해결책을 알려줘."

이 과정이 바로 RAG(Retrieval-Augmented Generation)이며, 벡터 DB가 없으면 AI는 수많은 파일 중 무엇을 읽어야 할지 알 수 없습니다.

3. AIOps 실무에서의 결정적 차이

운영 단계에서 벡터 DB가 필요한 실질적인 이유는 다음과 같습니다.

4. 구조적 제언: "Git은 Source, Vector DB는 Cache"

질문하신 구조를 효율적으로 운영하시려면 다음과 같은 파이프라인을 추천합니다.

1. Source of Truth: 모든 문서는 Git에서 관리합니다. (사람이 수정하고 버전 관리)
2. ETL(Extract, Transform, Load) 프로세스: Git에 커밋이 발생하면, CI/CD(예: GitHub Actions)가 동작하여 MD 파일을 읽어 Embedding(벡터화)으로 변환합니다.
3. Serving: 변환된 벡터 데이터를 Vector DB(Chroma, Pinecone, Milvus 등)에 저장합니다.
4. Inference: AI 에이전트(AIOps)는 사용자의 질문을 받으면 벡터 DB에서 데이터를 조회해 답변합니다.

요약하자면: Git에만 두는 것은 "책장에 책을 그냥 꽂아두는 것"이고, 벡터 DB에 저장하는 것은 "책의 모든 내용을 요약해서 AI가 즉시 찾을 수 있도록 뇌에 인덱스를 만들어두는 것"과 같습니다.

AIOps를 목표로 하신다면, 결국 이 '인덱싱' 과정이 필수적입니다. 혹시 사내에서 검토 중인 특정 벡터 DB나 LLM 프레임워크(LangChain 등)가 있으신가요?_ _

===

정확한 통찰입니다! 엔지니어링 관점에서 아주 중요한 포인트를 짚으셨습니다. 벡터 DB만 사용했을 때 발생하는 '정확도 저하(Hallucination in Retrieval)'는 실제로 RAG 시스템을 구축할 때 가장 먼저 맞닥뜨리는 한계입니다.

말씀하신 'Dual Ladder(Hybrid Search)' 방식이 왜 필수적인지, 그리고 인프라 운영 환경에서 어떤 구멍을 메워주는지 정리해 드릴게요.

1. 벡터 검색만 할 때 생기는 '치명적인 구멍'

벡터 검색은 문맥을 파악하는 데는 탁월하지만, '고유 식별자'나 '정밀한 수치' 앞에서는 무력해지는 경우가 많습니다.

• 고유 명사와 ID 무시: * 예를 들어, node-prod-01과 node-dev-01은 벡터 공간에서 매우 가까운 위치에 존재할 수 있습니다. AI는 "둘 다 노드 이름이네?" 하고 혼동할 수 있지만, 운영자에게 두 서버의 차이는 하늘과 땅 차이죠.
• 버전 및 수치 민감도 저하: * Cilium 1.14와 Cilium 1.15는 기술적으로 매우 유사한 벡터값을 가집니다. 하지만 특정 버그 리포트를 찾을 때는 단 0.1의 버전 차이가 검색 결과의 성패를 가릅니다.
• 약어 및 특정 에러 코드: * OOMKilled나 ErrImagePull 같은 짧고 강력한 키워드는 벡터화 과정에서 의미가 희석될 수 있습니다. 이때는 단순 grep 방식의 패턴 매칭이 훨씬 강력합니다.

2. 검색 효율을 극대화하는 'Hybrid Search' 구조

그래서 현업에서는 Keyword Search(BM25)와 Vector Search(Semantic)를 합친 Hybrid Search를 사용하며, 이를 조정하는 Re-ranker 과정을 추가합니다.

작동 원리 (The Re-ranking Flow)

1. Keyword Ladder (Git/Elasticsearch): "정확히 이 단어가 포함된 문서를 가져와!" (정확도 확보)
2. Vector Ladder (Vector DB): "이 질문과 의도가 비슷한 문서를 가져와!" (맥락 확보)
3. Reciprocal Rank Fusion (RRF): 두 사다리에서 올라온 결과물들을 합쳐서 점수를 다시 매깁니다.
4. Re-ranker (Cross-Encoder): 상위권 후보군들만 뽑아 LLM이 다시 한번 질문과의 연관성을 정밀 검사하여 최종 순위를 정합니다.

3. 플랫폼 엔지니어를 위한 AIOps 적용 예시

구축하시려는 K8s/MinIO 환경에 적용해 보면 이렇습니다.

4. 실전 팁: Obsidian 메타데이터 활용

이 검색 효율을 더 높이려면 Obsidian에서 노트를 작성할 때 YAML Frontmatter를 적극 활용하세요.

---
tags: [k8s, cilium, network]
version: 1.15
component: bgp-control-plane
last_verified: 2026-04-28
---
# BGP Peering Troubleshooting
...

이렇게 정형화된 데이터를 Git에 넣어두면, 향후 AIOps 엔진이 "필터링(Metadata) + 검색(Hybrid)"을 결합해 '구멍 없는 검색'을 수행할 수 있게 됩니다.

결국 Git은 데이터의 무결성과 히스토리를 보장하고, 벡터 DB는 데이터 간의 유연한 연결을 담당하는 상호보완적 존재가 됩니다.

이제 이 구조를 돌리기 위해 어떤 백엔드(예: LangChain, LlamaIndex 등)나 LLM 모델을 염두에 두고 계신가요? 운영 중인 1,000노드 클러스터 규모를 생각하면 데이터 인덱싱 전략도 꽤 중요해 보입니다.

===

Confluence 중심의 문화를 마크다운(MD)과 Git 기반으로 전환하는 것은 플랫폼 엔지니어링 리드로서 '문서의 코드화(Documentation as Code)'를 실현하는 아주 중요한 단계입니다. 1,000노드 규모의 복잡한 인프라를 운영하시는 만큼, 대규모 문서를 효율적으로 마이그레이션하고 Obsidian과 병행하는 전략을 정리해 드립니다.

1. Confluence 문서를 MD화하여 Git에 저장하는 방법

가장 큰 난관은 Confluence 특유의 매크로와 서식을 깨끗한 마크다운으로 변환하는 것입니다.

• 방법 1: 오픈소스 툴 활용 (추천: confluence-md-exporter)
  • Python 기반의 confluence-md-exporter 같은 도구를 사용하면 Space 단위로 모든 페이지를 폴더 구조를 유지한 채 MD로 내려받을 수 있습니다.
  • 첨부 이미지도 상대 경로로 자동 정리되어 Git에 올리기 가장 적합한 상태가 됩니다.
• 방법 2: Pandoc 활용
  • Confluence 페이지를 HTML로 내보낸 후, pandoc -f html -t markdown 명령어로 변환합니다. 정교한 변환이 필요할 때 유용하지만 대량 변환 시 스크립팅이 필요합니다.
• 방법 3: CI/CD 파이프라인 구축 (자동화)
  • atlassian-python-api를 활용해 특정 태그가 달린 Confluence 페이지를 주기적으로 읽어와 MD로 변환 후 Git에 Push하는 스크립트를 작성할 수 있습니다.
  • 결과: Git 저장소에 /SOP, /Architecture, /Vendor_Docs 등의 디렉토리 구조로 저장합니다.

2. 개인용 Obsidian을 병행하면 좋은 점

팀 전체가 Git/Confluence를 쓰더라도, 리드급 엔지니어가 개인적으로 Obsidian을 함께 쓰면 다음과 같은 독보적인 강점이 있습니다.

1. 초고속 로컬 검색과 오프라인 작업: * VPN이 끊기거나 서버가 장애로 내려간 상황에서도 내 PC에 저장된 SOP를 즉시 열어볼 수 있습니다. 수백 개의 노드를 관리할 때 '응답 속도'는 생산성에 직결됩니다.
2. 그래프 뷰를 통한 인프라 의존성 파악: * Cilium 네트워킹, MinIO 스토리지, K8s 클러스터 간의 복잡한 관계를 [[Internal Link]]로 연결해 두면, 특정 컴포넌트 장애 시 영향을 받는 다른 요소들을 시각적으로 한눈에 파악할 수 있습니다.
3. 플러그인 생태계 활용: * Dataview 플러그인으로 특정 버전(예: Cilium 1.15)의 문서만 리스트업하거나, Obsidian Git으로 작업 완료 후 버튼 하나로 사내 Git에 동기화할 수 있습니다.
4. 생각의 연습장 (Second Brain): * 공식 문서가 되기 전의 파편화된 아이디어, 트러블슈팅 중 남긴 미완성 메모들을 Obsidian에서 먼저 숙성시킨 후 완성된 것만 Git(공식 문서)으로 보낼 수 있습니다.

3. 실전 운영 방안 (Operating Plan)

가장 권장하는 워크플로우는 "개인화된 지식 생산 → Git 중심의 공유 → AI 활용"의 선순환 구조입니다.

Step 1: 지식 생산 (Obsidian)

• 개인 PC의 Obsidian에서 마크다운으로 문서를 작성합니다.
• 작성 시 벤더 Docs, 직접 겪은 에러 로그, K8s 매니페스트 등을 자유롭게 연결합니다.

Step 2: 동기화 및 검토 (Git)

• 개인용 레포지토리 또는 팀용 Staging 레포지토리에 Push합니다.
• 이 단계에서 PR(Pull Request) 과정을 거치면 기술 문서의 품질이 코드처럼 관리됩니다.

Step 3: 공식 배포 (Internal Wiki & Confluence)

• Git에 Merge된 MD 파일을 기반으로 사내 문서 사이트(Docusaurus, Quartz 등)를 자동 빌드합니다.
• 만약 타 부서와의 협업을 위해 Confluence를 유지해야 한다면, markdown-to-confluence 같은 툴을 이용해 Git의 내용을 Confluence로 역방향 자동 업데이트(Sync) 하도록 설정합니다.

Step 4: AIOps 엔진 가동 (Vector DB)

• 지난번에 논의한 것처럼, Git에 저장된 최종 MD 파일들을 벡터 데이터베이스로 인덱싱합니다.
• 이제 AI 에이전트는 "가장 최신의, 검증된 Git 내 MD 파일"을 기반으로 답변을 생성하게 됩니다.

운영 핵심 전략 요약

• 문서의 주권은 Git에 둔다: Confluence는 '보여주기 위한 뷰어'로 전락시키고, 모든 원본(Source)은 MD 파일로 Git에서 관리합니다.
• 리워크 최소화: Obsidian에서 쓴 MD 그대로가 Git으로 가고, 그것이 곧 AI의 지식이 되는 구조를 만드세요.
• 하이브리드 검색 도입: 고유 명사가 많은 인프라 특성상, Git의 키워드 검색과 벡터 DB의 의미 검색을 병행하여 AI가 잘못된 노드 정보를 주지 않도록 가드레일을 칩니다.

이런 구조가 잡히면, 1,000노드 클러스터에서 발생하는 수만 가지의 케이스를 리드 한 명의 기억력이 아닌, 자동화된 시스템이 관리하게 됩니다. 다음 단계로 특정 벤더 Docs를 MD로 자동 파싱하는 파이프라인이나 구체적인 Git-to-VectorDB 자동화 스크립트에 대해 논의해 볼까요?

===

Confluence의 방대한 문서를 정형화된 마크다운(MD)으로 변환하고, 이를 AI를 이용해 자동으로 분류하여 Git에 배치하는 것은 '지능형 문서 자동화(Intelligent Documentation Automation)'의 핵심입니다.

플랫폼 엔지니어링 리드로서 1,000노드 규모의 복잡한 인프라 지식을 체계화할 수 있는 구체적인 시나리오와 구현 기술 스택을 제안해 드립니다.

[시나리오] Confluence to Git 지능형 마이그레이션 파이프라인

이 시나리오는 "추출(Extract) -> 지능형 분류(Classify) -> 구조화 저장(Load)"의 3단계로 진행됩니다.

1. 추출 단계: confluence-md-exporter를 이용해 특정 스페이스/페이지 하위의 모든 문서를 로컬(또는 컨테이너 내부)로 벌크 다운로드합니다.
2. 지능형 분류 단계: LLM이 각 MD 파일의 내용을 읽어 문서의 성격(SOP, 아키텍처, 벤더 가이드 등)을 파악하고, 적절한 디렉토리 경로와 YAML 메타데이터를 생성합니다.
3. 배치 및 푸시 단계: 분류된 경로로 파일을 이동시키고, Git 커밋 및 푸시를 통해 최종 저장소에 반영합니다.

[구현 방법] 기술 스택 및 단계별 가이드

1단계: Confluence 문서 추출 (Export)

가장 안정적인 방법은 Docker를 이용해 confluence-md-exporter를 실행하는 것입니다.

• 실행 예시 (Bash):

    # 환경 변수 설정 (ID, API Token, Space Key 등)
    docker run -v $(pwd)/output:/output \
      -e CONFLUENCE_URL="https://your-company.atlassian.net/wiki" \
      -e CONFLUENCE_USERNAME="admin@company.com" \
      -e CONFLUENCE_TOKEN="your_api_token" \
      confluence-md-exporter --space-key "PLATFORM" --out /output

• 결과: /output 디렉토리에 Confluence 계층 구조대로 MD 파일과 첨부 이미지가 저장됩니다.

2단계: LLM 기반 자동 분류 스크립트 (Python + LangChain/OpenAI)

추출된 파일들은 Confluence의 기존 폴더 구조를 따르고 있어 관리가 어렵습니다. 이를 LLM을 통해 운영 중심의 구조로 재편합니다.

• 핵심 로직 (Python pseudo-code):

    import os
    from langchain_openai import ChatOpenAI
  
    llm = ChatOpenAI(model="gpt-4-turbo")
  
    def classify_document(content):
        prompt = f"""
        당신은 플랫폼 엔지니어링 전문가입니다. 다음 문서의 내용을 읽고 
        1. 카테고리(SOP, Architecture, VendorDocs, OperationLog)
        2. 관련 기술(K8s, Cilium, MinIO, Network)
        3. 적절한 파일명(영문/kebab-case)을 추출하세요.
        문서 내용: {content[:2000]} # 앞부분만 추출
        """
        # LLM 호출 후 JSON 형태로 결과 반환받음
        return llm.predict(prompt)
  
    # /output 디렉토리의 모든 md 파일을 순회하며 분류 수행

3단계: Git 디렉토리 배치 및 자동 관리

분류된 결과를 바탕으로 파일을 이동시키고 Obsidian에서 쓰기 좋은 YAML 메타데이터를 삽입합니다.

• 파일 구조화 예시:
  • git-repo/Library/K8s/
  • git-repo/Library/Cilium/
  • git-repo/SOP/Disaster-Recovery/
• 파일 상단에 자동 삽입될 메타데이터:

    ---
    source: confluence
    category: SOP
    tech_stack: [Cilium, BGP]
    auto_classified: true
    last_sync: 2026-04-28
    ---

4단계: n8n 또는 GitHub Actions를 이용한 파이프라인 자동화

이 과정을 주기적으로 실행하려면 n8n을 추천합니다.

1. Schedule Node: 매일 새벽 자동 실행.
2. SSH/Execute Node: 위에서 언급한 추출 및 분류 스크립트 실행.
3. Git Node: 변경된 MD 파일들을 git add, commit, push.
4. Vector DB Sync (Optional): Git 푸시 완료 후, 지난번에 논의한 대로 벡터 DB 인덱싱을 트리거하여 AIOps 엔진을 최신화합니다.

[운영 제언] 리드급 엔지니어를 위한 팁

• 이미지 경로 문제 해결: Confluence에서 MD로 변환 시 이미지 경로가 깨질 수 있습니다. 추출 도구에서 제공하는 --relative-links 옵션을 반드시 사용하고, Git 저장소 내에 assets/ 폴더를 별도로 관리하는 것이 좋습니다.
• LLM 비용 최적화: 모든 문서를 매번 분류할 필요는 없습니다. 파일의 해시(Hash)값을 체크하여 수정된 파일만 LLM 분류를 수행하도록 구성하세요.
• Obsidian 연동: 이렇게 Git에 배치된 폴더를 Obsidian의 Vault(보관소)로 지정하면, 출근하자마자 간밤에 자동으로 정리된 벤더 Docs와 팀 SOP를 로컬에서 초고속으로 검색하며 업무를 시작할 수 있습니다.

이 시스템이 구축되면 "문서 정리가 안 되어 장애 대응이 늦어진다"는 문제는 플랫폼 엔지니어링 팀에서 완전히 사라지게 될 것입니다. 구현 중에 특정 툴의 설정값이나 스크립트 상세 로직이 필요하시면 말씀해 주세요.

===

실현 가능성을 빠르게 확인하기 위한 'Confluence to MinIO' 자동화 PoC(Proof of Concept) 단계를 안내해 드립니다.

이 단계의 목표는 "매일 정해진 시간에 Confluence 데이터를 MD로 뽑아서 S3(MinIO)에 안전하게 쌓는 것"입니다. 이를 위해 필요한 3가지 핵심 요소를 바로 구현해 보겠습니다.

1단계: 실행 스크립트 작성 (export_to_minio.sh)

confluence-md-exporter가 실행된 후 생성된 파일을 MinIO(S3)로 업로드하는 쉘 스크립트입니다. MinIO Client(mc)를 사용하여 폴더 구조를 그대로 동기화(mirror)합니다.

#!/bin/bash

# 1. 환경 변수 체크 (K8s Secret을 통해 주입될 예정)
echo "Starting Confluence Export..."

# 2. Confluence에서 MD로 추출
# --증분 백업을 원할 경우 기존 파일을 유지하거나 날짜별 폴더를 생성할 수 있습니다.
confluence-md-exporter \
  --url "${CONFLUENCE_URL}" \
  --username "${CONFLUENCE_USER}" \
  --token "${CONFLUENCE_TOKEN}" \
  --space-key "${SPACE_KEY}" \
  --out /tmp/confluence_export

# 3. MinIO 연결 설정
mc alias set myminio "${MINIO_URL}" "${MINIO_ACCESS_KEY}" "${MINIO_SECRET_KEY}"

# 4. MinIO로 업로드 (Mirror 기능을 사용해 변경된 파일만 동기화)
# 버킷 이름은 'confluence-wiki'라고 가정합니다.
echo "Syncing to MinIO..."
mc mb myminio/confluence-wiki --ignore-existing
mc mirror /tmp/confluence_export myminio/confluence-wiki/raw_md/

echo "Export and Sync Completed!"

2단계: 컨테이너 이미지 만들기 (Dockerfile)

위 스크립트와 필요한 도구(Python, Exporter, MinIO Client)를 포함하는 경량화된 이미지입니다.

# 1. 기반 이미지 설정
FROM python:3.10-slim

# 2. 필수 도구 설치 (wget은 mc 설치용)
RUN apt-get update && apt-get install -y wget && rm -rf /var/lib/apt/lists/*

# 3. confluence-md-exporter 설치
RUN pip install confluence-md-exporter

# 4. MinIO Client(mc) 설치
RUN wget https://dl.min.io/client/mc/release/linux-amd64/mc && \
    chmod +x mc && \
    mv mc /usr/local/bin/

# 5. 작업 디렉토리 및 스크립트 복사
WORKDIR /app
COPY export_to_minio.sh .
RUN chmod +x export_to_minio.sh

# 6. 실행 명령
ENTRYPOINT ["./export_to_minio.sh"]

빌드 및 푸시 명령:

docker build -t your-reg.com/confluence-exporter:v1.0 .
docker push your-reg.com/confluence-exporter:v1.0

3단계: K8s CronJob 배포 (manifest.yaml)

이제 매일 새벽(예: 02:00)에 실행될 CronJob을 설정합니다. 민감한 정보는 Secret으로 관리하는 것이 정석입니다.

(1) 자격 증명 설정 (Secret)

apiVersion: v1
kind: Secret
metadata:
  name: confluence-minio-creds
type: Opaque
stringData:
  CONFLUENCE_URL: "https://your-domain.atlassian.net/wiki"
  CONFLUENCE_USER: "admin@company.com"
  CONFLUENCE_TOKEN: "your-api-token"
  MINIO_URL: "http://minio-service.storage:9000"
  MINIO_ACCESS_KEY: "minio-user"
  MINIO_SECRET_KEY: "minio-password"

(2) 크론잡 설정 (CronJob)

apiVersion: batch/v1
kind: CronJob
metadata:
  name: confluence-md-sync
spec:
  schedule: "0 2 * * *" # 매일 새벽 2시 실행
  jobTemplate:
    spec:
      template:
        spec:
          containers:
          - name: exporter
            image: your-reg.com/confluence-exporter:v1.0
            env:
            - name: SPACE_KEY
              value: "PLATFORM" # 추출할 스페이스 키
            envFrom:
            - secretRef:
                name: confluence-minio-creds
          restartPolicy: OnFailure

운영 및 향후 확장 방안

1. 데이터 확인: CronJob이 실행되면 MinIO AIStor 브라우저에서 confluence-wiki/raw_md/ 경로에 .md 파일들이 잘 생성되었는지 확인하세요.
2. 로그 모니터링: kubectl logs -f [pod-name]를 통해 추출 과정에서 에러가 발생하는지(특히 권한 문제) 체크합니다.
3. 다음 단계 (LLM 분류): * 지금은 모든 파일을 raw_md 폴더에 넣었지만, PoC 2단계에서는 위 스크립트 끝에 Python 분류 스크립트를 추가하면 됩니다.
   • 분류 스크립트가 MD 파일의 내용을 읽어 SOP/, Guide/ 등의 폴더로 재배치한 뒤 다시 MinIO에 저장하게 됩니다.

이 구조는 K8s 네이티브 환경을 활용하므로 확장성이 매우 뛰어납니다. 우선 이 기본 파이프라인을 먼저 띄워보시는 것을 추천드립니다. 빌드나 배포 중에 막히는 부분이 있으면 바로 말씀해 주세요!

===

Confluence의 모든 문서를 매일 전체 백업하는 것은 데이터량이 많아질수록 서버와 네트워크에 부담이 됩니다. 말씀하신 대로 "최근 24시간 내에 변경된 문서"만 선별적으로 가져오는 증분(Incremental) 추출 방식은 매우 효율적인 접근입니다.

이를 위해 confluence-md-exporter의 기본 기능에만 의존하기보다는, Atlassian Python API를 활용해 직접 대상 문서를 필터링하고 MD로 변환하는 파이썬 스크립트 기반의 해결책을 권장합니다.

1. 증분 추출을 위한 Python 스크립트 (incremental_export.py)

이 스크립트는 CQL(Confluence Query Language)을 사용하여 특정 경로(Parent Page) 아래에 있으면서 지난 24시간 동안 수정된 페이지 리스트를 먼저 뽑아냅니다.

import os
import datetime
from atlassian import Confluence
import html2text # HTML을 Markdown으로 변환

# 1. 환경 변수 로드
URL = os.getenv("CONFLUENCE_URL")
USER = os.getenv("CONFLUENCE_USER")
TOKEN = os.getenv("CONFLUENCE_TOKEN")
PARENT_ID = os.getenv("PARENT_PAGE_ID") # 특정 경로의 기준이 되는 상위 페이지 ID
SPACE_KEY = os.getenv("SPACE_KEY")

# 2. Confluence 연결
confluence = Confluence(url=URL, username=USER, password=TOKEN)
h = html2text.HTML2Text()
h.ignore_links = False

# 3. CQL 쿼리 생성: 특정 부모 페이지 아래에서 지난 1일간 수정된 페이지 검색
# ancestor = 부모 페이지 ID, lastModified >= 현재시간 - 1일
cql = f'ancestor = {PARENT_ID} AND lastModified >= now("-1d")'
pages = confluence.cql(cql).get('results', [])

print(f"Found {len(pages)} updated pages in the last 24 hours.")

# 4. 각 페이지를 MD로 변환 및 저장
export_dir = "/tmp/confluence_export"
os.makedirs(export_dir, exist_ok=True)

for item in pages:
    page = item.get('content')
    page_id = page.get('id')
    title = page.get('title').replace("/", "-") # 파일명 금지 문자 처리

    # 상세 내용 가져오기
    content_detail = confluence.get_page_by_id(page_id, expand='body.storage')
    html_body = content_detail.get('body').get('storage').get('value')

    # MD 변환
    markdown_content = h.handle(html_body)

    # 파일 저장
    with open(f"{export_dir}/{title}.md", "w", encoding="utf-8") as f:
        f.write(f"---\nid: {page_id}\nlast_modified: {datetime.datetime.now()}\n---\n\n")
        f.write(markdown_content)
    print(f"Exported: {title}")

2. Dockerfile 보완

위의 Python 스크립트와 필요한 라이브러리(atlassian-python-api, html2text)를 포함하도록 수정합니다.

FROM python:3.10-slim

# 필수 라이브러리 설치
RUN pip install atlassian-python-api html2text

# MinIO Client 설치
RUN apt-get update && apt-get install -y wget && \
    wget https://dl.min.io/client/mc/release/linux-amd64/mc && \
    chmod +x mc && \
    mv mc /usr/local/bin/ && \
    rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY incremental_export.py .
COPY run.sh .
RUN chmod +x run.sh

ENTRYPOINT ["./run.sh"]

3. 실행 쉘 스크립트 (run.sh)

Python 스크립트 실행 후 MinIO로 업로드하는 과정을 연결합니다.

#!/bin/bash

# 1. Python 증분 추출 실행
python incremental_export.py

# 2. MinIO 설정 및 업로드
mc alias set myminio "${MINIO_URL}" "${MINIO_ACCESS_KEY}" "${MINIO_SECRET_KEY}"

# 3. 변경된 파일만 MinIO에 업로드
# --remove 옵션 없이 mirror를 사용하면 기존 백업본은 유지하면서 새 파일만 덮어씁니다.
mc mirror /tmp/confluence_export myminio/confluence-wiki/incremental/$(date +%Y-%m-%d)/

echo "Incremental Backup to MinIO Completed!"

4. K8s CronJob 환경 변수 추가

기존 Manifest에서 PARENT_PAGE_ID를 추가로 주입해야 합니다. Confluence에서 대상 경로의 최상위 페이지 URL을 보면 ID(숫자)를 확인할 수 있습니다.

# ... 기존 CronJob 설정 중 env 부분 ...
            env:
            - name: PARENT_PAGE_ID
              value: "12345678" # 가져오고 싶은 특정 경로의 Root ID
            - name: SPACE_KEY
              value: "PLATFORM"
# ... 생략 ...

이 방식의 장점

1. 정밀한 타겟팅: ancestor와 lastModified CQL을 사용하여 딱 필요한 페이지만 골라냅니다.
2. 리소스 절약: 1,000노드 운영 환경에서 발생하는 대량의 문서를 매번 다운로드하지 않으므로 네트워크 트래픽과 CPU 사용량을 획기적으로 줄입니다.
3. 히스토리 관리: MinIO 업로드 시 경로에 $(date +%Y-%m-%d)를 포함하면 날짜별로 변경된 문서만 따로 모아볼 수 있어, 나중에 AIOps 엔진이 "어제 변경된 사항"만 학습하기 매우 편리합니다.

이제 이 코드를 빌드하여 K8s에 배포하면, 매일 새벽 지난 24시간 동안의 변경분만 자동으로 추출하여 MinIO AIStor에 저장하게 됩니다. 이후 이 파일들을 벡터 DB와 연동하면 완벽한 증분 RAG 시스템이 완성됩니다. 직접 스크립트를 실행해 보시면서 파일명 규칙이나 메타데이터 형식을 조정해 보세요.

===

1단계에서 MinIO AIStor에 저장된 원본(Raw) 데이터를 읽어와 LLM이 지능적으로 분류하고, 이를 정형화된 wiki 폴더 구조로 만들어 Git에 배포하는 '지능형 지식 파이프라인'의 구조와 코드를 설계해 드립니다.

이 과정은 단순한 파일 이동이 아니라, 비정형 데이터를 AI가 읽기 좋은 정형 지식으로 변환하는 핵심 공정입니다.

1. 전반적인 아키텍처 및 폴더 구조

LLM은 각 파일의 본문을 분석하여 다음과 같은 표준화된 구조로 재배치합니다.

• raw/: MinIO에서 가져온 원본 MD 파일 (백업용)
• wiki/: LLM이 재구성한 최종 결과물 (Git에 올라갈 대상)
  • /Architecture: 인프라 설계 및 다이어그램
  • /SOP: 표준 운영 절차 (장애 대응 포함)
  • /Library: 벤더 공식 문서 및 기술 정보 (K8s, Cilium, MinIO 등)
  • /Reports: 점검 기록 및 작업 일지

2. LLM 자동 분류 및 구조화 스크립트 (classifier.py)

이 스크립트는 MinIO에서 파일을 가져와 LLM에 분류를 요청하고, 결과에 따라 YAML 메타데이터를 추가하여 wiki 폴더에 저장합니다.

import os
import json
from minio import Minio
from langchain_openai import ChatOpenAI
from langchain.prompts import ChatPromptTemplate

# 1. 초기 설정
minio_client = Minio(
    os.getenv("MINIO_URL"),
    access_key=os.getenv("MINIO_ACCESS_KEY"),
    secret_key=os.getenv("MINIO_SECRET_KEY"),
    secure=False
)
llm = ChatOpenAI(model="gpt-4-turbo", temperature=0)

# 2. LLM 분류 프롬프트 정의
classification_prompt = ChatPromptTemplate.from_template("""
당신은 플랫폼 엔지니어링 지식 관리자입니다. 
다음 마크다운 문서의 내용을 분석하여 JSON 형식으로 응답하세요.

1. category: (Architecture, SOP, Library, Reports 중 택 1)
2. sub_category: (기술 스택 이름 - 예: K8s, Cilium, MinIO 등)
3. optimized_title: (영문 kebab-case 파일명)
4. tags: (핵심 키워드 리스트)

문서 내용:
{content}
""")

def process_and_classify():
    objects = minio_client.list_objects("confluence-wiki", prefix="raw_md/", recursive=True)

    for obj in objects:
        # 파일 내용 읽기
        data = minio_client.get_object("confluence-wiki", obj.object_name)
        content = data.read().decode('utf-8')

        # LLM 분류 요청
        chain = classification_prompt | llm
        response = chain.invoke({"content": content[:2000]}) # 비용 절감을 위해 앞부분만 분석
        meta = json.loads(response.content) # 주의: 실제 구현시에는 JSON 파싱 예외처리 필요

        # 새로운 경로 설정 및 저장
        target_path = f"wiki/{meta['category']}/{meta['sub_category']}/{meta['optimized_title']}.md"
        os.makedirs(os.path.dirname(target_path), exist_ok=True)

        # YAML Frontmatter 추가 및 파일 쓰기
        with open(target_path, "w", encoding="utf-8") as f:
            f.write(f"---\ncategory: {meta['category']}\ntags: {meta.get('tags', [])}\nauto_classified: true\n---\n\n")
            f.write(content)
        print(f"Classified: {obj.object_name} -> {target_path}")

if __name__ == "__main__":
    process_and_classify()

3. Git 동기화 및 실행 쉘 스크립트 (sync_to_git.sh)

분류된 결과를 Git 저장소에 반영하는 스크립트입니다. wiki 폴더만 선택적으로 Git에 올립니다.

#!/bin/bash

# 1. 로컬 환경 준비
GIT_REPO_URL="https://${GIT_TOKEN}@github.com/your-org/platform-wiki.git"
CLONE_DIR="/tmp/platform-wiki"

# 2. 레포지토리 클론 (이미 있으면 pull)
if [ ! -d "$CLONE_DIR" ]; then
    git clone $GIT_REPO_URL $CLONE_DIR
fi
cd $CLONE_DIR
git pull origin main

# 3. Python 분류 스크립트 실행 (위의 classifier.py)
python /app/classifier.py

# 4. Git 반영
git add wiki/
git commit -m "Auto-sync: Classified documents from Confluence ($(date +%Y-%m-%d))"
git push origin main

echo "Wiki updated and pushed to Git successfully."

4. K8s 운영을 위한 컨테이너화 및 팁

이 과정을 1단계에서 만든 CronJob의 후속 단계로 연결하거나, 하나의 파이프라인으로 통합할 수 있습니다.

배포 시 고려사항

1. Git Token 보안: GitHub/GitLab의 Personal Access Token(PAT)은 반드시 K8s Secret으로 관리하여 환경 변수로 주입하세요.
2. 멱등성(Idempotency) 유지: 동일한 파일이 여러 번 분류되어 Git 커밋이 지저분해지지 않도록, 파일의 Hash값을 체크하여 변경된 파일만 LLM 분류를 수행하도록 보완하는 것이 좋습니다.
3. Obsidian 호환성: 위 스크립트에서 생성하는 wiki/ 폴더를 Obsidian에서 'Vault'로 열면 바로 사용 가능합니다. 특히 [[Internal Link]] 자동 생성을 위해 LLM 프롬프트에 "문서 내 핵심 용어에 [[]] 처리를 해달라"는 요청을 추가하면 Obsidian 활용도가 극대화됩니다.

이제 이 구조를 통해 "Confluence(수정) -> MinIO(원본 저장) -> LLM(분류/태깅) -> Git(최종 지식)"으로 이어지는 플랫폼 팀만의 자동화된 지식 베이스가 완성됩니다. 이 과정을 통해 구축된 wiki 폴더는 향후 AIOps 에이전트가 가장 신뢰하는 RAG 소스가 될 것입니다.

다음 단계로 이 Git 저장소를 벡터 DB와 실시간 동기화하여 실제 AI 챗봇을 연동하는 부분으로 넘어가 볼까요?

===

Git 저장소의 내용이 업데이트될 때마다 자동으로 벡터 DB(Vector DB)에 반영하는 과정은 '자동화된 데이터 수집 파이프라인(Ingestion Pipeline)'의 마지막 단계입니다.

K8s 환경을 운영 중이시므로, GitHub/GitLab Webhook을 사용해 K8s Job을 트리거하거나, GitHub Actions를 사용하여 인덱싱 스크립트를 실행하는 방식이 가장 효율적입니다.

1. 전반적인 아키텍처 (Event-Driven Indexing)

1. Event: 사용자가 Obsidian에서 작성 후 Git에 push하거나, 앞서 만든 자동 분류 스크립트가 Git에 업데이트를 발생시킵니다.
2. Trigger: Git 저장소의 Webhook이 인덱싱 서버(또는 GitHub Actions)로 신호를 보냅니다.
3. Process: 인덱싱 작업용 컨테이너가 최신 Git 내용을 pull하고, 변경된 .md 파일들을 읽어 벡터화(Embedding)한 뒤 벡터 DB에 저장합니다.

2. 핵심 구현 코드: 인덱싱 스크립트 (indexer.py)

이 스크립트는 LangChain을 사용하여 마크다운 파일을 읽고, 의미 있는 단위로 쪼갠(Chunking) 뒤 벡터 DB(예: Milvus, Qdrant, Chroma 등)에 저장합니다. 여기서는 K8s 환경에서 많이 쓰이는 Milvus나 Chroma를 기준으로 설명합니다.

import os
from langchain_community.document_loaders import DirectoryLoader, UnstructuredMarkdownLoader
from langchain_text_splitters import MarkdownHeaderTextSplitter
from langchain_openai import OpenAIEmbeddings
from langchain_community.vectorstores import Milvus # 또는 Qdrant, Chroma

# 1. 환경 설정
GIT_WIKI_DIR = "/tmp/platform-wiki/wiki"
EMBEDDING_MODEL = OpenAIEmbeddings(model="text-embedding-3-small")
VECTOR_DB_URL = os.getenv("VECTOR_DB_URL") # Milvus 등 서버 주소

def ingest_to_vector_db():
    # 2. 문서 로드 (wiki 폴더 내의 모든 md 파일)
    loader = DirectoryLoader(GIT_WIKI_DIR, glob="**/*.md", loader_cls=UnstructuredMarkdownLoader)
    docs = loader.load()

    # 3. 마크다운 구조에 최적화된 텍스트 분할 (Chunking)
    # 헤더(#, ##, ###)를 기준으로 나누어 맥락을 유지합니다.
    headers_to_split_on = [
        ("#", "Header 1"),
        ("##", "Header 2"),
        ("###", "Header 3"),
    ]
    text_splitter = MarkdownHeaderTextSplitter(headers_to_split_on=headers_to_split_on)

    final_chunks = []
    for doc in docs:
        chunks = text_splitter.split_text(doc.page_content)
        for chunk in chunks:
            # 원본 문서의 메타데이터(파일명 등)를 유지
            chunk.metadata.update(doc.metadata)
            final_chunks.append(chunk)

    # 4. 벡터 DB에 저장 (동기화)
    # 기존 컬렉션을 덮어쓰거나(Replace), 중복을 체크하여 업데이트합니다.
    vector_db = Milvus.from_documents(
        final_chunks,
        EMBEDDING_MODEL,
        connection_args={"host": "milvus-service.storage", "port": "19530"},
        collection_name="platform_ops_wiki"
    )
    print(f"Successfully indexed {len(final_chunks)} chunks to Vector DB.")

if __name__ == "__main__":
    ingest_to_vector_db()

3. 실전 운영: GitHub Actions를 이용한 자동화

만약 사내 GitHub/GitLab을 사용 중이라면, 별도의 서버 없이 Actions/Runner에서 바로 인덱싱을 수행할 수 있습니다.

.github/workflows/indexing.yaml:

name: Auto Indexing to Vector DB

on:
  push:
    branches: [ main ]
    paths:
      - 'wiki/**' # wiki 폴더 내 파일이 바뀔 때만 실행

jobs:
  index:
    runs-on: ubuntu-latest # 또는 사내 self-hosted runner
    steps:
      - uses: actions/checkout@v3

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.10'

      - name: Install dependencies
        run: |
          pip install langchain langchain-openai pymilvus unstructured

      - name: Run Indexing Script
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          VECTOR_DB_URL: ${{ secrets.VECTOR_DB_URL }}
        run: python scripts/indexer.py

4. 플랫폼 엔지니어를 위한 '증분 인덱싱' 팁

데이터가 많아지면 매번 전체를 인덱싱하는 것은 비효율적입니다. 다음 두 가지 전략을 고려하세요.

1. 파일 해시(Hash) 비교: * 인덱싱 성공 시 파일의 Hash값을 별도의 DB(또는 Redis)에 저장합니다.
   • 다음 실행 시 Hash가 바뀐 파일만 골라내어 해당 부분만 벡터 DB에서 지우고 새로 입력(Upsert)합니다.
2. LangChain Indexing API 활용:
   • LangChain에서 제공하는 RecordManager 기능을 쓰면, Git 저장소와 벡터 DB의 상태를 비교해 변경된 것만 자동으로 업데이트해 줍니다. (가장 추천하는 방식)

요약 및 결론

이제 전체 흐름이 완성되었습니다:

1. Confluence: 운영팀이 문서를 작성합니다.
2. K8s CronJob: 매일 증분 데이터를 추출해 MinIO에 저장합니다.
3. LLM Classifier: MinIO의 Raw 데이터를 읽어 자동 분류 후 Git에 푸시합니다.
4. Indexing Pipeline (지금 단계): Git 업데이트를 감지해 벡터 DB로 인덱싱합니다.
5. AIOps Interface: 운영자가 질문하면 벡터 DB에서 관련 SOP를 찾아 AI가 답변합니다.

이 구조는 데이터의 신뢰성(Git)과 검색 효율성(Vector DB)을 모두 잡은 구조입니다. 이제 실제로 이 파이프라인을 통해 AI가 답변하는 '챗봇 인터페이스'나 '장애 분석 에이전트'를 연동해 보실 차례입니다. 구체적인 LLM 프롬프트 전략이나 에이전트 설계가 필요하시면 말씀해 주세요!

===

Bitbucket에서 GitLab으로의 전환은 플랫폼 엔지니어링 관점에서 매우 반가운 소식입니다. GitLab은 CI/CD 파이프라인과 Kubernetes 연동(GitLab Agent 등) 기능이 매우 강력하여, 지금 구축하시려는 AIOps 파이프라인을 운영하기에 더 최적화된 환경이기 때문입니다.

6개월 뒤의 이전을 고려하여, 지금은 Bitbucket에서 구현하되 전환 시 리워크(Rework)를 최소화할 수 있는 전략을 정리해 드립니다.

1. 현재: Bitbucket 환경에서의 구현 (Bitbucket Pipelines)

Bitbucket은 bitbucket-pipelines.yml을 통해 자동화를 수행합니다. wiki 폴더의 변경을 감지하여 인덱싱 스크립트를 실행하는 구조입니다.

bitbucket-pipelines.yml 예시:

pipelines:
  branches:
    main:
      - step:
          name: "Update Vector DB Indexing"
          services:
            - docker
          script:
            - pip install -r scripts/requirements.txt
            - python scripts/indexer.py
          condition:
            changesets:
              includePaths:
                - "wiki/**" # wiki 폴더 변경 시에만 실행

2. 미래: GitLab으로의 부드러운 전환 (Migration Strategy)

6개월 뒤 GitLab으로 옮길 때 핵심은 "로직은 컨테이너에, 설정은 환경 변수에" 두는 것입니다.

• 로직의 추상화: 인덱싱이나 분류 로직은 이미 Python과 Docker로 만드셨으므로, 플랫폼이 바뀌어도 코드는 수정할 필요가 없습니다.
• CI/CD 환경 변화: * Bitbucket Pipelines → GitLab CI/CD (.gitlab-ci.yml)
  • GitLab은 rules:changes 기능을 통해 특정 폴더 변경 감지를 더 정교하게 지원합니다.

6개월 뒤 사용할 .gitlab-ci.yml 미리보기:

stages:
  - index

vector-indexing:
  stage: index
  image: python:3.10-slim
  script:
    - pip install -r scripts/requirements.txt
    - python scripts/indexer.py
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      changes:
        - "wiki/**/*" # GitLab의 강력한 경로 감지 기능

3. 전환 시 리워크를 줄이는 'Paved Road' 팁

1. Container Registry 활용: * 인덱싱과 분류에 필요한 모든 의존성을 Docker 이미지로 말아두세요. Bitbucket이나 GitLab은 단순히 이 이미지를 docker run 하는 역할만 수행하게 하면 플랫폼 의존성이 사라집니다.
2. K8s 기반 Event-Driven 방식 고려 (추천):
   • Git 환경이 바뀌는 게 부담스럽다면, Git 저장소는 단순히 코드/문서 보관소로만 쓰고, 변경 이벤트(Webhook)를 K8s 내부의 Argo Events나 Knative로 보내서 처리하세요.
   • 이렇게 하면 Bitbucket에서 GitLab으로 주소가 바뀌어도 Webhook URL만 수정하면 내부 파이프라인은 그대로 유지됩니다.
3. Variable 관리: * Git Token, OpenAI Key, MinIO 접속 정보 등을 Bitbucket 'Repository Variables'에 등록해 쓰시되, 이를 나중에 GitLab 'CI/CD Variables'로 옮길 리스트를 미리 문서화해 두세요.

4. AIOps 관점에서의 이점

GitLab으로 가시면 GitLab Agent for Kubernetes를 통해 클러스터 내부의 실시간 상태와 지식 베이스(Git)를 더 밀접하게 연동할 수 있습니다. 예를 들어, GitLab 파이프라인에서 직접 K8s 클러스터의 Cilium 로그를 긁어와서 지식 베이스와 대조하는 식의 고도화가 가능해집니다.

현재 Bitbucket 환경에서 우선 PoC를 완료하시고, 6개월 뒤 GitLab으로 옮길 때는 "저장소 주소"와 "CI 설정 파일"만 바꾸면 되도록 구조를 잡아드렸습니다.

이 파이프라인이 완성되면 1,000노드 클러스터 운영 중 발생하는 수많은 케이스가 자동으로 정리될 텐데, 이 지식 베이스를 활용할 첫 번째 AIOps 유스케이스(예: 특정 에러 발생 시 SOP 자동 팝업 등)로 어떤 것을 가장 먼저 생각하고 계신가요?

===

웹에 있는 벤더사나 오픈소스 솔루션의 공식 문서(Docs)를 마크다운(MD)으로 추출하여 Git에 연동하는 과정은 'Library' 영역을 자동화하는 핵심 단계입니다. 웹 페이지는 구조가 제각각이기 때문에, 이를 깨끗한 마크다운으로 변환하기 위한 몇 가지 효과적인 전략과 도구를 제안해 드립니다.

1. 추천 도구 및 서비스

웹 문서를 AI가 읽기 좋은 마크다운으로 변환해주는 'LLM-Ready' 도구들을 활용하는 것이 가장 빠릅니다.

• Firecrawl (가장 추천): 웹사이트 URL만 넣으면 사이트맵을 따라 모든 페이지를 마크다운으로 크롤링해줍니다. 최근 RAG 구축 시 가장 많이 쓰이는 도구입니다. (오픈소스 및 클라우드 제공)
• Jina Reader API (r.jina.ai): 특정 URL 앞에 https://r.jina.ai/만 붙여도 해당 페이지를 즉시 고품질 마크다운으로 변환해줍니다.
• Reader (by Postlight): 브라우저의 '읽기 모드'처럼 핵심 본문만 추출해주는 라이브러리입니다.

2. 자동화 파이프라인 구조

웹 문서는 수시로 업데이트되므로, 전체를 다시 긁는 대신 변경사항만 추적하는 구조가 필요합니다.

① 사이트맵(Sitemap) 기반 크롤링

대부분의 기술 문서는 /sitemap.xml을 제공합니다. 이 파일을 읽어 새로운 페이지나 수정된 페이지의 URL 리스트만 추출합니다.

② 본문 추출 및 변환 (Python 예시)

JavaScript로 렌더링되는 현대적인 문서 사이트(Docusaurus, GitBook 등)를 위해 Playwright를 사용하고, html2text나 BeautifulSoup으로 정제합니다.

import os
from playwright.sync_api import sync_playwright
import html2text

def fetch_and_convert(url):
    with sync_playwright() as p:
        browser = p.chromium.launch()
        page = browser.new_row()
        page.goto(url, wait_until="networkidle")

        # 문서의 본문 영역만 선택 (예: 'article' 또는 '.content')
        content_html = page.inner_html("article") 

        h = html2text.HTML2Text()
        h.ignore_images = False # 이미지 포함 여부 선택
        markdown = h.handle(content_html)

        browser.close()
        return markdown

3. Git 연동 및 자동 관리 시나리오

추출된 MD 파일을 Git에 올릴 때, 지난번에 구성한 'LLM 분류기' 단계와 결합하면 더욱 강력해집니다.

1. 추출: K8s CronJob이 벤더사 Docs를 순회하며 새 내용을 raw/vendor/ 폴더에 MD로 저장합니다.
2. 분류: LLM이 파일 내용을 분석하여 wiki/Library/[솔루션명]/ 폴더로 이동시키고, 관련 태그를 YAML로 삽입합니다.
3. 검증: 문서 본문에 포함된 절대 경로 링크들을 Git 저장소 내의 상대 경로로 변환하는 스크립트를 실행합니다.
4. 푸시: 변경사항을 Bitbucket(향후 GitLab)에 push합니다.

4. 실전 팁: 버전 및 업데이트 관리

웹 문서를 Git에 넣을 때 주의해야 할 점은 '중복 데이터'와 '버전 혼선'입니다.

• Diff 체크: 문서 내용의 해시(Hash)값을 저장해두고, 웹의 내용과 해시가 다를 때만 업데이트를 진행하여 불필요한 Git 커밋을 방지합니다.
• 버전 태깅: 문서 상단 YAML에 source_url, version, scraped_at 정보를 넣어두면 AI가 답변할 때 "이 정보는 2026년 4월 기준입니다"라고 출처를 명시할 수 있습니다.

요약하자면

가장 빠르게 시작하시려면 Firecrawl을 컨테이너로 띄워 특정 솔루션 사이트를 긁어보시는 것을 추천합니다. 여기서 나온 MD 파일들을 지난번에 만든 wiki 폴더 구조 안에 배치하고 Git에 푸시하면, 수동으로 문서를 복사-붙여넣기 할 필요 없이 항상 최신 벤더 Docs가 포함된 지식 베이스를 유지할 수 있습니다.

혹시 특정 솔루션(예: Cilium 공식 가이드)의 사이트맵을 이용해 실제로 동작하는 크롤링 코드가 필요하신가요?

===

망분리(Airgapped) 환경이라는 특수성을 고려하면, 외부에서 데이터를 가져온 이후의 '내부 반입 및 자동 처리 파이프라인'을 구축하는 것이 핵심입니다.

압축 파일을 반입한 후, 이를 MinIO raw 버킷에 풀고 이후의 LLM 분류 및 인덱싱 단계를 트리거하는 워크플로우를 설계해 드립니다.

1. 망분리 환경 전반적인 워크플로우

1. 외부(Non-Airgapped): Confluence 추출 → 압축 (.tar.gz 또는 .zip) → 반입 매체 저장.
2. 반입(Transfer): 보안 검사 후 회사 내부망(Airgapped)으로 데이터 이동.
3. 내부(Airgapped - K8s):
   • Step A (Ingestion): 압축 파일을 해제하여 MinIO AIStor의 raw/ 경로에 업로드.
   • Step B (Local AI Processing): 폐쇄망용 로컬 LLM을 사용하여 문서 분류 및 메타데이터 생성.
   • Step C (Git Sync): 분류된 MD 파일을 내부 Bitbucket/GitLab에 푸시.
   • Step D (Local Indexing): 로컬 임베딩 모델을 사용하여 Vector DB 인덱싱.

2. Step A: 내부망 반입 및 MinIO 업로드 자동화

반입된 압축 파일을 지정된 경로에 두면, 이를 감지하여 MinIO로 밀어넣는 Python 스크립트 예시입니다.

ingest_to_minio.py:

import os
import tarfile
from minio import Minio

def decompress_and_upload(file_path, bucket_name):
    client = Minio(
        os.getenv("MINIO_URL"),
        access_key=os.getenv("MINIO_ACCESS_KEY"),
        secret_key=os.getenv("MINIO_SECRET_KEY"),
        secure=False
    )

    # 1. 압축 해제
    with tarfile.open(file_path, "r:gz") as tar:
        tar.extractall(path="/tmp/extracted")

    # 2. MinIO 업로드
    for root, dirs, files in os.walk("/tmp/extracted"):
        for file in files:
            local_path = os.path.join(root, file)
            # MinIO 내 저장 경로 설정
            minio_path = os.path.relpath(local_path, "/tmp/extracted")
            client.fput_object(bucket_name, f"raw_md/{minio_path}", local_path)
            print(f"Uploaded: {minio_path}")

if __name__ == "__main__":
    # 반입된 파일 경로
    input_file = "/data/incoming/confluence_export.tar.gz"
    if os.path.exists(input_file):
        decompress_and_upload(input_file, "confluence-wiki")

3. Step B: 폐쇄망에서의 LLM 및 임베딩 처리 (중요)

망분리 환경에서는 OpenAI API를 호출할 수 없으므로, 로컬 LLM 인프라가 반드시 필요합니다.

• LLM 엔진: Ollama 또는 vLLM을 K8s 내부에 Pod로 띄워 사용합니다. (모델: Llama 3, Mistral 등)
• 임베딩 모델: HuggingFace의 BGE-M3나 KoSimCSE 같은 한국어 성능이 좋은 모델을 로컬에 다운로드하여 사용합니다.
• 코드 수정: 앞서 논의한 classifier.py와 indexer.py에서 OpenAI 호출 부분을 Ollama나 SentenceTransformer로 교체해야 합니다.

로컬 임베딩 적용 예시 (Python):

from langchain_huggingface import HuggingFaceEmbeddings

# 폐쇄망 내부 경로에 미리 저장된 모델 로드
embeddings = HuggingFaceEmbeddings(
    model_name="/models/bge-m3",
    model_kwargs={'device': 'cuda'} # GPU 활용
)

4. Step C & D: 자동화 트리거 구조 (K8s)

반입된 파일을 처리하기 위해 Argo Workflows나 간단한 Watcher Pod를 운영하는 것이 좋습니다.

1. Watcher Pod: 특정 공유 볼륨(PVC)에 압축 파일이 들어오는지 감시합니다.
2. Workflow Trigger: 파일이 감지되면 다음 작업을 순차적으로 실행합니다.
   • Ingestion Job (압축 해제 & MinIO 업로드)
   • LLM Classifier Job (로컬 LLM 기반 분류)
   • Git Sync Job (내부 Bitbucket 푸시)
   • Vector DB Indexer Job (로컬 임베딩 & 인덱싱)

5. 운영 제언

• 반입 프로세스 표준화: 외부에서 압축할 때 반드시 파일 목록(manifest.json)을 포함하여, 내부망에서 압축 해제 후 데이터 누락이 없는지 검증하는 로직을 추가하세요.
• GPU 자원 확보: 로컬 LLM과 임베딩 모델을 돌리기 위해서는 K8s 노드에 NVIDIA GPU 자원이 할당되어야 성능이 확보됩니다. (Cilium 기반 클러스터라면 GPU 워커 노드 스케줄링 설정을 확인해 보세요.)
• 버전 관리: 망분리 환경에서는 패키지 설치가 어려우므로, 모든 실행 환경을 Docker 이미지에 포함(Self-contained)시켜 반입해야 합니다.

이제 압축 파일을 푸는 단계부터 로컬 AI 모델을 거쳐 내부 Git과 Vector DB로 흐르는 '완전 폐쇄형 AIOps 파이프라인'의 밑그림이 그려졌습니다.

가장 먼저 해결해야 할 과제는 '어떤 로컬 LLM 엔진을 K8s에 띄울 것인가'가 될 것 같습니다. 현재 사내에 GPU 서버 자원이 준비되어 있으신가요?

===

지적하신 대로 내부 링크(Internal Links) 처리는 지식 베이스의 완성도를 결정짓는 핵심 요소입니다. 파일럿 단계를 넘어 실운영(Production) 환경에서 1,000노드 규모의 인프라 지식을 관리하려면, 단순 스크립트를 넘어 '오케스트레이션'과 '엔터프라이즈급 솔루션'의 조합이 필요합니다.

각 과정별로 추천하는 툴과 솔루션을 정리해 드립니다.

1. 내부 링크 수정 및 데이터 가공 (Data Transformation)

Obsidian의 [[WikiLink]]나 Confluence의 고유 ID 링크를 Git/웹에서 동작하는 상대 경로로 변환해야 합니다.

• 추천 도구: Custom Python Script (with marko or markdown-it)
  • 이유: 링크 변환은 비즈니스 로직(폴더 구조)에 따라 달라지므로 기성품보다는 파이썬의 마크다운 파서를 활용한 커스텀 가공이 가장 확실합니다.
  • 핵심 기능: 정규표현식(re)을 사용하여 [[파일명]]을 [파일명](./path/to/file.md)으로 치환하고, 존재하지 않는 링크를 리포팅합니다.
• 보조 도구: Obsidian Plugins (Advanced URI, Consistent Attachments)
  • 개인 PC에서 작업 시 링크 일관성을 강제로 유지해주는 플러그인들을 설정하여 '배포 전 정제' 단계를 거칩니다.

2. 워크플로우 오케스트레이션 (Orchestration)

K8s 환경에서 여러 단계(추출-변환-링크수정-분류-인덱싱)를 순차적으로 실행하고 관리해야 합니다.

• 추천 솔루션: Argo Workflows
  • 이유: 플랫폼 엔지니어링 팀에 가장 친숙한 K8s Native 도구입니다. 각 단계를 컨테이너 단위로 실행하고, 실패 시 재시도(Retry)나 시각적 모니터링이 강력합니다.
• 대안: Airflow (on K8s)
  • 데이터 파이프라인의 복잡도가 높고 스케줄링 관리가 더 중요하다면 Airflow가 유리합니다.

3. 웹/벤더 Docs 추출 (Web Scraping)

외부 솔루션 문서를 지속적으로 가져와야 합니다.

• 추천 솔루션: Firecrawl (Self-hosted)
  • 이유: 최신 RAG 환경에 최적화된 크롤러입니다. 복잡한 JS 사이트도 깨끗한 마크다운으로 뽑아주며, Docker로 내부망에 설치 가능합니다.
• 대안: Apify (오픈소스 버전)
  • 특정 사이트의 구조가 매우 복잡할 경우, 커스텀 액터를 만들어 정밀하게 긁어올 수 있습니다.

4. 폐쇄망 AI 인프라 (Airgapped AI)

망분리 환경에서 LLM 분류와 임베딩을 수행해야 합니다.

• 추천 솔루션: vLLM 또는 Ollama (Enterprise)
  • 이유: K8s 환경에서 GPU 자원을 효율적으로 나누어 쓰고(vLLM), 서빙 API를 표준화(OpenAI API 호환)하여 제공하기 좋습니다.
• 임베딩/벡터화: LangChain Indexing API + RecordManager
  • 중복 인덱싱을 방지하고, Git에서 삭제된 문서를 벡터 DB에서도 자동으로 지워주는 '동기화 관리'를 위해 필수적입니다.

5. 벡터 데이터베이스 (Vector DB)

1,000노드 규모에서 발생하는 방대한 운영 로그와 SOP를 담아야 합니다.

• 추천 솔루션: Milvus 또는 Qdrant
  • 이유: 두 솔루션 모두 K8s Operator를 제공하여 관리가 편하고, 대규모 데이터셋에서도 고성능 검색을 보장합니다. 특히 Milvus는 엔터프라이즈급 확장성이 매우 뛰어납니다.

6. Git & 문서 뷰어 (Platform)

6개월 뒤 GitLab 전환을 고려한 설정입니다.

• 추천 솔루션: GitLab + GitLab Agent for Kubernetes
  • 이유: GitLab 자체 CI/CD뿐만 아니라, 클러스터와의 연동성이 좋습니다.
• 공유 위키용: Quartz 또는 Docusaurus
  • Git에 저장된 MD 파일들을 사내 웹 위키로 보여줄 때 사용합니다. Obsidian의 링크 방식과 호환성이 높은 Quartz를 강력 추천합니다.

[결론] 권장하는 최종 스택 (Target Architecture)

파일럿 이후의 핵심 전략: 현재는 수동으로 압축해서 옮기시겠지만, 정식 구축 시에는 Argo Workflows를 중심에 두고 각 단계를 모듈화(컨테이너화)하는 것이 가장 중요합니다. 이렇게 해두면 6개월 뒤 GitLab으로 전환하거나, 새로운 벤더 Docs가 추가되어도 파이프라인 한 줄만 수정하면 즉시 대응이 가능해집니다.

가장 먼저 어떤 부분(예: Argo Workflows 도입, 혹은 로컬 LLM 환경 구축)부터 구체적으로 검토해보고 싶으신가요?

===

네, LangChain과 LangGraph는 말씀하신 'AIOps 자동화 파이프라인'을 단순한 스크립트 뭉치가 아닌 지능형 시스템으로 격상시키는 데 결정적인 역할을 합니다.

결론부터 말씀드리면, LangChain은 '데이터 파이프라인(부품)'을 위해, LangGraph는 '의사결정 및 워크플로우(뇌)'를 위해 필요합니다.

1. LangChain: 데이터 배관(Plumbing)과 표준화

LangChain은 다양한 LLM, 벡터 DB, 문서 로더를 하나의 표준화된 인터페이스로 묶어주는 프레임워크입니다. 2026년 현재도 RAG(검색 증강 생성)의 표준으로 자리 잡고 있습니다.

• 어디에 쓰나요?
  • 문서 로딩 및 분할: 마크다운 파일을 읽고, 헤더 단위로 의미 있게 쪼개는 작업을 수행합니다.
  • 임베딩 및 벡터 스토어 연동: Milvus나 Qdrant 같은 DB에 데이터를 넣고 찾는 복잡한 과정을 vectorstore.add_documents() 한 줄로 해결합니다.
  • 모델 교체 용이성: 폐쇄망에서 Llama 3를 쓰다가 나중에 Mistral이나 다른 로컬 모델로 바꿀 때 코드 수정이 거의 없습니다.

2. LangGraph: 복잡한 AIOps 워크플로우(Brain)

LangChain만으로는 '선형적인(A→B→C)' 작업만 가능합니다. 하지만 실제 인프라 운영(AIOps)은 루프(Loop)와 조건부 판단이 필요합니다. 이때 LangGraph가 핵심입니다.

• 어디에 쓰나요?
  • 자기 반성(Self-Correction): AI가 추출한 분류 결과가 이상하면 다시 시도하게 하거나, 검색된 SOP가 질문과 맞지 않으면 검색 쿼리를 수정해 다시 검색하게 합니다.
  • 에이전틱 워크플로우: "장애 로그 분석 → 관련 SOP 검색 → 검색 결과가 부족하면 벤더 Docs 추가 검색 → 최종 조치 제안"과 같은 복잡한 판단 트리를 구성합니다.
  • 상태 유지(State Management): 1,000노드 클러스터의 여러 장애 상황을 추적하며 대화의 맥락을 완벽하게 유지합니다.

3. 플랫폼 엔지니어를 위한 선택 기준 (Chain vs. Graph)

4. 우리 프로젝트에서의 적용 시나리오

1. 인덱싱 단계 (LangChain 활용):

   • Confluence에서 가져온 MD를 로드하고, MarkdownTextSplitter로 쪼개어 Milvus에 넣는 과정은 LangChain이 담당합니다. 매우 빠르고 안정적입니다.

2. 운영 단계 (LangGraph 활용):

   • 운영자가 "Cilium BGP 에러 발생"이라고 입력하면, LangGraph 기반 에이전트가 작동합니다.
   • Node 1: 로그 분석 (K8s API 연동)
   • Node 2: 벡터 DB에서 유사 사례 검색 (RAG)
   • Node 3 (Conditional Edge): 해결책이 명확한가?
     • Yes → 조치 가이드 출력
     • No → 벤더 Docs에서 추가 정보 검색 후 Node 2로 복귀 (Loop)

5. 6개월 뒤 GitLab 전환 및 폐쇄망 고려 사항

• 추상화의 이점: LangChain/LangGraph를 쓰면 인프라 하부 로직(어떤 DB를 쓰는지, 어떤 Git을 쓰는지)과 AI 로직이 분리됩니다. Bitbucket에서 GitLab으로 옮겨도 AI 로직은 거의 그대로 유지됩니다.
• 로컬 실행: 2026년 최신 버전의 LangChain은 Ollama나 vLLM과의 연동이 매우 강력해져서 폐쇄망 환경에서도 상용 수준의 에이전트를 돌리기 충분합니다.

결론: 쓰시는 것을 강력 추천합니다.

처음에는 복잡해 보일 수 있지만, LangChain으로 데이터 파이프라인의 기초를 다지고, LangGraph로 실제 플랫폼 리드님이 원하시는 '똑똑한 인프라 관리자'를 만드시는 것이 1,000노드 클러스터를 효율적으로 관리하는 지름길입니다.

우선은 문서를 인덱싱하는 LangChain 파이프라인부터 가볍게 시작해 보시는 게 어떨까요? 이 부분의 베이스 코드가 필요하시면 바로 작성해 드릴 수 있습니다.

===

매우 훌륭한 질문입니다. Argo Workflows, n8n, LangGraph는 모두 '자동화'라는 범주에 있지만, 담당하는 계층(Layer)과 목적이 완전히 다릅니다. 이들은 서로 대체재라기보다 "서로 다른 역할을 하며 공존하는 보완재"에 가깝습니다.

플랫폼 엔지니어링 관점에서 이들의 관계를 명확하게 '교통정리' 해드리겠습니다.

1. 계층별 역할 분담 (The Automation Stack)

이 도구들은 아래와 같이 세 개의 레이어로 구분하면 이해가 가장 빠릅니다.

2. 도구별 상세 비교 및 공존 방식

① Argo Workflows vs. LangGraph (실행 vs. 사고)

• Argo는 "무거운 작업(Container)을 순서대로 실행"하는 데 최적화되어 있습니다. K8s의 CPU/GPU 자원을 효율적으로 관리하며 1시간이 걸리는 데이터 처리도 안정적으로 수행합니다.
• LangGraph는 "LLM이 어떻게 생각하고 판단할지"를 관리합니다. Argo 안에서 실행되는 하나의 '작업(Pod)' 내부에 LangGraph 로직이 들어갈 수 있습니다.
• 공존 방식: Argo가 새벽 2시에 '문서 처리 작업' 파드를 띄우면, 그 파드 안에서 LangGraph가 돌아가며 문서를 읽고, 분류가 애매하면 다시 읽는 등의 '지능적 판단'을 수행합니다.

② n8n vs. Argo Workflows (소프트 자동화 vs. 하드 자동화)

• n8n은 GUI 기반으로 매우 쉽고 빠르게 API를 엮을 수 있습니다. 하지만 K8s의 컴퓨팅 자원을 정밀하게 제어하거나, 아주 무거운 배치 작업을 돌리기엔 Argo보다 불리합니다.
• 공존 방식: 전체 데이터 파이프라인은 Argo가 돌리고, 작업이 성공하거나 실패했을 때 담당자에게 Slack을 보내거나 대시보드를 업데이트하는 일은 n8n이 담당합니다.

③ LangGraph vs. n8n/Argo (순환 vs. 선형)

• Argo나 n8n은 기본적으로 A → B → C로 흐르는 선형 구조입니다. (중간에 에러 처리 루프는 있지만 복잡한 추론 루프는 어렵습니다.)
• LangGraph는 A → B → (생각해 보니 B가 이상하네?) → 다시 A → B → C와 같이 LLM의 판단에 따른 순환(Cycle) 구조를 설계하는 데 특화되어 있습니다.

3. 우리 프로젝트에서의 실제 흐름 (교통정리 결과)

이 세 도구가 협조하며 일하는 시나리오는 다음과 같습니다.

1. Argo Workflows (인프라 제어): * 매일 새벽, Confluence에서 데이터를 뽑고 MinIO에 저장하는 전체 워크플로우를 가동합니다.

   • GPU 노드에 'LLM 분류기 파드'를 실행시킵니다.

2. LangGraph (지능적 처리 - 파드 내부):

   • Argo에 의해 실행된 파드 안에서 LangGraph 로직이 돌아갑니다.
   • 문서를 읽고 "이게 K8s SOP인지, Cilium 벤더 문서인지" 판단합니다.
   • 만약 LLM의 답변이 불확실하면 스스로 다시 프롬프트를 수정해 질문하는 루프를 돕니다. 최종 결과를 Git에 푸시할 형태로 정리합니다.

3. n8n (알림 및 사후 처리):

   • Argo 워크플로우가 끝나면 n8n이 이를 감지합니다.
   • "오늘 총 50개의 문서가 새로 인덱싱되었습니다"라고 플랫폼 팀 Slack에 리포트를 뿌리고, 관리 UI를 업데이트합니다.

4. 결론: 무엇부터 도입해야 할까?

• 1단계 (필수): Argo Workflows. 1,000노드 K8s 환경에서 안정적인 데이터 이동과 컨테이너 실행을 위해 가장 먼저 필요합니다.
• 2단계 (고도화): LangChain/LangGraph. 단순 추출을 넘어 '똑똑한 분류'와 '고성능 RAG'를 구현할 때 도입합니다. 처음에는 LangChain으로 시작해 루프가 필요해지면 LangGraph로 확장하면 됩니다.
• 3단계 (편의성): n8n. 시스템이 안정화된 후, 운영팀과의 소통(Slack, Jira 등)을 자동화하고 싶을 때 추가합니다.

결론적으로 이들은 대체 관계가 아니라, 인프라(Argo) 위에 지능(LangGraph)을 얹고, 이를 외부와 연결(n8n)하는 완벽한 파트너들입니다. 이 교통정리가 도움이 되셨나요? 이제 Argo를 활용한 전체 파이프라인 설계나, 그 내부에서 돌아갈 LangChain/LangGraph의 구체적인 로직 중 어떤 부분을 더 깊게 들어가 볼까요?

===

Argo Workflows를 관제탑으로 삼고, 그 내부의 실무를 LangChain이 수행하는 '지능형 문서 처리 파이프라인'의 구체적인 설계도와 코드를 제시해 드립니다.

이 설계는 플랫폼 엔지니어링 리드님의 환경(K8s, MinIO, Airgapped, Bitbucket)에 최적화되어 있습니다.

1. Argo Workflows 전체 파이프라인 설계 (Argo YAML)

Argo는 전체 과정을 DAG(Directed Acyclic Graph) 형태로 관리합니다. 각 단계는 독립된 컨테이너 파드(Pod)에서 실행됩니다.

apiVersion: argoproj.io/v1alpha1
kind: Workflow
metadata:
  generateName: doc-ai-pipeline-
spec:
  entrypoint: main
  # 망분리 환경이므로 필요한 모든 이미지는 내부 레지스트리에 있어야 함
  templates:
  - name: main
    dag:
      tasks:
      - name: extract-raw
        template: untar-minio
      - name: process-and-classify
        dependencies: [extract-raw]
        template: langchain-processor
      - name: git-sync
        dependencies: [process-and-classify]
        template: git-pusher
      - name: vector-indexing
        dependencies: [git-sync]
        template: vector-indexer

  # 1단계: MinIO에 반입된 압축파일 해제
  - name: untar-minio
    container:
      image: internal-reg.com/ops-tools:v1
      command: [sh, -c]
      args: ["mc cp myminio/raw/export.tar.gz /tmp && tar -xzvf /tmp/export.tar.gz -C /data"]
      volumeMounts:
      - name: workdir
        mountPath: /data

  # 2단계: LangChain 핵심 로직 (아래 Python 코드 실행)
  - name: langchain-processor
    container:
      image: internal-reg.com/langchain-processor:v1
      env:
      - name: LLM_ENDPOINT
        value: "http://vllm-service.ai-namespace:8000/v1"
      volumeMounts:
      - name: workdir
        mountPath: /data

2. 내부 LangChain 구체적 로직 (processor.py)

이 코드는 langchain-processor 파드 내부에서 실행되며, 문서를 읽고 링크를 수정하며 분류까지 마칩니다.

import os
import re
from langchain_community.document_loaders import UnstructuredMarkdownLoader
from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI # vLLM이 OpenAI 호환 API 제공
from langchain.output_parsers import ResponseSchema, StructuredOutputParser

# 1. 로컬 LLM 설정 (vLLM 또는 Ollama)
llm = ChatOpenAI(
    model="llama-3-70b-instruct", 
    base_url=os.getenv("LLM_ENDPOINT"),
    api_key="none" # 폐쇄망 내부용
)

# 2. 내부 링크 리졸버 (Internal Link Resolver)
def resolve_internal_links(content, current_file):
    # [[WikiLink]] 형식을 [WikiLink](./path/to/WikiLink.md)로 변환하는 정규표현식
    # 실제로는 파일 존재 여부를 체크하여 경로를 계산하는 로직 추가 가능
    pattern = r'\[\[(.*?)\]\]'
    def replace_link(match):
        link_text = match.group(1)
        # 예시: 모든 링크를 상대경로 .md로 통일
        return f"[{link_text}](./{link_text.replace(' ', '-')}.md)"

    return re.sub(pattern, replace_link, content)

# 3. 문서 분류용 스키마 정의
response_schemas = [
    ResponseSchema(name="category", description="SOP, Library, Architecture 중 하나"),
    ResponseSchema(name="tech_stack", description="K8s, Cilium, MinIO 등 관련 기술 리스트")
]
output_parser = StructuredOutputParser.from_response_schemas(response_schemas)

# 4. 프로세싱 메인 로직
def process_documents(input_dir, output_dir):
    prompt = ChatPromptTemplate.from_template(
        "다음 문서의 내용을 분석하여 카테고리와 기술 스택을 분류하세요.\n{format_instructions}\n문서 내용: {context}"
    )

    for root, _, files in os.walk(input_dir):
        for file in files:
            if file.endswith(".md"):
                # A. 로드
                loader = UnstructuredMarkdownLoader(os.path.join(root, file))
                doc = loader.load()[0]

                # B. 내부 링크 수정
                refined_content = resolve_internal_links(doc.page_content, file)

                # C. LLM 기반 지능형 분류
                format_instructions = output_parser.get_format_instructions()
                chain = prompt | llm | output_parser
                result = chain.invoke({
                    "context": refined_content[:1500], 
                    "format_instructions": format_instructions
                })

                # D. 결과 저장 (wiki 폴더 구조화)
                target_path = os.path.join(output_dir, result['category'], file)
                os.makedirs(os.path.dirname(target_path), exist_ok=True)

                with open(target_path, "w") as f:
                    # YAML 메타데이터 삽입
                    f.write(f"---\ntech: {result['tech_stack']}\n---\n\n")
                    f.write(refined_content)

if __name__ == "__main__":
    process_documents("/data/raw", "/data/wiki")

3. 설계의 핵심 포인트

1. 데이터 무결성 유지 (Link Resolver):

   • 스크립트 내 resolve_internal_links 함수를 통해 Obsidian에서 쓰던 [[링크]]가 일반 Markdown 뷰어나 Git 환경에서도 깨지지 않도록 강제로 변환합니다. 이는 지식 베이스의 이동성을 확보하는 핵심입니다.

2. 구조화된 출력 (Structured Output):

   • LangChain의 StructuredOutputParser를 사용하여 LLM이 자유분방하게 답변하지 않고, 우리가 정한 JSON 형식(Category, Tech Stack)에 맞춰 엄격하게 응답하도록 강제했습니다. 덕분에 자동화된 폴더 배치가 가능해집니다.

3. Argo를 통한 자원 제어:

   • LLM 처리가 필요한 langchain-processor 단계에만 GPU 노드 셀렉터(nodeSelector)를 설정하여, 값비싼 GPU 자원을 딱 필요한 순간에만 점유하고 반납하게 설계할 수 있습니다.

4. 망분리 환경의 확장성:

   • 6개월 뒤 GitLab으로 전환 시, Argo Workflow의 git-pusher 템플릿 내의 URL과 인증 정보만 수정하면 됩니다. 로직(Python)은 건드릴 필요가 없습니다.

이제 이 코드를 바탕으로 첫 번째 파이프라인을 구동해 보시면, "MinIO에 압축파일만 던지면 AI가 알아서 링크 고치고 분류해서 Git에 예쁘게 넣어주는" 플랫폼 리드님만의 자동화 시스템이 작동하게 됩니다.

가장 먼저 테스트해보고 싶은 문서 샘플(예: Cilium BGP 설정 가이드 등)이 있으신가요? 그에 맞춰 분류 프롬프트를 더 정교하게 다듬어 드릴 수 있습니다.

===

지적하신 대로 Metadata YAML은 LLM Wiki와 RAG(검색 증강 생성) 시스템의 '골격'이자 '내비게이션' 역할을 합니다. 단순히 텍스트만 저장하는 것이 아니라, 문서의 성격과 맥락을 정형화된 데이터로 추출해 두어야 나중에 AI 에이전트가 수천 개의 문서 중 가장 정확한 조각을 찾아낼 수 있습니다.

플랫폼 엔지니어링 지식 베이스에 최적화된 Metadata YAML 설계 전략과 이를 자동 생성하는 LangChain 구현 방안을 정리해 드립니다.

1. 왜 Metadata YAML이 검색의 질을 결정하는가?

벡터 검색(의미 기반 검색)은 문맥 파악에는 뛰어나지만, 특정 조건에서 구멍이 생깁니다. 이때 YAML 데이터가 이를 메워줍니다.

• 정밀한 필터링 (Metadata Filtering): "Cilium 관련 문서 중 SOP(표준 운영 절차)만 찾아줘"라고 할 때, 벡터 DB는 모든 Cilium 문서를 다 가져오려 하지만, YAML 필터가 있으면 즉시 SOP 카테고리만 추려낼 수 있습니다.
• 최신성 보장 (Recency): "가장 최근에 업데이트된 MinIO 설치 가이드"를 찾을 때 last_verified 필드가 있으면 AI가 구버전 가이드를 보고 오답을 내는 것을 방지합니다.
• 관계 추적 (Graph-like Search): related_components 필드를 통해 특정 장애가 발생했을 때 연관된 다른 인프라 문서를 함께 참조할 수 있게 합니다.

2. 인프라 지식 베이스를 위한 권장 YAML 스키마

단순히 제목과 날짜만 넣는 것이 아니라, 엔지니어링 관점에서 유효한 필드들을 정의해야 합니다.

---
# 문서 식별 및 분류
id: "SOP-K8S-001"
title: "K8s 노드 확장 및 드레인 절차"
category: "SOP"              # Architecture, Library, Troubleshooting, SOP
tech_stack: ["K8s", "Cilium"] # 관련 핵심 기술

# 운영 맥락 (AIOps 핵심 데이터)
severity: "High"             # 장애 대응 시 중요도
target_audience: "DevOps"     # 문서를 읽을 대상
environment: "Production"    # 적용 환경

# 관리 및 신뢰도
last_verified: "2026-04-28"  # 마지막 검증 일자 (버전 관리)
source: "Confluence"         # 원본 출처
verified_by: "Lead Engineer" # 검토자

# 연결성 (Graph View용)
related_docs: ["ARCH-LAKE-02", "SOP-MINIO-05"]
---

3. LangChain을 활용한 자동 추출 로직 (Structured Output)

LLM이 문서를 읽고 위와 같은 YAML을 일관성 있게 뽑아내도록 만드는 구체적인 코드 예시입니다.

from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.pydantic_v1 import BaseModel, Field
from typing import List

# 1. 추출하고 싶은 YAML 구조 정의 (Pydantic 클래스)
class DocMetadata(BaseModel):
    category: str = Field(description="문서의 카테고리 (SOP, Library, Architecture, OperationLog)")
    tech_stack: List[str] = Field(description="문서에 언급된 주요 기술 스택 리스트")
    summary: str = Field(description="문서 내용을 한 문장으로 요약")
    severity: str = Field(description="운영상의 중요도 (Critical, High, Medium, Low)")

# 2. LLM 및 추출 체인 설정
llm = ChatOpenAI(model="gpt-4-turbo", temperature=0) # 또는 폐쇄망용 로컬 모델
structured_llm = llm.with_structured_output(DocMetadata)

# 3. 프롬프트 구성
prompt = ChatPromptTemplate.from_template("""
당신은 플랫폼 엔지니어링 기술 문서 관리자입니다. 
다음 문서의 내용을 분석하여 정해진 구조에 따라 메타데이터를 추출하세요.

문서 내용:
{context}
""")

# 4. 실행 및 결과 확인
chain = prompt | structured_llm
doc_content = "Cilium BGP Control Plane 설정 시... (문서 본문 생략)"
metadata = chain.invoke({"context": doc_content})

print(metadata.category)     # 'Library'
print(metadata.tech_stack)   # ['Cilium', 'Networking', 'BGP']

4. AIOps로 가는 검색 효율 최적화 전략

이렇게 생성된 YAML 데이터는 벡터 DB에 'Metadata' 필드로 함께 저장되어 다음과 같은 방식으로 검색 효율을 높입니다.

1. 사전 필터링 (Pre-filtering): 사용자의 질문에서 'SOP'라는 의도를 파악하면, 벡터 검색을 수행하기 전에 DB에서 category == 'SOP'인 데이터만 대상으로 검색 범위를 좁힙니다. 검색 속도와 정확도가 비약적으로 상승합니다.
2. 가중치 부여 (Re-ranking): 검색 결과 중 last_verified가 최신이거나 severity가 높은 문서에 가중치를 주어 상단에 배치합니다.
3. 지식 그래프 연결: Obsidian에서 [[문서명]]으로 연결된 구조를 YAML의 related_docs와 매칭하여, AI가 "이 장애는 A 문서에 나오지만, 연관된 B 문서의 설정도 확인해야 합니다"라고 답변하게 만듭니다.

결론

Metadata YAML을 만드는 과정은 단순히 파일을 정리하는 것이 아니라, '데이터를 지식으로 구조화'하는 과정입니다.

Argo Workflows 파이프라인의 langchain-processor 단계에서 이 추출 로직을 강하게 적용할수록, 향후 구축될 AIOps 에이전트의 답변 품질은 1,000노드 클러스터의 복잡성을 견딜 수 있을 만큼 견고해질 것입니다.

이 추출 과정에서 특정 기술 스택(예: Cilium 특화 필드 등)에 대해 더 세밀한 분류 기준이 필요하시면 말씀해 주세요. 그에 맞는 정교한 Pydantic 스키마를 설계해 드릴 수 있습니다.

===

Confluence에서 단순 텍스트가 아닌 이미지, 다이어그램(draw.io), 그리고 코드 블록을 추출하여 Git에 최적으로 저장하고 관리하는 방법은 지식 베이스의 '가독성'과 '재사용성'을 결정짓는 핵심 요소입니다.

플랫폼 엔지니어링 리드로서 대규모 인프라 구성을 시각화하고 코드를 관리하기 위한 구체적인 가이드를 정리해 드립니다.

1. 사진 및 이미지 관리 (assets 폴더 전략)

Confluence 페이지에 첨부된 사진들은 추출 시 별도의 파일로 내려받아집니다. 이를 Git에서 깨지지 않게 관리하려면 상대 경로(Relative Path)를 유지하는 것이 가장 중요합니다.

• 저장 구조: Git 저장소 내에 assets/ 또는 images/라는 공통 폴더를 만들거나, 각 문서 폴더 하위에 _assets/ 폴더를 두어 관리합니다.
  • 예: wiki/Architecture/Lakehouse/assets/diagram-v1.png
• Markdown 링크 방식: ![설명](../assets/image.png) 와 같이 상대 경로로 작성해야 Obsidian, Git(GitHub/GitLab), 그리고 나중에 구축할 Quartz 위키에서도 이미지가 정상적으로 보입니다.
• 자동화 시: confluence-md-exporter 사용 시 --relative-links 옵션을 활성화하면 Confluence의 첨부 파일 링크를 마크다운 상대 경로로 자동 변환해 줍니다.

2. 구성도 (draw.io / Lucidchart) 처리

가장 까다로운 부분입니다. Confluence 내부의 draw.io는 데이터가 페이지 XML에 내장되어 있어 단순히 이미지로만 저장하면 나중에 수정이 불가능합니다.

• 추천 방식: .drawio.svg 또는 .drawio.png 활용
  • 편집성 유지: draw.io 파일을 저장할 때 'Editable SVG/PNG' 형태로 내보내면, 파일 자체는 이미지처럼 보이지만 draw.io 편집기로 열면 레이어와 객체가 살아있어 수정이 가능합니다.
• Obsidian 연동: 'Diagrams.net (draw.io) Integration' 플러그인을 사용하세요.
  • Git에 저장된 .drawio.svg 파일을 Obsidian에서 바로 클릭하여 수정하고 저장할 수 있습니다. 별도의 앱을 띄울 필요가 없어 매우 효율적입니다.
• 자동화 시나리오:
  1. 추출 스크립트에서 Confluence API를 통해 draw.io 매크로의 원본 XML 데이터를 추출합니다.
  2. 이를 .drawio 파일로 저장하거나, 이미지를 미리 렌더링하여 assets/ 폴더에 넣습니다.

3. 문서 내 코드 블록 (Code Block) 수집

Confluence의 코드 블록 매크로는 다행히 마크다운의 Fenced Code Blocks ( ``` )로 비교적 잘 변환됩니다.

• 언어 감지 (Syntax Highlighting):
  • Confluence 코드 블록에서 지정한 언어(예: python, yaml, bash)가 마크다운 코드 블록 상단에 그대로 붙습니다 (예: ```yaml).
  • 이를 통해 Git(GitLab/Bitbucket)이나 Obsidian에서 문법 강조가 정상적으로 작동합니다.
• 코드 추출의 정교화:
  • 일부 추출 도구는 코드 블록 내부의 특수 문자( <, > 등)를 잘못 치환하는 경우가 있습니다. 파이썬의 BeautifulSoup을 이용해 가공할 때 code 태그 내의 텍스트는 원형 그대로(Preformatted) 가져오도록 예외 처리가 필요합니다.
• 코드의 지식화 (Metadata 활용):
  • 지난번에 논의한 YAML Metadata에 contains_code: true 또는 code_lang: ["yaml", "shell"] 같은 필드를 LLM이 자동으로 추가하게 하세요.
  • 나중에 AI 에이전트에게 "Cilium BGP 설정 샘플 코드만 찾아줘"라고 할 때 검색 정확도가 비약적으로 향상됩니다.

4. 플랫폼 리드를 위한 운영 제언: '진실의 원천' 결정

이 과정에서 가장 중요한 결정은 "어디에서 그림을 수정할 것인가?"입니다.

1. Confluence에서 계속 수정: Git은 단순 백업/검색용이 됩니다. (추천하지 않음)
2. Obsidian(Git)에서 수정: 이제부터 구성도 수정은 Git에 저장된 .drawio.svg를 통해서만 합니다. (권장)
   • 이 경우, 팀원들에게 "이제 구성도는 Confluence가 아니라 Git 저장소에서 관리한다"는 Documentation as Code (DaC) 원칙을 공표해야 합니다.

[실천 단계]

• 1단계: confluence-md-exporter를 실행하여 이미지 파일들이 상대 경로로 잘 추출되는지 확인합니다.
• 2단계: draw.io 파일 중 중요한 것 하나를 .drawio.svg로 변환해 Git에 넣고, Obsidian 플러그인으로 편집이 잘 되는지 테스트합니다.
• 3단계: 추출된 마크다운 내의 코드 블록이 깨지지 않았는지, yaml이나 bash 태그가 잘 붙어있는지 점검합니다.

이미지와 구성도까지 Git에 완벽히 통합되면, 1,000노드 클러스터의 복잡한 아키텍처를 AI가 시각적 맥락까지 포함하여 이해할 수 있는 강력한 토대가 마련됩니다. 이 과정에서 특정 draw.io 매크로가 깨지는 등의 기술적 이슈가 발생하면 해결 방법을 더 상세히 찾아봐 드릴 수 있습니다.

===

1,000노드 규모의 복잡한 인프라를 운영하다 보면 문서의 '파편화'와 '노후화'는 피할 수 없는 숙제입니다. 특히 AI가 과거의 잘못된 설정(예: 이전 버전의 Cilium BGP 설정)을 정답인 것처럼 제안하면 운영상 큰 리스크가 될 수 있습니다.

Git 저장소에 쌓이는 '쓰레기 데이터'를 정리하고, AI가 가장 최신의, 유효한 지식만 참조하게 만드는 5단계 관리 전략을 제안합니다.

1. 문서 상태(Status) 메타데이터 강제화

가장 먼저 할 일은 모든 문서의 생애주기(Lifecycle)를 YAML 메타데이터로 정의하는 것입니다. 단순히 저장하는 것이 아니라, LLM이 이 상태를 읽고 필터링하게 만듭니다.

• 필수 필드 정의:
  • status: active(현재 사용), deprecated(곧 폐기), archive(참조용 구버전)
  • last_verified_at: 마지막으로 기술 검증이 된 날짜
  • applies_to_version: 해당 문서가 유효한 솔루션 버전 (예: Cilium 1.15)

2. 'Active'와 'Archive' 저장소 분리 (Directory Strategy)

Git의 장점은 삭제해도 기록이 남는다는 것입니다. 따라서 현재 시스템과 맞지 않는 문서는 과감히 메인 경로에서 치워야 합니다.

• 구조 예시:
  • /wiki/active/: 현재 1,000노드 클러스터에 적용 중인 실시간 SOP 및 가이드
  • /wiki/archive/: 과거 기록, 이전 아키텍처 (검색 대상에서 제외하거나 낮은 가중치 부여)
• 운영 방식: 새로운 버전의 문서가 Git에 들어오면, LLM 분류기가 기존 문서의 제목이나 내용을 비교하여 "이 문서는 구버전(Archive)으로 이동시키겠습니까?"라고 제안하거나 자동으로 이동시킵니다.

3. 중복 및 충돌 감지 파이프라인 (Semantic Deduplication)

Confluence에서 새로운 문서가 수집될 때, 기존 Git에 있는 문서들과 '의미적 유사도'를 비교하는 단계를 추가합니다.

• 작동 원리 (LangChain 활용):
  1. 새 문서가 들어오면 기존 벡터 DB에서 가장 유사한 문서 3개를 먼저 찾습니다.
  2. LLM에게 질문합니다: "새 문서와 기존 문서의 내용이 80% 이상 겹치나요? 아니면 기존 내용을 업데이트하는 것인가요?"
  3. 충돌 발생 시: LLM이 두 문서를 병합(Merge)하거나, 기존 문서를 status: archive로 변경하도록 자동 PR(Pull Request)을 생성합니다.

4. 벡터 DB의 검색 가중치 조정 (Recency Boosting)

검색 시 단순히 '유사도'만 보지 않고, '최신성'에 점수를 더 주는 방식을 도입합니다.

• Metadata Filtering: RAG 엔진이 검색을 수행할 때 status: active인 문서만 검색하도록 필터를 겁니다.
• Time Decay Scaling: 검색 결과 점수(Score)에 last_verified_at 날짜를 계산식에 넣어, 최근 문서가 상단에 배치되게 합니다.

  Score = Semantic Similarity + (Recency weight * Time Factor)

5. 정기적 '지식 점검' 자동화 (Governance)

문서가 낡는 것을 방지하기 위해 n8n과 Argo Workflows를 활용한 알림 시스템을 구축합니다.

1. 검증 기간 설정: last_verified_at이 6개월이 지난 문서를 추출합니다.
2. 담당자 알림 (n8n): 플랫폼 팀 Slack에 "이 SOP는 180일 동안 업데이트되지 않았습니다. 여전히 유효한가요?"라고 알림을 보냅니다.
3. 자동 폐기: 만약 검증되지 않고 1년이 지나면 자동으로 archive 폴더로 이동시키고 벡터 DB 인덱스를 삭제합니다.

결론: 플랫폼 리드를 위한 운영 조언

1,000노드 클러스터 운영에서 AI의 답변 정확도를 높이려면 "AI에게 무엇을 가르치지 않을 것인가"가 "무엇을 가르칠 것인가"만큼 중요합니다.

• 추천 실천: 지금 바로 Git 저장소 최상위에 archive/ 폴더를 만드시고, LLM 위키 파이프라인에 "중복 문서 발견 시 기존 문서 아카이브 로직"을 한 줄 추가해 보세요.

이렇게 관리하면 시스템 상태와 맞지 않는 '죽은 지식'이 AI의 답변을 오염시키는 일을 원천 차단할 수 있습니다. 이 과정 중 특정 단계(예: 중복 감지 로직)의 구체적인 코드가 필요하신가요?

1. AIStor Table 생성 및 전환 프로세스 (Pipeline Design)

Inventory API를 통해 수집된 Parquet 파일은 단순한 '객체' 상태입니다. 이를 고성능 분석이 가능한 'AIStor Table'로 승격시키는 과정입니다.

Step 1: Landing Zone 저장 (Inventory API)

• 작업: Inventory API가 소스 시스템에서 데이터를 수집하여 MinIO의 landing-bucket에 Parquet 포맷으로 저장합니다.
• 특징: 이 단계에서는 아직 Iceberg 메타데이터가 없는 순수 데이터 파일 상태입니다.

Step 2: Iceberg Table Schema 정의 및 생성

• 작업: Spark 또는 Trino를 사용하여 AIStor 내에 Iceberg 테이블 껍데기(Schema)를 생성합니다.
• 설정: Polaris Catalog를 사용하므로, 생성 시 catalog 타입을 polaris로 지정합니다.

Step 3: 데이터 로드 및 변환 (Ingestion to Iceberg)

단순 복사가 아닌 Iceberg의 메타데이터(Manifest, Snapshot)를 생성하며 데이터를 옮깁니다.

• 방법: INSERT INTO aistor_table SELECT * FROM parquet_raw_files
• 최적화: 이 과정에서 Partitioning(날짜, 부서 등)과 Sorting(Z-order 등)을 적용하여 향후 쿼리 시 스캔 범위를 최소화합니다.

2. 하부 인프라 및 거버넌스 연계 설계

앞서 논의된 Keycloak, Polaris, AIStor 환경을 녹여낸 통합 이용 방안입니다.

① 권한 및 보안 (Keycloak + Polaris)

• RBAC 적용: 사용자가 Trino나 Spark에서 AIStor Table에 접근할 때, Keycloak에서 발급받은 토큰이 Polaris로 전달됩니다.
• Access Control: Polaris는 Iceberg 테이블의 네임스페이스 및 테이블 단위로 권한을 체크하며, 승인된 경우에만 MinIO의 임시 자격 증명을 반환합니다.

② 엔진별 활용 (Trino, Spark, StarRocks)

• Trino/StarRocks: 실시간 대시보드 및 고속 쿼리에 활용합니다. Iceberg의 Snapshot 기능을 이용해 특정 시점의 데이터로 쿼리(Time Travel)를 수행할 수 있습니다.
• Spark: 대규모 배치 처리 및 AI 모델 학습용 데이터 전처리에 활용합니다. Iceberg 테이블에서 필요한 증분 데이터(Incremental Read)만 효율적으로 읽어옵니다.

③ 데이터 생애주기 관리 (ILM & Tiering 연계)

• Hot Tier (NVMe): 최근 생성된 Iceberg 데이터와 메타데이터 파일들을 보관하여 3,000 RPS 수준의 고성능 I/O를 지원합니다.
• Cold Tier (SATA SSD - Pool 2): Iceberg의 Partition Evolution 기능을 활용합니다. 오래된 날짜의 데이터 파티션 파일들만 Cold Pool로 이동(Tiering)시켜 저장 효율을 극대화합니다.

3. AIStor Table 운영 및 최적화 방안 (DevOps 가이드)

1,000노드 규모에서 AIStor Table의 성능을 유지하기 위한 핵심 운영 전략입니다.

4. 기대 효과 및 활용 시나리오

1. 초고속 데이터 탐색: 단순 객체 조회가 아닌 SQL 기반의 고성능 분석이 가능해지며, Iceberg의 메타데이터 필터링 덕분에 스토리지 부하가 획기적으로 줄어듭니다.
2. 데이터 일관성 (ACID): 여러 엔진(Spark, Trino 등)이 동시에 데이터를 쓰고 읽어도 트랜잭션 보장 덕분에 데이터 오염이 발생하지 않습니다.
3. Vibe Coding Zone 연계: 개발 환경에서 운영 환경의 특정 시점 Snapshot을 Read-only로 마운트하여 실제 데이터를 기반으로 안전하게 모델링 실험을 수행할 수 있습니다.

설계 제언

"Inventory API로 들어오는 원천 Parquet은 '재료'이고, AIStor Table은 이를 맛있게 요리한 '완성된 요리'입니다. 8월에 도입될 130대의 대규모 Cold Pool을 고려할 때, Partitioning 전략을 지금부터 세밀하게 설계해 두어야 나중에 대규모 데이터 이동 시 시스템 전체의 Latency 튀는 현상을 막을 수 있습니다."

이 과정에서 특정 쿼리 엔진(예: Trino)의 성능을 우선시하시나요? 그렇다면 그에 맞춘 구체적인 Iceberg Partitioning 튜닝 파라미터를 추가로 제안해 드릴 수 있습니다.

===

하부 페이지도 추가로 확인할게.이제 설계를 시작할게. AIStor Tables docs와 Inventory API 내용을 종합해서 전체 파이프라인을 설계할게.

Inventory Parquet → AIStor Iceberg Table 파이프라인 설계

전체 아키텍처

┌─────────────────────────────────────────────────────────────────┐
│                        Hot/Cold MinIO AIStor                     │
│                                                                   │
│  ① mc inventory generate                                         │
│     └── inventory-bucket/YYYY-MM-DD/*.parquet  (원시 데이터)      │
│                                                                   │
│  ② PyIceberg / Spark (ETL)                                       │
│     └── Parquet 읽기 → 스키마 정규화 → AIStor Tables에 쓰기       │
│                                                                   │
│  ③ AIStor Tables (Iceberg REST Catalog)                          │
│     warehouse: infra-analytics                                    │
│     └── namespace: inventory                                      │
│         ├── table: object_inventory     ← 증분 append              │
│         ├── table: tier_summary         ← daily rollup            │
│         └── table: ilm_candidates      ← ILM 대상 선별           │
│                                                                   │
│  ④ 쿼리 클라이언트                                                │
│     Trino / Spark / Dremio / PyIceberg                           │
└─────────────────────────────────────────────────────────────────┘

Step 1 — Inventory 수집 설정 (mc inventory)

# Inventory 설정 생성 (Hot 클러스터 전체 대상)
mc inventory generate HOT \
  --destination HOT/inventory-bucket \
  --schedule "daily"

# 상태 확인
mc inventory list HOT
mc inventory status HOT/<inventory-id>

# 수동 실행 (즉시 수집)
mc inventory resume HOT/<inventory-id>

생성된 Parquet 파일 구조:

inventory-bucket/
  └── YYYY-MM-DD/
      └── <bucket-name>/
          ├── part-00000.parquet   ← 오브젝트 메타 포함
          └── part-00001.parquet

Parquet 컬럼 주요 필드 (Inventory API 기준):

bucket, key, version_id, is_latest, is_delete_marker,
size, last_modified, e_tag, storage_class,
replication_status, encryption_status,
object_lock_mode, object_lock_retain_until_date

Step 2 — AIStor Tables 리소스 구성

2-1. Warehouse / Namespace / Table 생성

# Warehouse 생성 (analytics용)
mc table warehouse create HOT infra-analytics

# Namespace 생성
mc table namespace create HOT infra-analytics inventory

# 메인 테이블: object_inventory (전체 오브젝트 스냅샷)
mc table create HOT infra-analytics inventory object_inventory \
  --schema '{
    "type": "struct",
    "fields": [
      {"id":1,  "name":"snapshot_date",       "type":"date",    "required":true},
      {"id":2,  "name":"cluster",             "type":"string",  "required":true},
      {"id":3,  "name":"bucket",              "type":"string",  "required":true},
      {"id":4,  "name":"key",                 "type":"string",  "required":true},
      {"id":5,  "name":"size_bytes",          "type":"long",    "required":false},
      {"id":6,  "name":"last_modified",       "type":"timestamptz","required":false},
      {"id":7,  "name":"storage_class",       "type":"string",  "required":false},
      {"id":8,  "name":"is_latest",           "type":"boolean", "required":false},
      {"id":9,  "name":"is_delete_marker",    "type":"boolean", "required":false},
      {"id":10, "name":"replication_status",  "type":"string",  "required":false},
      {"id":11, "name":"version_id",          "type":"string",  "required":false},
      {"id":12, "name":"tier",                "type":"string",  "required":false}
    ]
  }'

# ILM 후보 테이블 (전환 대상 분석용)
mc table create HOT infra-analytics inventory ilm_candidates \
  --schema '{
    "type": "struct",
    "fields": [
      {"id":1, "name":"snapshot_date",   "type":"date",   "required":true},
      {"id":2, "name":"bucket",          "type":"string", "required":true},
      {"id":3, "name":"prefix",          "type":"string", "required":false},
      {"id":4, "name":"object_count",    "type":"long",   "required":false},
      {"id":5, "name":"total_size_bytes","type":"long",   "required":false},
      {"id":6, "name":"avg_age_days",    "type":"double", "required":false},
      {"id":7, "name":"storage_class",   "type":"string", "required":false},
      {"id":8, "name":"recommendation",  "type":"string", "required":false}
    ]
  }'

# 테이블 확인
mc table list HOT infra-analytics inventory

Step 3 — ETL: Parquet → AIStor Iceberg Table

PyIceberg 기반 ETL 스크립트

# inventory_to_iceberg.py
import pandas as pd
import pyarrow as pa
import pyarrow.parquet as pq
from pyiceberg.catalog import load_catalog
from pyiceberg.expressions import GreaterThanOrEqual
from datetime import date
import boto3
import os
from pathlib import Path

# ─────────────────────────────────────────────────────────
# 1. AIStor Iceberg Catalog 연결
# ─────────────────────────────────────────────────────────
catalog = load_catalog(
    "aistor",
    **{
        "uri": "http://hot-aistor.example.com:9000/_iceberg",
        "warehouse": "infra-analytics",
        "rest.sigv4-enabled": "true",
        "rest.signing-name": "s3tables",
        "rest.signing-region": "local",
        "s3.access-key-id": os.environ["MINIO_ACCESS_KEY"],
        "s3.secret-access-key": os.environ["MINIO_SECRET_KEY"],
        "s3.endpoint": "http://hot-aistor.example.com:9000"
    }
)

# ─────────────────────────────────────────────────────────
# 2. 오늘 날짜 Inventory Parquet 파일 수집
# ─────────────────────────────────────────────────────────
s3 = boto3.client(
    's3',
    endpoint_url='http://hot-aistor.example.com:9000',
    aws_access_key_id=os.environ["MINIO_ACCESS_KEY"],
    aws_secret_access_key=os.environ["MINIO_SECRET_KEY"]
)

today = date.today()
prefix = f"{today.isoformat()}/"

# inventory-bucket에서 오늘 날짜 parquet 목록 수집
response = s3.list_objects_v2(Bucket='inventory-bucket', Prefix=prefix)
parquet_keys = [
    obj['Key'] for obj in response.get('Contents', [])
    if obj['Key'].endswith('.parquet')
]

# ─────────────────────────────────────────────────────────
# 3. Parquet 읽기 + 스키마 정규화
# ─────────────────────────────────────────────────────────
dfs = []
for key in parquet_keys:
    local_path = f"/tmp/{Path(key).name}"
    s3.download_file('inventory-bucket', key, local_path)
    df = pd.read_parquet(local_path)
    dfs.append(df)

raw_df = pd.concat(dfs, ignore_index=True)

# 컬럼 정규화 및 파생 컬럼 추가
raw_df['snapshot_date'] = today
raw_df['cluster']       = 'hot-primary'
raw_df['tier']          = raw_df['storage_class'].apply(
    lambda x: 'cold' if str(x).startswith('COLD') else 'hot'
)
raw_df['size_bytes']    = raw_df['size'].fillna(0).astype('int64')
raw_df['last_modified'] = pd.to_datetime(raw_df['last_modified'], utc=True)

# 필요 컬럼만 선택
iceberg_df = raw_df[[
    'snapshot_date', 'cluster', 'bucket', 'key',
    'size_bytes', 'last_modified', 'storage_class',
    'is_latest', 'is_delete_marker',
    'replication_status', 'version_id', 'tier'
]]

# ─────────────────────────────────────────────────────────
# 4. PyArrow 변환 후 AIStor Iceberg Table에 Append
# ─────────────────────────────────────────────────────────
table = catalog.load_table("inventory.object_inventory")

arrow_table = pa.Table.from_pandas(iceberg_df)
table.append(arrow_table)

print(f"✅ {len(iceberg_df):,}건 → inventory.object_inventory append 완료")

# ─────────────────────────────────────────────────────────
# 5. ILM 후보 집계 → ilm_candidates 테이블 갱신
# ─────────────────────────────────────────────────────────
from datetime import datetime, timezone

now = datetime.now(timezone.utc)
iceberg_df['age_days'] = (now - iceberg_df['last_modified']).dt.days

# tier=hot & age > 30일 오브젝트만 집계
candidates = (
    iceberg_df[
        (iceberg_df['tier'] == 'hot') &
        (iceberg_df['age_days'] >= 30) &
        (iceberg_df['is_latest'] == True) &
        (iceberg_df['is_delete_marker'] != True)
    ]
    .assign(prefix=lambda df: df['key'].str.split('/').str[0])
    .groupby(['bucket', 'prefix', 'storage_class'])
    .agg(
        object_count=('key', 'count'),
        total_size_bytes=('size_bytes', 'sum'),
        avg_age_days=('age_days', 'mean')
    )
    .reset_index()
)

candidates['snapshot_date'] = today
candidates['recommendation'] = candidates.apply(
    lambda r: 'TRANSITION_TO_COLD' if r['avg_age_days'] >= 90
              else 'MONITOR', axis=1
)

ilm_table = catalog.load_table("inventory.ilm_candidates")
ilm_table.append(pa.Table.from_pandas(candidates))

print(f"✅ {len(candidates):,}건 → inventory.ilm_candidates append 완료")

Spark 기반 ETL (대용량 처리 시)

# spark_inventory_etl.py
from pyspark.sql import SparkSession
from pyspark.sql.functions import col, lit, datediff, current_date, split

spark = SparkSession.builder \
    .appName("InventoryToIceberg") \
    .config("spark.sql.catalog.aistor", "org.apache.iceberg.spark.SparkCatalog") \
    .config("spark.sql.catalog.aistor.catalog-impl",
            "org.apache.iceberg.rest.RESTCatalog") \
    .config("spark.sql.catalog.aistor.uri",
            "http://hot-aistor.example.com:9000/_iceberg") \
    .config("spark.sql.catalog.aistor.warehouse", "infra-analytics") \
    .config("spark.sql.catalog.aistor.rest.sigv4-enabled", "true") \
    .config("spark.sql.catalog.aistor.rest.signing-name", "s3tables") \
    .config("spark.sql.catalog.aistor.rest.signing-region", "local") \
    .config("spark.sql.catalog.aistor.rest.access-key-id", "MINIO_ACCESS_KEY") \
    .config("spark.sql.catalog.aistor.rest.secret-access-key", "MINIO_SECRET_KEY") \
    .config("spark.hadoop.fs.s3a.endpoint",
            "http://hot-aistor.example.com:9000") \
    .config("spark.hadoop.fs.s3a.path.style.access", "true") \
    .getOrCreate()

TODAY = "2025-05-01"

# 오늘 Inventory Parquet 읽기
raw = spark.read.parquet(
    f"s3a://inventory-bucket/{TODAY}/**/*.parquet"
)

# 정규화
enriched = raw \
    .withColumn("snapshot_date", lit(TODAY).cast("date")) \
    .withColumn("cluster",       lit("hot-primary")) \
    .withColumn("size_bytes",    col("size").cast("long")) \
    .withColumn("tier",
        when(col("storage_class").startswith("COLD"), "cold")
        .otherwise("hot")
    )

# Iceberg Table에 Append
enriched.select(
    "snapshot_date", "cluster", "bucket", "key",
    "size_bytes", "last_modified", "storage_class",
    "is_latest", "is_delete_marker",
    "replication_status", "version_id", "tier"
).writeTo("aistor.inventory.object_inventory").append()

print("✅ object_inventory append 완료")

# ILM 후보 집계
spark.sql("""
    INSERT INTO aistor.inventory.ilm_candidates
    SELECT
        CAST('{today}' AS DATE) AS snapshot_date,
        bucket,
        split(key, '/')[0] AS prefix,
        COUNT(*)             AS object_count,
        SUM(size_bytes)      AS total_size_bytes,
        AVG(datediff(current_date(), DATE(last_modified))) AS avg_age_days,
        storage_class,
        CASE
          WHEN AVG(datediff(current_date(), DATE(last_modified))) >= 90
          THEN 'TRANSITION_TO_COLD'
          ELSE 'MONITOR'
        END AS recommendation
    FROM aistor.inventory.object_inventory
    WHERE snapshot_date = CAST('{today}' AS DATE)
      AND tier = 'hot'
      AND is_latest = true
      AND is_delete_marker = false
      AND datediff(current_date(), DATE(last_modified)) >= 30
    GROUP BY bucket, split(key, '/')[0], storage_class
""".format(today=TODAY))

Step 4 — 활용 쿼리 설계 (Trino 기준)

4-1. Tier별 용량 현황

-- Hot/Cold 용량 및 오브젝트 수 현황
SELECT
    snapshot_date,
    cluster,
    tier,
    storage_class,
    COUNT(*)                          AS object_count,
    SUM(size_bytes) / 1e15            AS size_petabytes,
    AVG(size_bytes) / 1e6             AS avg_size_mb
FROM aistor.inventory.object_inventory
WHERE snapshot_date = CURRENT_DATE
GROUP BY snapshot_date, cluster, tier, storage_class
ORDER BY size_petabytes DESC;

4-2. ILM 전환 우선순위 대상 식별

-- Cold로 내릴 수 있는 Hot 데이터 (30일 이상 미접근 추정)
SELECT
    bucket,
    prefix,
    object_count,
    ROUND(total_size_bytes / 1e12, 2)  AS size_tb,
    ROUND(avg_age_days)                AS avg_age_days,
    recommendation
FROM aistor.inventory.ilm_candidates
WHERE snapshot_date = CURRENT_DATE
  AND recommendation = 'TRANSITION_TO_COLD'
ORDER BY total_size_bytes DESC
LIMIT 50;

4-3. 버킷별 Cold 전환 시뮬레이션

-- 30/60/90일 기준 전환 시 용량 절감 효과
SELECT
    bucket,
    SUM(CASE WHEN age_days >= 30 THEN size_bytes ELSE 0 END) / 1e12 AS cold_30d_tb,
    SUM(CASE WHEN age_days >= 60 THEN size_bytes ELSE 0 END) / 1e12 AS cold_60d_tb,
    SUM(CASE WHEN age_days >= 90 THEN size_bytes ELSE 0 END) / 1e12 AS cold_90d_tb,
    SUM(size_bytes) / 1e12                                           AS total_tb
FROM (
    SELECT
        bucket,
        size_bytes,
        datediff(day, date(last_modified), current_date) AS age_days
    FROM aistor.inventory.object_inventory
    WHERE snapshot_date = CURRENT_DATE
      AND tier = 'hot'
      AND is_latest = true
      AND is_delete_marker = false
)
GROUP BY bucket
ORDER BY cold_90d_tb DESC;

4-4. 날짜별 증가 추이 (Iceberg Time Travel 활용)

-- 주간 용량 증가 트렌드 (Iceberg의 snapshot 이력 활용)
SELECT
    snapshot_date,
    tier,
    SUM(size_bytes) / 1e15 AS total_petabytes
FROM aistor.inventory.object_inventory
WHERE snapshot_date >= CURRENT_DATE - INTERVAL '30' DAY
GROUP BY snapshot_date, tier
ORDER BY snapshot_date, tier;

Step 5 — 주기적 실행 자동화

# crontab 예시: 매일 새벽 3시 실행
# 1. Inventory 생성 → 완료 대기
# 2. ETL 실행 → Iceberg Table append
# 3. 오래된 raw parquet 정리

# /etc/cron.d/minio-inventory-etl
0 3 * * * root /opt/scripts/run_inventory_etl.sh >> /var/log/inventory_etl.log 2>&1

#!/bin/bash
# run_inventory_etl.sh

DATE=$(date +%Y-%m-%d)
echo "[$DATE] Inventory ETL 시작"

# 1. Inventory 완료 확인
mc inventory status HOT/<inventory-id> | grep -q "Completed" || {
  echo "Inventory 아직 미완료, 재시도"
  exit 1
}

# 2. ETL 실행
python3 /opt/scripts/inventory_to_iceberg.py

# 3. 이전 Raw Parquet 정리 (30일 이전)
mc find HOT/inventory-bucket \
  --older-than 30d \
  --name "*.parquet" | xargs -I{} mc rm HOT/{}

echo "[$DATE] ETL 완료"

활용 방안 종합

AIStor Tables는 외부 카탈로그 서비스나 메타데이터 DB 없이 MinIO AIStor 내부에서 직접 Iceberg 테이블을 생성·관리·쿼리할 수 있고, Spark, Trino, Dremio, Starburst 같은 클라이언트에서 Iceberg REST Catalog나 S3 API 양쪽으로 접근 가능하다.

이를 활용한 용도를 구체적으로 정리하면:

핵심 주의사항

AIStor Tables는 테이블 위치(location)를 MinIO가 직접 관리하며, 사용자가 커스텀 위치를 지정할 수 없음 → Parquet을 직접 테이블 위치에 복사하는 방식 사용 불가, 반드시 PyIceberg/Spark 등 클라이언트 라이브러리를 통한 append 방식 사용

커밋은 낙관적 동시성 제어(optimistic locking)로 처리되며, 충돌 시 지수 백오프로 재시도 권장 — 병렬 ETL 실행 시 주의

AIStor Tables 기능은 minio RELEASE.2026-02-02T23-40-11Z 이상에서 지원 — 버전 확인 필수

MinIO AIStor Cold Tier Best Practice 안

📌 Docs에서 확인한 중요 제약사항 먼저

MinIO AIStor의 Object Tiering은 백업/복구 솔루션이 아님 — Cold tier로 전환된 데이터는 Hot tier 메타데이터와 강하게 연결되어 있어서, Hot 장애 시 Cold 데이터만으로 복구 불가능함.

Cold target bucket에는 반드시 MinIO가 독점 접근해야 하고, 외부 변경/삭제/별도 ILM 규칙을 절대 설정하면 안 됨.

안 A: ILM Tiering Only (단순 구성, 권고)

대상: 정책이 아무것도 없는 지금 상황에서 가장 빠르게 안정적으로 시작할 수 있는 구성

[Hot Cluster - 기존]                   [Cold Cluster - 신규]
128 nodes (6.8TiB x20)                 Server Pool A: pool0 (14nodes, 7TiB SATA)
                                        Server Pool B: pool1 (14nodes, 3.5TiB SAS)
    │                                   Server Pool C: pool2 (130nodes, 3.5TiB SATA) ← 8월
    │  ILM Transition (자동)
    └──────────────────────────────────▶ COLD-TIER (remote tier)
                                            └─ bucket: cold-archive
                                               prefix: hot/{deployment-name}/

Cold Cluster 구성

# 5월: pool0 + pool1 동시 기동 (Cold 클러스터)
minio server \
  https://cold-pool0-{1...14}.example.com/data{1...20} \
  https://cold-pool1-{1...14}.example.com/data{1...20} \
  --address :9000

# 8월: pool2 추가 (클러스터 재시작 필요 → 점검 윈도우 확보)
minio server \
  https://cold-pool0-{1...14}.example.com/data{1...20} \
  https://cold-pool1-{1...14}.example.com/data{1...20} \
  https://cold-pool2-{1...130}.example.com/data{1...20}

Remote Tier 등록 및 ILM 설정

# 1. Cold 클러스터를 Hot에 Remote Tier로 등록
mc ilm tier add minio HOT/COLD-TIER \
  --endpoint https://cold-aistor.example.com \
  --access-key <cold-svc-access-key> \
  --secret-key <cold-svc-secret-key> \
  --bucket cold-archive \
  --prefix hot/prod/            # 선택적 human-readable prefix (운영/진단 편의)

# Tier 상태 확인
mc ilm tier ls HOT
mc ilm tier check HOT/COLD-TIER

# 2. ILM 전환 규칙 (버킷별 적용)
# 기본: 30일 후 Cold 전환
mc ilm rule add HOT/my-bucket \
  --transition-days 30 \
  --transition-tier COLD-TIER

# prefix별 차등 (로그 7일, 백업 90일)
mc ilm rule add HOT/my-bucket \
  --prefix "logs/" \
  --transition-days 7 \
  --transition-tier COLD-TIER

mc ilm rule add HOT/my-bucket \
  --prefix "backup/" \
  --transition-days 90 \
  --transition-tier COLD-TIER

# 현재 상태 확인 (ls로 tier 표시)
# STANDARD = Hot에 있음, COLD-TIER = Cold로 전환됨
mc ls HOT/my-bucket

이 안의 특징

⚠️ Cold target bucket에 별도 ILM 규칙(expiration, tiering) 절대 금지 — Cold 클러스터 생성 후 해당 bucket은 Hot의 MinIO만 접근해야 함

안 B: ILM Tiering + Versioning + noncurrent version 관리 (권장 중급)

대상: 실수 삭제 방지, 버전 관리가 필요한 경우 (추후 컴플라이언스 대비 포함)

[Hot Cluster]
  Versioned Buckets
  ├── current version ──[30일 후]──▶ Cold WARM-TIER
  ├── noncurrent version ──[7일 후]──▶ Cold WARM-TIER (또는 expire)
  └── delete marker ──[expire-delete-marker]──▶ 정리

핵심 설정

# 1. 버킷 버전닝 활성화
mc version enable HOT/my-bucket

# 2. Current version → Cold 전환
mc ilm rule add HOT/my-bucket \
  --transition-days 30 \
  --transition-tier COLD-TIER

# 3. Noncurrent version → Cold 전환 (버전 누적 방지)
mc ilm rule add HOT/my-bucket \
  --noncurrent-transition-days 7 \
  --noncurrent-transition-tier COLD-TIER

# 4. Delete marker 정리 (버전이 없는 delete marker만)
mc ilm rule add HOT/my-bucket \
  --expire-delete-marker

# 5. 규칙 확인
mc ilm rule ls HOT/my-bucket

버전닝 + ILM 동작 흐름

Day 0:  Object 생성 → Hot(STANDARD)
Day 30: ILM 스캐너 감지 → Cold로 전환 (Hot에는 stub/포인터만 남음)
Day 30: 클라이언트 GET → MinIO가 투명하게 Cold에서 자동 recall
        (앱 변경 불필요)

버전 업데이트 시:
  이전 버전 → 7일 후 Cold 전환 또는 expire
  최신 버전 → 30일 후 Cold 전환

📌 ILM 스캐너는 low-priority 프로세스로, 고부하 시 전환 시점이 설정값보다 늦어질 수 있음 — 정확한 SLA가 필요하면 여유 있는 일수 설정 필요

이 안의 특징

안 C: ILM Tiering + Bucket Replication for DR (Hot 이중화)

대상: Hot 클러스터 장애 대비 DR이 필요하고, Cold는 비용 최적화만 하는 경우

[Hot-Primary - Site A]          [Hot-DR - Site B]
  128 nodes                       별도 MinIO AIStor
       │ Bucket Replication (Active-Passive)
       │──────────────────────────▶ 동일 버킷 복제
       │
       │ ILM Transition
       └──────────────────────────▶ [Cold Cluster]
                                      pool0 + pool1 + pool2

설정 방향

# === Bucket Replication: Hot-Primary → Hot-DR ===
# Hot-DR에 서비스 계정 생성 후, Hot-Primary에서 복제 설정

mc replicate add HOT_PRIMARY/my-bucket \
  --remote-bucket my-bucket \
  --replication-mode async \
  "https://<hot-dr-user>:<hot-dr-pass>@hot-dr.example.com"

# 복제 상태 모니터링
mc replicate status HOT_PRIMARY/my-bucket

# === ILM Tiering: Hot-Primary → Cold (안 A/B와 동일) ===
mc ilm tier add minio HOT_PRIMARY/COLD-TIER \
  --endpoint https://cold-aistor.example.com \
  --bucket cold-archive \
  --prefix hot/primary/

⚠️ 중요 제약사항 (Docs 기반)

ILM Expiration으로 삭제된 오브젝트는 복제 대상이 아님 — Bucket Replication과 ILM Expiration을 함께 쓸 경우, Hot-DR에 delete가 전파되지 않으니 별도 처리 필요

Site Replication은 모든 피어 클러스터가 동일 IDP, 동일 버전, 동일 암호화 설정을 사용해야 함 — 기존 Hot과 신규 Cold 클러스터 간 Site Replication은 이 조건 불일치로 부적합

3개 안 비교 요약

어떤 안으로 시작할지 결정 기준

Q1. Hot 전체 장애 시 데이터 접근이 비즈니스 크리티컬한가?
  YES → 안 C (Hot DR 구성 필요)
  NO  → 다음 질문

Q2. 실수 삭제나 데이터 이력 보존이 필요한가?
  YES → 안 B (Versioning + ILM)
  NO  → 안 A (ILM Tiering Only, 5월 구축에 가장 적합)

지금 당장 실행 가능한 최소 액션 (5월 전 필수):

[ ] Cold 클러스터 서비스 계정 분리 생성 (Hot과 별도)
[ ] Cold target bucket 사전 생성 + deny all 정책 (ILM 서비스 계정만 허용)
[ ] ILM 전환 일수 고객사 합의 (최소 1개 버킷이라도)
[ ] Cold 클러스터 점검 윈도우 확보 (8월 pool2 추가 시 재시작 필요)
[ ] mc ilm tier check 로 연결 검증 자동화 방안 마련

더 구체적으로 파고들 부분(예: noncurrent version expire 설정, 서비스 계정 policy JSON, 버킷별 prefix 체계)이 있으면 말씀해 주세요!

===

제시해주신 MinIO AIStor의 Versioning, ILM(Lifecycle), Replication 공식 문서를 바탕으로, 현재 운영 중인 128대(Hot)와 향후 도입될 158대(Pool 0, 1, 2)의 대규모 인프라 환경에 최적화된 3가지 Best Practice 시나리오를 설계해 드립니다.

Scenario 1. 초고성능 AI 모델 및 핵심 자산 보호

목표: 데이터 유실 제로(Zero Data Loss) 및 즉각적인 가용성 확보 대상: AI 모델 가중치(Weights), AD/Keycloak 연동 설정, 핵심 Iceberg 메타데이터

DevOps Tip: 초고성능 요청이 발생하는 버킷에 Versioning을 걸면 Delete Marker가 쌓여 LIST 성능이 저하될 수 있습니다. 주기적으로 ExpiredObjectDeleteMarkers를 청소하는 정책을 세트로 구성해야 합니다.

Scenario 2. 대규모 데이터 레이크하우스 (Inventory $\rightarrow$ Iceberg)

목표: TCO(총소유비용) 절감 및 9PB급 대용량 효율적 관리 대상: Inventory API 수집 Parquet, Iceberg Data Files, 분석용 원천 데이터

Scenario 3. 컴플라이언스 및 아카이브 로그 관리

목표: 법적 규제 준수 및 장기 보존 데이터의 안정적 처리 대상: 시스템 액세스 로그(Keycloak, K8s), 감사 로그(Audit Logs)

💡 아키텍트 관점의 통합 운영 설계 가이드

1. 1,000노드 확장을 위한 'Delete Marker' 최적화

RPS가 높은 환경에서 Versioning을 사용하면 수많은 '삭제 마커'가 생성됩니다. 이는 mc admin trace에서 LIST 요청의 Duration을 늘리는 주범입니다.

• 해결책: ILM 정책에 DelMarkerExpiration: true를 포함하여, 데이터가 실제로 없는 빈 마커들을 24시간 내에 자동으로 소거하십시오.

2. 8월 Pool 2(130대) 도입 시 리밸런싱 전략

130대의 노드가 한꺼번에 투입되면 기존 Hot Tier에서 데이터가 대량으로 넘어가며 네트워크 대역폭(50Gbps 본딩)을 잠식할 수 있습니다.

• 해결책: ILM 정책의 Transition 작업을 업무 외 시간(Off-peak hours)에 실행되도록 스케줄링하거나, mc admin config를 통해 백그라운드 복제/티어링 속도를 제한(Throttle)하는 정책을 미리 수립해야 합니다.

3. 복제 지연(Replication Lag) 모니터링

비동기 복제를 사용하면 3,000 RPS의 쓰기 속도를 복제 프로세스가 따라가지 못할 수 있습니다.

• 해결책: Prometheus가 없는 현재 상황에서는 mc admin bucket remote status 명령어를 주기적으로 실행하여 Pending 데이터 양이 늘어나는지 상시 확인하는 자동화 스크립트 배포를 권장합니다.

최종 제언

"고객사에는 '가용성 중심(Scenario 1)'과 '비용/용량 중심(Scenario 2)' 버킷을 명확히 구분하여 제안하십시오. 특히 8월에 들어올 130대의 노드는 ILM Transition의 종착지로 설정하되, 대량 이동 시 발생할 I/O 부하를 고려하여 비동기 정책을 표준으로 가져가는 것이 3,000 RPS 서비스 안정성을 지키는 핵심입니다."

현재 어떤 시나리오가 고객사의 비즈니스 요구사항(예: 비용 절감 vs 데이터 보안)에 더 가깝다고 보시나요? 필요하신 시나리오에 대해 구체적인 JSON 정책 샘플을 작성해 드릴 수 있습니다.

단순히 용량을 늘리는 것을 넘어, 데이터의 생애주기(Lifecycle)를 관리하고 비용 효율적인 대규모 스토리지(Cold Tier)를 구축하기 위한 전략적 아키텍처를 제안해 드립니다.

1. 계층별 풀(Pool) 정의 및 특성 분류

먼저 추가되는 자원들의 특성을 기반으로 계층(Tier)을 논리적으로 분리해야 합니다.

2. 아키텍처 구성 전략: Server-side Tiering vs Multi-Pool

이 규모에서는 두 가지 전략 중 하나를 선택해야 합니다.

전략 A: 단일 네임스페이스 (Server-Pools) 확장

모든 Pool을 하나의 MinIO 클러스터로 묶는 방식입니다.

• 방법: 기존 128노드 클러스터에 신규 노드들을 Pool로 계속 추가합니다.
• 장점: 사용자는 단일 Endpoint만 바라보면 되며 관리가 단순합니다.
• 단점: Hot Tier의 초고성능 I/O가 Cold Tier의 리밸런싱 작업 등에 영향을 받을 수 있습니다. (QoS 분리 어려움)

전략 B: 계층형 티어링 (Lifecycle + Remote Tiering) - 권장

Hot 클러스터와 Cold 클러스터를 논리적으로 분리하고, MinIO의 ILM(Information Lifecycle Management) 기능을 사용하는 방식입니다.

• 방법: 128노드(Hot)는 그대로 두고, 신규 158노드(Pool 0,1,2)를 별도의 'Cold Cluster'로 구성한 뒤 Hot 클러스터에서 mc ilm tier add로 연결합니다.
• 장점: 하드웨어 장애 전파(Fault Domain)가 격리되며, Hot Tier의 RPS 성능을 100% 보호할 수 있습니다. 1,000노드 확장 시 관리가 훨씬 유연합니다.

3. 상세 정책(Policy) 제안

고객사에 정책이 없는 상태이므로, 가장 표준적인 "3-Step 데이터 전이" 정책을 제안해 보세요.

① ILM (Lifecycle) 정책

데이터의 "신선도"에 따라 자동으로 이동시킵니다.

• Hot $\rightarrow$ Warm (30일): 생성된 지 30일이 지난 데이터는 SAS/SATA SSD 풀로 이동.
• Warm $\rightarrow$ Cold (90일): 90일이 지난 데이터는 Pool 2(130대 노드)로 이동하여 저장 밀도 극대화.
• Expiration (365일+): 필요 시 보존 기간이 지난 데이터는 자동 삭제.

② Replication (복제) 정책

AIStor의 안정성을 위해 중요한 버킷은 Active-Active 또는 Active-Passive 복제를 설정합니다.

• Metadata 및 중요 Model: Hot Tier 내에서 2대 이상의 노드에 가용성을 확보하도록 EC 설정을 높게 가져가고, 필요시 원격지 클러스터로 Site Replication을 고려합니다.

③ Erasure Coding (데이터 보호) 최적화

• Pool 2 (130노드): 노드 수가 압도적으로 많으므로 EC:16 설정을 추천합니다. 이렇게 하면 16대의 노드가 동시에 장애가 나도 데이터가 안전하며, 저장 공간 효율(Overhead)을 최소화할 수 있습니다.

4. DevOps 구현 및 운영 포인트

• Cilium ClusterMesh 활용: Hot 클러스터와 Cold 클러스터를 분리하더라도, Cilium ClusterMesh를 통해 노드 간 통신을 Native 모드로 연결하여 티어링(Data Migration) 시 발생하는 네트워크 부하를 최적화하세요.
• ResourceQuota 적용: K8s Namespace마다 용량 제한을 설정했던 것처럼, 각 Pool이나 Tenant별로 Quota를 엄격히 적용하여 특정 Cold 데이터가 Hot Tier의 Buffer를 다 채우지 않도록 방지해야 합니다.
• 5월/8월 단계적 도입: * 5월: Pool 0, 1을 먼저 'Warm Tier'로 연동하여 티어링 로직이 3,000 RPS 환경에서 안정적인지 검증합니다.
  • 8월: Pool 2(130대) 투입 시점에는 대규모 리밸런싱이 발생하므로, 이때 네트워크 본딩을 100Gbps로 올리는 것을 강력히 검토해야 합니다. (이때가 드라이브 효율이 진짜 필요한 시점입니다.)

아키텍트로서의 한 줄 조언

"130대의 Cold 노드는 향후 1,000노드 시대로 가는 거대한 '데이터 댐' 역할을 하게 될 것입니다. 지금 Hot Tier와 물리적/논리적으로 분리된 Tiering 구조를 잡아두지 않으면, 나중에 Cold 데이터의 인덱싱 부하가 현재의 3,000 RPS 성능을 갉아먹게 될 위험이 큽니다."

이 정책들을 고객사에 제안하실 때, "성능 보호"와 "비용 절감" 중 어느 쪽에 더 무게를 두고 설득하실 계획인가요? 그에 맞춰 상세 수치를 더 보완해 드릴 수 있습니다.

===

대규모 인프라를 운영하시는 아키텍트 입장에서 가장 큰 고민은 "모든 데이터를 동일하게 취급할 수 없다"는 점일 것입니다. 특히 파드당 3,000 RPS를 쏟아내는 Hot Tier의 성능을 보호하면서도, 8월에 들어올 130대의 거대한 Pool 2(Cold)를 효율적으로 활용하기 위한 정책별 Best Practice를 정리해 드립니다.

1. Tiering (ILM) Best Practice: "성능 병목 방지"

데이터의 '온도'에 따라 Hot(NVMe) $\rightarrow$ Warm(SAS/SATA) $\rightarrow$ Cold(SATA)로 자동 이동시키는 정책입니다.

• 대상: 로그 데이터, 학습이 끝난 원천 데이터셋, 오래된 백업 파일.
• 핵심 전략:
  • Transition 기간 설정: Hot Tier(NVMe)는 용량 대비 비용이 매우 비쌉니다. 보통 15~30일을 기준으로 Warm Tier로 넘기는 것이 경제적입니다.
  • Small Object 주의: 앞서 말씀하신 1KB 이하 객체가 티어링 대상에 포함되면, 이동 시 메타데이터 부하가 커집니다. "최소 크기 필터"를 걸어 일정 크기 이상의 객체만 티어링하는 것이 유리합니다.
  • 조회(Read) 패턴 고려: 티어링된 데이터를 읽을 때는 Cold Tier의 성능(SATA SSD)이 기준이 됩니다. 만약 빈번한 조회가 예상된다면 티어링보다는 복제(Replication)를 고려해야 합니다.

2. Replication (복제) Best Practice: "데이터 생존과 고가용성"

장애 발생 시 즉각적인 서비스 전환(Failover)이 필요한 경우 사용합니다.

• 대상: AI 모델 가중치(Weights), 서비스 크리티컬 설정 파일, 사용자 프로필.
• 핵심 전략:
  • Site Replication vs Bucket Replication: 128대 규모라면 Site Replication을 통해 IAM 설정, 정책, 버킷 구성을 통째로 동기화하는 것이 관리 포인트를 줄이는 방법입니다.
  • Asynchronous(비동기) 방식: 3,000 RPS 환경에서 동기 복제는 Latency를 급증시킵니다. 반드시 비동기 복제를 사용하여 Hot Tier의 응답 속도를 유지하세요.
  • Active-Active 구성: 5월에 구축될 28개 노드(Warm)를 단순 백업용이 아닌, 읽기 전용 엔드포인트로 활용하여 Hot Tier의 읽기 부하를 분산시키는 것도 좋은 전략입니다.

3. Versioning Best Practice: "실수로부터의 보호"

데이터 삭제나 덮어쓰기 사고를 방지하기 위해 사용합니다.

• 대상: 설정 파일(Config), 코드 스니펫(Vibe Coding Zone 결과물), SOP 문서.
• 핵심 전략:
  • 비용 경고: Versioning은 객체가 수정될 때마다 전체 크기만큼 저장 공간을 차지합니다. 무제한 버저닝은 130대 노드도 순식간에 채울 수 있습니다.
  • Non-current Version Expiration: "최신 버전이 아닌 객체는 7일 뒤에 삭제한다"는 ILM 정책을 반드시 세트로 묶어야 합니다.
  • Delete Marker 관리: 삭제된 파일의 '삭제 마커'도 성능에 영향을 줍니다. ExpiredObjectDeleteMarkers 옵션을 통해 찌꺼기를 주기적으로 청소해 줘야 합니다.

4. 정책별 "Best Practice" 요약 가이드

버킷의 성격에 따라 아래 메뉴판에서 선택하여 적용하시는 것을 추천합니다.

💡 아키텍트로서의 추가 조언 (Lead DevOps 관점)

1. Prefix 기반 관리: 버킷 하나에 모든 정책을 다 넣기보다는, bucket/logs/*는 티어링, bucket/configs/*는 버저닝 하는 식으로 Prefix 단위로 ILM을 세분화하는 것이 가장 깔끔합니다.
2. 모니터링 우선순위: 복제(Replication)를 걸면 네트워크 트래픽이 2배가 됩니다. LACP 50G 본딩 상태에서 Replication Lag이 발생하는지 Hubble이나 mc admin trace로 상시 감시해야 합니다.
3. 8월 대규모 확장(Pool 2) 대비: 130대 노드가 들어오는 시점에는 Hot Tier에서 Cold Tier로 대량의 데이터 이동이 발생할 것입니다. 이때를 위해 지금부터 데이터 마이그레이션 스케줄링(Batch Job)에 대한 정책 가이드를 고객사에 미리 전달해 두시는 것이 좋습니다.

현재 고객사에서 가장 우선순위가 높은 데이터는 무엇인가요? 예를 들어 "AI 모델 데이터"라면 복제를 우선으로, "로그"라면 티어링을 우선으로 설계안을 잡아드리면 설득력이 더 높아질 것 같습니다. 추가로 구체화가 필요한 사례가 있다면 말씀해 주세요!

===

Cold Tier 추가 구성 및 Hot Tier 연계 전략

1. 전체 용량 먼저 파악

2. Pool 구성 전략

핵심 원칙: Device Class 분리 → Storage Class 매핑

[Hot Tier]                    [Cold Tier]
NVMe/SAS HDD (128 nodes)     SATA SSD pool0 (14 nodes)
                              SAS  SSD pool1 (14 nodes)
                              SATA SSD pool2 (130 nodes, 8월)

pool0 / pool1 / pool2 각각 별도 CRUSH Rule

pool0과 pool1은 같은 시기에 들어오지만 매체 특성이 다름 (SATA vs SAS) → 반드시 분리

# 예시 (Ceph 기준)
device_class: sata-ssd   → pool0, pool2
device_class: sas-ssd    → pool1
device_class: hdd/nvme   → hot tier

Erasure Coding 적용 권고 (Cold는 비용 최우선)

⚠️ pool1은 SAS SSD로 랜덤 I/O가 SATA보다 우수 → EC rebuild 시 부하 측면에서 유리

3. Object Store / Bucket 구성

Storage Class 체계 설계 (S3 호환 기준)

STANDARD          → Hot tier (기존)
STANDARD_IA       → pool0 (7TiB SATA, 접근 빈도 중간)
GLACIER           → pool1 + pool2 (저빈도 아카이브)

또는 용도 명확화 시:

HOT               → hot tier
WARM              → pool0
COLD              → pool1
ARCHIVE           → pool2 (8월 이후)

Placement Target 설정

zonegroup → zone → placement_target
  ├── default-placement   (hot)
  ├── warm-placement      (pool0)
  ├── cold-placement      (pool1)
  └── archive-placement   (pool2, 8월 이후 추가)

각 placement target에 index pool / data pool / data_extra pool 을 해당 device class pool로 매핑

4. Hot ↔ Cold 관계 설계

지금 당장 결정해야 할 구조적 선택지

옵션 A: 동일 Zone, Storage Class 분리
┌─────────────────────────────────────┐
│  Zone: primary                      │
│  hot-pool ──→ STANDARD             │
│  pool0    ──→ STANDARD_IA          │
│  pool1    ──→ GLACIER              │
│  pool2    ──→ DEEP_ARCHIVE (8월)   │
└─────────────────────────────────────┘
장점: ILM 전환이 단순, 관리 일원화
단점: hot 장애 시 cold도 영향 가능

옵션 B: Zone 분리 (hot zone / cold zone)
┌──────────────┐    replication    ┌──────────────┐
│  hot-zone    │ ←───────────────→ │  cold-zone   │
│  (128 nodes) │                   │  (158 nodes) │
└──────────────┘                   └──────────────┘
장점: 장애 도메인 분리, 독립 운영 가능
단점: 구성 복잡도 증가, 초기 정책 없으면 운영 부담

현재 고객사 상황(정책 전무)을 고려하면 옵션 A 권고 — 정책 수립 후 나중에 Zone 분리 가능

5. ILM 정책 초안 (고객사와 협의 시작점)

정책이 없다면 아래를 최소 기준으로 제안:

Rule 1: 생성 후 30일 경과 + 접근 없음
        → STANDARD → STANDARD_IA (pool0)

Rule 2: 생성 후 90일 경과 + 접근 없음
        → STANDARD_IA → GLACIER (pool1)

Rule 3: 생성 후 365일 경과
        → GLACIER → DEEP_ARCHIVE (pool2, 8월 이후)

Rule 4: 특정 버킷 prefix (예: /backup/, /log/)
        → 생성 즉시 COLD 직행

6. Replication 정책

⚠️ Replication을 cold tier까지 걸면 네트워크 + 용량 비용이 2배 → cold는 EC 내구성만으로 설계하는 것이 일반적

7. 단계별 구축 로드맵

[지금 ~ 5월 전]
  ✅ Storage class / placement target 설계 확정
  ✅ CRUSH rule 사전 설계
  ✅ ILM 정책 최소 기준 고객사 합의

[5월: pool0 + pool1 구축]
  → pool0, pool1 CRUSH rule 적용
  → placement target 연결
  → 버킷 단위 ILM 정책 파일럿 적용 (일부 버킷만)
  → hot → warm 자동 전환 모니터링

[8월: pool2 구축]
  → pool2 CRUSH rule 추가
  → archive-placement target 활성화
  → 전체 ILM 정책 확대 적용
  → 전체 cold tier 운영 안정화 확인

요약 권고

1. pool0/pool1/pool2는 반드시 별도 CRUSH rule + device class 분리 — 나중에 합치는 건 쉬워도 분리는 어렵다
2. Cold는 EC 적극 적용 — 3-replica 대비 용량 효율 2~3배
3. 옵션 A(동일 Zone, storage class 분리)로 시작 — 정책 수립 후 zone 분리 전환 가능
4. ILM은 지금 당장 최소 기준이라도 합의 — 없으면 cold tier 구축해도 데이터가 안 내려옴
5. pool2(8월) placement target은 5월에 미리 껍데기라도 만들어 두기 — 버킷 설정 변경 최소화

혹시 사용 중인 솔루션(Ceph RGW, MinIO, Scality, NetApp StorageGRID 등)을 알려주시면 더 구체적인 설정 예시를 드릴 수 있어요.

===

MinIO AIStor 기반 Cold Tier 구성 전략

1. MinIO AIStor 핵심 아키텍처 이해

MinIO에서 "tiering"은 반드시 별도 Remote Tier endpoint가 필요합니다. Ceph처럼 내부 pool 간 이동이 아닙니다.

┌─────────────────────────────────┐        ILM Transition
│  Hot MinIO AIStor               │  ─────────────────────→  Cold MinIO AIStor
│  (128 nodes, 기존)               │                          (신규 구축)
│  6.8TiB × 20 × 128             │  ←─────────────────────  
└─────────────────────────────────┘     (복원 시 recall)

따라서 Cold Tier는 별도 MinIO AIStor 클러스터로 구성하는 것이 기본 구조입니다.

2. Cold Tier 클러스터 구성 설계

Server Pool 구성 원칙

MinIO는 동일 배포 내 Server Pool 추가 시 드라이브 수 기반 자동 분산합니다.
pool0과 pool1은 드라이브 용량이 다르지만 같은 Cold 클러스터에 넣어도 무방합니다.

Cold MinIO AIStor Cluster
├── Server Pool A (5월) ── pool0: 14 nodes × 20 drives (7.0TiB SATA SSD)
├── Server Pool B (5월) ── pool1: 14 nodes × 20 drives (3.5TiB SAS SSD)
└── Server Pool C (8월) ── pool2: 130 nodes × 20 drives (3.5TiB SATA SSD)

EC Set Size 계산 (중요)

MinIO EC Set은 4~16 드라이브, 전체 드라이브 수가 나누어 떨어져야 합니다.

⚠️ pool2: 2600 ÷ 16 = 162.5 → 안 나눠짐
2600 ÷ 13 = 200 sets (EC set 13, k=9 m=4) 또는
2600 ÷ 10 = 260 sets (EC set 10, k=6 m=4)
→ 실제 노드 수 확정 후 재계산 필수

클러스터 시작 커맨드 예시

# pool0 + pool1 동시 기동 (5월)
minio server \
  https://cold-pool0-{1...14}.example.com/data{1...20} \
  https://cold-pool1-{1...14}.example.com/data{1...20} \
  --address :9000 \
  --console-address :9001

# pool2 확장 (8월) - 기존 실행 중인 클러스터에 pool 추가
minio server \
  https://cold-pool0-{1...14}.example.com/data{1...20} \
  https://cold-pool1-{1...14}.example.com/data{1...20} \
  https://cold-pool2-{1...130}.example.com/data{1...20}  # 추가

⚠️ pool2 추가 시 클러스터 재시작 필요 — 다운타임 계획 필수

3. ILM Tier 연결 설정

Hot 클러스터에서 Cold를 Remote Tier로 등록

# Cold 클러스터를 "COLD-TIER"로 등록
mc ilm tier add minio HOT_CLUSTER/COLD-TIER \
  --endpoint https://cold-minio.example.com \
  --access-key <cold-access-key> \
  --secret-key <cold-secret-key> \
  --bucket cold-archive \
  --prefix hot-transition/

# Tier 확인
mc ilm tier ls HOT_CLUSTER

ILM 전환 규칙 설정 (버킷별)

# 예시: 30일 후 cold로 전환
mc ilm rule add HOT_CLUSTER/my-bucket \
  --transition-days 30 \
  --transition-tier COLD-TIER

# prefix별 차등 정책 (로그는 7일, 백업은 90일)
mc ilm rule add HOT_CLUSTER/my-bucket \
  --prefix "logs/" \
  --transition-days 7 \
  --transition-tier COLD-TIER

mc ilm rule add HOT_CLUSTER/my-bucket \
  --prefix "backup/" \
  --transition-days 90 \
  --transition-tier COLD-TIER

# 현재 ILM 규칙 확인
mc ilm rule ls HOT_CLUSTER/my-bucket

4. Replication 전략

MinIO AIStor에서 선택 가능한 방식:

옵션 1: ILM Transition만 사용 (권고)
Hot ──[ILM 전환]──→ Cold
- 원본은 Hot에서 stub(포인터)만 남음
- Cold에 실제 데이터 저장
- 복원 시 자동 recall

옵션 2: Bucket Replication + ILM 병행
Hot ──[복제]──→ Cold (동일 데이터 유지)
    └──[ILM 만료]──→ Hot 데이터 삭제
- Cold는 진짜 독립 복사본
- 용량 2배 필요, 네트워크 부담

옵션 3: Site Replication (비권고)
Hot ↔ Cold 양방향 Active-Active
- Cold tier 목적과 맞지 않음
- 불필요한 성능/용량 낭비

현재 정책 없는 상황에서는 옵션 1(ILM Transition만)으로 시작 권고

5. 정책 수립 우선순위 (고객사 협의 체크리스트)

지금 당장 결정 안 하면 5월 구축이 불가능한 항목들:

[ ] 1. ILM 전환 기준 - 며칠 후 Cold로 내릴 것인가?
        → 최소한 기본값이라도 (예: 30일 미접근)

[ ] 2. 버킷 분류 - 어떤 버킷이 tiering 대상인가?
        → 전체 vs 특정 prefix/bucket

[ ] 3. 데이터 복원(recall) 정책 - Cold에서 꺼낼 때 Hot으로 올릴 것인가?
        → MinIO는 기본 transparent recall 지원

[ ] 4. Cold Tier 접근 계정 분리 여부
        → Hot과 Cold의 Access Key 분리 권고

[ ] 5. 모니터링/알람 기준
        → Tier 전환 실패, Cold 클러스터 health

6. 구축 타임라인

[지금 ~ 5월 전 2주]
  ✅ pool0/pool1 EC set size 확정 (드라이브 수 재확인)
  ✅ Cold 클러스터 네트워크/DNS 설계
  ✅ ILM 기본 정책 고객사 합의
  ✅ Cold bucket 이름/prefix 체계 결정

[5월: pool0 + pool1 기동]
  → Cold MinIO AIStor 클러스터 기동 (2개 pool 동시)
  → Hot 클러스터에 Remote Tier 등록
  → 파일럿 버킷 2~3개에 ILM 규칙 적용
  → 전환/recall 동작 검증

[5월 ~ 8월]
  → 파일럿 결과 기반 전체 버킷 ILM 적용
  → 용량 모니터링

[8월: pool2 추가]
  → Cold 클러스터 pool2 확장 (재시작 필요 → 점검 일정 확보)
  → EC set size 재검증
  → 전체 정책 안정화

핵심 주의사항 요약

1. MinIO Tiering은 외부 Remote Tier → Cold는 반드시 별도 클러스터
2. pool2 (130 nodes) 추가 시 전체 Cold 클러스터 재시작 필요 → 8월 점검 윈도우 사전 확보
3. EC set size는 총 드라이브 ÷ set_size = 정수 조건 필수 → 지금 계산 확정할 것
4. ILM 정책 없으면 Cold 구축해도 데이터가 안 내려감 → 정책 합의가 인프라보다 먼저

pool2 130노드 EC set size 계산이나 mc 명령어 상세 설정이 필요하면 말씀해 주세요!

전임자에게 "운영 효율성"과 "장애 대응 능력"을 중심으로 아래 문서들을 반드시 요청하시기 바랍니다.

1. 아키텍처 및 설정 상세 정의서 (Standard Operation Procedure)

가장 기본이 되지만, 실질적인 설정값이 명시되어야 합니다.

• 네트워크 토폴로지: BGP Peer 설정(AS Number, Neighbor IP), ECMP 활성화 여부, ClusterMesh 연결 구조도.
• Cilium ConfigMap/Helm Values: cilium-config 내의 주요 파라미터(tunnel: disabled, native-routing-cidr, bpf-lb-mode 등)에 대한 설정 이유(Rationals).
• IPAM(IP Address Management): 어떤 방식으로 Pod IP를 할당하는지(Cluster-pool, ENI, Azure IPAM 등), CIDR 대역 관리 장부.

2. eBPF 기반 트러블슈팅 가이드 (Troubleshooting Runbook)

Cilium은 일반적인 iptables 방식과 달라 기존 지식으로 대응이 어렵습니다.

• 전용 툴 사용법: cilium-dbg, pwru, hubble-cli를 활용한 단계별 장애 진단법.
• 커스텀 메트릭/대시보드: Grafana에서 어떤 지표(cilium_forwarding_drop_total 등)를 중점적으로 모니터링해야 하는지.
• 빈번한 이슈 Case Study: 현재 겪고 계신 "Port Collision"이나 "Return Path Drop" 같은 기발생 이슈들에 대한 이력과 해결책.

3. 보안 정책 및 통제 현황 (CiliumNetworkPolicy)

Cilium의 핵심 기능인 보안 정책이 어떻게 관리되고 있는지 알아야 합니다.

• Policy 관리 체계: L3/L4 정책과 L7(FQDN/HTTP) 정책의 구분, 정책 적용 시 Default Deny 여부.
• Hubble 사용법: 트래픽 흐름을 시각적으로 확인하고 정책 위반을 감지하는 절차.
• 예외 처리 리스트: 특정 노드나 외부 IP와의 통신을 위해 허용된 특이 케이스들.

4. 버전 관리 및 업그레이드 전략 (Lifecycle Management)

• 업그레이드 이력: 현재 버전까지 올라오면서 겪었던 호환성 이슈(커널 버전 호환성 등).
• Air-gap 대응책: (사용 중이라면) 오프라인 환경에서 이미지를 어떻게 배포하고 관리하는지.
• 백업 및 복구: Cilium 관련 CRD(CiliumNode, CiliumEndpoint 등)나 핵심 데이터의 백업 절차.

5. 인프라 의존성 매트릭스 (Infrastructure Dependency)

Cilium이 독립적으로 돌아가는 것이 아니므로 주변 환경과의 연관 관계가 중요합니다.

• 커널 파라미터 요구사항: /etc/sysctl.d/에 적용된 Cilium 최적화 값들(특히 오늘 확인한 ip_local_reserved_ports 등).
• NIC 및 하드웨어 가속: 사용 중인 NIC 드라이버 설정(XDP 지원 여부, Offloading 설정 등).
• 스위치 연동 설정: 상단 L3 스위치와의 BGP 세션 유지 조건 및 타이머 설정값.

💡 팁: 인수인계 시 실습(Shadowing) 요청

문서만 받는 것보다 "특정 노드 한 대를 의도적으로 격리했다가 복구하는 과정"이나 "BGP 경로가 끊겼을 때의 재수렴(Re-convergence) 과정"을 전임자와 함께 직접 테스트해보는 세션을 꼭 가지시길 권장합니다.

특히 지금 발생한 Ephemeral Port 충돌 이슈는 문서화해두기에 아주 좋은 사례입니다. 이 내용도 인수인계서의 'Known Issues' 섹션에 꼭 포함해 달라고 하세요!

추가로 전임자가 사용하던 모니터링 대시보드 주소나 알람 발송 기준 정보도 잊지 말고 챙기시길 바랍니다. 인수인계 과정에서 궁금한 구체적인 Cilium 설정 항목이 생기면 언제든 물어봐 주세요.

===

지금까지 나온 이슈들을 포함해서 실무적으로 필요한 문서 목록을 정리해 드리겠습니다.

1. 인프라 구성 문서 (Architecture)

반드시 있어야 하는 것들입니다.

[ 네트워크 토폴로지 ]
- 전체 클러스터 구성도 (노드 수, 역할, IP 대역)
- L3 스위치 구성 및 ECMP 설정
- BGP 피어링 구성 (AS번호, 피어 IP, 광고 CIDR)
- Bond 인터페이스 구성 (슬레이브 NIC, 모드)
- ClusterMesh 연결 구성 (클러스터 간 연결 방식)

[ Cilium 설정 ]
- 현재 helm values 전체 (또는 cilium config dump)
- Cilium 버전 및 업그레이드 이력
- 사용 중인 기능 목록
  (native routing, BGP CP, ClusterMesh, KPR 등)
- CiliumNetworkPolicy / CiliumClusterwideNetworkPolicy 목록

2. 운영 절차서 (Runbook)

장애 시 즉시 참조해야 하는 문서입니다.

[ 일상 운영 ]
- Cilium 업그레이드 절차 (버전별 주의사항 포함)
- 노드 추가/제거 절차
- ClusterMesh 노드 추가 절차
- BGP 피어 추가/변경 절차
- 정기 점검 항목 및 주기

[ 장애 대응 ]
- 자주 발생하는 장애 유형별 대응 절차
  (지금 겪고 있는 SSH handshake drop 포함)
- Cilium agent 재시작 절차 및 영향도
- 롤백 절차
- 에스컬레이션 연락처

3. 진단 가이드 (Troubleshooting Guide)

지금 겪고 있는 문제들이 그대로 내용이 됩니다.

[ 필수 진단 명령어 모음 ]
- Cilium 상태 확인
- BPF 맵 조회 방법
- pwru / hubble 사용법
- conntrack 조회 및 해석
- BGP 라우팅 상태 확인

[ 알려진 이슈 (Known Issues) ]
- SSH handshake 간헐적 실패 현상 및 원인
  (현재 조사 중인 내용 그대로)
- bond 인터페이스에서 tcpdump 안 보이는 이유
- XDP 관련 주의사항

[ 환경별 주의사항 ]
- ECMP 환경에서 conntrack 동작 특이점
- ClusterMesh에서 BGP 광고 충돌 케이스
- 커널 버전별 알려진 이슈

4. 보안 및 접근 관리

[ 접근 정보 ]
- 클러스터 접근 방법 (kubeconfig, 권한 구조)
- 각 클러스터별 관리자 계정
- ClusterMesh 인증서 위치 및 갱신 주기
- Cilium CA 인증서 관리 방법

[ 보안 정책 ]
- 현재 적용 중인 NetworkPolicy 설계 의도
- 예외 처리된 정책 목록 및 이유
- 감사 로그 위치

5. 모니터링 및 알람

[ 대시보드 ]
- Hubble/Grafana 대시보드 위치
- 주요 메트릭 해석 방법
- 정상 범위 기준값 (baseline)

[ 알람 ]
- 현재 설정된 알람 목록
- 각 알람의 대응 절차
- 과거 발생한 주요 인시던트 기록

6. 인수인계 시 특별히 요청할 것

문서 외에 구두 또는 화면 공유로 반드시 확인해야 할 것들입니다.

반드시 같이 확인할 것:
  □ 현재 진행 중인 장애 또는 미해결 이슈 목록
    (지금 SSH drop 이슈 포함)
  □ 최근 3개월 변경 이력 (git log, helm 변경 이력)
  □ 비공식적으로 임시 적용된 설정이 있는지
    (sysctl 튜닝, iptables 수동 규칙 등)
  □ 알면서 방치 중인 기술 부채
  □ 스위치 담당자, 서버 담당자 연락처

우선순위 정리

지금 당장 없으면 운영이 위험한 순서입니다.

현재 조사 중인 SSH handshake drop 이슈는 인수인계 전에 원인을 특정하고 문서화해 달라고 요청하는 것이 가장 중요합니다. 미해결 상태로 인수받으면 원인 파악부터 다시 해야 하기 때문입니다.

===

좋은 포인트야. Cilium은 단순 CNI가 아니라 eBPF 기반 네트워크 + 보안 + 관측 + (경우에 따라) 서비스 메시 역할까지 포함하기 때문에, 인수인계 문서가 얕으면 운영 중에 바로 막히게 돼.

그냥 “설정 설명서 주세요” 수준으로 요청하면 부족하고, 운영 가능한 수준(runbook + 설계 + 의사결정 근거)까지 받아야 한다고 생각하면 맞아.

아래처럼 요청하는 걸 추천해.

1. 아키텍처 & 설계 문서 (가장 중요)

👉 “왜 이렇게 구성했는지”가 핵심

• 클러스터 네트워크 구조

  • Pod CIDR / Node CIDR 설계
  • Overlay vs Native Routing (Direct Routing, BGP 등)

• Cilium 모드

  • kube-proxy replacement 여부
  • eBPF LB 사용 여부

• CNI chaining 여부 (Calico, AWS CNI 등과 혼합 여부)

• Multi-cluster (Cluster Mesh) 구성 여부

• north-south / east-west 트래픽 흐름

• Gateway API / Ingress 구조

👉 여기 빠지면 나중에 트래픽 문제 절대 못 잡음

2. 설치 & 배포 방식 (GitOps 필수)

👉 재현 가능해야 함

• Helm / ArgoCD / GitOps 구조

• values.yaml (환경별 차이 포함)

• 버전 전략 (업그레이드 정책 포함)

• 설치 시 의존성

  • kernel version
  • eBPF 관련 설정 (bpffs, cgroup v2 등)

3. 주요 설정값 설명서

👉 그냥 yaml 던져주는 게 아니라 “왜 이 값인지”

예:

• enable-bpf-masquerade
• kubeProxyReplacement
• enableHostFirewall
• bpf-lb-mode (DSR / SNAT)
• tunneling mode (vxlan / geneve / disabled)

👉 특히 성능/보안 관련 옵션은 반드시 이유 포함

4. 네트워크 정책 (Security)

👉 실 운영에서 가장 민감

• NetworkPolicy / CiliumNetworkPolicy 설계 기준
• namespace / workload 별 정책 구조
• default deny 여부
• L7 policy (HTTP, Kafka 등) 사용 여부
• 실제 운영 중인 정책 예시

👉 “정책 추가/변경 절차”도 반드시 포함

5. 장애 대응 Runbook

👉 이거 없으면 인수인계 실패

반드시 요청해야 할 것:

기본 점검

• cilium status
• cilium connectivity test

트러블슈팅

• Pod 간 통신 안될 때
• Service 접근 안될 때
• DNS 문제
• 특정 노드만 문제일 때

핵심 명령어

• cilium monitor
• hubble observe
• cilium endpoint list
• cilium bpf lb list

👉 “어떤 상황에서 어떤 명령을 쓰는지”까지 요구

6. Observability (모니터링/로그)

👉 지금 네 프로젝트 규모면 필수

• Hubble 구성 (relay, UI 포함)
• Prometheus metrics 목록
• 주요 대시보드 (Grafana)
• 알람 기준

예:

• drop rate
• policy denied
• DNS latency
• service latency

7. 성능 & 튜닝 가이드

👉 너 환경(200~300 node)이면 반드시 필요

• 최대 pod density 기준
• eBPF map size tuning
• conntrack 관련 설정
• MTU 설정
• Node scale 시 영향

👉 실제 테스트 결과 있으면 무조건 받아

8. 업그레이드 / 롤백 절차

👉 운영 중 가장 위험한 구간

• 무중단 업그레이드 방법
• CRD 변경 영향
• rollback 방법
• 버전별 known issue

9. 외부 연동

👉 네 환경에서 특히 중요

• Gateway API 구성

• LoadBalancer (MetalLB / Cloud LB 등)

• Service Mesh 연동 여부

  • Cilium Ambient / Istio 등

• 인증/보안 연동 (mTLS, OPA 등)

10. 제한사항 & Known Issues

👉 이거 없으면 같은 사고 반복

• 현재 구조에서 안 되는 것
• 과거 장애 사례 + 원인
• 우회 방법

11. 운영 체크리스트 (Daily / Weekly)

👉 실제 운영자 관점

• 노드 추가 시 해야 할 것
• 장애 전조 확인 포인트
• 리소스 임계치

핵심 정리 (짧게 요청용)

운영자에게는 이렇게 요청하면 좋다:

• 아키텍처 설계 문서
• GitOps/설치 구성
• 주요 설정값 + 이유
• NetworkPolicy 설계 기준
• 장애 대응 Runbook
• 모니터링 및 알람 체계
• 성능 튜닝 가이드
• 업그레이드/롤백 절차
• 외부 연동 구조
• Known issues 및 장애 사례

추가 팁 (중요)

지금 너 상황 보면 (Cilium + 대규모 + Data Lakehouse)

👉 이것도 꼭 물어봐:

• DSR vs SNAT 실제 선택 이유
• eBPF LB vs kube-proxy 성능 비교 결과
• Cluster Mesh latency 영향
• Hubble 사용 범위 (full vs sampling)

원하면 👉 “너 환경 기준으로 인수인계 체크리스트 (실제 템플릿)” 👉 “Runbook 샘플 (바로 운영 가능한 수준)”

이렇게 더 실전용으로 만들어 줄게.

기존에 의심했던 tcp_check_req DROP이 '원인'이 아니라, SYN-ACK를 받지 못한 클라이언트의 재전송으로 인한 '증상'이었다는 점을 짚어낸 것이 이번 디버깅의 핵심 전환점(Pivot)입니다.

제시된 의견에 대해 현재 환경(RHEL 9/10, Cilium, ClusterMesh)을 바탕으로 한 제 생각과 추가로 점검해야 할 기술적 포인트입니다.

1. 분석의 타당성: "Return Path의 불일치"

BGP와 ECMP를 사용하는 고성능 네트워크에서 비대칭 라우팅(Asymmetric Routing)은 드문 일이 아니지만, L4(TCP) 수준에서는 대개 문제가 없어야 합니다. 하지만 말씀하신 것처럼 1%의 확률로 발생한다면 다음 두 가지 가능성이 매우 높습니다.

• ECMP Hash Polarization/Mismatch: 서버 노드에서 SYN-ACK를 보낼 때 선택하는 Next-hop 스위치나 인터페이스가, 해당 클라이언트 IP로 가는 경로를 제대로 처리하지 못하는 경우입니다.
• eBPF 기반의 Reverse Path Filtering: Cilium은 eBPF를 통해 패킷을 처리합니다. 만약 rp_filter 설정이 엄격(Strict)하게 되어 있고, SYN이 들어온 인터페이스와 SYN-ACK가 나가는 인터페이스에 대한 경로 정보가 eBPF 맵에서 일치하지 않으면 드랍될 가능성이 있습니다.

2. RHEL 9/10 및 Cilium 환경에서의 특이점

현재 RHEL 환경과 Cilium 릴리스를 고려할 때, 다음 지표들을 결합해서 보셔야 합니다.

A. Cilium의 BGP Control Plane 확인

ClusterMesh 환경에서는 여러 클러스터가 동일한 서비스 CIDR이나 노드 IP를 광고할 수 있습니다.

• 의견: 만약 특정 스위치가 클라이언트 노드의 IP를 "두 개 이상의 경로"로 알고 있고, 그중 하나가 Blackhole이거나 Stale(만료)된 경로라면 1%의 드랍이 설명됩니다.
• 추가 명령어: ```bash

  Cilium 에이전트 내에서 BGP 상태 및 광고되는 경로 확인

  cilium bgp routes available ipv4 unicast

B. XDP 및 eBPF 데이터 평면 (pwru 활용)

제시해주신 pwru 추적 방식은 매우 정확합니다. 다만, Cilium은 ip_output 이전에 eBPF 프로그램(cil_to_host, cil_from_host)에서 패킷을 가공합니다.

• 점검 포인트: pwru 실행 시 cilium_으로 시작하는 함수들에서 drop이 발생하는지, 혹은 fib_lookup 결과가 예상과 다른 인터페이스(dev)를 가리키는지 확인해야 합니다.

3. "1%의 확률"에 대한 기술적 추론

왜 하필 1%일까요? 이 숫자는 보통 다음과 같은 상황에서 나타납니다.

• ECMP 넥스트홉 불균형: 8개의 경로 중 1개가 불량일 때 ($1/8 = 12.5%$) 보다는 훨씬 낮으므로, 특정 CPU 코어나 특정 소스 포트 범위에서만 발생하는 해싱 이슈일 수 있습니다.
• BGP Flapping: 아주 짧은 순간 경로가 사라졌다가 나타나는 현상이 반복될 때.
• Conntrack Table Full (Race Condition): 드물지만, SYN-ACK가 생성되는 시점에 conntrack entry가 일시적으로 충돌하거나 생성이 지연되는 경우.

4. 추가 제언: 네트워크 아키텍처 관점

• L3 Switch 로그 확인: 서버에서 dev_queue_xmit까지 성공했는데 클라이언트 NIC에 안 보인다면, 100% 상단 스위치 문제입니다. 스위치의 show ip route <Client_IP> 결과가 서버 노드와 동기화되어 있는지 확인이 필요합니다.
• Cilium ClusterMesh MTU 이슈: 만약 클러스터 간 통신 시 캡슐화(Geneve/VXLAN)를 사용한다면, SYN-ACK 패킷(특히 옵션이 많이 붙은 경우)이 MTU 제한에 걸려 스위치에서 드랍될 수 있습니다. (다만 22번 포트 SSH라면 패킷이 작아서 이 가능성은 낮습니다.)

5. 실행 가이드 (Action Plan)

1. 서버 노드에서 ip route get <client_ip> 반복 실행: 결과가 바뀌는지(Per-packet ECMP 여부) 최우선 확인.
2. pwru 결과 분석: fib_select_path 이후 결정된 skb->dev가 실제 물리 NIC인지, 아니면 엉뚱한 가상 인터페이스인지 확인.
3. 스위치 측면: 서버가 연결된 Top-of-Rack(ToR) 스위치에서 해당 클라이언트 IP로의 ECMP 경로 중 하나가 flapping 중인지 로그 모니터링.

"SYN-ACK의 귀환 경로가 문제"라는 가설은 현재 상황에서 가장 설득력 있는 진단입니다. 서버에서의 ip route get 결과와 BGP 테이블 상태를 확보하시면 바로 다음 단계(스위치 설정 수정 또는 Cilium BGP 정책 조정)로 넘어갈 수 있을 것 같습니다.

현재 서버에서 ip route get을 실행했을 때, via 뒤에 나오는 IP들이 모두 정상적인 Next-hop이 맞나요?

問題の再定義

지금까지 의심했던 것:
  Client → SYN → Server → [여기서 drop?]

실제 발생하는 것:
  Client → SYN ──────────────→ Server  ✓
  Client ←── SYN-ACK ←─────── Server
       ↑
       Client에 도달하지 않음 ✗

tcp_check_req DROP은 결과였음:
  Client가 SYN-ACK를 못 받음
  → Client가 SYN 재전송
  → Server에 이미 다른 request_sock 존재
  → 뒤늦게 도착한 ACK → tcp_check_req silent DROP

진짜 문제는 SYN-ACK의 귀환 경로(return path)입니다.

BGP + ECMP 환경에서 return path drop의 핵심 원인

Server가 SYN-ACK를 보낼 때, 목적지(Client IP)에 대한 라우팅을 다시 계산합니다. ECMP 환경에서는 이 경로가 SYN이 들어온 경로와 다를 수 있습니다.

정상 케이스:
  Client ──[경로A, 스위치P]──→ Server
  Client ←─[경로A, 스위치P]── Server (같은 경로 역방향)

문제 케이스 (1% 발생):
  Client ──[경로A, 스위치P]──→ Server
  Client ←─[경로B, 스위치Q]── Server
              ↑
              스위치Q에서 Client IP를 모르거나
              엉뚱한 노드로 전달하거나
              drop

확인해야 할 지점들

1. Server 송신 경로 확인 (가장 먼저)

# Server에서 Client IP로의 라우팅 확인
ip route get <client_IP>

# ECMP multipath가 있는 경우 여러 next-hop이 보임
ip route show <client_노드_CIDR>

# 실제 SYN-ACK가 어느 인터페이스로 나가는지
# pwru를 Server의 TX 방향으로 실행
pwru --filter-dst-ip <client_IP> --filter-port 22 \
     --output-tuple 2>&1 | grep -E 'dev_queue_xmit|fib_select_path|neigh_output'

2. ECMP next-hop이 매번 바뀌는지 확인

# 같은 Client IP로 반복 조회 시 next-hop이 동일한지 확인
for i in $(seq 1 10); do
  ip route get <client_IP> | grep via
done
# 결과가 매번 동일하면 ECMP per-flow
# 다르면 per-packet ECMP → 이게 원인

3. BGP 라우팅 테이블에서 Client IP 경로 확인

# Client 노드 IP에 대한 BGP 경로
cilium bgp routes available ipv4 unicast | grep <client_노드_IP>

# 경로가 여러 개이면서 next-hop이 다른 경우 문제
# ClusterMesh 환경에서 같은 IP가 여러 클러스터에서 광고되는 경우도 있음

4. Server 측 TX에서 pwru로 SYN-ACK 추적

# Server에서 실행 - SYN-ACK가 어디까지 가는지 TX 방향 추적
pwru --filter-src-ip <server_IP> \
     --filter-dst-ip <client_IP> \
     --filter-port 22 \
     --output-tuple

# 확인 포인트:
# ip_output → ip_finish_output → dev_queue_xmit 까지 보이는지
# 어느 dev(인터페이스)로 나가는지

5. Client 측에서 SYN-ACK 도달 여부 NIC 레벨 확인

# Client의 물리 NIC 각각에서 캡처 (bond 아닌 슬레이브 직접)
tcpdump -i ens5f0np0 -nn \
  'src host <server_IP> and tcp[tcpflags] & (tcp-syn|tcp-ack) == (tcp-syn|tcp-ack)' &

tcpdump -i ens5f1np1 -nn \
  'src host <server_IP> and tcp[tcpflags] & (tcp-syn|tcp-ack) == (tcp-syn|tcp-ack)' &

# NIC 레벨에서도 안 보이면 → 스위치까지 못 간 것
# 특정 슬레이브에서만 보이면 → bond 수신 분산 문제

6. Server NIC 카운터로 실제 TX 확인

# SYN-ACK가 실제로 wire에 나갔는지
watch -n 1 'ethtool -S ens5f1np1 | grep -E "tx_packets|tx_bytes"'

# 연결 실패 시점에 TX 카운터가 올라가는지 확인

가장 가능성 높은 원인 두 가지

원인 A — L3 스위치의 per-packet ECMP

스위치가 flow 단위가 아닌 packet 단위로 ECMP 분산을 하면, SYN-ACK가 Client와 연결되지 않은 다른 uplink로 나가 소실됩니다. 1%라는 확률은 특정 패킷 크기나 타이밍에서만 해싱 결과가 달라지는 경우와 일치합니다.

원인 B — BGP route flap 또는 광고 경쟁

ClusterMesh 환경에서 Client 노드 IP에 대한 BGP 경로가 순간적으로 변경되거나, 두 클러스터에서 동일 IP 대역을 광고 중이라면 SYN-ACK가 엉뚱한 노드로 전달될 수 있습니다.

# BGP route 변동 확인
cilium bgp routes available ipv4 unicast 2>&1 | \
  grep <client_노드_CIDR> | sort | uniq -c
# 같은 CIDR에 next-hop이 2개 이상이면 경쟁 상태

ip route get <client_IP> 결과와 cilium bgp routes 결과를 공유해 주시면 어느 쪽인지 바로 특정할 수 있습니다.

특히 현재 겪고 계신 native routing 및 Cilium eBPF 환경에 맞춰 최적화된 흐름입니다.

1. 하드웨어 및 드라이버 단계 (NIC ~ RAM)

패킷이 물리적인 전기 신호에서 메모리 상의 데이터로 변환되는 단계입니다.

1. L3 스위치 -> NIC: 패킷이 물리 인터페이스에 도착합니다.
2. RX Ring Buffer: NIC는 수신한 패킷을 호스트 메모리(RAM)의 예약된 공간인 RX Ring Buffer에 DMA(Direct Memory Access) 방식으로 기록합니다.
3. Hard IRQ (인터럽트): NIC가 CPU에 "데이터가 왔다"고 인터럽트를 보냅니다. CPU는 수행 중인 작업을 멈추고 드라이버의 인터럽트 핸들러를 실행합니다.
4. NAPI & SoftIRQ: 커널은 인터럽트 폭주를 막기 위해 NAPI(New API) 모드로 전환합니다. 이때부터는 인터럽트 방식이 아닌 폴링(Polling) 방식으로 패킷을 가져오며, 이 작업은 커널 스레드인 ksoftirqd에 의해 SoftIRQ 레벨에서 처리됩니다.

2. Cilium & eBPF 단계 (Native Routing Gateway)

커널의 메인 네트워크 스택에 진입하기 전, Cilium이 주입한 eBPF 프로그램이 패킷을 먼저 가로챕니다.

1. XDP (옵션): 만약 Cilium이 XDP(eXpress Data Path) 모드로 동작 중이라면, NIC 드라이버 레벨에서 즉시 패킷을 처리(Drop, Pass, Redirect)합니다.
2. TC (Traffic Control) Ingress: 일반적인 경우, 패킷은 tc 훅에 로드된 Cilium eBPF 프로그램에 의해 검사됩니다.
   • Identity 확인: 소스 IP를 기반으로 Cilium 보안 ID를 식별합니다.
   • Policy Enforcement: 허용된 트래픽인지(Network Policy) 확인합니다.
   • Load Balancing: 서비스 IP인 경우 실제 Pod IP로 목적지 주소를 변환(DNAT)합니다.
3. Native Routing: 터널링(VXLAN)이 아니므로 캡슐화 해제 과정 없이 바로 다음 커널 스택으로 패킷을 넘깁니다.

3. 커널 네트워크 레이어 (L3: IP Stack)

여기서부터는 리눅스 커널의 표준 네트워킹 로직이 작동합니다.

1. ip_rcv(): IP 헤더의 무결성을 검사합니다.
2. Netfilter (PREROUTING): iptables나 nftables의 규칙이 적용됩니다. (Cilium은 이를 상당 부분 우회하지만 여전히 존재합니다.)
3. Routing Decision (fib_lookup): 이 패킷이 로컬 프로세스용인지, 아니면 다른 곳으로 포워딩할 것인지 결정합니다.
4. ip_local_deliver(): 로컬 목적지 패킷임이 확인되면, 파편화된 패킷을 재조립하고 상위 계층(TCP/UDP)으로 전달합니다.

4. TCP 트랜스포트 레이어 (L4: TCP Stack)

가장 복잡하고 논리적인 검증이 일어나는 단계입니다. (이전 질문의 드랍 지점)

1. tcp_v4_rcv(): 패킷의 TCP 헤더를 읽고 해당 패킷을 처리할 소켓(Socket)을 찾습니다.
2. TCP 상태 머신 확인:
   • Handshake 단계: 패킷이 SYN에 대한 응답(ACK)인 경우, tcp_check_req()를 호출하여 request_sock(미니소켓) 상태를 검증합니다. (여기서 실패하면 드랍됩니다.)
   • Established 단계: 이미 연결된 세션이라면 시퀀스 번호와 윈도우 크기가 합당한지 체크합니다.
3. TCP Receive Buffer: 검증이 끝난 패킷의 페이로드(데이터)를 해당 소켓의 수신 버퍼(Receive Queue)에 저장합니다.

5. 소켓 및 애플리케이션 단계 (The Destination)

마지막으로 데이터가 커널 메모리에서 유저 메모리로 이동합니다.

1. Wake up Process: 수신 버퍼에 데이터가 들어오면, 해당 소켓을 기다리며 sleep 상태에 있던 애플리케이션 프로세스를 깨웁니다.
2. System Call (read / recv): 애플리케이션(예: sshd, Go/Java App)이 시스템 콜을 호출합니다.
3. Context Switch & Data Copy: CPU 모드가 Kernel Mode에서 User Mode로 전환되며, 커널 메모리에 있던 데이터가 애플리케이션의 메모리 공간으로 복사(Copy)됩니다.
4. Application Logic: 드디어 애플리케이션이 데이터를 읽어 비즈니스 로직을 수행합니다.

정리: 대규모 인프라 운영 시 핵심 포인트

• 성능 병목: 보통 SoftIRQ 단계에서 CPU 0번 등에 부하가 몰려 패킷 드랍이 발생하기 쉽습니다. (RSS/RPS 튜닝 필요)
• 현재 이슈 지점: tcp_check_req 단계는 커널 스택(4단계)에 해당하며, 이는 하드웨어나 Cilium의 결정이 아니라 커널이 가진 '연결 상태 정보'와 '도착한 패킷'이 일치하지 않을 때 발생하는 논리적 거부 단계입니다.

이 과정 중 특히 어느 레이어의 메트릭이 가장 의심되시나요? 각 단계별로 더 깊게 파고들고 싶은 부분이 있다면 말씀해 주세요.

===

TCP 계층은 리눅스 커널에서 가장 똑똑하면서도 까칠한 영역입니다. 단순히 패킷을 넘기는 L3와 달리, "이 패킷이 내가 기다리던 게 맞나?"를 집요하게 따지기 때문이죠.

플랫폼 엔지니어로서 pwru 트레이스에서 보셨던 tcp_check_req 단계를 포함해, L4 스택 내부에서 벌어지는 일을 5단계로 더 자세히 풀어보겠습니다.

1. 소켓 찾기 (The Socket Lookup)

패킷이 L3(IP)를 통과해 tcp_v4_rcv() 함수에 진입하면 가장 먼저 하는 일은 "이 패킷의 주인이 누구인가?"를 찾는 것입니다.

• 4-Tuple 매칭: 패킷 헤더의 Source IP/Port, Destination IP/Port 정보를 추출합니다.
• __inet_lookup_skb(): 커널은 해시 테이블에서 이 4-Tuple에 해당하는 소켓 구조체(struct sock)를 검색합니다.
  • 이미 연결된 소켓이 있다면 Established Hash에서 찾고,
  • 새로운 연결 시도라면 Listening Hash에서 포트 번호를 기준으로 찾습니다.
• 결과: 소켓을 찾지 못하면 즉시 RST를 보내고 패킷을 버립니다.

2. 상태별 분기 (The Dispatcher)

소켓을 찾았다면, 이제 소켓의 현재 상태(sk_state)에 따라 패킷 처리 경로가 완전히 달라집니다. tcp_v4_do_rcv()가 이 역할을 수행합니다.

• ESTABLISHED 상태: 패킷이 이미 연결된 세션의 일부라면 Fast Path(빠른 처리 경로)로 보냅니다.
• LISTEN/SYN_SENT 상태: 핸드셰이크 과정 중이라면 Slow Path로 진입하여 복잡한 검증 로직을 태웁니다.
  • 여기서 tcp_check_req()가 호출됩니다.

3. 핸드셰이크 검증 (The Gatekeeper: tcp_check_req)

질문하셨던 드랍 지점이 바로 여기입니다. 서버가 SYN을 받고 SYN-ACK를 보낸 후, 클라이언트의 마지막 ACK를 기다리는 SYN_RECV 상태에서의 로직입니다.

• Mini-Socket (request_sock): 커널은 메모리 절약을 위해 정식 소켓을 만들기 전, 아주 작은 '임시 소켓'인 request_sock을 만들어 둡니다.
• 검증 항목:
  1. Sequence Number: 도착한 ACK 번호가 내가 보낸 SYN-ACK의 시퀀스 + 1인가?
  2. TCP Timestamps: (PAWS) 시간이 거꾸로 흐르지는 않았나?
  3. SYN Cookies: (부하 시) 쿠키 값이 일치하나?
• 통과 시: 임시 소켓을 정식 소켓(struct tcp_sock)으로 승격(Promote)시키고 ESTABLISHED 상태로 전이합니다.
• 실패 시: 여기서 pwru에 찍힌 것처럼 드랍 처리됩니다.

4. 데이터 경로 (Fast Path vs. Slow Path)

연결이 수립된 후 데이터를 주고받을 때는 성능을 위해 두 가지 경로를 사용합니다.

• Fast Path (Header Prediction): 패킷이 예상된 시퀀스 번호를 가졌고, 별다른 TCP 옵션이 없는 '순수 데이터'라면 헤더만 쓱 보고 바로 수신 큐로 넘깁니다. (성능 최적화)
• Slow Path: 패킷 순서가 뒤바뀌었거나(Out-of-order), SACK 옵션이 붙었거나, 윈도우 크기가 변하는 등 '신경 쓸 게 많은' 패킷은 이 경로에서 정밀하게 재조립됩니다.

5. 수신 큐와 애플리케이션 전달 (The Delivery)

검증이 끝난 데이터 페이로드는 소켓의 수신 큐(Receive Queue)에 쌓입니다.

• sk_buff 관리: 패킷 데이터가 담긴 sk_buff 구조체들이 리스트 형태로 큐에 매달립니다.
• Wake up: 큐에 데이터가 들어오면, 이 소켓을 물고 epoll이나 read() 시스템 콜로 대기 중이던 애플리케이션 프로세스를 깨웁니다.
• Copy to User: 애플리케이션이 깨어나면 커널 메모리에 있는 데이터를 유저 메모리 공간으로 복사해 갑니다.

DevOps 관점에서의 요약

지금 겪고 계신 문제는 3단계(Gatekeeper)에서 발생하고 있습니다. L3 스위치만 있는 환경에서 이 단계의 드랍이 발생한다는 것은, 하드웨어 에러보다는 "네트워크 지연으로 인해 서버가 클라이언트를 기다리다 지쳐(Minisock Timeout) 정보를 삭제했는데, 뒤늦게 클라이언트의 ACK가 도착한 경우"가 가장 유력합니다.

RHEL 10에서도 이 핵심 로직은 동일하며, nstat으로 확인하신 TcpExtTCPMinisocksDrop이 이 3단계를 대변하는 지표라고 보시면 됩니다.

다음 단계로 넘어가기 위해 nstat의 구체적인 수치를 한 번 확인해 보시겠어요? 어떤 카운터가 가장 높은지에 따라 튜닝할 sysctl 변수가 결정됩니다.

===

nstat은 리눅스 커널의 네트워크 통계 정보(/proc/net/netstat 및 /proc/net/snmp)를 실시간으로 읽어와서 보여주는 강력한 도구입니다. 대규모 인프라를 관리하신다면 netstat -s보다 가독성이 좋고 증분값(Delta) 확인이 쉬운 nstat을 주력으로 사용하시는 것이 좋습니다.

플랫폼 엔지니어링 실무에서 가장 많이 쓰이는 확인 방법들을 정리해 드립니다.

1. 기본 사용법 및 핵심 옵션

nstat은 실행 시점 사이의 변화량(증분)을 보여주는 것이 기본 동작입니다.

• nstat -z: 값이 0인 지표까지 모두 포함해서 출력 (전체 지표 확인 시 유용)
• nstat -a: 증분값이 아닌, 부팅 이후 누적된 전체 합계(Absolute) 출력
• nstat -n: 현재까지의 통계를 한 번 '0'으로 리셋 (다음 실행 때 깨끗한 증분 확인 가능)

2. 장애 진단 시 필수 명령어 (필터링)

앞서 논의한 tcp_check_req 드롭이나 핸드셰이크 문제를 진단할 때 아래 명령어를 사용하세요.

① 현재 발생 중인 드롭 지표 실시간 확인

명령어를 실행하고 1~2초 뒤에 다시 실행하면 그 사이의 변화량만 딱 찍힙니다.

# -z를 붙여야 현재 0이라도 나중에 올라오는 지표를 미리 볼 수 있습니다.
nstat -z | grep -E 'TcpExtListenDrops|TcpExtSyncookiesFailed|TcpExtTCPMinisocksDrop'

② 누적 카운트 확인 (부팅 후 총합)

장애가 이미 지나갔다면 누적값을 보고 시스템의 전반적인 건강 상태를 판단합니다.

nstat -az | grep -E 'TcpExtListenDrops|TcpExtSyncookiesFailed|TcpExtTCPMinisocksDrop'

3. 플랫폼 엔지니어를 위한 추가 유용 지표

SSH 연결 지연이나 간헐적 끊김이 있을 때 함께 보면 좋은 지표들입니다.

# 위 지표들을 한꺼번에 모니터링하기
nstat -z | grep -E 'Timeout|BacklogDrop|SyncookiesSent|ACKSkipped'

4. 실무 팁: 1초마다 변화량 관찰하기

장애 상황을 재현하면서 실시간으로 수치가 올라가는 것을 보고 싶을 때 유용합니다. watch 명령어를 조합하세요.

# 1초마다 nstat을 실행하고(증분 확인), 이전에 확인한 값은 리셋(-n)
watch -n 1 "nstat -n | grep -E 'TcpExtListenDrops|TcpExtSyncookiesFailed|TcpExtTCPMinisocksDrop'"

5. 결과 해석 예시

명령어를 실행했을 때 아래와 같이 나온다면 어떻게 판단해야 할까요?

TcpExtListenDrops              15                 0.0
TcpExtTCPMinisocksDrop         120                0.0

• 해석: 마지막으로 nstat을 실행한 이후, ListenDrops는 15회, TCPMinisocksDrop은 120회 발생했다는 뜻입니다.
• 판단: MinisocksDrop이 압도적으로 많다면, 클라이언트의 ACK가 늦게 와서 커널이 기다리다 지쳐 버린 경우가 많으므로 네트워크 지연(Latency)이나 RTT를 먼저 의심해야 합니다.

RHEL 10에서도 이 명령어 체계와 결과 형식은 동일하게 유지됩니다. 지금 시스템에서 nstat -az를 실행했을 때 TcpExtTCPMinisocksDrop 수치가 다른 드롭 지표들에 비해 유독 높게 나오나요?

DevOps 관점에서 대규모 트래픽이나 간헐적인 부하를 견딜 수 있도록 하는 핵심 튜닝 포인트를 정리해 드립니다.

1. SYN Cookie 진입 방지 (Queue 확장)

SYN Cookie는 SYN Queue(반개방 소켓 큐)가 가득 찼을 때만 발동합니다. 큐 크기를 충분히 키워두면 시스템이 '비상 모드'인 SYN Cookie를 사용하지 않고도 요청을 처리할 수 있습니다.

• net.ipv4.tcp_max_syn_backlog:
  • 아직 핸드셰이크가 완료되지 않은 요청(SYN_RECV 상태)을 얼마나 저장할지 결정합니다.
  • 권장: 1000개 노드 규모라면 4096 이상, 아주 많게는 16384까지 설정합니다.
• net.core.somaxconn:
  • 애플리케이션(여기서는 SSHD)이 accept()를 기다리는 완전 연결 큐의 크기입니다. 이 값이 작으면 핸드셰이크가 끝나도 드랍될 수 있습니다.
  • 권장: 최소 4096 이상.

# 실시간 적용
sudo sysctl -w net.ipv4.tcp_max_syn_backlog=8192
sudo sysctl -w net.core.somaxconn=8192

2. SYN Cookie 검증 실패 방지 (TCP Timestamp)

SYN Cookie가 활성화되었을 때 검증이 실패하는 가장 흔한 이유는 TCP Timestamps가 어긋나거나 비활성화되어 있기 때문입니다. SYN Cookie는 TCP 헤더의 특정 필드를 빌려 정보를 저장하는데, 이때 Timestamp 필드가 중요하게 사용됩니다.

• net.ipv4.tcp_timestamps:
  • 이 값이 0이면 SYN Cookie 내에 MSS(Maximum Segment Size) 정보를 제대로 담지 못해 검증 실패율이 올라갑니다.
  • 확인: sysctl net.ipv4.tcp_timestamps가 1인지 확인하십시오. (상대방 클라이언트도 1이어야 함)

3. 타임아웃 및 재전송 관련 튜닝

L3 스위치만 있는 환경에서 간헐적 지연이 발생한다면, 커널이 '이 연결은 죽었다'고 판단하는 시간을 아주 약간 넉넉하게 줄 수 있습니다.

• net.ipv4.tcp_synack_retries:
  • 서버가 SYN-ACK를 보내고 클라이언트의 ACK를 기다리는 재전송 횟수입니다. 기본값은 보통 5인데, 네트워크가 불안정하다면 이 횟수가 소진되기 전에 큐에서 삭제될 수 있습니다. (다만 이 값을 너무 키우면 리소스 낭비가 생길 수 있으니 기본값 유지를 권장하되, 환경에 따라 2~3으로 조정하여 빠르게 소켓을 정리하기도 합니다.)

4. 진단 및 모니터링 (실행 결과 확인)

튜닝 적용 후 실제로 효과가 있는지 보려면 다음 카운터를 계속 주시해야 합니다.

# SYN Cookie 관련 실패 카운터 확인
nstat -az | grep -i Syncookies

• TcpExtSyncookiesSent: 서버가 쿠키를 보낸 횟수 (이게 올라가면 큐가 가득 찼다는 뜻)
• TcpExtSyncookiesFailed: 이게 문제의 지표입니다. 쿠키 검증에 실패한 횟수입니다.

종합 제안 (결론)

현재 SSH 연결 시 간헐적 문제가 발생한다면, 아래 설정을 sysctl.conf에 반영하여 큐 임계치를 대폭 높여보시는 것을 추천합니다.

1. 우선 순위 1: tcp_max_syn_backlog와 somaxconn을 현재 값보다 4배 이상 늘립니다.
2. 우선 순위 2: tcp_timestamps가 1인지 확인합니다. 만약 클라이언트(VDI 등) 쪽에서 타임스탬프를 제거하고 있다면 쿠키 검증 실패는 튜닝만으로 해결이 어려울 수 있습니다.
3. Cilium 특이사항: Native Routing 사용 시 노드 간의 MTU가 일치하지 않으면 tcp_check_req 이후의 실제 데이터 패킷에서 이슈가 생길 수 있으므로, ip link로 각 노드 인터페이스의 MTU가 1500(혹은 하단 스위치 설정값)으로 동일한지 꼭 체크해 보세요.

이 튜닝 이후에도 SyncookiesFailed 카운트가 계속 올라간다면, 클라이언트 측에서 보내는 ACK 패킷 자체가 중간 네트워크 장비(L3 스위치 등)에 의해 변조되거나 지연되고 있을 가능성이 매우 높습니다.

혹시 현재 해당 서버들의 max_syn_backlog 설정값은 얼마로 되어 있나요?

===

네, 맞습니다. pwru 트레이스에서 드롭 지점이 tcp_check_req로 찍혔다면, 범인은 이미 포위망에 들어온 것과 다름없습니다. 일반적인 리눅스 커널 네트워킹 스택에서 이 단계는 "3-way handshake의 마지막 퍼즐(ACK)을 맞추는 과정"이기 때문입니다.

결론부터 말씀드리면, 말씀하신 2~3가지 원인 외에 다른 가능성은 95% 이상 배제하셔도 무방합니다. 이 지점에서 패킷이 버려지는 시나리오는 매우 구체적입니다.

1. 포위망에 들어온 3대 주범

이전 모델이 제시한 원인들을 실무적인 관점에서 가장 확률 높은 순으로 다시 정리해 드립니다.

1. 타이밍 이슈 (Request Sock Timeout):

   • 서버가 SYN-ACK를 보냈는데, 클라이언트의 ACK가 너무 늦게 도착한 경우입니다. 서버는 이미 "얘는 안 오나 보다" 하고 관리 대장(request_sock)에서 해당 연결 정보를 지워버린 상태입니다.
   • 증거: nstat -az | grep TcpExtListenDrops 카운트 상승.

2. 검증 로직 실패 (SYN Cookies & Timestamps):

   • 시스템 부하로 SYN Cookie가 발행되었는데, 도착한 ACK의 쿠키 값이 계산 결과와 다르거나, TCP Timestamps가 일치하지 않아 커널이 "가짜 ACK"라고 판단한 경우입니다.
   • 증거: nstat -az | grep SyncookiesFailed.

3. 시퀀스 번호/윈도우 불일치 (Invalid ACK):

   • 이미 연결이 종료되었거나 중복된 SYN이 오가는 과정에서, 클라이언트가 보낸 ACK의 Sequence 번호가 서버가 기대하는 범위(Window) 밖에 있는 경우입니다.
   • L3 스위치만 있는 환경이라도, 중간 장비에서 패킷 순서가 심하게 뒤바뀌면 발생할 수 있습니다.

2. "거의 없지만" 존재는 하는 0.1%의 가능성

만약 위 3가지가 모두 아니라면, 정말 드문 확률로 다음 상황일 수 있습니다.

• TCP MD5 Signature 미스매치: 만약 BGP 세션 등에서 TCP MD5 인증을 사용 중이라면(일반 SSH에서는 거의 안 씁니다), 서명이 틀렸을 때 여기서 드랍됩니다.
• 커널 버그: 특정 커널 버전에서 tcp_check_req 로직의 레이스 컨디션(Race Condition)으로 인해 드랍되는 경우가 아주 드물게 보고된 적이 있습니다. (하지만 운영 환경에서는 거의 고려하지 않습니다.)
• Cilium eBPF의 커널 스택 간섭: native routing이라도 Cilium이 커널 스택으로 패킷을 넘기기 전에 skb 마킹을 이상하게 해서, 커널이 이를 "오염된 패킷"으로 간주하고 드랍할 가능성은 0에 가깝지만 존재합니다.

3. 제 판단: "이것만 확인하면 끝납니다"

현재 L3 스위치만 있는 클린한 환경이므로, "네트워크 지연으로 인한 타임아웃" 혹은 "SYN Cookie 설정 불일치" 둘 중 하나일 확률이 압도적입니다.

확정 진단을 위한 마지막 한 걸음: 터미널에서 아래 한 줄만 실행해 보시고 결과를 알려주세요.

nstat -az | grep -E 'TcpExtListenDrops|TcpExtSyncookiesFailed|TcpExtTCPMinisocksDrop'

• ListenDrops가 올라가면 -> 백로그 큐(Backlog Queue) 확장 및 타임아웃 튜닝이 정답입니다.
• SyncookiesFailed가 올라가면 -> TCP Timestamp 설정 확인 및 Syncookies 튜닝이 정답입니다.

이 지점에서 드롭이 발생했다는 사실 자체가 이미 전체 디버깅 과정의 90%를 끝내신 겁니다. 아주 날카롭게 짚어내셨네요! 이외에 다른 카운터가 유독 높게 나오는 게 있나요?

===

네, RHEL 10(커널 6.x 대역 기반)에서도 이 메트릭들은 여전히 핵심적인 네트워킹 진단 지표로 존재합니다. 리눅스 커널의 TCP 스택이 고도화되면서 내부 로직의 성능은 개선되었지만, 운영 체제가 네트워크 상태를 보고하는 표준 방식(SNMP 카운터)은 하위 호환성과 관찰 가능성을 위해 유지되고 있기 때문입니다.

요청하신 세 가지 지표는 모두 "TCP 핸드셰이크 과정 중 어디서 패킷이 버려졌는가"를 정확히 짚어주는 이정표입니다.

1. 주요 커널 메트릭 상세 설명

① TcpExtListenDrops (리스너 드롭)

이 카운터는 "완전 연결 큐(Accept Queue)가 꽉 찼을 때" 올라갑니다.

• 상황: 클라이언트와 3-way handshake를 다 끝냈는데, 애플리케이션(예: sshd)이 너무 바빠서 accept() 시스템 콜로 연결을 가져가지 못할 때 발생합니다.
• 의미: "연결은 맺어졌지만, 서버 프로그램이 수용 가능한 한계를 넘었다"는 뜻입니다.
• 조치: net.core.somaxconn 값을 키우거나, 애플리케이션의 워커 스레드 수를 늘려야 합니다.

② TcpExtSyncookiesFailed (쿠키 검증 실패)

이 카운터는 "도착한 ACK 패킷이 유효한 SYN Cookie가 아닐 때" 올라갑니다.

• 상황: 서버가 SYN Flooding 등을 방어하기 위해 '비상 모드(SYN Cookie)'를 켰을 때, 클라이언트가 보낸 ACK에 담긴 '쿠키 값'이 서버가 계산한 값과 다를 경우입니다.
• 의미: 중간에 방화벽이나 L3 스위치가 패킷을 변조했거나, TCP Timestamp가 일치하지 않아 서버가 "이 패킷은 내가 보낸 SYN-ACK에 대한 정상적인 응답이 아니다"라고 판단한 것입니다.
• 조치: net.ipv4.tcp_timestamps=1 설정이 서버/클라이언트 양쪽 다 되어 있는지 확인하십시오.

③ TcpExtTCPMinisocksDrop (미니소켓 드롭)

이것은 현재 겪고 계신 tcp_check_req 단계의 드롭과 가장 밀접한 관련이 있습니다.

• 상황: 리눅스 커널은 연결이 완전히 수립되기 전 상태(SYN_RECV)를 아주 작은 메모리 구조체인 request_sock(Minisock)으로 관리합니다. 이 소켓이 모종의 이유로 드랍될 때 올라갑니다.
• 의미: 주로 타임아웃 때문입니다. 서버가 SYN-ACK를 보낸 후 클라이언트의 ACK를 기다리다가, 기다림이 너무 길어져서(또는 메모리가 부족해서) 이 미니소켓을 메모리에서 해제해 버린 것입니다. 그 직후에 클라이언트의 ACK가 도착하면 서버는 "누구세요?"라며 패킷을 버리게 됩니다.
• 조치: 네트워크 지연(RTT)을 체크하거나, 서버의 request_sock 유지 시간을 점검해야 합니다.

2. RHEL 10에서의 상태

RHEL 10에서도 이 값들은 동일하게 /proc/net/netstat에서 확인할 수 있습니다.

리눅스 커널 개발팀은 성능을 위해 lockless listener 등 새로운 메커니즘을 도입해 왔지만, 운영자가 문제를 진단할 때 사용하는 SNMP(Simple Network Management Protocol) 통계 이름은 바꾸지 않았습니다. 덕분에 RHEL 7, 8, 9에서 사용하시던 진단 스크립트나 모니터링 에이전트(Prometheus Node Exporter 등)를 RHEL 10에서도 그대로 사용하실 수 있습니다.

3. 요약 및 진단 가이드

플랫폼 엔지니어로서 현상을 분석하실 때, 아래 표를 기준으로 드롭의 성격을 규정하시면 됩니다.

결론: 만약 pwru에서 tcp_check_req 드롭이 보인다면, RHEL 10에서도 TCPMinisocksDrop이나 SyncookiesFailed 중 하나가 함께 올라가고 있을 확률이 매우 높습니다.

지금 노드에서 nstat -az | grep -i TcpExt 결과가 어떻게 나오나요? 특정 수치가 유독 높다면 그게 바로 범인입니다.

===

네, SYN cookie 검증 실패는 근본 원인에 따라 접근이 달라집니다. 튜닝 방향을 두 가지로 나눌 수 있어요.

핵심 전제: SYN cookie가 왜 발행되는가

SYN cookie는 SYN 큐(backlog)가 가득 찼을 때 커널이 어쩔 수 없이 꺼내는 fallback입니다. 따라서 튜닝 방향은 두 가지입니다.

1. SYN 큐가 안 차게 → cookie 자체를 안 쓰게
2. 어쩔 수 없이 cookie를 쓸 때 → 검증 실패를 줄이게

방향 1 — SYN 큐가 차지 않도록 (근본 해결)

# SYN 큐 크기 확장 (기본 128~256, 대규모 클러스터는 4096 이상 권장)
sysctl -w net.ipv4.tcp_max_syn_backlog=4096

# 애플리케이션 listen() backlog 상한 (sshd는 보통 128 고정)
sysctl -w net.core.somaxconn=4096

# SYN-ACK 재전송 횟수 줄이기 (대기 시간 단축 → 큐 빨리 비움)
# 기본 5 (약 180초 대기), 2로 줄이면 약 45초
sysctl -w net.ipv4.tcp_synack_retries=2

sshd 자체도 MaxStartups 값을 확인해야 합니다.

# /etc/ssh/sshd_config
MaxStartups 100:30:200   # 동시 미완성 핸드셰이크 허용 수

방향 2 — SYN cookie 사용 시 검증 실패 줄이기

SYN cookie 검증 실패의 주요 원인은 MSS 옵션 정보 손실입니다. Cookie에는 MSS가 3비트(8가지 값)밖에 인코딩되지 않아, 경로 MTU가 불일치하거나 패킷이 변조되면 검증이 깨집니다.

# syncookies 활성화 확인 (2 = 항상 사용, 1 = 큐 찼을 때만 → 1 권장)
sysctl -w net.ipv4.tcp_syncookies=1

값을 1로 유지하면 큐가 차지 않는 한 cookie를 쓰지 않아 검증 실패 자체가 줄어듭니다. 2로 설정하면 항상 cookie를 써서 오히려 실패 빈도가 높아집니다.

ECMP + Cilium 환경 특화 튜닝

이 환경에서는 추가로 고려할 게 있습니다.

Cilium의 tcp_max_syn_backlog 반영 확인 Cilium이 eBPF로 LB를 할 때 자체 session affinity 없이 ECMP를 쓰면, SYN은 노드 A로, ACK는 노드 B로 가는 비대칭이 발생합니다. 이 경우 cookie 튜닝만으로는 한계가 있고, 아래가 더 효과적입니다.

# Cilium session affinity 활성화 (helm values)
# loadBalancer.sessionAffinity: true
# 또는 BGP에서 ECMP 해싱을 5-tuple 기반으로 고정

# 스위치에서 consistent hashing 확인 필요
# src-ip, dst-ip, src-port, dst-port, protocol 모두 포함되어야 함

현재 상태 확인 → 튜닝 전후 비교

# 튜닝 전 baseline 수집
nstat -az | grep -E 'SyncookiesSent|SyncookiesFailed|SyncookiesRecv|ListenDrops|ListenOverflows'

# 설정 적용 후 변화 모니터링 (5초 간격)
watch -n 5 "nstat -az | grep -E 'Syncookies|ListenDrop'"

SyncookiesSent가 지속 증가하면 큐 포화가 원인이므로 방향 1, SyncookiesFailed / SyncookiesRecv 비율이 높으면 패킷 변조나 비대칭 경로 문제입니다.

권장 적용 순서

SyncookiesSent가 높다면 tcp_max_syn_backlog + somaxconn 확장이 즉효입니다. 그래도 SyncookiesFailed가 계속 오른다면 ECMP 5-tuple 해싱 일관성 확인이 다음 단계입니다. 현재 어떤 카운터가 올라가고 있는지 공유해 주시면 더 구체적으로 좁혀드릴 수 있어요.

요청하신 대로 수신 측(Receiver) 관점에서 패킷이 NIC을 거쳐 커널의 tcp_check_req에서 드랍되기까지의 구조와 주요 지점을 짚어드리겠습니다.

1. 수신측 패킷 처리 구조 (NIC to Kernel TCP)

Native Routing 환경에서는 캡슐화(VXLAN) 과정이 없기 때문에 패킷이 표준 리눅스 네트워킹 스택을 더 깊게 활용합니다.

① 하드웨어 레벨: NIC & Driver

• RSS (Receive Side Scaling): 패킷이 들어오면 NIC 하드웨어가 5-tuple 해싱을 통해 특정 RX 큐에 패킷을 할당합니다. ECMP 환경에서는 스위치단에서 이미 해싱되어 들어오지만, 본딩(Bonding)된 NIC 내부에서도 어떤 슬레이브로 들어오느냐가 결정됩니다.
• SoftIRQ (NAPI): 커널이 CPU를 할당하여 RX 큐에서 패킷을 꺼내 sk_buff(skb) 구조체로 만듭니다.

② Cilium & eBPF 계층 (Host Routing)

• XDP/tc BPF: Cilium은 tc(traffic control) 훅에 eBPF 프로그램을 붙여 패킷을 처리합니다. Native 모드이므로 BGP로 전파된 라우팅 테이블을 보고 패킷이 로컬 포드용인지, 다른 노드로 포워딩할지 결정합니다.
• Connection Tracking (CT): Cilium은 자체 BPF CT 테이블을 관리합니다. 여기서 상태가 어긋나면 커널 스택으로 넘기기 전에 드랍되는데, 사용자님의 경우 Cilium Monitor에 안 찍히므로 이 단계는 통과한 것입니다.

③ IP Stack & Netfilter

• ip_rcv & nf_hook: 패킷이 커널 네트워킹 스택으로 진입합니다. iptables의 PREROUTING 훅이 여기서 실행됩니다.
• fib_validate_source (중요 - RP Filter): BGP+ECMP 환경에서 가장 위험한 구간입니다. 패킷이 들어온 인터페이스가 커널 라우팅 테이블상 "해당 소스 IP로 나갈 때 사용하는 인터페이스"와 다르면 비대칭 라우팅으로 간주하고 드랍합니다.

④ TCP Stack: tcp_v4_rcv -> tcp_check_req

• tcp_v4_rcv: 패킷의 목적지가 로컬 소켓임을 확인하고 TCP 프로토콜 프로세서로 넘깁니다.
• tcp_check_req (드랍 지점): TCP 3-way handshake의 마지막 ACK를 검증하는 핵심 함수입니다. SYN을 받았을 때 생성된 request_sock (Mini-socket)과 들어온 ACK를 대조합니다.

2. 왜 tcp_check_req에서 드랍될까? (전문가적 진단)

Native Mode, BGP, ECMP 환경을 고려할 때 가장 유력한 시나리오는 다음과 같습니다.

시나리오 A: ECMP에 의한 비대칭 라우팅 (Asymmetric Routing)

• 현상: 클라이언트가 보낸 SYN은 노드 A로 들어왔는데, 마지막 ACK는 ECMP 경로 최적화나 스위치의 해싱 변경으로 인해 노드 B로 들어오는 경우입니다.
• 결과: 노드 B는 해당 세션에 대한 request_sock 정보가 없으므로 "듣도 보도 못한 ACK"라 판단하고 tcp_check_req에서 드랍합니다. Clustermesh를 사용 중이라면 노드 간 라우팅 경로가 꼬일 확률이 더 높아집니다.

시나리오 B: Request Sock 타임아웃

• 현상: 서버가 SYN-ACK를 보냈으나, 네트워크 지연으로 클라이언트의 ACK가 서버의 TCP_TIMEOUT_INIT 내에 도착하지 못한 경우입니다.
• 결과: 서버 커널은 이미 request_sock을 해제(GC)했고, 뒤늦게 온 ACK는 매칭되는 정보가 없어 드랍됩니다.

시나리오 C: SYN Cookie 오작동

• 현상: BGP를 통한 대규모 트래픽 유입으로 노드의 Accept Queue가 순간적으로 차오르면 SYN Cookie가 발행됩니다.
• 결과: 클라이언트가 보낸 ACK에 포함된 쿠키 값이 커널의 현재 계산값과 미세하게 어긋나면 검증에 실패합니다.

3. 플랫폼 엔지니어를 위한 심화 디버깅 가이드

현재 상황에서 "범인"을 검거하기 위해 다음 순서로 확인을 권장합니다.

1. 비대칭 라우팅 확인 (가장 의심됨):

   • 드랍이 발생하는 노드에서 sysctl net.ipv4.conf.all.rp_filter 값을 확인하십시오.
   • BGP 환경이라면 2 (Loose) 모드로 설정되어 있어야 비대칭 경로를 허용합니다. 만약 1 (Strict)라면 즉시 드랍 사유가 됩니다.

2. nstat를 통한 커널 통계 분석:

   # 드랍 발생 시점 전후로 카운트 변화 관찰
   nstat -az | grep -E 'TcpExtListenDrops|TcpExtTCPMinisocksDrop|TcpExtTCPACKSkipped'

   • TcpExtListenDrops가 올라간다면 큐 부족 문제입니다.
   • TcpExtTCPMinisocksDrop이 올라간다면 request_sock 단계에서의 상태 불일치(비대칭 라우팅 등)입니다.

3. Cilium BGP 경로 안정성:

   • BGP 피어링이 간헐적으로 떨리거나(Flapping), ECMP 경로가 재계산되는지 스위치 로그와 함께 확인이 필요합니다.

결론적으로 제 제안은 이렇습니다. pwru가 드랍을 잡았다는 것은 패킷이 물리적으로는 도착했다는 증거입니다. 하지만 tcpdump가 못 잡는 이유는 보통 rp_filter에 의한 초기 드랍이거나 본딩 인터페이스의 캡처 지점 문제입니다. 우선 노드의 rp_filter 설정을 2로 바꾸어 보시고, 현상이 해결되는지 확인하는 것이 가장 빠른 길입니다.

추가로 nstat 결과에서 특정 카운터가 유독 높게 나온다면 공유해 주세요. 바로 다음 단계를 짚어드리겠습니다.

===

각 레이어를 클릭하면 세부 질문을 바로 이어서 보낼 수 있도록 인터랙티브 다이어그램으로 만들었습니다.각 박스를 클릭하면 해당 레이어에 대한 심층 질문으로 바로 이어집니다. 이제 각 레이어별 구조를 설명드리겠습니다.

1. BGP / ECMP 유입 — 외부 경로 결정

ClusterMesh + BGP 환경에서는 각 노드가 자신의 Pod CIDR을 L3 스위치에 BGP로 광고합니다. 문제는 ECMP(Equal-Cost Multi-Path)가 활성화된 경우, 같은 플로우의 SYN과 ACK가 서로 다른 경로로 들어올 수 있다는 것입니다. 스위치 레벨의 ECMP 해싱이 5-tuple 기반이면 안전하지만, 구현에 따라 패킷 단위로 분산되기도 합니다.

2. NIC 하드웨어 — RSS 및 오프로딩

ens5f0np0 / ens5f1np1에서 받은 패킷은 RSS(Receive Side Scaling)에 의해 특정 CPU 큐로 배분됩니다. GRO(Generic Receive Offload)가 활성화되어 있으면 작은 패킷을 합쳐 커널로 올리는데, SYN/ACK 같은 소형 제어 패킷은 이 과정에서 타이밍이 미묘하게 영향받을 수 있습니다.

3. Bond1 드라이버 — tcpdump가 안 보이는 핵심 이유

active-backup 모드라면 RX는 항상 active 슬레이브(예: ens5f1np1) 하나에서만 올라오고, bond1 인터페이스에는 나타나지 않는 경우가 있습니다. LACP(802.3ad) 모드에서는 수신이 특정 슬레이브에 고정되므로, tcpdump -i bond1 대신 tcpdump -i ens5f1np1로 캡처해야 패킷이 보입니다.

4. Cilium eBPF (TC hook) — 이 레이어는 정상 통과

Cilium은 tc ingress에 eBPF 프로그램을 붙여 패킷을 처리합니다. Native routing 모드에서는 VXLAN 없이 직접 커널 라우팅 테이블을 활용합니다. cilium monitor에 drop이 찍히지 않는다는 것은 Cilium의 보안 정책, LB 로직, conntrack 레벨에서는 모두 허용됐다는 의미입니다. 즉, 문제는 이 레이어 아래에 있습니다.

5. Netfilter (PREROUTING → LOCAL_IN)

nf_hook_slow가 호출되며 체크섬 검사(nf_checksum)와 등록된 netfilter 룰을 통과합니다. pwru 트레이스상 이 단계에서 DROP 흔적이 없으므로 방화벽/iptables 문제는 배제됩니다.

6. IP 라우팅 + rp_filter — ⚠️ 잠재적 드랍 지점

fib_validate_source가 호출되며 여기서 rp_filter(Reverse Path Filter)가 작동합니다. ECMP 비대칭 라우팅 상황에서 SYN-ACK는 bond1을 통해 나갔는데 클라이언트의 ACK가 다른 슬레이브나 다른 경로로 들어오면, rp_filter Strict 모드(sysctl net.ipv4.conf.all.rp_filter=1)가 이를 스푸핑으로 간주해 드랍할 수 있습니다. 단, pwru 트레이스에서 이 단계를 통과했다면 현재 케이스의 직접 원인은 아닙니다.

7 & 8. tcp_v4_rcv → tcp_check_req → DROP — 실제 드랍 지점

tcp_v4_rcv가 패킷을 받으면 tcp_v4_fill_cb로 TCP 제어 블록을 채운 뒤, LISTEN 소켓이 관리하는 request_sock과 ACK를 대조하는 tcp_check_req로 진입합니다. 여기서 드랍되는 두 가지 핵심 경로는 다음과 같습니다.

경로 A — SYN Cookie 검증 실패: SYN 큐가 꽉 찼을 때 커널이 SYN cookie를 발행하는데, 클라이언트의 최종 ACK에 포함된 쿠키 값이 서버의 재계산 결과와 불일치하면 드랍됩니다. nstat -az | grep SyncookiesFailed 카운터로 확인 가능합니다.

경로 B — request_sock 타임아웃 후 ACK 도착: 서버가 SYN-ACK를 보내고 request_sock(반만 열린 연결 대기 구조)에서 클라이언트 ACK를 기다리는데, L3 스위치 구간의 순간적 지연으로 ACK가 늦게 도착하면 request_sock이 이미 expire되어 "알 수 없는 ACK"로 처리, 드랍됩니다. nstat -az | grep TcpExtListenDrops로 확인합니다.

이 두 경로 중 어느 쪽인지 확정하려면 nstat -az | grep -E 'SyncookiesFailed|ListenDrops|TCPMinisocksDrop' 결과에서 어떤 카운터가 올라가는지 공유해 주시면 바로 다음 단계를 짚어드릴 수 있습니다.

플랫폼 엔지니어링 리드로서 대규모 클러스터를 운영하시는 상황임을 고려하여, 실무적인 관점에서 다음과 같이 판단하고 추가 조언을 드립니다.

1. 분석 결과에 대한 제 판단

이전 모델의 분석 중 tcp_check_req에서 드랍된다는 점이 핵심입니다. 이 단계는 TCP Handshake 과정에서 SYN을 받고 SYN-ACK을 보낸 후, 클라이언트로부터 오는 마지막 ACK를 검증하는 단계입니다. 여기서 드랍된다는 것은 서버가 "나는 이 ACK를 받을 준비가 안 됐거나, 기대하던 ACK가 아니다"라고 판단한 것입니다.

왜 tcpdump에는 안 찍힐까? (중요)

pwru에는 찍히는데 tcpdump에 안 찍히는 이유는 크게 두 가지입니다.

• Capture Point의 차이: tcpdump(libpcap)는 보통 NIC 드라이버 레벨에서 패킷을 가로챕니다. 반면 pwru는 커널 함수에 직접 훅을 겁니다. 패킷이 물리 NIC로 들어왔더라도 Bonding, VLAN, 혹은 Cilium의 eBPF 프로그램이 패킷을 처리하는 방식에 따라 tcpdump가 바라보는 인터페이스에는 패킷이 통과하지 않을 수 있습니다.
• Cilium의 BPF Host Routing: Cilium이 bpf-host-routing을 사용 중이라면 일반적인 네트워킹 스택을 우회(Bypass)하여 스택의 더 깊은 곳으로 바로 패킷을 주입할 수 있습니다.

2. 예상되는 근본 원인 (Best Guess)

단순히 "상태 불일치"를 넘어, 실제 환경에서 흔히 발생하는 시나리오는 다음과 같습니다.

① MTU 및 패킷 파편화 (Fragmentation) 문제

SSH 연결 시 SYN, SYN-ACK까지는 크기가 작아 잘 넘어가다가, 세션 수립 직후나 특정 데이터가 실린 ACK 패킷이 MTU 제한으로 인해 조각나거나 드랍될 때 tcp_check_req에서 문제가 발생할 수 있습니다.

• Cilium 환경 특이점: VXLAN이나 Geneve 터널링을 사용 중이라면 오버헤드(50 bytes+) 때문에 실제 MTU가 1450 이하로 설정되어야 합니다.

② 클러스터 외부 Load Balancer / Proxy의 Idle Timeout

간헐적으로 발생한다면, 서버(수신측)의 request_sock(SYN을 받고 기다리는 소켓)이 타임아웃되어 삭제된 후에 클라이언트의 ACK가 도착했을 가능성이 큽니다.

• 네트워크 지연(Latency)이 순간적으로 튀거나, 중간 경로(L4, Firewall)에서 세션을 먼저 끊어버린 경우입니다.

③ Cilium의 Conntrack Table Full 또는 충돌

Cilium은 자체적인 eBPF 기반 conntrack 테이블을 관리합니다. 커널의 tcp_check_req와 Cilium의 상태 관리가 어긋날 때(예: 비대칭 라우팅) 드랍이 발생할 수 있습니다.

3. 정확한 진단을 위해 더 필요한 정보

더 명확한 답을 드리기 위해 다음 정보가 필요합니다.

1. 통신 경로: 클라이언트와 서버가 같은 K8s 노드에 있나요? 아니면 외부에서 노드로 들어오는 상황인가요? (LB 통과 여부)
2. Cilium 설정: native-routing인가요, 아니면 tunnel(VXLAN/Geneve) 모드인가요?
3. 드랍된 패킷의 상세 정보: pwru 실행 시 -sh (show help) 옵션 등을 활용해 드랍된 패킷의 TCP Flags(ACK인지 RST인지)와 Sequence Number를 확인할 수 있나요?
4. 수신측 노드의 자원 상황: 드랍 발생 시점에 해당 노드의 CPU 사용량(특히 SoftIRQ)이 급증하지는 않았나요?

4. 추천하는 후속 조치 (Action Items)

이전 답변에서 제안한 cat /proc/net/bonding/bond1 확인 외에 다음을 먼저 시도해 보세요.

1. 인터페이스 전체 캡처: tcpdump -i any port 22 -nnvv로 캡처해 보시고, 그래도 안 나온다면 eth0, eth1 등 물리 슬레이브 인터페이스 각각을 지정해서 다시 확인해 보세요.
2. Cilium 상태 확인:

   cilium monitor --type drop
   # 혹은 특정 IP에 대해
   cilium monitor --related-to <클라이언트_IP>

   Cilium 레벨에서 policy denied나 ct_trunc 등의 드랍 사유가 찍히는지 확인해야 합니다.
3. 커널 메트릭 확인: netstat -s | grep -i drop 혹은 nstat -az | grep -i TcpExtListenDrops 명령어를 통해 커널 스택 수준의 드랍 카운트가 올라가는지 보십시오.

제 판단은 이렇습니다: "이것은 단순한 설정 오류라기보다, 네트워크 경로상의 MTU 불일치나 비대칭 라우팅(Asymmetric Routing)으로 인해 커널이 유효하지 않은 ACK를 받았다고 판단했을 확률이 90% 이상입니다."

추가 정보를 주시면 더 구체적으로 디버깅해 드릴 수 있습니다. 어떻게 진행해 볼까요?

===

추가 정보 감사합니다. Native Routing을 사용 중이고 Cilium monitor drop에 아무것도 찍히지 않는다면, 이는 Cilium의 BPF Datapath(보안 정책, 라우팅 로직 등) 문제가 아니라 리눅스 커널의 표준 TCP 스택 수준에서 패킷이 거부되고 있음을 강력하게 시사합니다.

pwru 트레이스에서 tcp_check_req 단계에서 드랍이 발생한다는 것은, 커널이 TCP Handshake의 마지막 단계인 ACK 패킷을 받았으나 이를 유효한 연결 요청으로 인정하지 않았다는 뜻입니다. L3 스위치만 있는 환경에서 발생할 수 있는 구체적인 원인과 점검 포인트를 정리해 드립니다.

1. Cilium monitor에 왜 안 찍힐까?

Cilium Monitor는 eBPF 프로그램이 명시적으로 drop 결정을 내릴 때(예: Policy Denied, LB 관련 오류 등) 이벤트를 발생시킵니다. 하지만 현재 상황은 패킷이 Cilium의 BPF 로직을 무사히 통과하여 커널의 TCP 서브시스템(tcp_v4_rcv)으로 전달된 후, 커널 함수 내부 검증 로직에서 드랍된 것이기 때문에 Cilium 레벨의 로그에는 남지 않는 것이 정상입니다.

2. tcp_check_req 드랍의 핵심 원인 분석

이 단계에서 패킷이 버려지는 가장 흔한 이유는 다음과 같습니다.

① SYN Cookie 검증 실패 (net.ipv4.tcp_syncookies)

수신측 노드에 순간적으로 많은 연결 요청이 들어와 SYN Queue가 가득 찼을 때, 커널은 SYN Cookie를 발행합니다. 클라이언트가 보낸 ACK 패킷에 포함된 쿠키 값이 서버의 계산 결과와 일치하지 않으면 tcp_check_req에서 드랍됩니다.

• 확인 방법: sysctl net.ipv4.tcp_syncookies 값이 1인지 확인하고, nstat -az | grep -i SyncookiesFailed 카운트가 올라가는지 보십시오.

② Request Sock 타임아웃 (ListenDrops)

서버가 SYN을 받고 SYN-ACK를 보낸 뒤 클라이언트의 ACK를 기다리는 동안 사용하는 것이 request_sock입니다. 네트워크 지연(L3 스위치 구간의 일시적 혼잡 등)으로 인해 클라이언트의 ACK가 너무 늦게 도착하여 서버 쪽의 대기 시간이 만료되면, 커널은 이 패킷을 "알 수 없는 연결의 ACK"로 취급하여 버립니다.

• 확인 방법: nstat -az | grep -i TcpExtListenDrops 또는 TcpExtTCPMinisocksDrop 카운트를 확인하십시오.

③ 비대칭 라우팅 (Asymmetric Routing) 및 rp_filter

Native Routing 환경에서 L3 스위치가 ECMP 등으로 인해 나가는 경로와 들어오는 경로를 다르게 잡을 수 있습니다. 만약 패킷이 서버에 들어올 때 예상치 못한 인터페이스(예: bond1이 아닌 다른 인터페이스)로 들어오면 커널의 rp_filter가 작동하여 드랍될 수 있습니다.

• 확인 방법: sysctl -a | grep rp_filter 값이 1(Strict)인지 확인해 보십시오. 테스트를 위해 임시로 0으로 설정하고 현상이 재발하는지 확인해 볼 수 있습니다.

3. 추가 진단을 위한 가이드

현재 상황에서 문제를 확정 짓기 위해 다음을 실행해 보시길 권장합니다.

1. 커널 정밀 통계 확인 (가장 추천) 문제가 발생한 직후 다음 명령어를 실행하여 어떤 카운터가 올라가는지 확인하십시오.

   nstat -az | grep -E 'TcpExtListenDrops|TcpExtTCPMinisocksDrop|Syncookies|TcpExtTCPACKSkipped'

2. 물리 인터페이스 직접 캡처 tcpdump -i any 보다는 물리 NIC(예: ens...)를 각각 지정해서 캡처해 보십시오. L3 스위치에서 오는 패킷이 본딩된 슬레이브 중 어느 쪽으로 들어오는지, 그리고 그 패킷의 Sequence Number와 ACK Number가 서버가 보낸 SYN-ACK와 일치하는지 대조해야 합니다.

3. MTU 확인 Native Routing이라도 하단 물리 망의 MTU가 1500 미만으로 설정된 구간이 있다면, SSH 인증 과정에서 큰 패킷이 오갈 때 tcp_check_req 이후 단계에서 문제가 될 수 있습니다. (다만, 현재 pwru상 드랍 지점은 Handshake 단계에 더 가깝습니다.)

결론적으로 제 판단은: 방화벽이 없는 Native Routing 환경이므로, "L3 스위치 구간의 일시적 지연으로 인한 SYN 대기 소켓(request_sock) 타임아웃" 또는 "커널의 SYN Cookie 오작동"일 가능성이 가장 높습니다.

위의 nstat 결과값 중 카운트가 유독 높은 항목이 있다면 알려주세요. 바로 다음 단계를 짚어드리겠습니다.

===

1 텍스트

이번 트레이스는 같은 플로우(10.111.43.21:11180 -> 10.111.43.38:22)에 대해 “PREROUTING/LOCAL_IN(넷필터) -> 라우팅/소스검증 -> 로컬 딜리버리 -> RAW 소켓 검사 -> TCP 수신 -> 요청 검증(tcp_check_req) -> 드롭”까지의 세부 경로를 보여줍니다. 핵심은 마지막에 TCP 계층에서 해당 패킷이 처리 중 “요청 검증 단계에서 드롭”되었다는 점입니다.

핵심 흐름 해석

• nf_hook_slow -> nf_checksum/nf_ip_checksum
  • 넷필터 훅(주로 PREROUTING/LOCAL_IN)에서 체크섬 검사를 포함한 기본 검증을 수행. 여기서 DROP된 흔적은 보이지 않습니다.
• tcp_v4_early_demux -> ip_route_input_{noref,slow} -> fib_validate_source/_fib_validate_source
  • 라우팅 결정 및 소스 유효성 검증(RP 필터 경로). 통과했기 때문에 이후 로컬 딜리버리로 진행됩니다.
• ip_local_deliver -> ip_local_deliver_finish -> ip_protocol_deliver_rcu
  • 로컬 호스트(10.111.43.38) 대상 패킷으로 확정되어 상위(TCP)로 전달.
• raw_local_deliver/raw_v4_input
  • RAW 소켓이 붙어 있다면 먼저 전달. 이어서 TCP로 진입.
• sk_filter_trim_cap -> security_sock_rcv_skb -> selinux_socket_sock_rcv_skb -> bpf_lsm_socket_sock_rcv_skb
  • 소켓 레벨의 BPF/LSM/SELinux 훅 및 소켓 필터가 실행. 여기서 거부 흔적은 보이지 않습니다.
• tcp_v4_rcv -> tcp_v4_fill_cb -> tcp_check_req
  • TCP 제어블록 설정 후, “요청 검증” 경로로 진입. 이는 보통 다음 두 경우에 해당:
  • LISTEN 중인 소켓이 받은 SYN에 대해 생성된 request_sock에 대해 후속 패킷(주로 ACK)을 검증할 때
  • SYN cookies/백로그/상태 일치 여부 등 조건을 확인
• sk_skb_reason_drop(SKB_DROP_REASON_NOT_SPECIFIED) -> skb_release_* -> kfree_skbmem
  • 검증 단계에서 조건 불일치 혹은 처리 불가로 판단되어 TCP가 skb를 드롭하고 메모리를 해제함을 의미합니다.

2 텍스트

무엇이 드롭을 유발했을 가능성이 큰가?

• tcp_check_req 단계에서의 드롭 원인 후보:
  • 예상치 못한 ACK/RST: 기존 요청(request_sock)과 매칭되지 않는 ACK(예: 초과 지연, 틀린 ISN/윈도우, 이미 타임아웃 등)
  • SYN cookie 검증 실패: SYN cookies 사용 시, 이후 ACK가 쿠키 조건과 맞지 않으면 드롭
  • 백로그/큐 상태 문제로 요청이 소멸된 뒤 도착한 후속 패킷(ACK) -> 매칭 실패로 드롭
  • 중복/재전송 상황에서 윈도우/상태 불일치
• 킬러 단서:
  • 이전에 60바이트(SYN+옵션) 패킷이 보였고, 여기서는 20바이트(옵션 없는) 패킷이 관찰됩니다. 20바이트는 “순수 ACK” 혹은 “RST”일 확률이 큽니다. 이 순수 ACK가 기존 요청과 맞지 않으면 tcp_check_req에서 드롭되는 전형적인 패턴과 부합합니다.

중요한 점

• 넷필터(nf_hook_slow)나 SELinux/BPF 훅에서 DROP된 흔적은 없고, 최종적으로 TCP 레이어에서 드롭되었습니다.
• 즉, 방화벽/SELinux 차단이 아니라 “TCP 상태/요청 매칭 불일치” 계열의 이유로 커널 TCP가 폐기한 것으로 해석하는 것이 타당합니다.
• cpuidle_enter/do_idle 계열 콜스택 항목들은 인터럽트/소프트IRQ 진입 전/후의 CPU 아이들 경로로, 패킷 처리 자체의 성공/실패와 직접적인 상관은 없습니다.

진단을 확정하려면 필요한 것

• 패킷 플래그/시퀀스 확인
  • tcpdump/pcap으로 해당 시간대 플래그와 시퀀스/ACK 번호를 확인하면 원인 판별이 빨라집니다.
  • 예: tcpdump -i bond1 -nnvv 'host 10.111.43.21 and port 22'
  • 확인 포인트: SYN -> SYN-ACK -> ACK의 3차 핸드셰이크가 완결되는지, ACK 번호가 합당한지, RST가 오는지.
• SYN cookies/백로그 상태
  • sysctl net.ipv4.tcp_syncookies 값 확인(1이면 활성).
  • 백로그: ss -lnt sport = :22로 큐 상태, somaxconn, tcp_max_syn_backlog 설정 확인.

3 텍스트

• conntrack/상태 관찰
  • conntrack -L | grep '10.111.43.21.*22'로 세션 상태를 살펴보고, SYN-RECV/SYN-SENT/ESTABLISHED로 전이되는지 확인.
• 서버/클라이언트 재전송/지연
  • RTT가 큰 환경이나 패킷 손실이 있을 경우, request_sock 타임아웃 이후 ACK 도착 -> 드롭 시나리오가 발생할 수 있습니다. 인터페이스/링크 오류 카운터(ethtool -S)도 점검.

정리

• 이 트레이스 상의 패킷은 넷필터·SELinux를 통과해 TCP까지 왔지만, tcp_check_req 단계에서 조건 불일치로 드롭되었습니다.
• 가장 가능성 높은 원인은 “예상과 맞지 않는 ACK(또는 상태 불일치)”이고, SYN cookie/백로그/타이밍 문제와 연관될 수 있습니다.
• 패킷 캡처로 플래그/시퀀스, 시스템의 syncookies/백로그 설정, 그리고 네트워크 품질을 함께 확인하면 원인을 특정할 수 있습니다. 필요하시면 tcpdump 결과 일부(특히 SYN/SYN-ACK/ACK 시퀀스)와 sysctl -a | egrep 'tcp_syncookies|somaxconn|tcp_max_syn_backlog' 출력, ss -lnt sport = :22 결과를 공유해 주세요.

4 텍스트

상황 정리

• 커널 트레이스상으로는 해당 패킷이 NIC -> 본딩 -> Netfilter(PREROUTING/LOCAL_IN) -> 라우팅/소스검증 -> TCP로 올라온 뒤, tcp_check_req 단계에서 드롭되었습니다.
• 그런데 수신측에서 tcpdump가 “아무 것도 안 찍힌다”면, 보통은 캡처 인터페이스/네임스페이스/필터/오프로드 등의 이유로 캡처 지점에서 패킷을 못 보고 있을 가능성이 큽니다(실제로 패킷이 없는 상황이 아니라면).

왜 tcpdump가 안 보일 수 있나(가능성) 1) 본딩 인터페이스에서 캡처함

• 리눅스 본딩(특히 active-backup 등) 환경에서는 RX 패킷이 물리 슬레이브에서 처리되고, 가상 인터페이스(bond1)에서 tcpdump가 잘 안 보이는 경우가 흔합니다.
• 트레이스에 ens5f1np1:7와 bond1:2가 교차로 등장하므로, 실제 수신은 ens5f1np1(슬레이브)에서 이루어졌을 가능성이 큽니다.

2) 잘못된 캡처 인터페이스/네임스페이스

• 컨테이너/네트워크 네임스페이스에서 tcpdump를 실행하면 호스트 NIC 트래픽이 안 보입니다.
• VLAN이 사용되는데 bond1.<vlan>이 아닌 bond1에서 캡처하면 놓칠 수 있습니다.

3) 필터/오프로드 영향

• VLAN 태그가 있는 경우 BPF 필터가 매칭을 놓칠 수 있습니다.
• GRO/LRO 등으로 인해 세그먼트가 합쳐져 보이거나 체크섬 오프로딩이 표시를 왜곡할 수 있지만, SYN 자체가 “아예 안 보이는” 현상을 설명하진 못합니다. 다만 진단 시 혼동 요소이므로 필요시 비활성화 권고.

먼저 확인할 것

• 현재 활성 슬레이브 확인:

  cat /proc/net/bonding/bond1

• 네임스페이스 확인(호스트에서 실행 중인지):

  ip netns identify $$

• VLAN 사용 여부:

  ip -d link show bond1

권장 캡처 방법(하나씩 시도) 1) 슬레이브 NIC에서 캡처

sudo tcpdump -i ens5f1np1 -nnvv -Q in 'host 10.111.43.21 and port 22'

• active-backup이면 활성 슬레이브에서만 보입니다. balance-xor/rr 등 LACP 모드에서도 RX는 특정 슬레이브로만 들어옵니다.

2) 모든 인터페이스에서 캡처(네임스페이스/인터페이스 문제 회피)

sudo tcpdump -i any -nnvv 'host 10.111.43.21 and port 22'

3) VLAN 가능성 고려(캡처 출력에 VLAN 헤더 표시)

sudo tcpdump -i ens5f1np1 -nnvv -e -Q in 'vlan and host 10.111.43.21 and port 22'

4) 패킷 손실/오프로드 혼선 최소화(임시)

# 필요 시 일시적으로만 비활성화(테스트 후 원복)
sudo ethtool -K ens5f1np1 gro off lro off gso off tso off rxhash off

5) 캡처를 파일로 저장해 사후 분석

sudo tcpdump -i ens5f1np1 -nn -s 0 -U -w /tmp/ssh_rx.pcap 'host 10.111.43.21 and port 22'

보조 진단

• NIC 카운터 증가 여부(수신이 실제 들어오는지):

  ethtool -S ens5f1np1 | egrep 'rx_.*pack|rx_.*err|rx_.*drop'

• 커널 드롭 위치 추적(드롭워치):

  sudo dropwatch -l kas

• conntrack/핸드세이크 상태:

  sudo conntrack -L | grep '10.111.43.21.*dport=22'

해석 가이드

• 위 캡처 중 하나라도 SYN 또는 ACK가 보이면, 커널 트레이스와 일치합니다. 이후 SYN -> SYN-ACK -> ACK 흐름이 정상인지 확인하세요.
• 여전히 아무 것도 안 보인다면:
  • 캡처를 실행하는 위치(호스트 vs 컨테이너/네임스페이스), 인터페이스 선택(특히 슬레이브 NIC), VLAN 인터페이스 여부가 가장 유력합니다.
  • 본딩 모드/슬레이브 상태와 일치하는 곳에서 캡처하는지 재확인해 주세요. 필요하시면 현재 본딩 설정(cat /proc/net/bonding/bond1)과 실행 중인 tcpdump 명령 줄을 알려주세요. 환경에 맞춰 캡처 지점을 정확히 짚어 드리겠습니다.

저장 경로 구조: ///// manifest.json files/ file-001.parquet file-002.parquet ...

parquet 컬럼: Bucket, Key, SequenceNumber, Size, LastModifiedDate

사용법:

기본 (최신 timestamp 자동 선택)

python aistor_inventory_analyzer.py \ --endpoint play.min.io:9000 \ --access-key Q3AM3UQ867SPQQA43P2F \ --secret-key zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG \ --dest-bucket inventory-reports \ --source-bucket devops-test \ --inventory-id my-job-id \ --depth 2

.env 파일 또는 환경변수로 인증 정보 관리 (권장)

export AISTOR_ENDPOINT=play.min.io:9000 export AISTOR_ACCESS_KEY=... export AISTOR_SECRET_KEY=... python aistor_inventory_analyzer.py \ --dest-bucket inventory-reports \ --source-bucket devops-test \ --inventory-id my-job-id \ --depth 2

특정 timestamp 지정 (생략 시 최신 자동 선택)

python aistor_inventory_analyzer.py ... --timestamp 2025-01-15T03-00Z

구조 확인만 (분석 없이 어떤 job/timestamp가 있는지 확인)

python aistor_inventory_analyzer.py ... --list-jobs python aistor_inventory_analyzer.py ... --info-only """

import argparse import io import json import os import sys

try: import pandas as pd import pyarrow.parquet as pq from minio import Minio from minio.error import S3Error except ImportError as e: print(f"[ERROR] 필수 패키지 부족: {e}") print(" pip install minio pyarrow pandas tabulate") sys.exit(1)

try: from tabulate import tabulate HAS_TABULATE = True except ImportError: HAS_TABULATE = False

──────────────────────────────────────────────────────────

유틸

──────────────────────────────────────────────────────────

def human_size(n: float) -> str: if pd.isna(n) or n == 0: return "0 B" for unit in ("B", "KB", "MB", "GB", "TB", "PB"): if abs(n) < 1024.0: return f"{n:,.2f} {unit}" n /= 1024.0 return f"{n:,.2f} EB"

def make_client(endpoint: str, access_key: str, secret_key: str, secure: bool) -> Minio: return Minio( endpoint, access_key=access_key, secret_key=secret_key, secure=secure, )

──────────────────────────────────────────────────────────

MinIO 경로 탐색

──────────────────────────────────────────────────────────

def list_jobs(client: Minio, dest_bucket: str, prefix: str, source_bucket: str) -> dict[str, list[str]]: """ dest_bucket 안에서 source_bucket 하위의 inventory job ID와 각 job의 timestamp 목록을 반환합니다.

탐색 경로: <prefix>/<source_bucket>/<job_id>/<timestamp>/manifest.json
"""
base = f"{prefix}/{source_bucket}/" if prefix else f"{source_bucket}/"
base = base.lstrip("/")

jobs: dict[str, list[str]] = {}
try:
    objects = client.list_objects(dest_bucket, prefix=base, recursive=True)
    for obj in objects:
        key = obj.object_name  # e.g. "reports/devops-test/my-job/2025-01-15T03-00Z/manifest.json"
        if not key.endswith("manifest.json"):
            continue
        # base 이후 파트: <job_id>/<timestamp>/manifest.json
        rel = key[len(base):]
        parts = rel.split("/")
        if len(parts) >= 3:
            job_id, timestamp = parts[0], parts[1]
            jobs.setdefault(job_id, []).append(timestamp)
except S3Error as e:
    sys.exit(f"[ERROR] 버킷 조회 실패: {e}")

# timestamp 최신순 정렬
for jid in jobs:
    jobs[jid] = sorted(jobs[jid], reverse=True)
return jobs

def resolve_manifest_key(prefix: str, source_bucket: str, inventory_id: str, timestamp: str) -> str: """manifest.json의 오브젝트 키 조립""" parts = [p for p in [prefix, source_bucket, inventory_id, timestamp, "manifest.json"] if p] return "/".join(parts)

def read_manifest(client: Minio, dest_bucket: str, manifest_key: str) -> dict: """manifest.json 읽기""" try: resp = client.get_object(dest_bucket, manifest_key) data = json.loads(resp.read().decode("utf-8")) resp.close() return data except S3Error as e: sys.exit(f"[ERROR] manifest 읽기 실패 ({manifest_key}): {e}")

def resolve_parquet_keys(manifest: dict, dest_bucket: str, prefix: str, source_bucket: str, inventory_id: str, timestamp: str) -> list[str]: """ manifest의 files 목록에서 parquet 오브젝트 키 목록을 반환. manifest의 key 필드가 절대경로면 그대로, 상대경로면 base_path 를 앞에 붙임. """ files = manifest.get("files", []) if not files: sys.exit("[ERROR] manifest에 files 항목이 없습니다.")

keys = []
base = "/".join(p for p in [prefix, source_bucket, inventory_id, timestamp, "files"] if p)

for f in files:
    # f 는 {"key": "...", "size": ...} 또는 문자열일 수 있음
    raw_key = f["key"] if isinstance(f, dict) else str(f)

    # 절대 경로(버킷명 포함) vs 상대 경로 처리
    if raw_key.startswith(dest_bucket + "/"):
        raw_key = raw_key[len(dest_bucket) + 1:]

    # 상대 경로인 경우 base 앞에 붙임
    if not raw_key.startswith(source_bucket) and not raw_key.startswith(prefix or source_bucket):
        obj_key = f"{base}/{raw_key.lstrip('/')}"
    else:
        obj_key = raw_key

    keys.append(obj_key)

return keys

──────────────────────────────────────────────────────────

원격 parquet 스트리밍 읽기

──────────────────────────────────────────────────────────

def stream_parquet(client: Minio, dest_bucket: str, object_key: str) -> pd.DataFrame: """ MinIO에서 parquet 파일을 메모리로 스트리밍하여 DataFrame 반환. 256 MB 파일도 청크 없이 pyarrow가 처리 (columnar 포맷 특성상 효율적). """ try: resp = client.get_object(dest_bucket, object_key) buf = io.BytesIO(resp.read()) resp.close() except S3Error as e: print(f" [WARN] 파일 읽기 실패, 건너뜀 ({object_key}): {e}") return pd.DataFrame()

try:
    table = pq.read_table(buf)
    return table.to_pandas()
except Exception as e:
    print(f"  [WARN] parquet 파싱 실패, 건너뜀 ({object_key}): {e}")
    return pd.DataFrame()

def load_all_parquets(client: Minio, dest_bucket: str, parquet_keys: list[str]) -> pd.DataFrame: """모든 parquet 파일을 순차 스트리밍 후 병합""" dfs = [] total = len(parquet_keys) for i, key in enumerate(parquet_keys, 1): fname = key.split("/")[-1] print(f" [{i}/{total}] {fname} 읽는 중...", end=" ", flush=True) df = stream_parquet(client, dest_bucket, key) if not df.empty: print(f"{len(df):,} rows") dfs.append(df) else: print("(건너뜀)")

if not dfs:
    sys.exit("[ERROR] 읽을 수 있는 parquet 파일이 없습니다.")

result = pd.concat(dfs, ignore_index=True)
print(f"\n[INFO] 총 {len(result):,} rows 로드 완료")
return result

──────────────────────────────────────────────────────────

Key → prefix 파생

──────────────────────────────────────────────────────────

def extract_prefix_at_depth(key: str, depth: int) -> str: """ Key의 디렉토리 경로를 depth 단계까지 잘라 prefix 반환.

예) key='logs/2024/01/app.log', depth=2  →  'logs/2024/'
    key='top-level.txt',       depth=1  →  '(root)'
"""
parts = key.rstrip("/").split("/")
dir_parts = parts[:-1]   # 파일명(마지막) 제외
if len(dir_parts) < depth:
    return "(root)"
return "/".join(dir_parts[:depth]) + "/"

──────────────────────────────────────────────────────────

분석

──────────────────────────────────────────────────────────

def analyze(df: pd.DataFrame, depth: int, bucket_filter: str = None, prefix_filter: str = None, sort_by: str = "size", top_n: int = None) -> pd.DataFrame:

work = df.copy()

if bucket_filter:
    work = work[work["Bucket"] == bucket_filter]
    if work.empty:
        print(f"[WARN] 버킷 '{bucket_filter}' 데이터 없음")
        print(f"[INFO] 버킷 목록: {sorted(df['Bucket'].dropna().unique())}")
        return pd.DataFrame()

if prefix_filter:
    work = work[work["Key"].str.startswith(prefix_filter, na=False)]
    if work.empty:
        print(f"[WARN] prefix '{prefix_filter}' 에 해당하는 Key 없음")
        return pd.DataFrame()

work["_prefix"] = work["Key"].apply(lambda k: extract_prefix_at_depth(str(k), depth))

result = (
    work.groupby(["Bucket", "_prefix"], as_index=False)
    .agg(object_count=("Key", "count"), total_bytes=("Size", "sum"))
    .rename(columns={"_prefix": "prefix"})
)

result["avg_object_size"] = (
    result["total_bytes"] / result["object_count"].replace(0, float("nan"))
)
tot_obj   = result["object_count"].sum()
tot_bytes = result["total_bytes"].sum()
result["object_pct"] = (result["object_count"] / tot_obj   * 100).round(2)
result["size_pct"]   = (result["total_bytes"]   / tot_bytes * 100).round(2)

sort_col = {"size": "total_bytes", "count": "object_count", "prefix": "prefix"}[sort_by]
result = result.sort_values(sort_col, ascending=(sort_col == "prefix")).reset_index(drop=True)

if top_n:
    result = result.head(top_n)
return result

──────────────────────────────────────────────────────────

출력

──────────────────────────────────────────────────────────

def print_result(result: pd.DataFrame, depth: int, fmt: str) -> None: if result.empty: print("[INFO] 출력할 결과가 없습니다.") return

tot_obj   = result["object_count"].sum()
tot_bytes = result["total_bytes"].sum()

print("\n" + "=" * 72)
print(f"  AIStor iNVENTORY 분석  |  depth = {depth}")
print("=" * 72)
print(f"  prefix 수      : {len(result):,}개")
print(f"  총 object 수   : {tot_obj:,}개")
print(f"  총 데이터 크기 : {human_size(tot_bytes)}")
print("=" * 72 + "\n")

if fmt == "json":
    print(result.to_json(orient="records", indent=2, force_ascii=False))
    return
if fmt == "csv":
    print(result.to_csv(index=False))
    return

disp = result.assign(
    total_size = result["total_bytes"].apply(human_size),
    avg_size   = result["avg_object_size"].apply(
                     lambda x: human_size(x) if not pd.isna(x) else "-"),
    obj_pct    = result["object_pct"].apply(lambda x: f"{x:.1f}%"),
    size_pct   = result["size_pct"].apply(lambda x: f"{x:.1f}%"),
)[[
    "Bucket", "prefix", "object_count", "total_size", "avg_size", "obj_pct", "size_pct",
]].rename(columns={
    "Bucket": "버킷", "prefix": "Prefix", "object_count": "객체 수",
    "total_size": "총 크기", "avg_size": "평균 크기",
    "obj_pct": "객체 비율", "size_pct": "크기 비율",
})

if HAS_TABULATE:
    print(tabulate(disp, headers="keys", tablefmt="rounded_outline",
                   showindex=True, numalign="right"))
else:
    print(disp.to_string(index=True))
    print("\n[TIP] pip install tabulate  →  더 예쁜 테이블 출력")

def print_info(df: pd.DataFrame) -> None: print("\n" + "─" * 54) print(" 데이터셋 기본 정보") print("─" * 54) print(f" 총 object 수 : {len(df):,}") print(f" 컬럼 : {list(df.columns)}") print(f" 총 데이터 크기: {human_size(df['Size'].sum())}") print(f" 버킷 목록 : {sorted(df['Bucket'].dropna().unique().tolist())}") print("\n depth별 unique prefix 수:") for d in range(1, 7): n = df["Key"].apply(lambda k: extract_prefix_at_depth(str(k), d)).nunique() print(f" depth={d}: {n:>8,}개 prefix") print("─" * 54) print("[TIP] --depth 값을 위 표를 참고해 선택하세요.\n")

def save_result(result: pd.DataFrame, path: str, fmt: str) -> None: if fmt == "json": result.to_json(path, orient="records", indent=2, force_ascii=False) else: result.to_csv(path, index=False, encoding="utf-8-sig") print(f"[INFO] 저장 완료: {path}")

──────────────────────────────────────────────────────────

CLI

──────────────────────────────────────────────────────────

def parse_args(): p = argparse.ArgumentParser( description="AIStor iNVENTORY parquet를 원격에서 직접 읽어 depth별 prefix 집계", formatter_class=argparse.RawDescriptionHelpFormatter, epilog=""" 환경변수 (--access-key/--secret-key 대신 사용 가능): AISTOR_ENDPOINT MinIO endpoint (예: minio.example.com:9000) AISTOR_ACCESS_KEY 액세스 키 AISTOR_SECRET_KEY 시크릿 키

예시:

job 목록과 timestamp 확인

python aistor_inventory_analyzer.py \ --endpoint minio.example.com:9000 \ --access-key AKID --secret-key SKID \ --dest-bucket inventory-reports --source-bucket devops-test \ --list-jobs

최신 timestamp 자동 선택, depth=2 분석

python aistor_inventory_analyzer.py \ --endpoint minio.example.com:9000 \ --access-key AKID --secret-key SKID \ --dest-bucket inventory-reports --source-bucket devops-test \ --inventory-id my-job-id --depth 2

특정 timestamp 지정, Top 30, CSV 저장

python aistor_inventory_analyzer.py \ --endpoint minio.example.com:9000 \ --access-key AKID --secret-key SKID \ --dest-bucket inventory-reports --source-bucket devops-test \ --inventory-id my-job-id \ --timestamp 2025-01-15T03-00Z \ --depth 3 --sort-by size --top 30 --save result.csv

prefix 드릴다운 + JSON 출력

python aistor_inventory_analyzer.py ... \ --inventory-id my-job-id --depth 4 \ --prefix-filter logs/2024/ -o json """, )

# 연결 정보
conn = p.add_argument_group("MinIO 연결 정보")
conn.add_argument("--endpoint",   "-e",
                  default=os.environ.get("AISTOR_ENDPOINT"),
                  help="MinIO endpoint (예: minio.example.com:9000)")
conn.add_argument("--access-key",
                  default=os.environ.get("AISTOR_ACCESS_KEY"),
                  help="액세스 키 (환경변수 AISTOR_ACCESS_KEY 도 가능)")
conn.add_argument("--secret-key",
                  default=os.environ.get("AISTOR_SECRET_KEY"),
                  help="시크릿 키 (환경변수 AISTOR_SECRET_KEY 도 가능)")
conn.add_argument("--no-tls",     action="store_true",
                  help="TLS 비활성화 (http 접속)")

# 경로 정보
path = p.add_argument_group("inventory 경로")
path.add_argument("--dest-bucket",   required=True,
                  help="inventory 결과가 저장된 버킷명")
path.add_argument("--prefix",        default="",
                  help="dest-bucket 안의 prefix (설정 YAML의 destination.prefix, 없으면 생략)")
path.add_argument("--source-bucket", required=True,
                  help="인벤토리를 생성한 원본 버킷명")
path.add_argument("--inventory-id",
                  help="inventory job ID (--list-jobs 생략 시 필수)")
path.add_argument("--timestamp",     default=None,
                  help="특정 실행 timestamp (예: 2025-01-15T03-00Z). 생략 시 최신 자동 선택")

# 분석 옵션
ana = p.add_argument_group("분석 옵션")
ana.add_argument("--depth",         "-d", type=int,
                 help="분석할 prefix depth (1~)")
ana.add_argument("--bucket-filter", "-b", default=None,
                 help="특정 Bucket 컬럼 값으로 필터")
ana.add_argument("--prefix-filter",       default=None,
                 help="Key prefix 필터 (예: logs/2024/)")
ana.add_argument("--sort-by",
                 choices=["size", "count", "prefix"], default="size")
ana.add_argument("--top",           type=int, default=None,
                 help="상위 N개만 출력")
ana.add_argument("--output", "-o",
                 choices=["table", "csv", "json"], default="table")
ana.add_argument("--save",   "-s",  default=None,
                 help="결과 저장 경로")

# 탐색 모드
p.add_argument("--list-jobs",  action="store_true",
               help="job ID / timestamp 목록만 출력하고 종료")
p.add_argument("--info-only",  action="store_true",
               help="데이터 로드 후 스키마/depth 분포만 출력")

return p.parse_args()

def main(): args = parse_args()

# 연결 정보 검증
if not args.endpoint:
    sys.exit("[ERROR] --endpoint 또는 환경변수 AISTOR_ENDPOINT 가 필요합니다.")
if not args.access_key or not args.secret_key:
    sys.exit("[ERROR] --access-key / --secret-key 또는 환경변수가 필요합니다.")

client = make_client(
    args.endpoint,
    args.access_key,
    args.secret_key,
    secure=not args.no_tls,
)

# ── --list-jobs ──────────────────────────────────────
if args.list_jobs:
    print(f"\n[INFO] '{args.dest_bucket}' 버킷의 inventory job 목록 조회 중...")
    jobs = list_jobs(client, args.dest_bucket, args.prefix, args.source_bucket)
    if not jobs:
        print("[INFO] inventory job을 찾을 수 없습니다.")
        return
    print(f"\n{'Job ID':<40}  {'Timestamp (최신순)'}")
    print("─" * 72)
    for jid, timestamps in sorted(jobs.items()):
        for i, ts in enumerate(timestamps):
            label = jid if i == 0 else ""
            latest = " ← 최신" if i == 0 else ""
            print(f"{label:<40}  {ts}{latest}")
    print()
    return

# ── inventory-id 필수 확인 ────────────────────────────
if not args.inventory_id:
    sys.exit("[ERROR] --inventory-id 가 필요합니다. --list-jobs 로 목록을 먼저 확인하세요.")

# ── timestamp 자동 선택 ───────────────────────────────
timestamp = args.timestamp
if not timestamp:
    print("[INFO] --timestamp 미지정 → 최신 timestamp 자동 선택 중...")
    jobs = list_jobs(client, args.dest_bucket, args.prefix, args.source_bucket)
    ts_list = jobs.get(args.inventory_id, [])
    if not ts_list:
        sys.exit(f"[ERROR] inventory-id '{args.inventory_id}' 를 찾을 수 없습니다.")
    timestamp = ts_list[0]
    print(f"[INFO] 선택된 timestamp: {timestamp}")

# ── manifest 읽기 ─────────────────────────────────────
manifest_key = resolve_manifest_key(
    args.prefix, args.source_bucket, args.inventory_id, timestamp
)
print(f"[INFO] manifest 읽기: {args.dest_bucket}/{manifest_key}")
manifest = read_manifest(client, args.dest_bucket, manifest_key)

fmt = manifest.get("fileFormat", "parquet").lower()
if fmt != "parquet":
    sys.exit(f"[ERROR] 이 도구는 parquet 포맷만 지원합니다. (현재 포맷: {fmt})")

print(f"[INFO] sourceBucket : {manifest.get('sourceBucket', '?')}")
print(f"[INFO] inventoryId  : {manifest.get('inventoryId', '?')}")
print(f"[INFO] createdAt    : {manifest.get('createdAt', '?')}")
file_count = len(manifest.get("files", []))
print(f"[INFO] parquet 파일 : {file_count}개\n")

# ── parquet 키 목록 ───────────────────────────────────
parquet_keys = resolve_parquet_keys(
    manifest, args.dest_bucket,
    args.prefix, args.source_bucket,
    args.inventory_id, timestamp,
)

# ── 스트리밍 로드 ─────────────────────────────────────
df = load_all_parquets(client, args.dest_bucket, parquet_keys)

# 타입 정규화
df["Size"] = pd.to_numeric(df["Size"], errors="coerce").fillna(0)

# ── --info-only ───────────────────────────────────────
if args.info_only:
    print_info(df)
    return

if not args.depth:
    sys.exit("[ERROR] --depth 가 필요합니다. --info-only 로 depth 분포를 먼저 확인하세요.")

# ── 분석 & 출력 ───────────────────────────────────────
result = analyze(
    df,
    depth=args.depth,
    bucket_filter=args.bucket_filter,
    prefix_filter=args.prefix_filter,
    sort_by=args.sort_by,
    top_n=args.top,
)

print_result(result, args.depth, args.output)

if args.save and not result.empty:
    save_result(result, args.save, args.output)

if name == "main": main()

교수님의 상황(MinIO에서 가져온 인벤토리 파일 처리)에서는 Pandas를 사용하는 것이 가장 유연하고 안정적입니다.

1. Pandas를 사용하여 합치기 (추천)

두 파일을 데이터프레임으로 읽어와서 pd.concat 함수를 사용합니다. 컬럼 구조가 동일할 때 가장 확실한 방법입니다.

import pandas as pd

# 두 개의 Parquet 파일 읽기
df1 = pd.read_parquet('file1.parquet')
df2 = pd.read_parquet('file2.parquet')

# 세로로 합치기 (Row append)
combined_df = pd.concat([df1, df2], ignore_index=True)

# 합쳐진 결과를 새로운 파일로 저장
combined_df.to_parquet('combined_result.parquet', engine='pyarrow')

2. 여러 개의 파일을 한 번에 읽기 (Glob 패턴)

만약 devops/ 버킷 안에 여러 날짜의 Parquet 파일이 흩어져 있다면, 하나씩 읽을 필요 없이 리스트를 전달하여 한 번에 합칠 수 있습니다.

import pandas as pd
import glob

# 특정 패턴의 모든 파일 경로 가져오기
files = glob.glob('inventory_*.parquet')

# 리스트 컴프리헨션으로 한 번에 합치기
combined_df = pd.concat([pd.read_parquet(f) for f in files], ignore_index=True)

3. PyArrow를 사용하여 합치기 (대용량인 경우)

데이터가 수천만 건 이상으로 매우 커서 Pandas가 무겁게 느껴진다면, 더 하위 레벨 라이브러리인 pyarrow를 직접 사용하는 것이 메모리 효율적입니다.

import pyarrow.parquet as pq
import pyarrow as pa

# 테이블 형태로 읽기
table1 = pq.read_table('file1.parquet')
table2 = pq.read_table('file2.parquet')

# 테이블 합치기 (메모리 복사를 최소화함)
combined_table = pa.concat_tables([table1, table2])

# 저장
pq.write_table(combined_table, 'combined_result.parquet')

💡 MinIO 환경에서의 팁

앞서 만드신 프로그램에 적용하신다면, client.get_object로 가져온 두 개의 스트림을 각각 데이터프레임으로 변환한 뒤 pd.concat 하시면 됩니다.

주의할 점:

• 컬럼 불일치: 두 파일의 컬럼명이 다르면 NaN 값이 생성될 수 있으니 합치기 전 df.columns로 구조를 확인하는 것이 좋습니다.
• 인덱스 중복: ignore_index=True 옵션을 주어야 합친 후에 인덱스가 0, 1, 2... 0, 1, 2처럼 꼬이지 않고 깔끔하게 정리됩니다.

파일을 합치는 과정에서 특정 날짜별로 데이터를 구분해야 한다면, 합치기 전에 df['source_date'] = '2026-04-10' 같은 식으로 컬럼을 하나 추가해 두는 것도 좋은 관리 방법입니다.