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
@@ -52,7 +52,7 @@ source:
libvirt 는 가상 머신의 수명 주기와 구성을 관리하는 계층이다. 가상 머신 정의에는 RAM 8 GiB, vCPU 4 같은 값이 들어 있다. libvirt 는 그 정의를 바탕으로 QEMU 를 적절한 옵션과 함께 실행하고 관리한다.
QEMU 는 호스트의 사용자 공간에서 실행되는 프로세스다. 4 vCPU 가상 머신이라면 메인·제어 스레드 하나와 vCPU 스레드 넷이 만들어진다. KVM 가속을 쓸 때 게스트의 일반 CPU 명령을 QEMU 가 하나씩 소프트웨어로 번역해 실행하는 경로가 핵심은 아니다. vCPU 스레드가 KVM 을 통해 게스트 실행을 요청하면 게스트 코드는 VMX 를 이용해 실제 CPU 에서 직접 실행된다.
QEMU 는 호스트의 사용자 공간에서 실행되는 프로세스다. 4 vCPU 가상 머신이라면 메인·제어 스레드 하나와 vCPU 스레드 넷이 만들어진다. KVM 가속을 사용할 때 일반적인 게스트 CPU 명령은 QEMU가 하나씩 소프트웨어로 해석하는 방식으로 실행되지 않는다. vCPU 스레드가 KVM을 통해 게스트 실행을 요청하면 VMX를 이용해 게스트 코드가 실제 CPU에서 실행된다.
`/dev/kvm` 은 프로세스가 아니라 Linux 가 사용자 공간 프로그램에 KVM API 를 노출하는 문자 장치(character device) 인터페이스다. QEMU 는 이 파일을 열고 `ioctl` 로 `KVM_CREATE_VM`, `KVM_CREATE_VCPU`, `KVM_SET_USER_MEMORY_REGION`, `KVM_RUN` 같은 동작을 요청한다.
@@ -26,7 +26,7 @@ source:
# Keycloak 작업의 VM Exit 분포는 idle · CPU-bound · I/O-bound 와 어떻게 다른가
2026-09-21 같은 `kc-lab-1`에서 baseline · CPU-bound · I/O-heavy · Keycloak 정상 요청 · Keycloak read-only 부하를 `perf kvm stat live -p <QEMU_PID>`로 비교했다. Keycloak 정상 요청 10회 구간은 baseline과 비슷했지만, OIDC discovery 1000회/concurrency 20 부하에서는 `EPT_MISCONFIG` 비중과 전체 VM Exit sample 수가 뚜렷하게 증가했다. **Keycloak workload의 Exit 분포는 부하 강도에 따라 실제로 달라지지만, 이 변화만으로 병목이라고 판정하지 않는다.**
2026-09-21 같은 `kc-lab-1`에서 baseline · CPU-bound · I/O-heavy · Keycloak 정상 요청 · Keycloak read-only 부하를 `perf kvm stat live -p <QEMU_PID>`로 비교했다. Keycloak 정상 요청 10회 구간은 baseline과 비슷했지만, OIDC discovery 1000회/concurrency 20 부하에서는 `EPT_MISCONFIG` 비중과 전체 VM Exit sample 수가 뚜렷하게 증가했다. Keycloak workload의 Exit 분포는 부하 강도에 따라 실제로 달라지지만, 이 변화만으로 병목이라고 판정하지 않는다.
## 2026-09-21에 비교한 다섯 구간
@@ -20,7 +20,7 @@ source:
# 이 호스트의 NUMA 토폴로지는 가상 머신 성능을 고려해야 할 구조인가
2026-09-21 현재 `test-server`는 **NUMA node 1개**다. `lscpu`에서 `NUMA node(s): 1`, `NUMA node0 CPU(s): 0-7`을 확인했고 sysfs의 `/sys/devices/system/node/node0/cpulist`도 `0-7`이었다. 따라서 현재 host에서는 remote NUMA 접근을 전제로 한 vCPU/memory locality 튜닝을 우선 항목으로 둘 이유가 없다.
2026-09-21 현재 `test-server`는 NUMA node 1개다. `lscpu`에서 `NUMA node(s): 1`, `NUMA node0 CPU(s): 0-7`을 확인했고 sysfs의 `/sys/devices/system/node/node0/cpulist`도 `0-7`이었다. 따라서 현재 host에서는 remote NUMA 접근을 전제로 한 vCPU/memory locality 튜닝을 우선 항목으로 둘 이유가 없다.
## 현재 호스트의 토폴로지
@@ -68,9 +68,9 @@ source:
### 3. 메모리 가상화 쪽에서 함께 본다 — 제외
상세한 메모리 배치를 「NUMA」~「NUMA는 실제 장비 topology부터 확인한다」에서는 다루므로 확인도 그쪽에서 하자는 방법이다.
여기서는 호스트의 NUMA node 수와 CPU 배치까지만 확인하고, 메모리 locality에 따른 성능 차이는 여러 NUMA node가 있는 환경에서 별도로 측정한다.
지금 필요한 판단은 이 항목을 실험 목록의 어디에 둘지 하나이고, 그것은 노드 수만으로 갈린다.
「NUMA는 실제 장비 topology부터 확인한다」에서는 먼저 topology 를 측정하고 NUMA 최적화가 필요한지 판단한다고 적었다. 그 순서대로면 노드 수는 여기서 재고 배치 조정을 그쪽이 받는다.
현재 호스트는 NUMA node가 하나뿐이므로 remote memory 배치 자체가 성립하지 않는다. 따라서 이 환경에서는 NUMA pinning이나 memory binding을 성능 최적화 항목으로 올리지 않는다.
## 이 호스트에서는 NUMA 간 차이를 비교할 수 없다
@@ -46,9 +46,9 @@ Steal time 증가 : Guest 에서 관측
Host CPU saturation : Host
「실험대 전체 배치 (2026-09-03 구축 완료, 실측값)」에서는 운영을 `desktop` 이라 부르고 그 배치를 `nginx → 127.0.0.1:30080(NodePort) → Traefik` 으로 적었다. 이 실험대의 배치와 다른 것은 단일 노드냐 2노드냐 하나다.
「nginx 설정 구조 — `sites-available`은 nginx 기능이 아니다」에서는 그 `desktop` 이 Ubuntu 라고 적는다. 같은 절이 이 실험대가 `sites-available` 방식을 쓰는 이유도 적었다. 「운영(`desktop`)이 Ubuntu라 그 구조를 쓰고 있으므로, 설정을 운영으로 옮길 때 경로가 그대로 맞는 편이 낫다는 판단이다.」 기존 문서가 운영과 같다고 적은 것은 그 2홉 경로와 이 설정 관례 둘이다.
확인된 운영 관련 정보는 두 가지뿐이다. 운영 쪽 nginx는 Ubuntu의 `sites-available`/`sites-enabled` 관례를 사용하고, 요청 경로도 nginx와 내부 라우터를 거치는 2홉 구조로 기록돼 있다. 이것만으로 운영 서버가 bare-metal인지 가상 머신인지 판단할 수는 없다.
운영 서버가 bare-metal 인지 상위 하이퍼바이저나 클라우드 가상 머신 위인지는 기존 문서에 적혀 있지 않다.
운영 서버가 bare-metal인지 상위 하이퍼바이저나 클라우드 가상 머신 위인지는 아직 확인되지 않았다.
## 판단에 필요한 전제
@@ -28,7 +28,7 @@ source:
# CPU pinning 전후로 Keycloak 지연과 vCPU 스케줄링 변동이 달라지는가
2026-09-21 두 worker를 live pinning으로 `kc-lab-1 vCPU0/1 → pCPU 0/1`, `kc-lab-2 vCPU0/1 → pCPU 2/3`에 묶고 동일 OIDC read-only 부하를 전후로 비교했다. pinning 전에는 같은 vCPU TID의 `PSR`이 여러 pCPU 사이를 이동했지만 pinning 뒤에는 각각 0/1/2/3에 고정됐다. 그러나 **Keycloak latency/throughput 개선은 반복 실행에서 재현되지 않았다.**
2026-09-21 두 worker를 live pinning으로 `kc-lab-1 vCPU0/1 → pCPU 0/1`, `kc-lab-2 vCPU0/1 → pCPU 2/3`에 묶고 동일 OIDC read-only 부하를 전후로 비교했다. pinning 전에는 같은 vCPU TID의 `PSR`이 여러 pCPU 사이를 이동했지만 pinning 뒤에는 각각 0/1/2/3에 고정됐다. 그러나 Keycloak latency/throughput 개선은 반복 실행에서 재현되지 않았다.
## pinning 전후 비교 결과
@@ -22,7 +22,7 @@ source:
# 가상 머신 두 대를 CPU-bound 로 만들면 게스트 steal time 은 얼마나 오르는가
2026-09-21 두 worker의 vCPU를 동시에 CPU-bound로 만든 10초 관측 구간에서 **guest steal time은 증가하지 않았다.** `kc-lab-1`과 `kc-lab-2` 모두 부하 중 `vmstat`의 `st`가 전 구간 0%였고, host에는 약 49~50% idle CPU가 남았다.
2026-09-21 두 worker의 vCPU를 동시에 CPU-bound로 만든 10초 관측 구간에서 guest steal time은 증가하지 않았다. `kc-lab-1`과 `kc-lab-2` 모두 부하 중 `vmstat`의 `st`가 전 구간 0%였고, host에는 약 49~50% idle CPU가 남았다.
## 두 worker를 CPU-bound로 만든 결과
@@ -23,7 +23,7 @@ source:
# cgroup CPU 제한과 호스트 vCPU 경쟁을 지표로 가를 수 있는가
2026-09-21 현재 Keycloak은 CPU request `100m`만 있고 CPU limit은 없으며 컨테이너의 `cpu.max`는 `max 100000`, `nr_throttled=0`이었다. 별도 disposable pod에 `100m` CPU limit을 걸어 cgroup throttling을 재현하고, 반대로 CPU limit 없이 한 VM의 두 vCPU를 같은 pCPU에 묶어 host-level contention을 재현했다. **두 원인은 실제 지표 조합이 다르게 나타났다.**
2026-09-21 현재 Keycloak은 CPU request `100m`만 있고 CPU limit은 없으며 컨테이너의 `cpu.max`는 `max 100000`, `nr_throttled=0`이었다. 별도 disposable pod에 `100m` CPU limit을 걸어 cgroup throttling을 재현하고, 반대로 CPU limit 없이 한 VM의 두 vCPU를 같은 pCPU에 묶어 host-level contention을 재현했다. 두 원인은 실제 지표 조합이 다르게 나타났다.
## 두 원인을 따로 재현한 결과
@@ -19,7 +19,7 @@ source:
# vCPU 를 늘릴수록 이 호스트에서 Keycloak 처리량도 계속 오르는가
이 비교는 아직 수행하지 않았다. 2026-09-21에는 현재 2 vCPU worker 구성에서 CPU-bound·OIDC 부하를 측정했지만, VM을 2·4·8 vCPU로 재정의해 같은 Keycloak 부하를 반복하지는 않았다. 현재 worker/edge가 실제 lab을 구성하고 있고 추가 상태변경 테스트는 마지막 단계로 미뤘으므로 topology 변경 비교는 별도 실험에서 수행한다.
2·4·8 vCPU 구성에서 같은 Keycloak 부하를 반복하는 비교는 아직 수행하지 않았다. 2026-09-21에는 현재 2 vCPU worker 구성에서 CPU-bound 부하와 OIDC 부하만 측정했다. 현재 worker/edge가 실제 lab을 구성하고 있고 추가 상태변경 테스트는 마지막 단계로 미뤘으므로 topology 변경 비교는 별도 실험에서 수행한다.
## 현재 호스트와 VM의 CPU 여유
@@ -65,7 +65,7 @@ vCPU 수만 바꾸고 Keycloak 설정과 부하는 세 실행에서 고정한다
논리 코어가 8 이라 8 vCPU 구성에서는 한 게스트의 vCPU 수가 코어 수와 같아진다. 나머지 게스트를 함께 띄우면 합이 8 을 넘으므로, 세 실행마다 그때 떠 있던 게스트와 총 vCPU 를 함께 적는다.
「단계 00 — lab host 가상화 준비」의 과거 출력에는 「16 코어 전부」가 남아 있었지만, 현재 호스트는 2026-09-17과 2026-09-21에 다시 확인한 **물리 4코어·8 logical CPU**다. 따라서 이 질문의 2·4·8 vCPU 비교는 8 logical CPU를 현재 truth로 둔다. 16코어 줄은 현재 `test-server`의 값으로 쓰지 않는다.
「단계 00 — lab host 가상화 준비」의 과거 출력에는 「16 코어 전부」가 남아 있었지만, 현재 호스트는 2026-09-17과 2026-09-21에 다시 확인한 **물리 4코어·8 logical CPU**다. 현재 `test-server`는 물리 4코어·8 logical CPU이므로 이후 2·4·8 vCPU 비교도 이 값을 기준으로 한다. 과거 문서의 16코어 출력은 현재 호스트의 값으로 사용하지 않는다.
「vCPU 과다 할당」에서 든 두 원인을 가르려면 처리량과 지연만으로는 부족하다. 게스트의 %st 를 같은 실행에서 남긴다.
@@ -22,7 +22,7 @@ source:
# 가상 머신 두 대에 동시에 부하를 주면 이 호스트에서 vCPU 경쟁이 실제로 생기는가
2026-09-21 `kc-lab-1`과 `kc-lab-2`의 2 vCPU를 각각 모두 CPU-bound로 만든 뒤 host와 두 guest를 동시에 관측했다. 부하 중 host run queue는 4~6으로 늘었지만 host는 약 49~50% idle이 남았고, 두 guest의 steal time은 계속 0%였다. **현재 8 logical CPU / worker 4 vCPU 구성에서는 이 부하로 host CPU 부족에 의한 vCPU contention이 관측되지 않았다.**
2026-09-21 `kc-lab-1`과 `kc-lab-2`의 2 vCPU를 각각 모두 CPU-bound로 만든 뒤 host와 두 guest를 동시에 관측했다. 부하 중 host run queue는 4~6으로 늘었지만 host는 약 49~50% idle이 남았고, 두 guest의 steal time은 계속 0%였다. 현재 8 logical CPU / worker 4 vCPU 구성에서는 이 부하로 host CPU 부족에 의한 vCPU contention이 관측되지 않았다.
## 두 worker를 동시에 태웠을 때
@@ -23,7 +23,7 @@ source:
# pinning 없이 vCPU 스레드는 호스트 논리 CPU 사이를 옮겨 다니는가
2026-09-21 QEMU monitor로 실제 vCPU thread ID를 얻고 `ps -eL`의 `PSR`을 약 3초 동안 반복해서 읽었다. pinning은 없었고 affinity는 모두 `0-7` 전체였다. 같은 TID의 `PSR`이 여러 값으로 바뀌어 **unpinned vCPU thread가 host logical CPU 사이를 실제로 이동하는 것**을 확인했다.
2026-09-21 QEMU monitor로 실제 vCPU thread ID를 얻고 `ps -eL`의 `PSR`을 약 3초 동안 반복해서 읽었다. pinning은 없었고 affinity는 모두 `0-7` 전체였다. 같은 TID의 `PSR`이 여러 값으로 바뀌어 unpinned vCPU thread가 host logical CPU 사이를 실제로 이동하는 것을 확인했다.
## 실제로 이동한 vCPU thread
@@ -56,7 +56,7 @@ CPU pinning 을 적용하면 실행 위치를 특정 논리 CPU 집합으로 제
## migration과 성능은 다른 질문이다
이 질문의 핵심인 실제 migration 여부와 pinning 유무는 해소됐다. 현재 vCPU thread는 `0-7` 전체에 실행 가능하고 짧은 관측에서도 실제 migration이 보였다. idle과 CPU-bound 상태에서 migration 빈도가 얼마나 달라지는지는 성능 비교 질문으로 분리한다.
현재 vCPU thread의 affinity는 `0-7` 전체이고, 짧은 관측에서도 같은 TID가 여러 pCPU 사이를 이동했다. pinning이 없는 상태에서 실제 migration이 발생한다는 것은 확인했다. idle과 CPU-bound 상태에서 migration 빈도가 얼마나 달라지는지는 별도 성능 비교가 필요하다.
## 이 결과의 범위
@@ -19,7 +19,7 @@ source:
# Keycloak 동시 refresh 실험 중 CPU 가상화 계층이 결과를 흔들 만큼 포화되는가
이 질문은 아직 실제 refresh 경쟁 조건으로 검증하지 않았다. 2026-09-21 OIDC discovery synthetic load와 KVM/host CPU 지표는 함께 측정했지만, 질문이 요구하는 **동일 refresh token 동시 요청 + Keycloak latency + PostgreSQL 지연** 실험은 수행하지 않았다. 현재 Keycloak lab에는 Redis가 배포돼 있지 않으므로 Redis 지연을 이 질문의 필수 항목으로 두지 않는다. 별도 BFF/Redis 구성을 함께 재는 실험이라면 그때 Redis 지표를 추가한다. OIDC 부하 결과를 refresh 경쟁 실험의 대체 근거로 사용하지 않는다.
동일 refresh token을 동시에 사용하는 경쟁 조건은 아직 실제로 검증하지 않았다. 2026-09-21 OIDC discovery synthetic load와 KVM/host CPU 지표는 함께 측정했지만, 질문이 요구하는 동일 refresh token 동시 요청 + Keycloak latency + PostgreSQL 지연 실험은 수행하지 않았다. 현재 Keycloak lab에는 Redis가 배포돼 있지 않으므로 이번 refresh 경쟁 실험의 측정 항목에도 Redis 지연을 포함하지 않는다. 별도 BFF/Redis 구성을 함께 재는 실험이라면 그때 Redis 지표를 추가한다. OIDC 부하 결과를 refresh 경쟁 실험의 대체 근거로 사용하지 않는다.
## 현재 실험대의 CPU 조건
@@ -26,7 +26,7 @@ source:
# 실제 작업에서 주로 발생하는 VM Exit 은 무엇인가
2026-09-21 `perf 7.2.2-1`의 `perf kvm stat live -p <QEMU_PID> --event vmexit`가 이 호스트에서 동작하는 것을 확인하고, 같은 `kc-lab-1` QEMU를 대상으로 baseline · CPU-bound · I/O-heavy · Keycloak 정상 요청 · Keycloak read-only 부하를 비교했다. **workload에 따라 VM Exit 분포가 실제로 달라졌다.** CPU-bound에서는 HLT가 사라지고 External Interrupt/Preemption Timer 비중이 크게 늘었고, Keycloak 고부하에서는 baseline보다 EPT_MISCONFIG 비중과 전체 sample 수가 증가했다.
2026-09-21 `perf 7.2.2-1`의 `perf kvm stat live -p <QEMU_PID> --event vmexit`가 이 호스트에서 동작하는 것을 확인하고, 같은 `kc-lab-1` QEMU를 대상으로 baseline · CPU-bound · I/O-heavy · Keycloak 정상 요청 · Keycloak read-only 부하를 비교했다. workload에 따라 VM Exit 분포가 실제로 달라졌다. CPU-bound에서는 HLT가 사라지고 External Interrupt/Preemption Timer 비중이 크게 늘었고, Keycloak 고부하에서는 baseline보다 EPT_MISCONFIG 비중과 전체 sample 수가 증가했다.
## workload마다 달라진 Exit 분포