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

This commit is contained in:
donghyeon-ka
2026-09-22 14:43:41 +09:00
parent a5d68c0767
commit 1549e62b5e
321 changed files with 13091 additions and 4522 deletions
@@ -23,22 +23,9 @@ source:
# packet 이 어디서 끊겼는지는 계층마다 capture 해서 가른다
가상 머신이 밖과 통신하지 못하면 게스트부터 뒤지지 말고 패킷이 지나야 할 네 지점에 캡처를 걸어 어디까지 보였는지로 구간을 좁힌다. 호스트의 물리 NIC(Network Interface Card) 와 브리지, 가상 머신에 붙은 TAP, 게스트 안의 인터페이스가 그 지점이다. 보이지 않은 첫 지점의 앞 구간이 의심 구간이 된다.
가상 머신이 밖과 통신하지 못하면 게스트부터 뒤지지 말고 패킷이 지나야 할 지점에 캡처를 걸어 어디까지 보였는지로 구간을 좁힌다. 첫 지점은 물리 NIC일 수도 있고 `tailscale0` 같은 host ingress 인터페이스일 수도 있다. 그 뒤로 브리지, 가상 머신에 붙은 TAP/vnet, 게스트 인터페이스를 따라간다. 보이지 않은 첫 지점의 앞 구간이 의심 구간이 된다.
## 관계
- **Guest 의 packet 이 Host Physical NIC 에 닿기까지 — virtio-net · virtqueue · vhost-net · TAP · Bridge**
이 절차가 관측 지점으로 쓰는 계층을 세운 글이다. 어느 계층이 무엇을 하는지는 그쪽에 있다.
- **Keycloak 실험 결과를 애플리케이션 원인으로 읽기 전에 network 계층을 따로 검증한다**
그 기준은 문제가 네트워크인지 아닌지를 가르고, 이 절차는 네트워크 안에서 어느 구간인지를 가른다.
- **이 호스트의 가상 머신 네트워크는 Bridge 인가 NAT 인가 Routing 인가**
캡처 지점 이름을 확정하는 첫 규칙이 그대로 이 물음의 확인 절차다.
- **VM1 과 VM2 의 TAP/vnet interface 는 무엇이고 어디에 붙어 있는가**
TAP 이름을 모르면 이 절차의 세 번째 지점에 캡처를 걸 수 없다.
- **Host Nginx 에서 Keycloak 까지 packet 은 실제로 어디를 지나는가**
그 경로를 처음 확인할 때 쓰는 절차다.
## 목적
## capture point를 나눠야 하는 이유
이 기준은 두 가지를 막는다.
@@ -46,13 +33,13 @@ source:
오프로드 때문에 실제 wire 와 다르게 보이는 정상 패킷을 결함으로 판정하는 일이 다른 하나다.
이 순서는 물음 셋이 함께 쓴다. 이 호스트의 가상 머신 네트워크가 무엇으로 구성돼 있는지, TAP 인터페이스가 무엇인지, 호스트 Nginx 에서 Keycloak 까지 패킷이 어디를 지나는지 셋이 모두 이 순서 위에서 돈다. 그래서 세 곳에 같은 절차를 되풀이하지 않고 한 편에 두었다.
이 순서는 여러 네트워크 질문이 함께 쓴다. VM network mode와 host-side `vnetN` mapping을 먼저 확인하고, 실제 요청은 현재 진입점인 `tailscale0 → host DNAT → edge VM → worker VM` 순서로 캡처한다. 과거 Host Nginx 배치와 현재 Edge VM 배치를 섞지 않고, 각 시점의 실제 ingress 인터페이스에서 시작한다.
## 규칙
## 바깥에서 안쪽으로 경로를 자른다
### 1. 캡처할 지점의 이름을 먼저 확정한다
관측 지점은 넷이다. 호스트의 물리 NIC, 호스트의 브리지, 가상 머신에 붙은 tap 또는 vnet, 그리고 게스트 안의 인터페이스.
기본 관측 지점은 host ingress 인터페이스, host bridge, 가상 머신에 붙은 tap 또는 vnet, 그리고 게스트 안의 인터페이스다. 현재 실험대의 외부 진입점은 물리 NIC가 아니라 `tailscale0`이다.
이름을 모른 채 시작하면 없는 인터페이스에 캡처를 걸어 놓고 패킷이 안 보인다고 판정하게 된다.
@@ -65,14 +52,14 @@ libvirt 가 만든 가상 네트워크가 무엇인지는 virsh net-list --all
### 2. 네 지점에 같은 요청을 흘리면서 캡처를 건다
호스트에서는 물리 NIC 와 브리지, tap 또는 vnet 에 각각 tcpdump -ni 로 캡처를 건다.
호스트에서는 실제 ingress 인터페이스와 브리지, tap 또는 vnet에 각각 `tcpdump -ni`로 캡처를 건다.
게스트에서는 게스트 인터페이스에 같은 방식으로 건다.
### 3. 보이지 않은 첫 지점의 앞 구간을 의심 구간으로 삼는다
판독은 어느 지점까지 보였는가로만 한다.
물리 NIC 에 보이고 브리지에도 보이는데 tap 에 안 보이면, 게스트 내부보다 먼저 호스트의 브리지와 tap 연결을 의심한다.
host ingress에 보이고 브리지에도 보이는데 tap에 안 보이면, 게스트 내부보다 먼저 호스트의 브리지와 tap 연결을 의심한다.
tap 에는 보이는데 게스트 NIC 에 안 보이면 virtio 와 vhost, 게스트 NIC 계층을 의심한다.
@@ -88,7 +75,7 @@ tap 에는 보이는데 게스트 NIC 에 안 보이면 virtio 와 vhost, 게스
가상 머신에서 인터넷으로 나가지 못하거나 외부에서 가상 머신에 접근하지 못하거나 특정 포트만 실패하면 nftables 와 iptables, NAT(Network Address Translation) 규칙, IP(Internet Protocol) forwarding 설정을 확인 대상으로 둔다.
이 실험대가 가장 오래 막힌 지점도 여기였다. 밖에서 온 요청만 엣지 게스트에 닿지 않았고, 거절한 것은 libvirt 가 자기 테이블의 guest_input 체인 끝에 둔 reject 규칙이었다(§180).
이 실험대가 가장 오래 막힌 지점도 여기였다. 밖에서 온 요청만 엣지 게스트에 닿지 않았고, 거절한 것은 libvirt 가 자기 테이블의 guest_input 체인 끝에 둔 reject 규칙이었다(「nftables 는 앞 체인의 `accept` 로 뒤 체인의 `reject` 를 막지 못한다」).
증상 셋을 각각 다른 기준으로 나누지 않은 것은 셋이 모두 어느 지점에서 끊겼는가 하나로 모이기 때문이다. 따로 적으면 같은 규칙의 부분 증상이 셋으로 늘어난다.
@@ -108,7 +95,7 @@ tap 에는 보이는데 게스트 NIC 에 안 보이면 virtio 와 vhost, 게스
이 절차가 가르는 것은 패킷이 어디서 끊겼는가다. 끊기지 않고 느리기만 하면 다른 기준으로 넘긴다.
## 적용 조건
## packet path를 의심할 때
KVM(Kernel-based Virtual Machine)/QEMU/libvirt 로 만든 가상 머신이 외부와 통신하지 못할 때.
@@ -116,7 +103,7 @@ KVM(Kernel-based Virtual Machine)/QEMU/libvirt 로 만든 가상 머신이 외
실제 패킷 경로를 처음 확인할 때.
## 예외
## capture만으로 답이 안 되는 경우
오프로드가 켜진 구성에서는 패킷 크기와 체크섬이 그대로 증거가 되지 않는데, 다섯 번째 규칙이 그 경우다.
@@ -124,13 +111,13 @@ KVM(Kernel-based Virtual Machine)/QEMU/libvirt 로 만든 가상 머신이 외
네 지점이 모두 보이는데 느린 경우는 이 기준이 다루지 않는다. 「Keycloak 실험 결과를 애플리케이션 원인으로 읽기 전에 network 계층을 따로 검증한다」 쪽으로 넘긴다.
이 저장소에는 아직 이 절차를 실제로 돌린 출력이 없다. 여기 적은 판독은 원문 문서가 서술한 것이고 이 호스트의 캡처로 확인한 것이 아니다.
2026-09-21에는 실제 요청을 여러 지점에서 캡처해 이 절차를 다시 확인했다. 따라서 아래 판독은 개념 설명만이 아니라 현재 실험대에서 확보한 패킷 캡처와 함께 읽는다.
§180 의 사건에서도 구간을 좁힌 것은 네 지점 캡처가 아니었다. 호스트에서 친 curl 은 404 를 받는데 밖에서 친 curl 만 connection refused 를 받았다는 차이가 단서였고, 범인은 그 reject 규칙의 카운터가 4 패킷 240 바이트로 밖에서 친 횟수와 맞아떨어져서 확정했다.
「nftables 는 앞 체인의 `accept` 로 뒤 체인의 `reject` 를 막지 못한다」의 사건에서도 구간을 좁힌 것은 네 지점 캡처가 아니었다. 호스트에서 친 curl 은 404 를 받는데 밖에서 친 curl 만 connection refused 를 받았다는 차이가 단서였고, 범인은 그 reject 규칙의 카운터가 4 패킷 240 바이트로 밖에서 친 횟수와 맞아떨어져서 확정했다.
## 예시
## 어디서 끊겼는지 판정하는 예
- 물리 NIC 에 보이고 브리지에도 보이는데 tap 에 안 보임 : 호스트의 브리지와 tap 연결을 먼저 확인한다
- host ingress 에 보이고 브리지에도 보이는데 tap 에 안 보임 : 호스트의 브리지와 tap 연결을 먼저 확인한다
- tap 에 보이는데 게스트 NIC 에 안 보임 : virtio 와 vhost, 게스트 NIC 계층을 확인한다
- 게스트 NIC 에 보이는데 소켓까지 안 옴 : 게스트의 라우팅과 방화벽, listen 상태를 확인한다
- 특정 가상 머신만 통신 불가 : ip link 와 bridge link, virsh domiflist 로 그 가상 머신의 tap 이 브리지에 붙어 있는지 본다
@@ -20,22 +20,9 @@ source:
# Keycloak 실험 결과를 애플리케이션 원인으로 읽기 전에 network 계층을 따로 검증한다
Refresh Token 경쟁 자체는 virtio-net 문제가 아니다. 다만 그 실험에서는 클라이언트에서 Nginx 와 가상 머신, K3s, Keycloak 을 거쳐 PostgreSQL 또는 Redis 까지 가는 경로를 여러 노드가 함께 쓴다. 그 경로 위의 네트워크 가상화 문제는 애플리케이션 동시성 문제와 비슷한 증상으로 나타난다.
Refresh Token 경쟁 자체는 virtio-net 문제가 아니다. 현재 Keycloak lab에서는 클라이언트에서 Edge Nginx와 가상 머신, K3s, Keycloak을 거쳐 PostgreSQL까지 가는 경로를 여러 노드가 함께 쓴다. Redis를 사용하는 별도 패턴 실험이라면 그 구간을 추가한다. 그 경로 위의 네트워크 가상화 문제는 애플리케이션 동시성 문제와 비슷한 증상으로 나타난다.
## 관계
- **Guest 의 packet 이 Host Physical NIC 에 닿기까지 — virtio-net · virtqueue · vhost-net · TAP · Bridge**
이 기준이 「따로 검증한다」고 말하는 계층을 세운 글이다.
- **packet 이 어디서 끊겼는지는 계층마다 capture 해서 가른다**
이 기준이 문제가 네트워크인지 아닌지를 가른다면, 그 절차는 네트워크 안에서 어느 구간인지를 가른다.
- **Host Nginx 에서 Keycloak 까지 packet 은 실제로 어디를 지나는가**
검증 순서의 첫 항목이다. 경로를 모르면 무엇을 관측할지도 정해지지 않는다.
- **부하 중 network 가상화가 지연을 바꿀 만큼 호스트 CPU 를 쓰는가**
검증 순서의 마지막 항목이고, 네트워크 처리와 CPU 경쟁을 가르는 관측이다.
- **Keycloak 동시 refresh 실험 중 CPU 가상화 계층이 결과를 흔들 만큼 포화되는가**
같은 실험을 CPU 쪽에서 본 물음이다. 두 계층이 같은 지연으로 보이므로 함께 기록한다.
## 목적
## 애플리케이션 원인으로 바로 읽지 않는 이유
이 기준은 실험 결과를 잘못된 원인에 붙이는 일을 막는다.
@@ -45,15 +32,15 @@ Keycloak 멀티 노드 실험에서 관측되는 지연과 실패에는 네트
이 분리는 실험 결과를 보고 나서 세운 규칙이 아니다. 원문 문서는 이 실험 기반으로 검증하려는 항목을 일곱 개 적어 두었고, 그 마지막이 「네트워크 계층 문제와 애플리케이션/저장소 문제의 분리」였다.
## 규칙
## 경로 · 노드 · CPU 비용을 따로 확인한다
### 1. 실험이 지나는 경로를 먼저 적고 시작한다
요청은 클라이언트에서 Nginx 로 가고, 거기서 가상 머신 두 대 중 하나로, 그 안의 K3s 를 지나 Keycloak 으로, 다시 PostgreSQL 또는 Redis 로 간다. 이 경로를 노드들이 공유한다.
현재 실험대의 진입 경로는 `Client → Tailscale ingress → Host DNAT/source rewrite → Edge Nginx → virbr0 → worker VM → Traefik`까지 실제 packet capture로 확인됐다. Edge Nginx가 TLS를 종료하고 worker로 새 HTTP 연결을 만들기 때문에 첫 번째 TLS flow와 두 번째 HTTP flow를 같은 연결로 보지 않는다. K3s CNI·Service·Pod 내부와 Keycloak 이후 PostgreSQL 구간은 별도 계층으로 남긴다. Redis는 현재 lab에는 없으므로 Redis를 포함한 별도 실험에서만 추가한다.
경로를 적지 않으면 어느 관측이 어느 구간을 덮는지 정해지지 않는다.
이 실험대에서 그렇게 어긋난 확인이 한 번 있었다. 04 단계의 확인 명령을 엣지 가상 머신 안에서 tailnet 주소로 쳤더니 connection refused 가 돌아왔는데, 엣지에서 나간 패킷은 호스트의 virbr0 으로 들어가고, 들어온 패킷의 도착지 주소를 바꿔 넘기는 호스트의 DNAT(Destination NAT, 도착지 주소 변환) 규칙은 tailscale0 으로 들어온 것만 매칭해서 안 걸렸기 때문이다(§190 · §182). 「설정 문제가 아니라 친 위치 문제다」가 그 단계가 남긴 한 줄이다.
이 실험대에서 그렇게 어긋난 확인이 한 번 있었다. 04 단계의 확인 명령을 엣지 가상 머신 안에서 tailnet 주소로 쳤더니 connection refused 가 돌아왔는데, 엣지에서 나간 패킷은 호스트의 virbr0 으로 들어가고, 들어온 패킷의 도착지 주소를 바꿔 넘기는 호스트의 DNAT(Destination NAT, 도착지 주소 변환) 규칙은 tailscale0 으로 들어온 것만 매칭해서 안 걸렸기 때문이다(「단계 04 — Let's Encrypt 와 인증서 갱신」· 「이 구축에서 드러난 문서 결함의 공통 원인」). 「설정 문제가 아니라 친 위치 문제다」가 그 단계가 남긴 한 줄이다.
### 2. 노드 하나에서만 나는 증상을 애플리케이션 동시성으로 먼저 읽지 않는다
@@ -73,13 +60,13 @@ vhost-net 과 QEMU 스레드, softirq 도 호스트 CPU 를 쓴다. 그래서
부하 실험을 돌릴 때 QEMU 와 vhost 의 CPU 사용량, 호스트와 게스트의 CPU, 네트워크 지연을 같은 시간축에 남긴다. 나중에 따로 재면 그때의 부하를 다시 만들어야 한다.
### 5. 세 가지 검증을 마친 뒤에 원인을 적는다
### 5. 경로와 CPU 비용을 분리해서 확인한 뒤 원인을 적는다
경로가 무엇인지, 그 경로가 끊기지 않았는지, 네트워크 처리가 호스트 CPU 를 얼마나 쓰는지 셋을 확인한다.
2026-09-21 재검증으로 Host ingress부터 Edge와 worker NIC까지의 실제 packet path는 확인됐다. 따라서 이후 장애에서는 같은 capture point에 패킷이 보이는지부터 비교하면 된다.
첫째는 호스트 Nginx 에서 Keycloak 까지의 실제 패킷 경로를 추적해서, 둘째는 계층마다 캡처해서, 셋째는 부하 중 CPU 사용량을 재서 답한다.
부하 중 네트워크 가상화 CPU 비용도 2026-09-21에 따로 측정했다. 외부 OIDC 부하에서 vhost와 softirq 사용량은 증가했지만 host CPU에는 여유가 남았고, 이번 부하 수준에서 네트워크 가상화 비용이 host CPU를 지배했다고 볼 근거는 없었다. 다만 guest workload 자체도 함께 증가했으므로 지연 변화를 네트워크 가상화 하나의 원인으로 귀속하지 않는다.
## 적용 조건
## 이 검증이 필요한 실험
여러 노드가 같은 네트워크 경로를 공유하는 실험의 결과를 원인에 귀속할 때.
@@ -89,22 +76,22 @@ vhost-net 과 QEMU 스레드, softirq 도 호스트 CPU 를 쓴다. 그래서
부하 구간에서만 커지는 지연을 애플리케이션 동시성이나 저장소 lock 으로 결론내려 할 때.
## 예외
## network가 깨끗해도 분석은 끝나지 않는다
애플리케이션 쪽 관측을 늘리는 것으로는 이 기준을 적용할 수 없다. Keycloak 이 게스트 소켓 위에서만 동작하므로 애플리케이션 로그로는 이 계층이 원인인지 가릴 수 없다.
네트워크 계층이 깨끗하다고 해서 이 기준이 애플리케이션 결함을 배제해 주지는 않는다. 여기서 나오는 것은 네트워크가 원인이 아니라는 것까지다.
네트워크 계층에서 뚜렷한 이상을 찾지 못했다고 해서 애플리케이션 결함이 증명되는 것은 아니다. 여기서 얻는 것은 **관측한 경로와 부하 범위에서는 네트워크 쪽 원인 후보가 줄었다**는 정도다.
가상 머신 위 K3s 안쪽은 이 기준의 범위 밖이다. CNI(Container Network Interface) 와 Service, Pod 네트워크는 별도 계층으로 두고 따로 분석한다.
원문 문서가 이 테스트 환경에 얹어 그린 경로는 확인된 것이 아니라 기준 구조를 그대로 옮겨 놓은 그림이다. 이 저장소에는 이 기준으로 원인을 실제로 가른 실험이 아직 없다.
과거 문서의 `Host Nginx → worker VM` 그림은 현재 구조와 달랐지만, 2026-09-21에는 실제 OIDC discovery 요청을 `tailscale0`, Edge/worker의 host-side `vnetN`, guest `enp1s0`에서 추적해 현재 경로를 확인했다. 이 검증은 애플리케이션 원인을 증명한 것이 아니라 **네트워크 경로 자체를 독립적으로 검증할 수 있게 된 것**이다.
가까운 것은 실험대를 세울 때 한 번 있었다. 밖에서 온 요청만 엣지에 닿지 않았는데 원인은 게스트 안이 아니라 호스트의 libvirt 방화벽 규칙이었고, 그때 엣지 nginx 는 호스트에서 친 요청에 404 로 응답하고 있었다(§180).
가까운 것은 실험대를 세울 때 한 번 있었다. 밖에서 온 요청만 엣지에 닿지 않았는데 원인은 게스트 안이 아니라 호스트의 libvirt 방화벽 규칙이었고, 그때 엣지 nginx 는 호스트에서 친 요청에 404 로 응답하고 있었다(「nftables 는 앞 체인의 `accept` 로 뒤 체인의 `reject` 를 막지 못한다」).
## 예시
## Keycloak 실험에 적용하는 방법
- Keycloak 노드 하나만 응답이 느림 : 그 노드가 있는 가상 머신까지의 경로부터 확인한다
- 가상 머신 하나에서만 요청이 실패 : 호스트 브리지 구성과 그 가상 머신의 tap 연결을 본다
- 부하를 올릴수록 지연이 커짐 : QEMU 와 vhost 의 CPU 사용량을 같은 시간축에서 함께 본다
- 동시 갱신 실험에서 두 번째 요청이 거부됨 : 네트워크 검증 셋을 마친 뒤에 Refresh Token 경쟁으로 적는다
- 네트워크 검증이 전부 깨끗함 : 네트워크가 원인이 아니라는 것까지만 적고 애플리케이션 쪽을 계속 본다
- 네트워크 검증에서 이상을 찾지 못함 : 관측한 범위에서 네트워크 원인 후보를 낮추고 애플리케이션 쪽을 계속 본다