refactor: 문서 사람처럼 작성하기
This commit is contained in:
+14
-27
@@ -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 이 브리지에 붙어 있는지 본다
|
||||
|
||||
+15
-28
@@ -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 경쟁으로 적는다
|
||||
- 네트워크 검증이 전부 깨끗함 : 네트워크가 원인이 아니라는 것까지만 적고 애플리케이션 쪽을 계속 본다
|
||||
- 네트워크 검증에서 이상을 찾지 못함 : 관측한 범위에서 네트워크 원인 후보를 낮추고 애플리케이션 쪽을 계속 본다
|
||||
|
||||
Reference in New Issue
Block a user