RCA 플랫폼을 관리 가능한 형태로 다듬기

Kubernetes Cluster Infra RCA Platform 개발 기록 6편

지난 글에서는 Backend, DB, Web Console을 Docker Compose로 묶으면서 로컬에서도 RCA 플랫폼 전체를 실행할 수 있게 만든 과정을 정리했습니다.

이제 프로젝트는 단순한 API 서버나 실험용 코드에서 조금 벗어나, 하나의 플랫폼처럼 실행될 수 있는 형태에 가까워졌습니다.

그 다음에는 기능을 크게 늘리기보다, 실제로 관리 가능한 형태로 다듬는 작업이 필요했습니다.

이번 글에서는 여러 작업을 하나로 압축해서 정리해보려고 합니다.

핵심은 세 가지였습니다.

1. cluster를 안전하게 삭제할 수 있게 만들기
2. RCA report를 export할 수 있게 만들기
3. README와 문서를 현재 구조에 맞게 정리하기

cluster 삭제 기능이 필요했던 이유

처음에는 cluster를 등록하는 기능이 더 중요했습니다.

RCA 플랫폼에서는 분석 대상이 되는 Kubernetes 클러스터를 먼저 등록해야 하고, 이후 Agent 설치 정보나 evidence request가 그 cluster를 기준으로 만들어지기 때문입니다.

하지만 등록만 있고 삭제가 없으면 문제가 생깁니다.

테스트용 cluster를 등록했다가 지우지 못하거나, 잘못 등록한 cluster가 계속 남아 있으면 운영 화면이 점점 지저분해집니다.

그래서 cluster 삭제 기능이 필요했습니다.

다만 여기서 중요한 점은, cluster 삭제가 단순한 CRUD 기능처럼 가볍게 다뤄지면 안 된다는 것이었습니다.

cluster를 삭제하면 관련된 node, evidence request, RCA report 같은 데이터에도 영향을 줄 수 있습니다.

그래서 실수로 삭제되지 않게 안전장치를 넣는 방향으로 잡았습니다.

문제:
cluster 삭제가 너무 쉬우면 운영 데이터가 실수로 사라질 수 있음

수정 방향:
삭제 시 cluster 이름 확인
admin 권한 요구
관련 데이터 처리 흐름 명확화

단순히 삭제 API를 만드는 것보다, “누가”, “무엇을”, “정말 삭제하려는지”를 확인하는 것이 더 중요했습니다.

confirm_name을 둔 이유

삭제 기능에서 가장 중요하게 본 것은 실수 방지였습니다.

그래서 cluster를 삭제할 때 단순히 버튼만 누르면 삭제되는 구조는 피하고 싶었습니다.

대신 삭제 대상 cluster 이름을 한 번 더 확인하는 방식을 생각했습니다.

DELETE /api/clusters/{cluster_id}

body:
{
  "confirm_name": "my-cluster"
}

이런 구조를 두면 사용자가 실수로 다른 cluster를 삭제할 가능성을 줄일 수 있습니다.

특히 운영 도구에서는 이런 작은 확인 절차가 생각보다 중요합니다.

편의성은 조금 떨어질 수 있지만, 운영 데이터 삭제 같은 작업에서는 안전성이 더 우선이라고 봤습니다.

RCA report export 기능

다음으로 추가한 것은 RCA report export 기능입니다.

Web Console에서 report를 보는 것도 중요하지만, 운영에서는 report를 밖으로 꺼내야 하는 경우가 많습니다.

예를 들면 이런 상황입니다.

• 장애 보고서로 공유해야 할 때
• 팀 내부 회고 자료로 남겨야 할 때
• incident 기록으로 보관해야 할 때
• 다른 시스템에 첨부해야 할 때
• 포트폴리오나 데모 자료로 정리해야 할 때

그래서 RCA report를 JSON 형태로 export할 수 있게 만들었습니다.

처음에는 PDF나 HTML까지 생각할 수도 있지만, 우선은 구조화된 JSON export가 더 중요하다고 봤습니다.

JSON으로 export하면 나중에 다른 포맷으로 변환하기도 쉽고, 자동화나 연동에도 활용할 수 있습니다.

RCA report
  -> JSON export
  -> 공유 / 보관 / 후처리 가능

이 기능을 넣으면서 report가 단순히 화면에서만 소비되는 정보가 아니라, 운영 기록으로 남을 수 있는 형태에 가까워졌습니다.

운영 도구는 “기록”이 중요하다

RCA 플랫폼을 만들면서 계속 느낀 점은, 장애 분석 도구는 결과를 보여주는 것만으로는 부족하다는 것입니다.

운영에서는 기록이 남아야 합니다.

어떤 장애가 있었고, 어떤 evidence가 수집되었고, 어떤 root cause candidate가 나왔고, 어떤 조치가 추천되었는지 나중에 다시 확인할 수 있어야 합니다.

