K8s Clue

Clue는 Kubernetes 장애 증거를 수집하고, 판단 근거와 함께 원인을 설명하고, 안전한 수정안을 제안한 뒤 실제 회복까지 검증하는 도구다. 이 절의 문서 14편은 그 목표 설계이며, 실제로 동작하는 구현체와는 범위가 다르다.

구현체와 목표 설계를 구분한다

두 가지를 섞어 읽으면 안 된다.

구분	구현체	이 절의 설계 문서
무엇인가	5인 팀이 2026-06~07에 만들고 이후 개인이 정리한 서비스	그 경험을 바탕으로 쓴 제품 목표 설계
언어·스택	Python · FastAPI · PostgreSQL · Helm	Java 25 · Native CLI를 목표로 검토 (문서 10 · 12 · 13)
배포 형태	관리 클러스터에 올리는 서비스와 콘솔	설치형 CLI와 Hub
저장소	`woonyong-choi/k8s-clue`	코드 없음. 문서만 있다
검증 수치	구현체에서 실행한 값이 따로 있다	전부 미완료 체크박스다. 달성한 수치가 아니다

이 문서들에 나오는 clue diagnose 같은 명령은 계획된 인터페이스다. 현재 실행할 수 있는 것은 구현체 저장소의 Make 타깃이다. 문서 9의 상태표 항목이 전부 빈 체크박스인 것은 누락이 아니라 아직 착수하지 않았다는 뜻이다.

구현체와 설계 문서는 같은 역할을 다른 이름으로 부른다. 문서 14편은 아래 오른쪽 열을 전제로 쓰여 있다.

Management라는 제품명은 쓰지 않는다. 관리 계층 전체를 가리킬 때만 일반 명사로 쓰고, 실행 인스턴스는 Hub라고 부른다.

구현체와 설계가 갈라지지 않는 지점이 하나 있다. 자동화의 권한을 어디서 차단할 것인가다.

문서 4와 5가 이 원칙을 설계 쪽에서 다시 진술한다.

처음 본다면 1 → 3 → 9 순으로 읽는다. 무엇을 풀려는지, 어떤 구조로 풀려는지, 어디까지 왔는지가 그 셋에 있다.