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
@@ -846,7 +846,7 @@
"case": [],
"concept": [
{
"title": "Guest 메모리 주소가 물리 RAM 에 닿기까지 — GVA · GPA · HPA",
"title": "게스트 가상 주소가 물리 메모리 주소로 변환되는 과정",
"kind": "concept",
"slug": "guest-memory-address-translation",
"readiness": "READY",
@@ -942,7 +942,7 @@
"evidenceFiles": []
},
{
"title": "Huge Page 를 VM 에서 볼 때 갈라지는 세 자리",
"title": "가상 머신에서 Huge Page를 확인할 때 구분해야 하는 세 계층",
"kind": "concept",
"slug": "huge-pages-in-a-vm",
"readiness": "READY",
@@ -1193,7 +1193,7 @@
]
},
{
"title": "QEMU 프로세스가 실제로 붙잡고 있는 호스트 메모리는 얼마이고 어떻게 나뉘어 있는가",
"title": "QEMU 프로세스의 호스트 메모리 사용량은 얼마인가",
"kind": "question",
"slug": "qemu-resident-memory-distribution",
"readiness": "OPEN",
@@ -1317,7 +1317,7 @@
]
},
{
"title": "호스트 메모리 압박이 게스트 애플리케이션 지연을 실제로 밀어 올리는가",
"title": "호스트 메모리 압박이 게스트 애플리케이션 지연에 영향을 주는가",
"kind": "question",
"slug": "host-memory-pressure-vs-guest-latency",
"readiness": "OPEN",
@@ -1557,7 +1557,7 @@
"case": [],
"concept": [
{
"title": "Guest 의 packet 이 Host Physical NIC 에 닿기까지 — virtio-net · virtqueue · vhost-net · TAP · Bridge",
"title": "게스트 패킷이 호스트 물리 NIC까지 전달되는 과정",
"kind": "concept",
"slug": "guest-packet-path-to-physical-nic",
"readiness": "READY",
@@ -1628,7 +1628,7 @@
],
"reference": [
{
"title": "packet 이 어디서 끊겼는지는 계층마다 capture 해서 가른다",
"title": "패킷 경로는 구간별 캡처로 확인한다",
"kind": "reference",
"slug": "bisect-the-packet-path-with-capture-points",
"readiness": "READY",
@@ -1950,7 +1950,7 @@
"case": [],
"concept": [
{
"title": "Guest 의 write() 가 virtqueue 에 실리기까지 — VFS · Filesystem · Page Cache · Block Layer · virtio-blk",
"title": "게스트의 write()가 virtqueue에 전달되는 과정",
"kind": "concept",
"slug": "guest-block-io-path-to-virtqueue",
"readiness": "READY",
@@ -2001,7 +2001,7 @@
"evidenceFiles": []
},
{
"title": "/dev/vda 뒤에 있는 것 — qcow2 · RAW · Host block device",
"title": "QEMU 디스크 백엔드: qcow2, RAW, 블록 장치",
"kind": "concept",
"slug": "qemu-block-backend-forms",
"readiness": "READY",
@@ -2042,7 +2042,7 @@
"evidenceFiles": []
},
{
"title": "완료라는 말의 네 가지 뜻 — write · writeback · flush · 전원 장애 생존",
"title": "write() 완료와 데이터 영속성은 같은 의미가 아니다",
"kind": "concept",
"slug": "write-completion-is-not-durability",
"readiness": "READY",
@@ -2089,7 +2089,7 @@
"evidenceFiles": []
},
{
"title": "VM 아래에 한 번 더 있는 Host block stack — blk-mq · I/O Scheduler · NVMe",
"title": "가상 머신 디스크 아래의 호스트 블록 I/O 계층",
"kind": "concept",
"slug": "host-block-stack-under-the-vm",
"readiness": "READY",
@@ -2136,7 +2136,7 @@
],
"reference": [
{
"title": "지연 원인을 CPU 로 읽기 전에 storage 계층을 따로 잰다",
"title": "지연 분석에서는 CPU와 스토리지를 함께 측정한다",
"kind": "reference",
"slug": "read-storage-before-blaming-cpu-for-latency",
"readiness": "READY",
@@ -2167,7 +2167,7 @@
"evidenceFiles": []
},
{
"title": "빨라진 구성이 durability contract 를 지운 것은 아닌지 먼저 가른다",
"title": "성능 개선 전후로 데이터 영속성 보장이 달라졌는지 확인한다",
"kind": "reference",
"slug": "a-speedup-that-removed-durability-is-not-an-optimization",
"readiness": "READY",
@@ -2200,7 +2200,7 @@
"evidenceFiles": []
},
{
"title": "Guest 안에서 본 disk 로 backend 를 단정하지 않는다",
"title": "디스크 백엔드는 호스트에서 확인한다",
"kind": "reference",
"slug": "confirm-the-disk-backend-on-the-host",
"readiness": "READY",
@@ -2400,7 +2400,7 @@
]
},
{
"title": "VM1 의 storage 부하가 VM2 의 지연을 실제로 밀어 올리는가",
"title": "VM1의 스토리지 부하가 VM2의 지연에 영향을 주는가",
"kind": "question",
"slug": "vm1-storage-load-vs-vm2-latency",
"readiness": "OPEN",
@@ -2485,7 +2485,7 @@
"kinds": {
"case": [
{
"title": "호스트 안에서는 404, 밖에서는 connection refused — 앞 체인의 accept 가 libvirt 의 reject 를 막지 못했다",
"title": "libvirt guest_input 체인의 reject로 외부 요청이 차단된 사례",
"kind": "case",
"slug": "nftables-accept-did-not-stop-the-libvirt-reject",
"readiness": "READY",
@@ -2519,7 +2519,7 @@
"evidenceFiles": []
},
{
"title": "메모리와 디스크의 선언량은 실제 점유량이 아니다 — 서로 다른 지표를 같은 숫자로 읽지 않는다",
"title": "설정한 메모리·디스크 크기와 실제 사용량을 구분해서 본다",
"kind": "case",
"slug": "declared-memory-and-disk-are-ceilings-not-occupancy",
"readiness": "READY",
@@ -2556,7 +2556,7 @@
],
"concept": [
{
"title": "qcow2 파일 한 장이 담는 것 — 매핑표와 데이터 클러스터가 같은 파일 안에 있고, 파일 밖을 가리키는 것은 백킹 파일 경로 하나다",
"title": "qcow2 파일에는 무엇이 저장되는가",
"kind": "concept",
"slug": "what-a-qcow2-file-carries",
"readiness": "READY",
@@ -2582,7 +2582,7 @@
"evidenceFiles": []
},
{
"title": "설치를 안 했는데 왜 뜨는가 — 클라우드 이미지는 설치가 끝난 디스크이고 cloud-init 이 빈칸을 채운다",
"title": "클라우드 이미지와 cloud-init은 각각 무엇을 준비하는가",
"kind": "concept",
"slug": "a-cloud-image-is-an-installed-disk-and-cloud-init-fills-the-blanks",
"readiness": "READY",
@@ -2613,7 +2613,7 @@
"evidenceFiles": []
},
{
"title": "qcow2 파일 안 — 매핑표와 클러스터, 그리고 항목이 0 이면 바닥에 다시 묻는다",
"title": "qcow2의 매핑 테이블과 데이터 클러스터",
"kind": "concept",
"slug": "inside-a-qcow2-file-the-mapping-table-and-its-clusters",
"readiness": "READY",
@@ -2967,7 +2967,7 @@
"evidenceFiles": []
},
{
"title": "같은 설정 파일이 두 배포판에서 같은 뜻이 아니다 — 옮기기 전에 세 가지를 본다",
"title": "배포판이 다르면 같은 설정 파일도 그대로 옮기지 않는다",
"kind": "reference",
"slug": "a-config-file-does-not-mean-the-same-thing-on-two-distros",
"readiness": "READY",
@@ -3002,7 +3002,7 @@
],
"question": [
{
"title": "libvirt 의 firewall_backend 가 iptables 일 때도 guest_input 에 구멍이 필요한가",
"title": "libvirt firewall_backend가 iptables일 때도 guest_input 예외 규칙이 필요한가",
"kind": "question",
"slug": "guest-input-hole-under-the-iptables-backend",
"readiness": "OPEN",
@@ -3126,7 +3126,7 @@
],
"decision": [
{
"title": "엣지 nginx 를 호스트에서 게스트 VM 으로 옮긴다 — 성능이 아니라 더러워지는 층의 격리",
"title": "Edge Nginx를 호스트에서 게스트 VM으로 분리한 이유",
"kind": "decision",
"slug": "edge-nginx-moved-into-a-guest-vm",
"readiness": "READY",
@@ -3155,7 +3155,7 @@
"evidenceFiles": []
},
{
"title": "인증서는 DNS-01 로 받는다 — 실험대 주소가 공개 인터넷에 없어 HTTP-01 이 성립하지 않는다",
"title": "공개 인터넷에 노출되지 않은 실험대에서 DNS-01을 선택한 이유",
"kind": "decision",
"slug": "dns-01-because-the-lab-is-not-on-the-public-internet",
"readiness": "READY",
@@ -3185,7 +3185,7 @@
"evidenceFiles": []
},
{
"title": "호스트에 직접 깔지 않고 게스트 VM 두 대로 간다 — 관측자가 실험 대상과 함께 죽으면 안 된다",
"title": "k3s를 호스트에 직접 설치하지 않고 두 VM으로 구성한 이유",
"kind": "decision",
"slug": "two-guest-vms-instead-of-installing-k3s-on-the-host",
"readiness": "READY",
@@ -3215,7 +3215,7 @@
"evidenceFiles": []
},
{
"title": "게스트 주소는 libvirt DHCP 예약으로 고정한다 — 바꿀 수 없어서가 아니라 되돌리기가 가장 비싸서",
"title": "게스트 IP를 libvirt DHCP 예약으로 고정한 이유",
"kind": "decision",
"slug": "fix-guest-addresses-with-a-dhcp-reservation",
"readiness": "READY",
@@ -3247,7 +3247,7 @@
"evidenceFiles": []
},
{
"title": "lab host 에는 Docker 를 깔지 않는다 — 이미지 저장소가 갈리고, 그 위에 네트워크 변수가 하나 더 붙는다",
"title": "lab host에 Docker를 설치하지 않은 이유",
"kind": "decision",
"slug": "no-docker-on-the-lab-host",
"readiness": "READY",
@@ -3285,7 +3285,7 @@
"kinds": {
"case": [
{
"title": "빈 토큰이 조용히 흘러갔다 — 설치 출력은 성공이었고 agent 만 5초마다 다시 죽었다",
"title": "k3s agent 설치 후 두 번째 노드가 등록되지 않은 원인",
"kind": "case",
"slug": "an-empty-token-installed-the-agent-anyway",
"readiness": "READY",
@@ -3316,7 +3316,7 @@
]
},
{
"title": "SSH 실패부터 보지 않았다 — cloud-init 시드 경로를 먼저 확인한 이유",
"title": "SSH 연결 실패를 확인할 때 cloud-init 시드부터 본 이유",
"kind": "case",
"slug": "cloud-init-failures-all-look-like-ssh-refused",
"readiness": "READY",
@@ -3345,7 +3345,7 @@
]
},
{
"title": "갱신은 매번 SUCCESS 였고 옛 인증서가 계속 나갔다 — 2305초와 1~2초",
"title": "인증서 갱신 후 nginx가 기존 인증서를 계속 제공한 문제",
"kind": "case",
"slug": "renewal-succeeded-while-the-old-certificate-kept-serving",
"readiness": "READY",
@@ -3375,7 +3375,7 @@
"concept": [],
"reference": [
{
"title": "가까운 층부터 한 층씩 건너뛰며 확인한다 — 층마다 성공 신호가 다르다",
"title": "장애를 확인할 때는 가까운 계층부터 확인한다",
"kind": "reference",
"slug": "check-the-nearest-layer-first",
"readiness": "READY",
@@ -3403,7 +3403,7 @@
"evidenceFiles": []
},
{
"title": "도구가 낸 출력은 대상의 상태가 아니다 — 그 명령이 무엇을 세는지부터 가른다",
"title": "명령 출력이 실제 상태를 의미하는지 먼저 확인한다",
"kind": "reference",
"slug": "tool-output-is-not-the-subject-state",
"readiness": "READY",
@@ -3480,7 +3480,7 @@
"case": [],
"concept": [
{
"title": "L7 이 두 겹인 이유와, 진입점 하나를 이중화하려 할 때 끝나지 않는 재귀",
"title": "이 실험대에서 L7 프록시를 두 단계로 둔 이유",
"kind": "concept",
"slug": "two-l7-hops-and-the-entry-point-recursion",
"readiness": "READY",
@@ -3548,7 +3548,7 @@
"question": [],
"decision": [
{
"title": "공개 터널을 쓰지 않고 tailnet 직결로 둔다 — 홉이 하나 늘면 재려던 계약이 오염된다",
"title": "공개 터널 대신 tailnet 직결을 선택한 이유",
"kind": "decision",
"slug": "no-public-tunnel-because-a-third-hop-pollutes-the-measurement",
"readiness": "READY",