refactor: 문서 사람처럼 작성하기

This commit is contained in:
donghyeon-ka
2026-09-22 16:24:58 +09:00
parent 1549e62b5e
commit f3bed70991
158 changed files with 4381 additions and 832 deletions
@@ -1,7 +1,7 @@
---
kind: REFERENCE
slug: check-the-nearest-layer-first
title: 가까운 층부터 한 층씩 건너뛰며 확인한다 — 층마다 성공 신호가 다르다
title: 장애를 확인할 때는 가까운 계층부터 확인한다
topic: build-completion-judgment
topicName: 끝났다는 판정
project: virtualization
@@ -13,9 +13,9 @@ source:
- final/document.md#191-단계-05-keycloak-2노드와-postgresql
---
# 가까운 층부터 한 층씩 건너뛰며 확인한다 — 층마다 성공 신호가 다르다
# 장애를 확인할 때는 가까운 계층부터 확인한다
가장 가까운 층부터 치고 한 칸씩 밖으로 나오며, 층마다 성공 신호를 미리 적는다. 200 이 아닌 층이 있다 — 03 단계 네 칸의 실측은 404 와 301 과 301 과 200 이었다. 밖에서 한 번 쳐서 받은 값 하나로는 여섯 층 가운데 어디서 끊겼는지가 나오지 않는다.
장애 지점을 찾을 때는 서비스에 가장 가까운 구간부터 확인하고, 한 단계씩 외부 방향으로 범위를 넓혔다. 이 실험대의 03 단계에서는 각 구간의 정상 응답이 404, 301, 301, 200으로 서로 달랐다. 외부에서 받은 응답 하나만으로는 어느 구간에서 문제가 생겼는지 구분할 수 없었다.
## 왜 가장 가까운 층부터 보는가
@@ -41,7 +41,7 @@ source:
### 4. 층을 좁힌 뒤에는 그 층이 내는 문구와 errno 와 종료 코드를 읽는다
같은 「안 된다」가 층마다 다른 낱말로 나온다. nginx upstream 의 connect() failed (113: No route to host) 는 네트워크 쪽이고, (111: Connection refused) 는 프로세스 쪽이며, no live upstreams 는 둘 다 죽었다는 판단이다. 노드를 잃었을 때 이 세 줄이 1분 안에 순서대로 나왔다. k3s agent 노드의 dial tcp [::1]:8080: connect: connection refused 는 네트워크 문제가 아니라 kubeconfig 을 하나도 못 찾아 하드코딩된 기본값으로 넘어간 것이다. 파드의 Exit Code 도 그것만으로 말이 된다 — 137 은 OOM 이나 강제 종료, 1 은 애플리케이션이 스스로 끝낸 것, 127 은 명령을 못 찾은 것이다.
같은 「안 된다」가 층마다 다른 낱말로 나온다. nginx upstream 의 connect() failed (113: No route to host) 는 네트워크 쪽이고, (111: Connection refused) 는 프로세스 쪽이며, `no live upstreams`는 nginx가 사용할 수 있는 upstream이 없다고 판단한 상태다. 노드를 잃었을 때 이 세 줄이 1분 안에 순서대로 나왔다. k3s agent 노드의 dial tcp [::1]:8080: connect: connection refused 는 네트워크 문제가 아니라 kubeconfig 을 하나도 못 찾아 하드코딩된 기본값으로 넘어간 것이다. 파드의 Exit Code 도 그것만으로 말이 된다 — 137 은 OOM 이나 강제 종료, 1 은 애플리케이션이 스스로 끝낸 것, 127 은 명령을 못 찾은 것이다.
### 5. 그 층 안에 물어볼 도구가 없으면 밖에서 묻는다
@@ -60,9 +60,9 @@ Keycloak 컨테이너에는 curl 이 없다. 공식 이미지가 최소 구성
네 칸이 다 통과하고도 나중에 터지는 것이 있다. DNAT 규칙의 443 을 433 으로 친 오타가 이 실험대에서 실제로 나왔는데, 433 도 유효한 포트라 nft 가 군말 없이 받고 80 은 멀쩡히 넘어가므로 03 단계의 확인은 다 통과하고 04 단계에서 443 쪽만 안 되는 형태로 뒤늦게 터진다.
이 절차는 어디서 끊겼는지를 좁힐 뿐 왜 끊겼는지를 말하지 않는다. 첫 칸에서 404 가 나와도 그 뒤의 값이 틀렸을 수 있고, 02 단계의 INTERNAL-IP 가 그렇다 — 두 노드가 Ready 인데 보고된 IP 가 우리가 준 값과 다르면 지금은 아무 증상이 없다가 03 단계의 upstream 에서 어긋난다. 로그를 읽어 좁히려다 잘린 문구를 붙들 수도 있다. nginx 에러 로그는 2048바이트에서 잘린다. 이 실험대에서도 502 원인이 error 로그에서는 잘린 채로 있었고, access 로그에는 3492자로 온전히 남아 있었다. 그쪽은 「도구가 낸 출력은 대상의 상태가 아니다」가 받는다.
이 절차는 문제가 생긴 구간을 좁히는 데까지만 사용한다. 예를 들어 두 노드가 `Ready`여도 보고된 `INTERNAL-IP`가 기대한 값과 다르면 당장은 증상이 없다가 nginx upstream 연결에서 문제가 드러날 수 있다. 로그도 잘린 일부만 보면 원인을 놓칠 수 있는데, 이 실험대에서는 nginx error log가 2048바이트에서 잘린 반면 access log에는 3492자의 원문이 남아 있었다. 구간을 좁힌 뒤에는 명령과 로그가 실제로 무엇을 보여 주는지 별도로 확인한다.
제3부의 「packet 이 어디서 끊겼는지는 계층마다 capture 해서 가른다」와는 재는 것이 다르다. 그쪽은 네 지점에서 capture 를 떠 패킷이 사라진 구간을 좁히고, 이쪽은 층을 건너뛴 요청의 응답 코드로 좁힌다. 응답이 아예 안 돌아오고 패킷도 안 보이는 상태에서는 이 절차가 답을 못 내므로 그때 그쪽으로 넘어간다.
응답 코드로 계층을 좁히는 방법과 packet capture는 측정 대상이 다르다. HTTP 응답이 돌아오면 각 계층을 건너뛴 요청의 응답으로 범위를 줄일 수 있고, 응답 자체가 없으면 여러 인터페이스에서 packet capture를 떠 패킷이 사라지는 구간을 찾는다.
## 이 실험대에서 쓴 예
@@ -74,6 +74,6 @@ Keycloak 컨테이너에는 curl 이 없다. 공식 이미지가 최소 구성
- 둘째 칸에서 막힌다 : 막힌 곳이 엣지 안이다
- 첫 칸이 502 : Traefik 은 떴고 뒤에 백엔드가 없다
- 첫 칸이 연결 거부나 타임아웃 : 02 단계의 노드 상태로 돌아간다
- 노드를 잃었을 때 1분 안에 순서대로 나온 세 줄 : 113 은 네트워크, 111 은 프로세스, no live upstreams 는 둘 다 죽었다는 판단
- 노드를 잃었을 때 1분 안에 순서대로 나온 세 줄 : 113은 네트워크 경로 문제, 111은 대상 프로세스 연결 거부, `no live upstreams`는 사용할 수 있는 upstream이 없다는 상태
- Keycloak 컨테이너 안에서 curl 이 exit code 127 : 서버가 아니라 명령이 없다. 밖에서 묻는다
- 04 단계 확인을 엣지 안에서 쳤을 때의 connection refused : 층의 답이 아니라 친 위치의 답이다
@@ -1,7 +1,7 @@
---
kind: REFERENCE
slug: tool-output-is-not-the-subject-state
title: 도구가 낸 출력은 대상의 상태가 아니다 — 그 명령이 무엇을 세는지부터 가른다
title: 명령 출력이 실제 상태를 의미하는지 먼저 확인한다
topic: build-completion-judgment
topicName: 끝났다는 판정
project: virtualization
@@ -13,7 +13,7 @@ source:
- final/document.md#186-단계-00-lab-host-가상화-준비
---
# 도구가 낸 출력은 대상의 상태가 아니다 — 그 명령이 무엇을 세는지부터 가른다
# 명령 출력이 실제 상태를 의미하는지 먼저 확인한다
상태를 묻는 명령의 출력을 대상의 상태로 바로 읽지 않고, 그 명령이 무엇을 세고 무엇을 안 세는지 먼저 적는다. 7800 포트를 끊었을 때 외부 응답은 전부 200 이었고, 503 이 나는 동안에도 up 은 1 이었다.
@@ -80,7 +80,7 @@ kubectl rollout status 는 끝날 때까지 아무것도 안 찍고 그 침묵
이 기준의 근거는 대부분 이 실험대 한 대에서 한 번씩 본 것이다. 다른 판 번호나 다른 배포판에서 같은 명령이 같은 것을 세는지는 재지 않았다.
가이드에 실린 출력이 이 호스트의 것인지도 한 군데에서 어긋났다. 「단계 00 — lab host 가상화 준비」의 과거 출력은 16 코어 전부에서 지원한다고 적었지만, 2026-09-17과 2026-09-21에 `nproc`·`lscpu`로 다시 확인한 현재 `test-server`는 i5-1135G7, 물리 4코어·8 logical CPU다. 따라서 16코어 줄은 **현재 호스트의 관측값이 아니라 다른 환경에서 섞여 들어온 historical output**으로 취급한다.
가이드에 실린 출력이 이 호스트의 것인지도 한 군데에서 어긋났다. 「단계 00 — lab host 가상화 준비」의 과거 출력은 16 코어 전부에서 지원한다고 적었지만, 2026-09-17과 2026-09-21에 `nproc`·`lscpu`로 다시 확인한 현재 `test-server`는 i5-1135G7, 물리 4코어·8 logical CPU다. 따라서 16코어 줄은 현재 호스트의 관측값이 아니라 다른 환경의 출력으로 구분한다.
## 실제 판독 예