RCA 결과를 운영자가 이해할 수 있게 만들기: Web Console 설계

Kubernetes Cluster Infra RCA Platform 개발 기록 4편

지난 글에서는 Node Agent의 Kubernetes 배포를 위한 DaemonSet, Helm Chart, smoke test를 정리했다.

Agent가 evidence를 모으고 Backend가 RCA report를 만드는 흐름이 어느 정도 잡힌 상태였다.

이제 생성된 결과를 화면에서 어떻게 확인할지 정해야 했다.

장애 상황에서 긴 JSON을 읽는 대신 필요한 결과와 근거를 찾을 수 있도록 Web Console을 붙였다.

목록에서 상황을 파악하고, 상세에서 판단 근거와 다음 확인 항목으로 이어지게 하려고 했다.

---

왜 Web Console이 필요했나

개발 초기에는 API만으로 흐름을 검증했다.

curl로 cluster를 등록하고 evidence request를 만든 뒤 report를 조회하면 최소 동작은 확인할 수 있었다.

실제로 사용할 화면에는 결과를 훑고 근거를 찾아가는 흐름이 필요했다.

확인할 정보는 다음과 같았다.

• 어떤 클러스터에서 문제가 발생했는지
• 어떤 노드가 영향을 받았는지
• RCA report가 언제 생성됐는지
• 원인 후보가 무엇인지
• 어떤 근거로 그렇게 판단했는지
• 추천 조치가 얼마나 위험한지
• 추가로 확인해야 할 것은 무엇인지

Web Console에서 이 정보를 한 흐름으로 볼 수 있도록 구성했다.

---

처음 Console에서 보여주고 싶었던 것

처음부터 대시보드를 크게 만들지는 않았다.

먼저 필요한 정보를 세 화면으로 나눴다.

Cluster 목록
  -> 등록된 클러스터 확인

RCA Report 목록
  -> 최근 장애 분석 결과 확인

RCA Report 상세
  -> 원인 후보, 근거, 추천 조치 확인

요약을 먼저 보여주고 필요할 때 근거로 내려가도록 구성했다.

목록에 정보를 모두 넣으면 장애 중에 필요한 결과를 찾기 어려울 수 있었다.

목록에서는 요약을 보고, 상세 화면에서 drilldown하도록 했다.

---

report는 결론보다 근거가 중요하다

원인 후보만 보고 조치를 결정하지 않도록 근거를 함께 배치했다.

다음과 같은 결과만 보여주면 확인할 내용이 많이 남는다.

Possible root cause:
container runtime issue

runtime 문제라는 후보만으로는 실제 장애인지 수집 제약인지 알 수 없다.

다음 질문에 답할 근거가 필요했다.

• 어떤 evidence를 보고 판단했는가?
• containerd가 실제로 죽은 것인가?
• socket 접근 권한 문제는 아닌가?
• kubelet log에는 어떤 내용이 있었는가?
• CNI나 DNS 증상도 같이 있었는가?

Console에서 원인 후보와 그 판단에 사용한 evidence를 같이 확인할 수 있어야 했다.

운영자가 결과를 검토하는 데 필요한 정보를 보여주는 방향으로 정했다.

---

Policy 판단을 화면에 드러내기

Policy Engine의 분류도 화면에 표시했다.

추천된 조치의 위험도는 원인 분석과 별도로 확인해야 했다.

검토할 수 있는 조치는 다음과 같다.

• kubelet 상태 확인
• containerd 재시작 검토
• 노드 cordon/drain
• CNI 설정 확인
• 디스크 정리
• 추가 로그 수집

상태 조회와 서비스에 영향을 주는 변경 작업이 함께 있으므로 구분이 필요했다.

Console에서 policy classification을 명시하도록 했다.

AUTO_SAFE
APPROVAL_REQUIRED
GITOPS_PR_ONLY
NEVER_AUTO_EXECUTE
MANUAL_INVESTIGATION

무슨 조치인지와 함께, 어떤 위험으로 분류됐는지 볼 수 있도록 했다.

AI가 제안한 조치도 정책 분류를 거쳐 운영자가 판단하는 흐름을 유지했다.

---

API와 Console을 붙이면서 생긴 문제

화면을 붙이면서 Backend API 연결과 오류 처리도 정리했다.

확인할 항목은 다음과 같았다.

• 로그인 세션 처리
• 권한이 없는 API 접근 시 에러 표시
• Backend 연결 실패 처리
• report가 없을 때의 빈 상태 화면
• API 응답 형식이 바뀌었을 때의 방어 코드
• readiness check와 smoke test 연동

Backend가 정상이어도 Console은 별도로 실패할 수 있었다.

API 경로, 응답 필드, 인증 방식이 바뀌면 화면 호출이 깨질 수 있기 때문이다.

이런 오류를 빈 화면으로 숨기지 않도록 했다.

Backend 연결 실패, 권한 없음, report 없음이 서로 다르게 표시되도록 구성했다.

---

Codex를 어떻게 활용했는가

화면의 우선순위와 정보 배치는 직접 정했다.

report 상세에서 보여줄 근거와 policy 표시 방식도 직접 검토했다.

반복 UI와 API 호출, 오류 처리 코드에는 Codex를 활용했다.

다음 작업이 해당했다.

• report 목록 UI 구성
• cluster 목록 UI 구성
• API fetch 함수 정리
• 에러 메시지 처리 패턴 보강
• empty state 화면 구성
• README에 Console 실행 방법 정리
• smoke test에서 Console 확인 흐름 추가

반복되는 화면과 호출 코드를 작성하는 시간을 줄였다.

필요한 정보가 화면에 드러나는지는 직접 확인했다.

작업을 다음처럼 나눴다.

사람:
운영자 관점 설계
report 정보 우선순위 결정
policy 노출 방식 판단
에러 상태 구분 기준 결정

Codex:
반복 UI 구현
API 호출 코드 정리
에러 처리 패턴 보강
문서 초안 정리

---

이 단계에서 가장 중요했던 점

장애 상황에서 결과를 이해하고 근거를 찾아가는 흐름을 기준으로 화면을 구성했다.

기준은 다음과 같았다.

1. report 목록에서는 핵심 정보만 보여준다
2. 상세 화면에서는 판단 근거까지 따라갈 수 있게 한다
3. AI 결과처럼 보이는 문장도 evidence와 함께 보여준다
4. 추천 조치는 policy level과 함께 보여준다
5. 에러는 숨기지 말고 상태별로 구분해서 보여준다
6. Console과 Backend 연결은 smoke test로 최소 검증한다
7. Codex는 구현 보조로 쓰고, 운영자 관점 설계는 사람이 한다

특히 3번과 4번을 함께 확인했다.

원인 후보의 근거와 추천 조치의 위험도가 화면에 모두 나와야 했다.

---

마무리

Web Console에 report 목록과 상세 화면을 붙였다.

목록을 보고 상세 근거로 이동한 뒤, 추천 조치의 위험도를 확인하는 흐름을 목표로 했다.

Backend는 분석을, Agent는 수집을, Console은 결과와 근거의 표시를 맡도록 정리했다.

원인 후보에는 근거를, 조치 제안에는 위험도를 함께 표시했다.

다음 글에서는 Docker Compose와 배포 패키징으로 전체 플랫폼을 로컬에서 실행하고 검증한 과정을 다룬다.