그래서 report export는 단순한 부가 기능이 아니라 운영 흐름에서 꽤 중요한 기능이라고 생각했습니다.

장애 상황이 끝난 뒤에는 항상 이런 질문이 남습니다.

• 왜 장애가 발생했는가?
• 어떤 근거로 판단했는가?
• 어떤 조치를 검토했는가?
• 비슷한 장애를 다음에 어떻게 줄일 수 있는가?

RCA report가 export 가능해야 이런 회고와 공유가 쉬워집니다.

README를 다시 정리한 이유

기능을 계속 추가하다 보면 README가 금방 실제 코드와 달라집니다.

처음 README에는 프로젝트의 큰 방향만 들어가 있었지만, 시간이 지나면서 구조가 꽤 바뀌었습니다.

Backend, Node Agent, Web Console, Helm Chart, Docker Compose, LLM Analyzer, Policy Engine, report export까지 들어가면서 문서도 다시 정리할 필요가 있었습니다.

README는 단순한 소개 문서가 아닙니다.

이 프로젝트를 처음 보는 사람이 가장 먼저 보는 문서이고, 포트폴리오에서도 프로젝트의 방향을 설명하는 첫 화면입니다.

그래서 README를 현재 구조에 맞게 다시 정리했습니다.

중요하게 정리한 것은 다음과 같습니다.

• 이 프로젝트가 애플리케이션 장애 분석기가 아니라 클러스터/노드/Linux RCA 플랫폼이라는 점
• LLM은 보조 역할이며, 직접 조치를 실행하지 않는다는 점
• Agent는 read-only evidence collector로 시작한다는 점
• Policy Engine이 추천 조치의 위험도를 분류한다는 점
• Docker Compose와 Helm Chart로 실행 및 배포 흐름을 제공한다는 점
• report export와 Web Console로 운영자가 결과를 확인할 수 있다는 점

문서가 정리되면서 프로젝트의 방향도 다시 분명해졌습니다.

Codex를 어떻게 활용했는가

이 단계에서는 반복적인 API 구현과 문서 정리에 Codex를 많이 활용했습니다.

다만 어떤 기능이 필요한지, 어떤 작업이 위험한지, 삭제 기능에 어떤 안전장치를 둬야 하는지는 직접 판단했습니다.

이번 단계의 역할 분담은 이렇게 볼 수 있습니다.

사람:
cluster 삭제 위험성 판단
confirm_name 같은 안전장치 설계
report export가 필요한 이유 정리
README 방향과 표현 검토

Codex:
삭제 API 반복 구현
export 응답 구조 정리
테스트 케이스 보강
README 초안 정리
문장 다듬기

Codex는 속도를 높이는 데 도움이 됐지만, 운영 도구에서 어떤 기능이 위험한지는 결국 사람이 판단해야 한다고 생각했습니다.

특히 삭제 기능은 단순 구현보다 정책과 안전장치가 더 중요했습니다.

이 단계에서 중요했던 점

이번 단계에서 가장 중요했던 것은 “관리 가능성”이었습니다.

기능이 많아지는 것보다, 운영자가 안전하게 관리할 수 있는 구조가 더 중요했습니다.

정리하면 기준은 이랬습니다.

1. cluster 삭제는 admin 권한과 확인 절차를 둔다
2. 삭제는 편의성보다 안전성을 우선한다
3. RCA report는 export 가능해야 한다
4. report는 화면에서 끝나는 정보가 아니라 운영 기록이어야 한다
5. README는 실제 구조와 계속 맞춰야 한다
6. Codex는 반복 구현에 활용하되, 위험 판단은 사람이 한다

개인적으로는 2번과 4번이 가장 중요했습니다.

운영 도구는 쉽게 만들 수 있지만, 쉽게 지우거나 쉽게 오해하게 만들면 안 됩니다.

마무리

이번 단계에서는 RCA 플랫폼을 실제로 관리 가능한 형태에 가깝게 다듬었습니다.

cluster 삭제 기능을 추가하면서 실수 방지를 고려했고, RCA report export를 통해 분석 결과를 운영 기록으로 남길 수 있게 했습니다.

또 README를 현재 구조에 맞게 정리하면서 프로젝트의 방향을 다시 명확히 했습니다.

이제 프로젝트는 단순히 장애를 분석하는 코드가 아니라, 클러스터를 등록하고, 증거를 수집하고, report를 확인하고, 필요하면 export하고, 관리할 수 있는 플랫폼 형태에 가까워졌습니다.

운영 도구는 기능보다 안전한 관리 흐름이 더 중요하다.

다음 글에서는 지금까지 만든 전체 구조를 돌아보면서, 이 프로젝트에서 아쉬웠던 점과 앞으로 보완하고 싶은 기능들을 정리해보려고 합니다.