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
@@ -2,7 +2,7 @@
id: 3b05c1f0-13e9-414a-97a6-2078fb4bab26
kind: CONCEPT
slug: guest-block-io-path-to-virtqueue
title: Guest 의 write() 가 virtqueue 에 실리기까지 — VFS · Filesystem · Page Cache · Block Layer · virtio-blk
title: 게스트의 write()가 virtqueue에 전달되는 과정
topic: storage-virtualization
topicName: 스토리지 가상화
project: virtualization
@@ -33,9 +33,9 @@ source:
- final/document.md#177-최종-요약
---
# Guest 의 write() 가 virtqueue 에 실리기까지 — VFS · Filesystem · Page Cache · Block Layer · virtio-blk
# 게스트의 write()가 virtqueue에 전달되는 과정
가상 머신 안의 PostgreSQL 이 파일에 데이터를 기록하면, 그 요청은 게스트 Linux 안에서만 VFS 와 ext4·XFS, 페이지 캐시, 블록 I/O 계층, virtio-blk 를 지난 뒤에야 virtqueue 에 실려 가상 머신 경계에 닿는다. 계층마다 무엇을 하고 무엇이 바뀌는지 차례로 살펴본다. 계층 이름과 게스트·호스트 구분을 아는 사람을 독자로 둔다. Keycloak 멀티 노드 실험을 가상 머신 두 대 위에서 돌리고 있다 보니, 이 경로를 알아 두면 게스트에서 본 저장소 지연을 애플리케이션 문제와 가상 머신 경계 아래의 문제로 갈라 볼 수 있다.
가상 머신 안의 PostgreSQL 이 파일에 데이터를 기록하면, 그 요청은 게스트 Linux 안에서만 VFS 와 ext4·XFS, 페이지 캐시, 블록 I/O 계층, virtio-blk 를 지난 뒤에야 virtqueue 에 실려 가상 머신 경계에 닿는다. 이 경로를 따라가면 게스트에서 관측한 저장소 지연이 애플리케이션 내부에서 생긴 것인지, 가상 머신 경계 아래의 블록 I/O 계층에서 생긴 것인지 구분할 수 있다.
<!-- body:start -->
@@ -94,7 +94,7 @@ SSD 는 `/var/lib/postgresql/data` 같은 디렉터리 구조를 모른다. 저
lsblk
```
```text label="기존 문서가 든 출력 예시. 이 호스트에서 실행한 결과가 아니다"
```text label="구조 설명용 출력 예시. 현재 호스트의 실측값은 아니다"
NAME SIZE TYPE MOUNTPOINT
vda 100G disk
├─vda1 1G part /boot
@@ -121,7 +121,7 @@ vda 100G disk
## 네트워크 가상화와 짝이 되는 이름들
제3부의 네트워크 경로를 먼저 읽었다면 이름이 하나씩 대응된다.
네트워크의 virtio-net과 비교하면 스토리지에서는 virtio-blk가 같은 위치의 프런트엔드 역할을 한다.
| Network | Storage |
|---|---|
@@ -140,6 +140,6 @@ vda 100G disk
2026-09-21 재검증에서 세 VM의 `vda`는 모두 qcow2 overlay file backend이고, 각 overlay는 공통 `base.qcow2`를 backing store로 사용한다는 것을 확인했다. 따라서 이 환경에서 guest `/dev/vda` 아래에 QEMU block backend와 host filesystem/block stack이 이어진다는 연결은 실제 구성과 맞는다.
다만 이 문서는 guest `write()`가 virtqueue에 실리기까지의 계층을 설명하는 데 집중한다. qcow2 L1/L2 table, `blk-mq` tag allocator, NVMe submission/completion queue 내부 구현은 범위 밖이다. 2026-09-21에는 guest `fsync()`와 host `iostat`을 같은 구간에 놓고 재서, guest fsync가 느려질 때 host NVMe의 `w_await`·`%util`·iowait도 함께 상승하는 구간을 실제로 확인했다. 이 결과는 경로의 존재를 보여 주지만, 모든 fsync 지연을 host storage 하나의 원인으로 일반화하지 않는다.
여기서 확인한 범위는 guest `write()`가 virtqueue에 전달되기까지다. qcow2 L1/L2 table, `blk-mq` tag allocator, NVMe submission/completion queue 내부 구현은 포함하지 않았다. 2026-09-21에는 guest `fsync()`와 host `iostat`을 같은 구간에 놓고 재서, guest fsync가 느려질 때 host NVMe의 `w_await`·`%util`·iowait도 함께 상승하는 구간을 실제로 확인했다. 이 결과는 경로의 존재를 보여 주지만, 모든 fsync 지연을 host storage 하나의 원인으로 일반화하지 않는다.
<!-- body:end -->
@@ -2,7 +2,7 @@
id: ecaaa37d-7b33-4cbf-9bc5-4c6caad14ee5
kind: CONCEPT
slug: host-block-stack-under-the-vm
title: VM 아래에 한 번 더 있는 Host block stack — blk-mq · I/O Scheduler · NVMe
title: 가상 머신 디스크 아래의 호스트 블록 I/O 계층
topic: storage-virtualization
topicName: 스토리지 가상화
project: virtualization
@@ -27,9 +27,9 @@ source:
- final/document.md#172-storage-virtualization-canonical-flow
---
# VM 아래에 한 번 더 있는 Host block stack — blk-mq · I/O Scheduler · NVMe
# 가상 머신 디스크 아래의 호스트 블록 I/O 계층
게스트가 디스크라고 부르는 것이 호스트에서는 qcow2 나 RAW 파일일 수 있고, 그러면 QEMU 의 쓰기는 호스트 파일시스템을 거쳐 호스트 블록 I/O 가 된다. 호스트 블록 계층은 그 요청이 가상 머신에서 왔는지 호스트 프로세스에서 왔는지 구분해 처리하는 계층이 아니라, 여러 QEMU 프로세스와 host의 SSH·관측·파일 작업 같은 I/O를 같은 아래쪽 장치로 받는다. 그 큐에서 blk-mq 와 I/O 스케줄러를 지나 NVMe 로 나가기까지를 따라가고, 거기서 생기는 스토리지 경쟁(Storage Contention)을 다투는 자원이 다른 CPU 경쟁과 갈라 놓는다. 블록 계층과 스케줄러 이름을 아는 사람을 독자로 둔다. 가상 머신 위에서 Keycloak 의 지연을 볼 때 이 계층을 CPU 계층과 갈라 두면 어느 쪽을 재야 하는지가 먼저 정해진다.
게스트가 디스크라고 부르는 것이 호스트에서는 qcow2 나 RAW 파일일 수 있고, 그러면 QEMU 의 쓰기는 호스트 파일시스템을 거쳐 호스트 블록 I/O 가 된다. 호스트 블록 계층은 그 요청이 가상 머신에서 왔는지 호스트 프로세스에서 왔는지 구분해 처리하는 계층이 아니라, 여러 QEMU 프로세스와 host의 SSH·관측·파일 작업 같은 I/O를 같은 아래쪽 장치로 받는다. 이 요청은 `blk-mq`와 I/O 스케줄러를 지나 NVMe로 전달된다. Keycloak 지연을 분석할 때 이 경로를 CPU 스케줄링과 분리해서 보면 CPU 사용률이 낮은데도 스토리지 대기 때문에 응답이 느려지는 경우를 구분할 수 있다.
<!-- body:start -->
@@ -38,7 +38,7 @@ source:
백엔드가 `qcow2` 파일이면 QEMU 가 물리 SSD 를 직접 제어하지 않는다. QEMU 는 `pread` 나 `pwrite` 같은 호출로 호스트 커널에 파일 I/O 를 요청하고, 그 요청이 호스트 파일시스템과 호스트 블록 계층, NVMe 드라이버를 지나 물리 NVMe 에 닿는다. 게스트 스토리지 계층 아래에 호스트 스토리지 계층이 한 번 더 존재할 수 있다.
호스트 블록 계층은 그 I/O 가 가상 머신 안의 PostgreSQL 에서 시작했는지 호스트 프로세스에서 시작했는지를 본질적으로 구분해서 처리하는 계층이 아니다. 내려온 것은 모두 호스트 블록 요청이다.
호스트 블록 계층은 요청이 게스트의 PostgreSQL에서 시작했는지 호스트 프로세스에서 시작했는지를 기준으로 별도 처리하지 않는다. 이 계층에 도달한 요청은 모두 호스트의 블록 I/O로 처리된다.
| 호스트 쪽 어느 계층인가 | 여기서 무엇이 일어나나 |
|---|---|
@@ -2,7 +2,7 @@
id: 892b6087-8961-486c-b4d9-d3dd46bc2605
kind: CONCEPT
slug: qemu-block-backend-forms
title: /dev/vda 뒤에 있는 것 — qcow2 · RAW · Host block device
title: QEMU 디스크 백엔드: qcow2, RAW, 블록 장치
topic: storage-virtualization
topicName: 스토리지 가상화
project: virtualization
@@ -26,24 +26,24 @@ source:
- final/document.md#174-핵심-claim
---
# /dev/vda 뒤에 있는 것 — qcow2 · RAW · Host block device
# QEMU 디스크 백엔드: qcow2, RAW, 블록 장치
게스트 안에서 /dev/vda 를 보는 것만으로는 호스트에 무엇이 있는지 알 수 없다. 가상 머신 경계를 넘으면 QEMU 의 virtio-blk 장치 모델과 블록 백엔드가 그 요청을 받는데, 그 백엔드는 qcow2 파일일 수도, RAW 파일일 수도, 호스트의 실제 블록 장치일 수도 있다. 파일 백엔드면 게스트 스토리지 계층 아래에 호스트 파일시스템과 블록 계층이 한 겹 더 놓이고, qcow2 면 게스트가 보는 크기와 호스트가 실제로 쓰는 크기가 갈린다. 무엇에 붙어 있는지는 게스트가 아니라 호스트에서 virsh domblklist 로 확인한다. 가상 머신에 디스크를 붙여 본 사람을 독자로 둔다.
게스트 안에서 /dev/vda 를 보는 것만으로는 호스트에 무엇이 있는지 알 수 없다. 가상 머신 경계를 넘으면 QEMU 의 virtio-blk 장치 모델과 블록 백엔드가 그 요청을 받는데, 그 백엔드는 qcow2 파일일 수도, RAW 파일일 수도, 호스트의 실제 블록 장치일 수도 있다. 파일 백엔드면 게스트 스토리지 계층 아래에 호스트 파일시스템과 블록 계층이 한 겹 더 놓이고, qcow2 면 게스트가 보는 크기와 호스트가 실제로 쓰는 크기가 갈린다. 무엇에 연결돼 있는지는 게스트가 아니라 호스트에서 `virsh domblklist`와 libvirt XML로 확인한다.
<!-- body:start -->
![Guest의 /dev/vda가 virtio-blk와 virtqueue를 지나 QEMU block backend에 도착한 뒤 qcow2 파일, RAW 파일, Host block device 세 갈래로 나뉘는 구조도. 그 아래 Host block stack은 별도 개념 문서가 맡아 이 그림에서는 다시 합치지 않는다.](../../../final/assets/diagrams/qemu-block-backend-forms/qemu-block-backend-forms.svg)
## 가상 머신 경계를 넘으면 QEMU 가 받는다
## virtio-blk 요청은 QEMU 블록 백엔드로 전달된다
게스트의 `virtio-blk` 가 `virtqueue` 에 게시한 요청은 가상 머신 경계를 넘어 호스트 사용자 공간의 QEMU 로 간다. QEMU 안에서는 `virtio-blk` 장치 모델과 블록 백엔드가 그 요청을 받는다. QEMU 는 게스트에게 가상 블록 장치를 노출하고, 게스트의 가상 I/O 를 호스트 백엔드에 연결한다.
기존 문서는 제4부의 전체 구조를 그린 뒤 이 갈림을 핵심 문장 하나로 따로 뽑아 두었다.
게스트에서 보이는 `/dev/vda`만으로는 호스트에서 어떤 백엔드를 사용하는지 알 수 없다. 실제 백엔드는 libvirt XML과 QEMU 실행 상태에서 확인해야 한다.
> Guest는 `/dev/vda`를 실제 block device처럼 보지만, Host에서는 그 disk가 qcow2 파일, RAW 파일, 또는 실제 block device에 연결되어 있을 수 있다.
이 글이 다루는 것이 그 문장이 남긴 세 갈래다.
이 세 가지 백엔드는 호스트에서 확인하는 방법과 성능·용량 특성이 서로 다르다.
## QEMU 가 물리 SSD 를 직접 제어하지는 않는다
@@ -73,11 +73,11 @@ RAW 는 `qcow2` 보다 구조가 단순하다. 게스트의 블록 요청이 `qc
그렇다고 RAW가 무조건 빠르고 `qcow2`가 무조건 느리다고 일반화하면 안 된다. 실제 성능은 cache mode, storage backend, workload pattern, queue depth, snapshot chain, host filesystem, physical device에 함께 영향을 받는다. 형식 이름만으로 어느 쪽이 빠른지 정해지지 않는다.
그 목록 가운데 스냅샷 체인이 왜 걸리는지는 기존 문서의 qcow2 내부 절이 따로 풀었다. 매핑 항목이 0 인 클러스터를 만날 때마다 한 층 아래로 내려가야 해서 체인이 깊으면 읽기가 느려지고, 그래서 이 실험대는 층을 두세 겹 넘게 쌓지 않는다. 굳힐 때는 `qemu-img commit` 으로 아래층에 병합하거나 `qemu-img convert` 로 단일 파일로 평탄화한다.
qcow2 스냅샷 체인이 깊어지면 현재 오버레이에 없는 클러스터를 읽을 때 backing chain을 여러 단계 확인해야 한다. 이 실험대에서는 체인을 깊게 쌓지 않고, 필요하면 `qemu-img commit`으로 변경분을 아래 이미지에 합치거나 `qemu-img convert`로 독립된 파일을 만든다.
## 백엔드가 파일이 아니라 호스트 블록 장치일 수도 있다
백엔드는 파일이 아니어도 된다. 게스트의 `/dev/vda` 가 `virtio-blk` 와 QEMU 를 지나 호스트의 `/dev/nvme0n1p3` 같은 블록 장치에 바로 연결될 수 있고, 기존 문서가 그린 이 경로에는 호스트 파일시스템이 없다. 같은 이름 아래에서 경로가 세 갈래로 갈리기 때문에, 게스트에 `/dev/vda` 가 있다는 정보만으로는 백엔드 구조를 알 수 없다.
백엔드는 파일이 아니라 호스트 블록 장치일 수도 있다. 게스트의 `/dev/vda`가 `virtio-blk`와 QEMU를 거쳐 호스트의 블록 장치에 직접 연결된 구성이라면 호스트 파일시스템을 거치지 않는다. 따라서 게스트에서 `/dev/vda`가 보인다는 사실만으로 백엔드가 qcow2인지 RAW 파일인지 블록 장치인지 알 수 없다.
## 세 갈래가 각각 바꾸는 것
@@ -99,7 +99,7 @@ lsblk
virsh domblklist <VM_NAME>
```
```text label="기존 문서가 든 출력 예시. 이 호스트에서 실행한 결과가 아니다"
```text label="구조 설명용 출력 예시. 현재 호스트의 실측값은 아니다"
Target Source
-----------------------------------------------
vda /var/lib/libvirt/images/vm1.qcow2
@@ -2,7 +2,7 @@
id: 8fafaeea-8746-4537-87a4-679a3a91aa4c
kind: CONCEPT
slug: write-completion-is-not-durability
title: 완료라는 말의 네 가지 뜻 — write · writeback · flush · 전원 장애 생존
title: write() 완료와 데이터 영속성은 같은 의미가 아니다
topic: storage-virtualization
topicName: 스토리지 가상화
project: virtualization
@@ -30,9 +30,9 @@ source:
- final/document.md#174-핵심-claim
---
# 완료라는 말의 네 가지 뜻 — write · writeback · flush · 전원 장애 생존
# write() 완료와 데이터 영속성은 같은 의미가 아니다
buffered I/O 에서 write() 는 페이지 캐시까지만 내려가고, 가상 머신에서는 그 페이지 캐시가 게스트와 호스트 양쪽에 두 번 나타날 수 있다. 게스트가 성공을 돌려받은 데이터가 호스트 메모리에 머무는 동안 호스트 전원이 나가면 물리 SSD 에는 이전 상태가 남는다. 그래서 완료라는 말이 네 단계로 갈린다 — write() 완료, writeback 완료, fsync/flush 완료, 전원 장애에도 안전한 영속성. Direct I/O 와 QEMU 캐시 모드가 이 가운데 어디까지 가는지를 바꾼다. 페이지 캐시와 fsync 를 아는 사람을 독자로 둔다. Keycloak 과 PostgreSQL 을 가상 머신 위에서 돌리는 실험에서는 이 구분을 먼저 세워야 지연을 재는 것과 데이터가 남는지를 재는 것이 한 실험에 섞이지 않는다.
buffered I/O 에서 write() 는 페이지 캐시까지만 내려가고, 가상 머신에서는 그 페이지 캐시가 게스트와 호스트 양쪽에 두 번 나타날 수 있다. 게스트가 성공을 돌려받은 데이터가 호스트 메모리에 머무는 동안 호스트 전원이 나가면 물리 SSD 에는 이전 상태가 남는다. 그래서 완료라는 말이 네 단계로 갈린다 — write() 완료, writeback 완료, fsync/flush 완료, 전원 장애에도 안전한 영속성. Direct I/O 와 QEMU 캐시 모드가 이 가운데 어디까지 가는지를 바꾼다. Keycloak과 PostgreSQL을 가상 머신 위에서 측정할 때는 응답 지연과 데이터 영속성을 별도 조건으로 확인해야 한다. 쓰기가 빨리 끝났다는 사실만으로 전원 장애 뒤에도 데이터가 남는다고 판단할 수는 없다.
<!-- body:start -->
@@ -71,7 +71,7 @@ write(fd, data, size);
fsync(fd);
```
가상 머신에서는 이 요청이 한 계층에서 끝나지 않는다. 게스트 PostgreSQL 의 `fsync()` 가 게스트 파일시스템으로 가고, 게스트 블록 계층에서 `FLUSH` 등으로 바뀐다. 그다음 `virtio-blk` 를 통해 QEMU 와 백엔드로 내려가고, 호스트 스토리지 계층을 지나 물리 저장장치까지 그 의미가 전달되어야 한다.
가상 머신에서 `fsync()`의 영속성 의미가 지켜지려면 요청이 게스트 파일시스템과 블록 계층, `virtio-blk`, QEMU 백엔드, 호스트 스토리지 계층을 거쳐 물리 저장장치까지 전달되어야 한다.
![PostgreSQL 이 부른 fsync() 가 Guest Filesystem 으로 내려가고, Guest Block Layer 에서 FLUSH 등으로 바뀌어 virtio-blk 와 QEMU / Backend, Host Storage Stack 을 지나 맨 아래 Physical Storage 까지 닿는 흐름도. 여섯 번 손이 바뀌는 동안 한 곳이라도 그 의미를 지키지 않으면 게스트가 받은 완료 응답이 거짓이 된다.](../../../final/assets/diagrams/write-completion-boundaries/write-completion-boundaries.svg)