KubeSage AI: DevOps 팀을 위한 인프라 우선 Kubernetes 플랫폼 운영

가공되지 않은 클러스터 텔레메트리(telemetry)를 실행 가능한 해결책으로 전환하는 Kubernetes 장애 조사 플랫폼 구축.

서론 (Introduction)

KubeSage AI는 클러스터 전반의 진단 데이터를 수집하고, 이를 GitOps 및 관측성(observability) 스택과 상관 분석하여, 플랫폼 엔지니어가 실제로 조치할 수 있는 해결 가이드로 변환하는 Kubernetes 장애 조사 플랫폼입니다.

저는 인프라 우선 플랫폼 엔지니어링(infrastructure-first platform engineering)의 의도적인 연습으로서 백엔드, 프론트엔드, 그리고 이들을 하나로 묶는 분석 엔진까지 이 엔드투엔드(end-to-end) 시스템을 직접 구축하고 설계했습니다. 이는 단순히 더 많은 데이터를 보여주는 또 다른 대시보드가 아닙니다. 모든 온콜(on-call) 엔지니어가 새벽 3시에 실제로 던지는 질문, 즉 _"이 상황에서 내가 무엇을 해야 하는가?"_에 대한 답을 찾는 데 도움을 주는 시스템입니다.

클라우드 네이티브 인프라 근처에서 일하고 있다면, 이 프로젝트는 여러분이 매일 살아가는 접점인 Kubernetes, GitOps, 코드형 인프라(Infrastructure as Code), 그리고 관측성(observability)이 맞물리는 지점, 즉 압박감이 심한 상황에서 이 네 가지 요소를 동시에 고려해야 할 때 발생하는 문제들을 다룹니다.

문제점: 텔레메트리(Telemetry)가 곧 정답은 아니다

실제 규모로 Kubernetes를 운영하는 플랫폼 팀은 반복적으로 동일한 벽에 부딪힙니다. 장애 대응의 한계는 데이터의 부족 때문이 아니라, 상관관계가 분석된(correlated) 데이터의 부족 때문입니다.

하나의 Pod가 CrashLoopBackOff 상태에 빠집니다. 어딘가에서는 Deployment 롤아웃이 진행 중입니다. HPA(Horizontal Pod Autoscaler)가 방금 스케일링을 수행했습니다. 지난주에 Ingress 규칙이 변경되었습니다. Prometheus는 서로 관련이 있는 것처럼 느껴지지만 공식적으로 연결되지 않은 세 가지 알람을 발생시키고 있습니다. 그리고 ArgoCD의 GitOps 상태는 클러스터에서 실제로 실행 중인 상태와 일치할 수도 있고, 그렇지 않을 수도 있습니다.

이런 상황은 전혀 이상한 것이 아닙니다. 평범한 화요일의 일상일 뿐입니다. 정작 부족한 것은 다음 요소들 사이의 연결 고리입니다:

• 가공되지 않은 클러스터 상태 (Raw cluster state) (pods, events, deployments, services, ConfigMaps)
• 관측성 신호 (Observability signals) (metrics, alerts, dashboards)
• 플랫폼 상태 (Platform state) (GitOps와 Terraform이 실행 중이어야 한다고 생각하는 상태)

일반적인 모니터링 도구들은 신호(signals)를 보여주기 위해 만들어졌을 뿐, 이를 종합(synthesize)하기 위해 만들어진 것이 아닙니다. 이러한 격차는 단순한 환경에서는 감내할 수 있는 수준입니다. 하지만 "실행 중인 것"과 "선언된 것"이 조용히 어긋날 수 있고, 장애를 디버깅하는 사람이 Terraform을 작성한 사람이 아닌 경우가 많은 GitOps 및 Terraform 기반 환경에서는 실제로 막대한 비용을 초래하게 됩니다.

그 격차를 메우기 위해 바로 KubeSage AI가 만들어졌습니다.

KubeSage AI가 해결하는 문제

KubeSage AI의 핵심은 다음 세 가지를 수행하는 것입니다:

1. 수집의 통합 (Unifies collection): 엔지니어가 장애 대응 중에 kubectl, Grafana, ArgoCD 사이를 탭을 옮겨 다니며 확인하도록 강요하는 대신, Kubernetes 진단 데이터와 플랫폼 데이터를 하나의 통합된 증거 세트(evidence set)로 통합합니다.
2. 장애 상관관계 분석 (Correlates incidents): Pod, Deployment, 메트릭(metrics), GitOps 상태, 그리고 관측성(observability) 도구 전반에 걸쳐 장애 간의 상관관계를 분석합니다. 이를 통해 시스템이 단순히 고립된 이벤트가 아닌 관계를 이해하도록 합니다.
3. 복구 가이드 생성 (Generates remediation guidance): 일반적인 챗봇의 출력물이 아닌, 실제 DevOps 워크플로우에 맞춰 구조화된, 상관관계가 분석된 증거에 기반한 복구 가이드를 생성합니다.

