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
@@ -52,30 +52,6 @@ source:
가상 머신 안의 Keycloak 이 HTTP 요청 하나를 받으려면 그 패킷이 호스트의 물리 NIC 에서 Linux Bridge 와 TAP, vhost-net, virtqueue 를 지나 게스트 커널의 TCP/IP 스택까지 올라와야 한다. virtio-net 은 그 경로에 놓인 프로그램 하나가 아니라 게스트 쪽 프런트엔드 드라이버와 호스트 쪽 백엔드를 잇는 I/O 계약이고, 그 백엔드 자리는 QEMU 사용자 공간이 맡을 수도 호스트 커널의 vhost-net 이 맡을 수도 있다. 가상 머신 두 대로 Keycloak 멀티 노드 실험을 돌리다 요청이 느려지거나 아예 닿지 않으면, 이 경로를 알아야 그 증상을 애플리케이션·저장소 쪽 문제와 네트워크 가상화 계층 문제로 갈라 볼 수 있다.
## 관계
- **packet 이 어디서 끊겼는지는 계층마다 capture 해서 가른다**
이 글이 세운 계층을 그대로 관측 지점으로 쓰는 절차다. 어느 계층까지 패킷이 보였는지로 의심 구간을 좁힌다.
- **Keycloak 실험 결과를 애플리케이션 원인으로 읽기 전에 network 계층을 따로 검증한다**
이 경로가 실험의 여러 노드에 공유되기 때문에 생기는 오귀속을 막는 기준이다.
- **이 호스트의 가상 머신 네트워크는 Bridge 인가 NAT 인가 Routing 인가**
이 글은 Bridge 와 라우팅, NAT 가 각각 무엇을 하는지까지만 적었다. 이 호스트가 NAT 로 돈다는 것은 실험대를 세운 기록이 나중에 적었고, 그 구성에서 프레임이 어느 계층을 지나는지는 그 물음이 받는다.
- **VM1 과 VM2 의 TAP/vnet interface 는 무엇이고 어디에 붙어 있는가**
TAP 이 게스트의 이더넷 프레임과 호스트 네트워크를 잇는 접점이라는 설명이 이 물음의 전제다.
- **이 호스트에서 vhost-net 이 실제로 packet datapath 를 맡고 있는가**
백엔드가 QEMU 사용자 공간일 수도 vhost-net 일 수도 있다고 적었다. 이 호스트가 어느 쪽인지는 아직 모른다.
- **QEMU backend 와 vhost-net 의 차이가 이 호스트에서 실제로 보이는가**
두 백엔드의 경로 차이는 여기 적었지만, 그 차이가 지연이나 CPU 사용량으로 드러나는지는 재지 않았다.
- **이 가상 머신들의 virtio-net 에 multi-queue 가 켜져 있는가**
큐를 하나만 쓰면 부하가 몰릴 수 있다고만 적었다. 지금 큐가 몇 개인지는 확인하지 않았다.
- **Host Nginx 에서 Keycloak 까지 packet 은 실제로 어디를 지나는가**
여기 그린 경로는 가장 기본적인 조합을 기준으로 한 것이고, 이 테스트 환경의 실제 경로는 추적하지 않았다.
- **부하 중 network 가상화가 지연을 바꿀 만큼 호스트 CPU 를 쓰는가**
vhost-net 과 QEMU 스레드, softirq 도 호스트 CPU 를 쓴다는 것까지가 이 글의 범위다.
- **KVM 에서 vCPU 가 물리 CPU 에서 실행되기까지**
QEMU 가 장치를 만들지만 반복 실행은 커널이 맡는다는 구조가 CPU 쪽과 같다. 그쪽 글이 같은 구분을 명령 실행으로 설명한다.
## 본문
<!-- body:start -->
@@ -326,16 +302,18 @@ sudo tcpdump -ni <tap-or-vnet>
sudo tcpdump -ni <guest-interface>
```
## 이 문서가 확인하지 않은 것
## 이 호스트에서 확인한 경로와 남은 것
위의 명령을 이 호스트에서 돌린 출력은 대부분 없다. 네트워크 구성만은 나중에 갈렸다. 실험대를 세운 기록이 이 호스트에 이더넷 없이 WiFi 만 있어 브리지를 못 쓰고 libvirt NAT 를 골랐다고 적었고, 게스트는 그 NAT 가 만드는 브리지에 붙는다. 브리지를 막은 것은 무선 링크다. 802.11 데이터 프레임은 기본적으로 주소 필드가 3개라, AP(Access Point, 무선 접속 장치) 는 연결된 단말의 MAC 만 알고 있고 그 단말이 자기 것이 아닌 출발지 MAC 을 단 프레임을 보내면 버린다. 브리지된 가상 머신이 보내는 것이 정확히 그런 프레임이다. 우회로 4-address 모드(WDS) 가 있지만 AP 와 클라이언트 드라이버가 모두 지원해야 하고 실제로는 거의 지원되지 않아, 그 기록은 현실적인 우회로 USB 이더넷 어댑터를 들었다. 같은 기록이 NAT 와 브리지와 macvtap 을 견준 표에서 뒤의 둘은 나란히 WiFi 라 불가다. TAP 또는 vnet 인터페이스의 이름과 vhost-net 이 실제로 데이터 경로를 맡는지, multi-queue 가 켜져 있는지는 아직 읽지 않았다. 그래서 이 글은 「이 구조에서는 이렇게 동작한다」까지만 말하고 「이 서버가 그 구조다」라고는 말하지 않는다. QEMU 백엔드와 vhost-net 의 성능 차이가 이 호스트에서 관찰되는지, Keycloak 부하 시험에서 네트워크 가상화가 지연에 영향을 줄 만큼 호스트 CPU 를 쓰는지도 재지 않았다.
2026-09-21 재검증으로 현재 host의 VM network는 libvirt `default` NAT network이고 내부 L2 연결은 `virbr0`가 맡는다는 것을 확인했다. host-side interface는 `kc-lab-edge → vnet13`, `kc-lab-1 → vnet18`, `kc-lab-2 → vnet19`이고 모두 `virbr0` forwarding port다. 세 VM의 QEMU 인자에는 `vhost:true`가 있어 datapath backend는 vhost-net이며, worker 둘의 guest queue는 각각 `rx-0`/`tx-0` 한 쌍이라 현재 single-queue 구성이다.
이 문서가 Keycloak 테스트 환경에 얹어 그린 경로는 그대로 쓰지 못한다. 그 그림은 호스트의 nginx 가 가상 머신 두 대로 프록시하는 모양인데, 실험대는 그 뒤에 nginx 를 게스트 한 대로 옮기고 호스트에는 커널 DNAT(Destination NAT, 목적지 주소 변환) 만 두었다. 게스트도 둘이 아니라 셋이고, 엣지 한 대와 K3s 노드 두 대다. 브리지와 라우팅·NAT, TAP, vhost-net, virtqueue 로 펼친 뒷부분은 TAP 이름과 vhost-net 사용 여부를 확인하기 전의 가정이어서, 재기 전에는 이 글의 그림으로 올리지 않는다.
외부 진입 경로도 packet capture로 확인했다. workmachine의 요청은 `tailscale0`에서 host로 들어와 DNAT과 Tailscale postrouting source rewrite를 거친 뒤 `vnet13`으로 나가 edge guest에 도달했다. edge Nginx는 TLS를 종료하고 `192.168.122.11:80` 또는 `.12:80`으로 새 HTTP 연결을 만들었고, 해당 요청은 `vnet18` 또는 `vnet19`와 worker `enp1s0`에서 확인됐다. 따라서 현재 실험대에서는 generic physical-NIC 그림을 그대로 대입하지 않고 **Tailscale ingress → host NAT → Edge VM → virbr0 L2 forwarding → worker**라는 실제 경로를 기준으로 본다.
과거의 `Host Nginx → worker VM` 그림은 현재 구성과 다르다. 지금은 nginx가 `kc-lab-edge` 안에 있고 host는 ingress DNAT을 담당한다. 다만 그 아래의 `virbr0 → vnetN → vhost-net → virtqueue → virtio-net → guest NIC` 구조는 현재 VM별 mapping과 QEMU runtime 설정으로 확인됐다. K3s CNI·Service·Pod 내부 경로는 이 문서 범위 밖이므로 worker guest NIC 이후를 곧바로 Keycloak Pod까지 한 줄로 단정하지 않는다.
여기 적은 것은 가장 기본적인 조합 안에서만 성립한다. 실제 환경은 Bridge 와 NAT, routed network, macvtap, SR-IOV, VFIO(Virtual Function I/O) passthrough, Open vSwitch, Kubernetes CNI(Container Network Interface) 에 따라 달라질 수 있다. 이 서술 자체는 판 번호를 달고 있지 않다. 실험대를 잰 기록이 그 호스트의 libvirt 12.7.0 과 QEMU 11.1.1, 커널 7.2.2-arch1-1 을 적었다. 여기 적은 동작은 그 판에서 읽은 것이 아니라 구조를 서술한 것이라, 세 값은 확인할 때의 조건으로 쓴다. 복사 동작 하나만 봐도 커널 버전과 QEMU 버전, vhost 설정, 오프로드, NIC 의 기능에 따라 달라지므로, 버전이 바뀌어 이 서술이 낡았는지는 위 확인 명령을 실제 호스트에서 돌릴 때 드러난다.
가상 머신 위에 올린 K3s 안쪽도 이 문서 밖이다. K3s 의 CNI 와 Service, Pod 네트워크는 이 네트워크 가상화 위에 더해지는 계층이라 따로 분석한다.
확인 순서는 물리 NIC 에서 시작한다. 그다음 libvirt 가상 네트워크와 Bridge·NAT·Route 구성, 가상 머신별 TAP 또는 vnet, virtio-net 장치, vhost-net 사용 여부, 게스트 NIC 와 route 를 차례로 본다. 이어서 호스트 Nginx 에서 가상 머신까지 패킷이 지나는 길을 `tcpdump` 로 추적하고, VM1 과 VM2 사이의 경로와 Keycloak 요청 때의 패킷 흐름을 확인한다. 마지막으로 부하를 걸었을 때 QEMU 와 vhost 의 CPU 사용량을 비교하고 multi-queue 와 오프로드 설정을 본다. 검증되지 않은 항목은 열린 질문으로 두고, 실제 결과가 나오면 재현 조건을 붙인 기록으로 옮긴다.
현재까지 구성·mapping·vhost-net·single queue·실제 ingress와 edge→worker packet path는 확인됐다. 부하 중 네트워크 가상화 CPU 비용도 2026-09-21에 측정했고, 이번 OIDC 부하 수준에서는 vhost/softirq 증가가 host CPU 전체를 지배하는 병목으로 보이지 않았다. 아직 남은 것은 QEMU userspace backend와 vhost-net을 같은 조건으로 비교하는 실험, RSS/RPS/XPS와 offload feature의 실제 상태다. 특히 offload feature 출력은 이번 캡처에서 확보하지 못했으므로 `tcpdump`의 packet size나 checksum을 wire-level 값으로 일반화하지 않는다.
<!-- body:end -->