목표는 엔지니어의 판단을 대체하는 것이 아닙니다. "무언가 잘못되었다"와 "실제로 무슨 일이 일어나고 있으며 어디를 살펴봐야 하는가" 사이의 시간을 단축하는 것입니다. 이 시간은 보통 모든 장애 상황에서 가장 비용이 많이 드는 부분입니다.

주요 기능

Kubernetes 증거 수집 (Kubernetes Evidence Collection)
장애 발생 시 실제로 중요한 객체들에 대해 심층적이고 구조화된 수집을 수행합니다: Pod, Event, Deployment, HPA 상태, Ingress, Service, ConfigMap, Secret 메타데이터(안전하게 — 실제 Secret 값은 제외), PersistentVolume/PVC, 그리고 Network Policy가 포함됩니다.

관측성 통합 (Observability Integration)
플랫폼 팀이 이미 운영 중인 도구들과의 네이티브 통합을 지원합니다: Prometheus, Grafana, Alertmanager와 통합하여, 메트릭을 별도의 조사 대상으로 취급하는 대신 클러스터 상태와 동일한 증거 세트로 실시간 신호를 가져옵니다.

GitOps 및 플랫폼 상태 인식 (Platform State Awareness)
KubeSage AI는 플랫폼 레이어(layer)도 읽어 들입니다: ArgoCD 동기화 상태(sync state), Helm 릴리스(releases), Terraform으로 관리되는 리소스, 그리고 GitHub Actions 파이프라인 컨텍스트(context)를 포함합니다. 이를 통해 선언된 상태(declared state)와 실제 상태(actual state) 사이의 드리프트(drift)를 추론할 수 있으며, 이는 일반적인 모니터링 도구가 놓치기 쉬운 정확한 문제 유형입니다.

장애 분석 및 권장 사항 생성 (Incident Analysis and Recommendation Generation)
증거가 수집되면, 분석 엔진은 이를 상관 분석(correlate)하여 구조화된 권장 사항을 생성합니다. 이는 단순한 원시 로그(raw logs)의 나열이 아니라, 현재 어떤 일이 일어나고 있는지, 그리고 다음에 무엇을 확인하거나 수정해야 하는지에 대한 종합적인 분석 결과입니다.

런북(Runbook), 사후 분석(Postmortem) 및 근본 원인 분석(RCA) 출력
증거 수집이 이미 구조화되어 있기 때문에, KubeSage AI는 조사로부터 직접 런북(runbook) 초안과 사후 분석(postmortem)/근본 원인 분석(RCA) 문서를 생성할 수 있습니다. 이를 통해 장애 대응을 일회성 Slack 스레드가 아닌, 재사용 가능한 조직의 지식으로 전환합니다.

아키텍처 (Architecture)

KubeSage AI는 대시보드에 덧붙여진 모놀리스(monolith)가 아닌, 모듈형 시스템으로 구축되었습니다:

• FastAPI 백엔드 오케스트레이터 (FastAPI backend orchestrator) — 모든 통합 시스템에 걸쳐 증거 수집, 상관 분석 및 분석 요청을 조정합니다.
• React + TypeScript 프론트엔드 대시보드 (React + TypeScript frontend dashboard) — 클러스터 및 플랫폼 상태의 구조화된 보기와 함께, 장애 조사를 위한 채팅 스타일의 운영자 인터페이스를 제공합니다.
• 모델 지원 장애 분석 엔진 (Model-assisted incident analysis engine) — 원시 증거를 순위가 매겨진 설명 가능한 권장 사항으로 변환하는 상관 분석 및 추론 레이어입니다.
• ChromaDB 임베딩을 활용한 지식 저장소 (Knowledge store with ChromaDB embeddings) — 과거의 장애 컨텍스트와 런북 지식을 유지하여, 매번 처음부터 시작하는 대신 과거의 조사가 미래의 조사에 도움을 줄 수 있도록 합니다.
• Docker Compose + Kubernetes 배포 스캐폴딩 (Docker Compose + Kubernetes deployment scaffolding) — 이 플랫폼은 조사 대상이 되는 시스템들과 동일한 방식으로 제공됩니다: 컨테이너화되어 있으며, 로컬 개발에서 클러스터 내 배포까지 명확한 경로를 제공합니다.

전체적인 설계 의도는 다음과 같습니다: 모든 계층은 독립적으로 테스트 가능하고 교체 가능해야 합니다. 즉, 분석 엔진(analysis engine)은 증거가 라이브 클러스터에서 왔는지 아니면 피스처(fixture)에서 왔는지 신경 쓰지 않아야 하며, 프론트엔드(frontend)는 백엔드(backend)가 데이터를 어떻게 가져오는지 신경 쓰지 않아야 합니다.

이것이 DevOps에 중요한 이유

KubeSage AI는 단순히 kubectl get pods 위에 얹혀진 장난감 같은 AI 래퍼(wrapper)가 아닙니다. 이는 인프라 우선 플랫폼 엔지니어링(infrastructure-first platform engineering)을 입증하고 실제로 구현하기 위해 구축되었습니다:

• **IaC, GitOps, 그리고 관측성(observability)**을 세 개의 별도 탭을 가진 세 개의 개별 도구로 취급하는 대신, 하나의 실용적인 조사 워크플로우(investigation workflow)로 연결합니다.
• 주말에 만든 해킹 결과물이 아닌, 프로덕션 플랫폼 도구에서 기대할 수 있는 것과 동일한 표준인 **클린 아키텍처(clean architecture), 모듈형 설계(modular design), 그리고 엔터프라이즈 준비성(enterprise-readiness)**을 염두에 두고 구축되었습니다.
• 실제 플랫폼 팀에서 장애 대응(incident response)이 실제로 어떻게 이루어지는지를 반영합니다: 다중 소스(multi-source)를 활용하며, 시간 압박이 있고, 출력값이 실행 가능한(actionable) 경우에만 유용합니다.

구현 하이라이트

이 프로젝트를 구축하면서 제가 의도적으로 고려한 몇 가지 사항입니다:

• 의존성 주입(dependency injection) 및 리포지토리 패턴(repository pattern)을 적용한 클린 아키텍처 — 데이터 액세스, 비즈니스 로직, 프레젠테이션을 깔끔하게 분리하여 시스템이 성장하더라도 테스트 가능한 상태를 유지합니다.
• 클러스터 및 관측성 통합을 위한 백엔드 어댑터(backend adapters) — 각 통합 요소(Kubernetes API, Prometheus, ArgoCD 등)는 어댑터 뒤에 격리되어 있어, 데이터 소스를 추가하거나 교체하더라도 시스템의 나머지 부분에 파급 효과를 주지 않습니다.
• 프론트엔드 대시보드 및 채팅 스타일의 운영자 인터페이스 — 조사는 대화하듯 느껴지지만, 모든 응답은 자유롭게 떠도는 모델의 출력이 아니라 구조화된 증거에 기반합니다.
• Docker Compose 및 Kubernetes 매니페스트(manifests)를 통한 배포 지원 — 플랫폼은 몇 분 안에 로컬에서 실행할 수 있으며, 별도의 "프로덕션 버전" 없이도 클러스터에 배포할 수 있습니다.

배운 점

이 프로젝트를 통해 제가 다시 한번 확인한 몇 가지 사항입니다:

• 실행 가능한 것이 관찰 가능한 것보다 낫습니다 (Actionable beats observable). 수많은 도구가 현재 무슨 일이 일어나고 있는지 보여줄 수 있습니다. 하지만 그에 대해 무엇을 해야 하는지 알려주는 도구는 훨씬 적습니다. 그것이 더 어렵고 — 더 가치 있는 — 문제입니다.
• 인프라 문맥이 일반적인 AI보다 낫습니다 (Infrastructure context beats generic AI). 여기서의 가치는 단순히 "AI가 클러스터를 분석한다"는 것이 아닙니다. 시스템이 Kubernetes, GitOps, 그리고 IaC를 충분히 깊게 이해하여 애초에 이들을 올바르게 상관 분석(correlate)할 수 있다는 점에 있습니다. 도메인 모델링 (Domain modeling)이 그 어떤 프롬프트보다 더 많은 역할을 수행했습니다.
• 포트폴리오급(Portfolio-grade)은 프로덕션급(production-grade)의 제약 조건을 의미합니다. 시니어 플랫폼 역할에 부합하는 수준으로 이를 구축한다는 것은 아키텍처, 테스트 가능성(testability), 그리고 배포 스토리(deployment story)를 데모 직전에 덧붙이는 부차적인 요소가 아니라, 일급 시민(first-class)으로 취급함을 의미했습니다.

기술 스택 (Technical Stack)

Python · FastAPI · React · TypeScript · Docker · Kubernetes · Helm · Terraform · Prometheus · Grafana · ChromaDB

프로젝트 목표: 프로덕션급(production-grade)이며 확장 가능하고, 시니어 플랫폼 엔지니어링 면접에서 기술적 검증을 견뎌낼 수 있도록 구축되었습니다.

프로젝트 살펴보기

KubeSage AI는 GitHub에 공개되어 있습니다: github.com/theycallmejc/KubeSage-AI

이 프로젝트는 "엄격함을 유지하면서 어떻게 Kubernetes 장애 대응(incident response) 속도를 높일 것인가?"라는 동일한 문제를 고민하는 DevOps 및 플랫폼 엔지니어를 위한 포트폴리오급 레퍼런스 구현체입니다. 프로젝트를 살펴보고, 여러분의 플랫폼 워크플로우에 맞게 조정해 보거나, 아키텍처를 다르게 구성해야 한다고 생각하신다면 이슈(issue)를 제기해 주세요. 진심으로 여러분의 의견을 듣고 싶습니다.