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
@@ -1,7 +1,7 @@
---
kind: CASE
slug: an-empty-token-installed-the-agent-anyway
title: 빈 토큰이 조용히 흘러갔다 — 설치 출력은 성공이었고 agent 만 5초마다 다시 죽었다
title: k3s agent 설치 후 두 번째 노드가 등록되지 않은 원인
topic: build-completion-judgment
topicName: 끝났다는 판정
project: virtualization
@@ -17,44 +17,46 @@ source:
- final/document.md#184-이-부의-출처와-범위
---
# 빈 토큰이 조용히 흘러갔다 — 설치 출력은 성공이었고 agent 만 5초마다 다시 죽었다
# k3s agent 설치 후 두 번째 노드가 등록되지 않은 원인
이 Case는 **과거 셸 변수 방식에서 생긴 실패**를 기록한다. k3s agent 설치 출력은 끝까지 진행됐지만 `kubectl get nodes`에는 노드가 하나뿐이었고, 뒤에서 `--token is required`가 드러났다. 현재 Setup은 이 경로를 그대로 쓰지 않는다. node-token을 파일로 내려받아 크기가 0이 아닌지 확인하고 `--token-file`로 넘기므로, 이 글은 왜 그 절차로 바뀌었는지를 설명하는 실패 기록으로 읽는다.
`kc-lab-2`에 k3s agent를 설치했을 때 설치 스크립트는 오류 없이 끝났지만, `kubectl get nodes`에는 `kc-lab-1`만 보였다. `k3s-agent` 로그를 확인하니 `--token is required`가 반복되고 있었고, agent에 전달한 토큰 변수가 비어 있던 것이 원인이었다. 현재 Setup에서는 토큰을 파일로 전달해 같은 문제가 생기지 않도록 절차를 바꿨다.
## 설치는 끝났는데 두 번째 노드가 없었다
## 설치 스크립트는 끝났지만 노드가 등록되지 않았다
k3s agent 설치가 끝까지 돌았고 출력에 오류가 없었다. 그런데 두 노드가 Ready 로 나와야 할 kubectl get nodes 에 두 번째 노드가 나타나지 않았다.
agent 설치 스크립트는 오류 없이 종료됐다. 하지만 두 노드가 `Ready` 상태로 보여야 하는 `kubectl get nodes`에는 `kc-lab-1`만 나왔다.
설치 출력의 오류 : x
kubectl get nodes 의 노드 수 : 1
k3s-agent 유닛 : 5초마다 재시작
journalctl -u k3s-agent : level=fatal msg="Error: --token is required"
| 확인 항목 | 결과 |
|---|---|
| agent 설치 스크립트 | 오류 없이 종료 |
| `kubectl get nodes` | `kc-lab-1`만 표시 |
| `k3s-agent` 서비스 | 5초 간격으로 재시작 |
| `journalctl -u k3s-agent` | `level=fatal msg="Error: --token is required"` |
실패가 화면에 나오지 않아 설치는 끝난 것으로 읽힌다.
설치 스크립트가 끝났다는 사실만으로는 agent가 정상적으로 클러스터에 등록됐다고 판단할 수 없었다.
## 빈 토큰이 설치 단계까지 조용히 흘렀다
## 토큰 변수에 빈 문자열이 들어간 원인
토큰을 꺼내는 ssh 를 게스트 안에서 쳤고 그 명령이 Host key verification failed. 로 끝났다. 명령 치환으로 감싸면 오류는 stderr 로 흘러가고 변수에는 빈 문자열이 담긴다. 셸은 아무 불평도 하지 않는다.
토큰을 읽는 `ssh` 명령을 lab host가 아니라 게스트 안에서 실행했고, 해당 명령은 `Host key verification failed.`로 실패했다. 이 명령을 `TOKEN=$(...)` 형태로 실행하면 표준 출력만 변수에 들어가기 때문에 `TOKEN`에는 빈 문자열이 남는다.
agent 는 --token '' 을 받아 level=fatal msg="Error: --token is required" 로 죽지만, 설치 스크립트는 그 전까지를 다 성공으로 찍고 끝난다. 그래서 설치 출력만 보면 성공이고, 유닛이 Restart=always 라 5초마다 조용히 재시도한다.
그 상태로 agent 설치 명령을 실행하면 `--token ''`이 전달된다. 설치 스크립트는 서비스 파일 생성과 enable 단계까지 끝내지만, 실제 `k3s-agent` 프로세스는 `level=fatal msg="Error: --token is required"`를 남기고 종료됐다. `Restart=always` 설정 때문에 서비스는 5초 간격으로 다시 시작됐다.
당시 바로잡은 방향 : 게스트 안에서 다시 `ssh kc-lab-1`을 부르지 않고 lab host에서 server token을 읽는다
당시 가드 : 비밀 값을 화면에 찍지 않고 비어 있지 않은지만 확인한다. 108자는 그 실행의 관측값이지 고정 규격이 아니다
현재 Setup : token을 파일로 받아 `wc -c`로 비어 있지 않은지 확인한 뒤 `--token-file`로 넘긴다. 셸 변수와 같은 셸 제약을 없앴다
당시에는 게스트 안에서 다시 `ssh kc-lab-1`을 실행하지 않고 lab host에서 server token을 읽도록 수정했다. 토큰 값 자체는 출력하지 않고 비어 있는지만 확인했으며, 108자는 당시 실행에서 관측한 길이일 뿐 고정 규격으로 사용하지 않았다. 현재 Setup에서는 토큰을 파일로 받아 `wc -c`로 크기를 확인한 뒤 `--token-file`로 전달한다.
## 당시 k3s 실험 환경
호스트 : test-server, Arch Linux
CPU : i5-1135G7, 논리 코어 8
RAM : 11,648MiB
QEMU : 11.1.1
libvirt : 12.7.0
게스트 : Debian 12 genericcloud
k3s : v1.36.4+k3s1
server 노드 : kc-lab-1, 192.168.122.11
agent 노드 : kc-lab-2, 192.168.122.12
토큰 길이 : 108자
토큰 형식 : K10<해시>::server:<비밀번호>
| 항목 | 값 |
|---|---|
| 호스트 | test-server, Arch Linux |
| CPU | i5-1135G7, 논리 코어 8 |
| RAM | 11,648MiB |
| QEMU | 11.1.1 |
| libvirt | 12.7.0 |
| 게스트 | Debian 12 genericcloud |
| k3s | v1.36.4+k3s1 |
| server 노드 | kc-lab-1, 192.168.122.11 |
| agent 노드 | kc-lab-2, 192.168.122.12 |
| 당시 토큰 길이 | 108자 |
| 토큰 형식 | K10<해시>::server:<비밀번호> |
## 같은 실패를 다시 만들려면
@@ -73,7 +75,7 @@ agent 노드 : kc-lab-2, 192.168.122.12
k3s server 는 `kc-lab-1` 에, agent 는 `kc-lab-2` 에 깔고 둘 다 lab host 에서 `ssh` 로 원격 실행한다. 가이드가 코드 블록마다 어느 기계에서 치는지를 붙여 둔 까닭이 여기에 있다 — 게스트는 libvirt NAT(`192.168.122.0/24`) 안에 있어 워크스테이션에서 직접 닿지 않고, `ssh kc-lab-1` 이라는 별칭도 lab host 의 `~/.ssh/config` 에만 있다.
당시 절차는 agent가 사용할 node-token을 lab host의 셸 변수에 담아 설치 명령으로 넘겼다. 바로 이 변수 전달이 실패 지점이 됐다. 현재 Setup은 token file을 사용하므로 아래 블록은 **historical failure path**다.
당시에는 agent가 사용할 node-token을 lab host의 셸 변수에 담아 설치 명령으로 넘겼다. 문제가 생긴 지점도 이 변수 전달 과정이었다. 현재 설치 절차는 토큰 파일을 사용하므로 아래 명령은 당시 문제를 설명하기 위한 예시다.
```bash
TOKEN=$(ssh kc-lab-1 'sudo cat /var/lib/rancher/k3s/server/node-token')
@@ -89,7 +91,7 @@ ssh kc-lab-2 "curl -sfL https://get.k3s.io | sudo sh -s - agent \
--node-ip 192.168.122.12"
```
## 게스트 안에서 친 ssh 는 빈 문자열이 된다
## 게스트에서 실행한 ssh 명령은 토큰을 가져오지 못했다
토큰을 꺼내려고 게스트에 먼저 들어가면 같은 명령이 다르게 끝난다. 게스트에는 lab host 의 개인키도 `~/.ssh/config` 도 없다.
@@ -98,11 +100,11 @@ ssh kc-lab-2 "curl -sfL https://get.k3s.io | sudo sh -s - agent \
Host key verification failed.
```
여기까지는 오류 문구가 찍힌다. 문제는 이 명령을 `TOKEN=$(...)` 로 감쌌을 때다. 명령 치환은 표준 출력만 변수에 담으므로 오류는 stderr 로 흘러가고 `TOKEN` 에는 빈 문자열이 담기며, 셸은 아무 불평도 하지 않는다. 뒤이어 치는 설치 명령은 `--token ''` 을 넘긴 것과 같아진다.
오류 메시지는 표준 오류로 출력된다. 그런데 같은 명령을 `TOKEN=$(...)`로 감싸면 표준 출력만 변수에 들어가므로 `TOKEN`에는 빈 문자열이 남는다. 뒤이어 실행한 설치 명령은 결국 `--token ''`을 전달한 것과 같았다.
## 설치 출력이 성공으로 끝나는 경로
## 설치 스크립트 종료와 agent 기동 성공은 다른 상태였다
빈 문자열을 받은 설치도 끝까지 돈다. agent 가 `--token ''` 을 받아 `level=fatal msg="Error: --token is required"` 로 죽는데, 설치 스크립트는 그 전까지를 다 성공으로 찍고 끝나므로 설치 출력만 보면 성공이다. 성공으로 찍힌 것은 내려받기와 유닛 생성과 `enable` 까지다. 유닛은 `Restart=always` 라 5초마다 조용히 재시도하고, 그래서 실패가 화면이 아니라 `journalctl -u k3s-agent` 안에서만 되풀이된다.
빈 토큰을 넘겨도 설치 스크립트는 바이너리 다운로드와 서비스 파일 생성, `enable` 단계까지 진행한다. 이 때문에 스크립트가 종료된 화면만 보면 설치가 끝난 것처럼 보인다. 하지만 실제 agent 프로세스는 `--token is required` 오류로 종료됐고, `Restart=always` 설정 때문에 5초 간격으로 재시작했다. 실제 실패 원인은 `journalctl -u k3s-agent`에서 확인할 수 있었다.
k3s server 와 agent 를 세우는 단계가 끝났다는 판정은 lab host 에서 노드 목록을 쳐서 두 노드가 `Ready` 로 나오는 것이다.
@@ -116,19 +118,19 @@ kc-lab-1 Ready control-plane 47m v1.36.4+k3s1 192.168.122.11
kc-lab-2 Ready <none> 21m v1.36.4+k3s1 192.168.122.12
```
빈 토큰으로 깔린 agent 는 이 목록에 올라오지 않는다.
토큰이 비어 있으면 agent는 정상적으로 기동하지 못하므로 이 목록에 두 번째 노드가 나타나지 않는다.
## 값을 보여 주지 않고 빈 토큰만 걸러낸다
## 토큰 값은 출력하지 않고 비어 있는지만 확인한다
이 사건에서 필요한 확인은 토큰 내용을 눈으로 대조하는 일이 아니었다. 설치를 시작하기 전에 값이 비어 있는지만 알면 됐다. 당시 기록에는 토큰 길이가 108자로 남아 있지만, 그 숫자는 한 번의 실행에서 나온 값이지 성공 조건이 아니다.
과거 절차에서는 셸 변수의 길이를 확인했다. 현재 Setup은 이 실패를 피하려고 token file로 바뀌었고, `wc -c`로 파일이 비어 있지 않은지 확인한 뒤 `--token-file`로 넘긴다. 따라서 이 Case에는 원문 근거에 없던 셸 가드 명령을 새로 보태지 않는다.
과거 절차에서는 셸 변수의 길이를 확인했다. 현재 설치 절차에서는 토큰을 파일로 받은 뒤 `wc -c`로 파일이 비어 있지 않은지 확인하고 `--token-file`로 넘긴다. 당시 기록에 없는 별도 셸 가드 명령은 추가하지 않았다.
길이가 `0` 으로 나올 수 있는 길은 하나로 한정되지 않는다. 게스트 안에서 다시 `ssh kc-lab-1`을 불러 실패할 수도 있고, server가 아직 token 파일을 만들지 못했을 수도 있고, 새 셸을 열면서 변수 자체가 사라졌을 수도 있다. 중요한 건 원인을 추측하기 전에 설치 직전의 입력이 비어 있는지부터 확인하는 것이다.
## 현재 Setup은 처음부터 token file을 쓴다
## 현재 설치 절차는 토큰 파일을 사용한다
셸 변수 방식은 새 창으로 넘어가면 값이 없고, command line에 token이 들어갈 위험도 있다. 그래서 현재 Setup은 이 Case의 우회책을 정식 절차로 올려 **처음부터 파일로 넘긴다.** 아래 파이프 형태는 사건 이후 사용한 historical/reference 방식이고, 현재 Setup은 `scp`·`chmod`·`wc -c`를 나눠 실패 지점을 더 분명하게 만든다.
셸 변수는 새 셸로 넘어가면 값이 사라질 수 있고, 토큰을 명령행 인자로 직접 넘기면 프로세스 인자에 값이 노출될 수 있다. 그래서 현재 설치 절차는 토큰을 파일로 전달한다. 아래 파이프 방식은 문제를 확인한 뒤 사용했던 방식이고, 현재 문서에서는 `scp`, `chmod`, `wc -c`를 각각 나눠 어느 단계에서 실패했는지 확인할 수 있게 했다.
```bash
ssh kc-lab-1 'sudo cat /var/lib/rancher/k3s/server/node-token' \
@@ -138,11 +140,11 @@ ssh kc-lab-2 "curl -sfL https://get.k3s.io | sudo sh -s - agent \
--node-ip 192.168.122.12; rm -f /tmp/token"
```
이 방식은 token 값을 command line 인자로 직접 넣지 않고 셸 변수에도 의존하지 않는다. 현재 canonical Setup은 여기에 파일 존재·길이 확인과 영구 경로 이동을 더해 재부팅 뒤에도 agent가 같은 token file을 읽도록 구성한다.
이 방식은 토큰 값을 명령행 인자로 직접 넣지 않고 셸 변수에도 의존하지 않는다. 현재 설치 절차는 여기에 파일 존재 여부와 길이 확인, 영구 경로 이동을 추가해 재부팅 뒤에도 agent가 같은 토큰 파일을 읽도록 구성한다.
## 아직 원문 증거가 부족한 부분
## 확인하지 못한 범위
원래 빈 토큰 사건의 `level=fatal msg="Error: --token is required"` 와 당시 설치 출력은 여전히 직접 raw가 없다. 다만 2026-09-17 후속 원문은 현재 정상 경로를 보강한다. `15-k3s-precheck.txt` 에는 별도 precheck에서 `Host key verification failed.`가 남아 있고, `21-k3s-token.txt` 는 재구축 시점의 **비어 있지 않은 토큰**을 길이로 확인했으며, `22-k3s-agent-install.txt` 는 그 토큰으로 agent 설치가 성공한 출력을 담는다. 이 셋은 원래 빈 토큰 실패의 재현이 아니라 **후속 정상 경로를 뒷받침하는 자료**다. 과거 사건의 토큰 108자와 후속 실행의 길이가 다르더라도 같은 측정으로 덮어쓰지 않는다.
당시 `level=fatal msg="Error: --token is required"` 로그와 설치 출력 원문은 남아 있지 않다. 2026-09-17에 다시 구성하면서 확보한 자료에는 `Host key verification failed.`가 발생한 사전 점검, 비어 있지 않은 토큰 길이 확인, 정상적인 agent 설치 출력이 남아 있다. 이 자료는 현재 정상 절차를 확인한 것이지 과거의 빈 토큰 실패를 다시 재현한 것은 아니다. 당시 토큰 길이 108자 역시 후속 실행의 값으로 덮어쓰지 않는다.
이 실패를 일부러 다시 만들어 본 기록은 없다. 빈 토큰 사건은 한 번의 과거 관측이고, 현재 정상 절차는 token file 방식으로 바뀌었다. 같은 문제가 다시 발생하면 설치 출력만 보지 말고 `journalctl -u k3s-agent`의 원문과 `kubectl get nodes` 결과를 함께 보존해 실패 지점을 확인한다.
@@ -1,7 +1,7 @@
---
kind: CASE
slug: cloud-init-failures-all-look-like-ssh-refused
title: SSH 실패부터 보지 않았다 — cloud-init 시드 경로를 먼저 확인한 이유
title: SSH 연결 실패를 확인할 때 cloud-init 시드부터 본 이유
topic: build-completion-judgment
topicName: 끝났다는 판정
project: virtualization
@@ -15,49 +15,53 @@ source:
- final/document.md#186-단계-00-lab-host-가상화-준비
---
# SSH 실패부터 보지 않았다 — cloud-init 시드 경로를 먼저 확인한 이유
# SSH 연결 실패를 확인할 때 cloud-init 시드부터 본 이유
게스트가 `running`인데 SSH가 안 붙으면 곧바로 SSH 키부터 고치지 않았다. 먼저 cloud-init이 시드를 읽었는지 확인했다. 이 실험대에서 실제로 확인한 것은 `--cloud-init`으로 붙인 시드 경로가 기대대로 보이지 않았던 사례와 cloud-init 22.4.2의 schema 거부다. YAML 파싱 실패, `vol-upload` 누락, libvirt network autostart 문제는 같은 단계에서 점검해야 할 **가능한 실패 경로**로 남기되, 모두 이 환경에서 같은 증상으로 재현했다고 쓰지 않는다.
게스트 세 대는 `running` 상태였지만 SSH 공개키 인증이 되지 않았고, 한 게스트의 호스트명은 `localhost`로 남아 있었다. SSH 설정만 수정하기 전에 cloud-init이 시드를 읽었는지부터 확인했다. 이 환경에서 실제로 확인한 문제는 기존 `--cloud-init` 연결에서 기대한 NoCloud 시드가 보이지 않았던 점과 cloud-init 22.4.2의 스키마 검사 결과였다. YAML 파싱 실패, `vol-upload` 누락, libvirt 네트워크 자동 시작 문제는 같은 증상을 만들 수 있는 점검 항목이지만 이 환경에서 각각 재현한 것은 아니다.
## VM은 떴는데 SSH만 붙지 않았다
## 게스트는 실행 중이었지만 SSH 공개키 인증이 되지 않았다
게스트 세 대가 running 인데 lab host 에서 SSH 가 키로 붙지 않는다.
가상 머신 자체는 모두 실행 중이었다. 문제는 운영체제가 기대한 초기 설정을 적용했는지였다.
virsh list --all : kc-lab-1 · kc-lab-2 · kc-lab-edge 모두 running
ssh donghyeon@192.168.122.11 : Permission denied (publickey)
게스트의 hostname : localhost
cloud-init 이 남긴 오류 : x
| 확인 항목 | 당시 상태 |
|---|---|
| `virsh list --all` | `kc-lab-1`, `kc-lab-2`, `kc-lab-edge` 모두 `running` |
| `ssh donghyeon@192.168.122.11` | `Permission denied (publickey)` |
| 게스트 호스트명 | `localhost` |
| cloud-init 오류 원문 | 별도로 보존하지 않음 |
cloud-init이 user-data를 적용하지 못하면 기대한 사용자와 SSH key도 들어가지 않을 수 있다. 다만 원인마다 남는 로그와 상태는 다를 수 있으므로 “cloud-init이 오류를 남기지 않는다”로 일반화하지 않는다. 이 사건에서는 SSH 실패와 `localhost` hostname이 먼저 눈에 띄었고, 그래서 시드/data source 경로를 SSH 설정보다 먼저 확인했다.
cloud-init이 `user-data`를 적용하지 못하면 사용자 계정과 SSH 공개키도 기대한 상태로 만들어지지 않을 수 있다. 이때 SSH 키만 바꾸면 원인을 놓칠 수 있으므로, 먼저 시드가 게스트에 전달됐는지 확인했다.
## SSH보다 먼저 cloud-init이 시드를 읽었는지 본다
## 먼저 cloud-init이 시드를 읽었는지 확인했다
SSH 실패가 보이면 아래 경로를 차례로 가른다.
SSH 연결 실패와 cloud-init 문제를 구분하기 위해 다음 항목을 순서대로 확인했다.
시드 연결 방식 : 이 환경에서는 `--cloud-init` 경로로 만든 시드가 guest에서 기대대로 읽히지 않았고, seed ISO를 `bus=virtio` disk로 붙인 구성에서는 `/dev/vdb`의 NoCloud data source로 확인됐다
YAML/cloud-config : syntax와 schema를 별도로 확인한다. parser/schema 실패는 guest 로그와 `cloud-init status --long`을 함께 본다
`vol-upload` 누락 : libvirt volume 이름만 존재하고 실제 seed 내용이 올라갔는지 용량과 업로드 절차를 확인한다
`default` network autostart : host 재부팅 뒤 network 자체가 안 올라온 경우에는 cloud-init과 별개로 guest 접근 경로가 사라질 수 있으므로 `virsh net-info default`를 본다
| 확인 항목 | 확인하는 내용 |
|---|---|
| 시드 연결 방식 | 이 환경에서는 virtio 디스크로 붙인 seed ISO가 `/dev/vdb`의 NoCloud 데이터소스로 인식됐다 |
| YAML과 cloud-config | YAML 문법과 cloud-init 스키마 검사는 별도로 확인한다 |
| `vol-upload` | libvirt 볼륨만 만든 것이 아니라 실제 seed ISO 내용까지 업로드됐는지 확인한다 |
| `default` 네트워크 | 호스트 재부팅 뒤 libvirt 네트워크가 올라왔는지 `virsh net-info default`로 확인한다 |
판정 : SSH 설정을 고치기 전에 호스트명 한 낱말을 본다. ssh kc-lab-edge 'hostname' 이 kc-lab-edge 를 내면 시드가 읽혔고, 시드가 읽혔으면 같은 파일에 있던 SSH 키도 들어갔다
못 들어가면 : virsh screenshot 으로 화면을 떠서 로그인 프롬프트 앞의 호스트명을 읽는다
키가 안 들어갔을 때의 탈출구 : cloud-init 의 plain_text_passwd 로 콘솔 로그인
SSH가 가능하면 `hostname`과 `cloud-init status`를 먼저 확인한다. 접속 자체가 되지 않으면 `virsh screenshot`으로 콘솔의 호스트명을 확인할 수 있다. 공개키가 적용되지 않았을 때 콘솔 로그인이 필요하도록 `plain_text_passwd`도 당시 cloud-init 설정에 포함했다.
반대 방향도 하나 있다. 게스트의 cloud-init 22.4.2 스키마 검사기는 sudo 를 리스트로 쓴 것을 거부한다. 그런데 그 표기로도 부팅은 되고, kc-lab-1 과 kc-lab-2 에서 그 상태로 NOPASSWD sudo 가 돌고 있다. 검사가 통과해도 안 도는 쪽이 넷이고 검사에 걸려도 도는 쪽이 하나라, 어느 방향이든 검사 결과를 게스트의 상태로 읽으면 틀린다.
다만 스키마 검사 결과만으로 게스트의 최종 상태를 판단하지는 않는다. cloud-init 22.4.2는 `sudo`를 리스트로 쓴 표현을 거부했지만, 기존 `kc-lab-1`과 `kc-lab-2`에서는 같은 표현으로 `NOPASSWD` sudo가 실제 동작하고 있었다. 스키마 검사는 사전 점검이고, 최종 상태는 부팅한 게스트에서 다시 확인해야 했다.
## 당시 cloud-init 실험 환경
호스트 : test-server, Arch Linux
RAM : 11,648MiB
QEMU : 11.1.1
libvirt : 12.7.0
base 이미지 : Debian 12 genericcloud amd64
게스트 OS : Debian GNU/Linux 12 (bookworm)
게스트 : kc-lab-edge 192.168.122.10 · kc-lab-1 192.168.122.11 · kc-lab-2 192.168.122.12
시드 : seed-<이름>.iso, CIDATA 라벨, bus=virtio 로 붙임
게스트의 cloud-init : 22.4.2
cloud-init 이 깐 패키지 : curl · nftables
running 에서 done 까지 : 약 50초
| 항목 | 값 |
|---|---|
| 호스트 | test-server, Arch Linux |
| RAM | 11,648MiB |
| QEMU | 11.1.1 |
| libvirt | 12.7.0 |
| base 이미지 | Debian 12 genericcloud amd64 |
| 게스트 OS | Debian GNU/Linux 12 (bookworm) |
| 게스트 | kc-lab-edge 192.168.122.10 · kc-lab-1 192.168.122.11 · kc-lab-2 192.168.122.12 |
| 시드 | `seed-<이름>.iso`, CIDATA 라벨, `bus=virtio` |
| cloud-init | 22.4.2 |
| cloud-init으로 설치한 패키지 | curl · nftables |
| `running`에서 `done`까지 | 약 50초 |
## 같은 증상을 확인하는 순서
@@ -96,10 +100,10 @@ virsh vol-upload --pool default seed-kc-lab-1.iso seed-kc-lab-1.iso
|---|---|
| `--cloud-init`으로 붙인 시드가 guest에서 기대대로 읽히지 않음 | 이 환경에서 실제 관측. 수동 virtio seed 구성으로 바꾼 뒤 NoCloud `seed=/dev/vdb` 확인 |
| YAML/cloud-config 파싱 또는 schema 문제 | schema 거부는 실제 관측. 임의의 YAML parsing failure를 같은 증상으로 재현한 기록은 없음 |
| `vol-upload` 누락 | 절차상 가능한 실패 경로. 실제 누락 부팅 재현 원문은 없음 |
| `default` network autostart 비활성 | host reboot 뒤 접근 경로에 영향을 줄 수 있는 사전 조건. 이 실패를 실제 재현한 원문은 없음 |
| `vol-upload` 누락 | 절차상 가능한 실패 경로. 실제 누락 부팅을 재현한 기록은 없음 |
| `default` network autostart 비활성 | host reboot 뒤 접근 경로에 영향을 줄 수 있는 사전 조건. 이 실패를 실제로 재현한 기록은 없음 |
시드 연결 방식은 이 실험대에서 실제로 문제를 겪은 부분이다. 당시 `--cloud-init`이 만든 연결에서는 guest가 기대한 NoCloud seed를 읽지 못했고, 최종 구성에서는 seed ISO를 `device=disk,bus=virtio,readonly=on`으로 붙였다. 2026-09-17의 정상 guest `cloud-init status --long`에는 `DataSourceNoCloud [seed=/dev/vdb][dsmode=net]`가 남아 있다. **원인을 ‘Debian genericcloud에는 AHCI 드라이버가 없다’로 일반화하지 않는다.** 현재 증거가 확정하는 것은 이 환경에서 virtio `vdb` seed 경로가 실제로 동작했다는 것까지다.
시드 연결 방식은 이 실험대에서 실제로 문제를 겪은 부분이다. 당시 `--cloud-init`이 만든 연결에서는 guest가 기대한 NoCloud seed를 읽지 못했고, 최종 구성에서는 seed ISO를 `device=disk,bus=virtio,readonly=on`으로 붙였다. 2026-09-17의 정상 guest `cloud-init status --long`에는 `DataSourceNoCloud [seed=/dev/vdb][dsmode=net]`가 남아 있다. 현재 남아 있는 증거만으로 `--cloud-init` 경로가 기대대로 동작하지 않은 원인을 특정할 수는 없다. 확인된 것은 virtio `vdb`로 연결한 seed 경로가 이 환경에서 실제로 동작했다는 것까지다.
```bash
virt-install --name kc-lab-1 --memory 5120 --vcpus 2 \
@@ -109,9 +113,9 @@ virt-install --name kc-lab-1 --memory 5120 --vcpus 2 \
--import --os-variant debian12 --noautoconsole
```
`default` network의 autostart도 guest 내부 문제와 분리해 본다. host 재부팅 뒤 libvirt network가 올라오지 않으면 SSH 접근이 함께 끊길 수 있으므로 `virsh net-info default`의 `Active`와 `Autostart`를 먼저 확인한다. 이 문서는 그 실패를 이 환경에서 실제 재현했다고 주장하지 않고, 재부팅 뒤 접근 경로를 가르는 사전 확인으로 둔다.
`default` network의 autostart도 guest 내부 문제와 분리해 확인한다. host 재부팅 뒤 libvirt network가 올라오지 않으면 SSH 접근 경로도 사라질 수 있으므로 `virsh net-info default`의 `Active`와 `Autostart`를 확인한다. network autostart 비활성 자체는 이 환경에서 재현하지 않았으며, 재부팅 뒤 접근 경로를 확인하기 위한 점검 항목으로만 남긴다.
## 호스트명 한 낱말이 시드와 SSH 를 가른다
## 호스트명과 cloud-init 상태로 시드 적용 여부를 확인했다
게스트에 SSH 가 붙는다면 확인은 한 줄로 끝난다.
@@ -125,7 +129,7 @@ enp1s0 UP 192.168.122.10/24 metric 100
status: done
```
호스트명이 바뀌었다는 것은 시드가 읽혔다는 뜻이고, 시드가 읽혔으면 같은 파일에 있던 SSH 키도 들어갔다. `localhost` 가 나오면 SSH 설정을 고치지 말고 시드부터 의심한다. `cloud-init status` 가 `running` 이면 아직 패키지를 받는 중이고, 이 실험대에서는 `done` 까지 약 50초 걸렸다.
호스트명이 `kc-lab-edge`로 바뀌고 `cloud-init status`가 `done`이면 해당 시드가 적용된 상태로 볼 수 있었다. 반대로 `localhost`가 남아 있으면 SSH 설정을 수정하기 전에 시드 연결과 cloud-init 상태부터 다시 확인했다. 이 실험대에서는 `running`에서 `done`까지 약 50초가 걸렸다.
게스트에 못 들어가면 화면을 직접 뜬다.
@@ -133,9 +137,9 @@ status: done
virsh screenshot kc-lab-1 /tmp/kc1.ppm # 확장자와 무관하게 PNG 로 저장된다
```
로그인 프롬프트 앞의 호스트명 한 낱말만 읽는다. `localhost login:` 이면 cloud-init 이 아예 안 돌았으므로 SSH 쪽은 볼 것이 없다. `kc-lab-1 login:` 이면 cloud-init 은 돌았고 그 안의 사용자·키 단계에서 틀린 것이라 콘솔로 들어가 로그를 본다. 콘솔 로그인에 쓰는 비밀번호가 cloud-init 의 `plain_text_passwd` 이고, 키가 안 들어갔을 때 게스트로 들어가는 길이 이것 하나다.
로그인 프롬프트의 호스트명이 `localhost`라면 시드 적용 여부부터 다시 확인한다. `kc-lab-1`처럼 기대한 호스트명이 보인다면 cloud-init은 일부 단계를 수행한 것이므로 콘솔에 로그인해 사용자와 SSH 키 적용 로그를 확인한다. 당시 설정의 `plain_text_passwd`는 공개키 인증이 되지 않을 때 콘솔로 들어가기 위한 수단이었다.
순서를 이렇게 정한 까닭이 여기에 있다. 화면 한 장과 콘솔에서 보는 로그 두 줄이 「SSH 가 안 되는 이유」를 절반으로 줄인다. 호스트명이 그 절반을 가르므로, 어느 쪽 절반을 볼지가 정해지기 전에는 SSH 설정을 열 이유가 없다.
이 순서를 사용하면 SSH 설정 자체의 문제인지, 그보다 앞선 cloud-init 초기화 문제인지 먼저 구분할 수 있다.
## 검사가 거부해도 부팅은 된다
@@ -167,21 +171,21 @@ python3 -c 'import yaml,sys; yaml.safe_load(open("kc-lab-1.yaml")); print("YAML
`0` 과 `2` 와 `YAML OK` 셋이 맞아야 시드를 만든다. 셋이 맞아도 cloud-config 로 유효하지는 않다 — 키 이름을 `users` 대신 `user` 로 친 오타는 이 세 줄을 그냥 통과한다. 그래서 게스트가 한 대라도 떠 있으면 cloud-init 자신의 스키마 검사기를 쓴다.
```bash label="[lab host] [reference] historical command"
```bash label="[lab host] 당시 사용한 명령"
ssh donghyeon@192.168.122.11 'umask 077; cat > ~/kc-lab-2.yaml' < kc-lab-2.yaml
ssh donghyeon@192.168.122.11 'cloud-init schema -c ~/kc-lab-2.yaml; rm -f ~/kc-lab-2.yaml'
```
이 두 줄은 **당시 문서에 남은 historical command**다. 둘째 줄은 스키마 검사가 실패해도 `; rm` 때문에 파일을 지운다. 따라 하는 절차에서는 검사와 삭제를 분리하고, 검사 성공 여부를 본 뒤 삭제한다.
이 두 줄은 당시 문서에 남아 있던 명령이다. 둘째 줄은 스키마 검사가 실패해도 `; rm` 뒤의 삭제가 실행될 수 있으므로, 현재 절차에서는 검사와 삭제를 분리하고 검사 결과를 확인한 뒤 파일을 지운다.
이 파일에는 콘솔 비밀번호가 평문으로 들어 있어 `/tmp` 가 아니라 자기 홈에 `600` 으로 두고, 검사가 끝나면 바로 지운다.
## 실제로 재현한 실패와 아직 가정인 실패
네 경로 가운데 실제 관측으로 직접 닫힌 것은 두 부분이다. 첫째, 기존 `--cloud-init` 연결에서는 기대한 seed 동작을 얻지 못했고 최종 virtio seed에서는 `DataSourceNoCloud [seed=/dev/vdb]`가 확인됐다. 둘째, cloud-init 22.4.2 schema 검사기는 `sudo` 리스트 표기를 실제로 거부했다. 임의의 YAML parsing failure, `vol-upload` 누락, network autostart 비활성은 이 실험대에서 같은 SSH 증상으로 재현한 원문이 없으므로 **진단 후보**로만 남긴다.
네 경로 가운데 실제 관측으로 직접 닫힌 것은 두 부분이다. 첫째, 기존 `--cloud-init` 연결에서는 기대한 seed 동작을 얻지 못했고 최종 virtio seed에서는 `DataSourceNoCloud [seed=/dev/vdb]`가 확인됐다. 둘째, cloud-init 22.4.2 schema 검사기는 `sudo` 리스트 표기를 실제로 거부했다. 임의의 YAML parsing failure, `vol-upload` 누락, network autostart 비활성은 이 실험대에서 같은 SSH 증상으로 재현한 기록이 없으므로 진단 후보로만 남긴다.
후속 원문도 남겼다. `14-cloudinit-schema-check.txt`에는 cloud-init 22.4.2가 `sudo` 리스트 표기를 실제로 거부한 출력이 있다. `15-k3s-precheck.txt`의 `Host key verification failed.`는 2026-09-17 재구축 중 나온 별도 SSH 실패라 원래 사건의 `Permission denied (publickey)`를 재현한 것은 아니다. 원래 `Permission denied (publickey)`, `cloud-init status: done`, 약 50초, `virsh screenshot` 화면은 아직 별도 raw 파일이 없고 당시 본문 기록만 남아 있다.
이 Case의 과거 실패 조합 전체를 그대로 다시 만드는 재현은 하지 않았다. 다만 2026-09-21에는 worker 두 대를 실제로 철거하고 현재 Setup의 qcow2·seed ISO·cloud-init 경로로 다시 만들어 `cloud-init status: done`과 SSH, 고정 IP, k3s 재합류까지 확인했다. 따라서 **현재 정상 생성 경로는 재검증됐고**, 과거 실패 후보 각각을 일부러 다시 유발한 것은 아니다.
과거에 의심했던 실패 조건을 하나씩 다시 만들어 보지는 않았다. 대신 2026-09-21에는 worker 두 대를 실제로 철거한 뒤 현재 문서의 qcow2, seed ISO, cloud-init 절차로 다시 생성했고 `cloud-init status: done`, SSH 접속, 고정 IP, k3s 재합류까지 확인했다. 현재 생성 절차가 동작한다는 것은 확인했지만, 과거의 각 실패 조건을 개별적으로 재현한 것은 아니다.
<!-- body:end -->
@@ -1,7 +1,7 @@
---
kind: CASE
slug: renewal-succeeded-while-the-old-certificate-kept-serving
title: 갱신은 매번 SUCCESS 였고 옛 인증서가 계속 나갔다 — 2305초와 1~2초
title: 인증서 갱신 후 nginx가 기존 인증서를 계속 제공한 문제
topic: build-completion-judgment
topicName: 끝났다는 판정
project: virtualization
@@ -13,50 +13,47 @@ source:
- final/document.md#194-이-부에서-파생될-open-question
---
# 갱신은 매번 SUCCESS 였고 옛 인증서가 계속 나갔다 — 2305초와 1~2초
# 인증서 갱신 후 nginx가 기존 인증서를 계속 제공한 문제
과거 물리 호스트 배치에서는 갱신이 SUCCESS로 끝나도 nginx가 옛 인증서를 계속 내보냈다. 당시 `certbot-renew.service`에 reload 훅이 없어 갱신에서 서빙까지 2305초 걸렸고, deploy 훅을 두니 1~2초였다. **현재 2026-09-21 edge Debian 12 배치는 `certbot.timer → certbot.service`를 쓴다.** 이 글의 2305초·1~2초는 과거 배치의 측정값으로 남긴다.
과거 물리 호스트에서 certbot 갱신은 정상 종료됐지만 nginx가 제공하는 인증서는 바뀌지 않았다. 당시 `certbot-renew.service`에는 nginx reload를 실행하는 훅이 없었고, 인증서 파일이 갱신된 뒤 실제 서비스에 반영되기까지 2305초가 걸렸다. deploy 훅을 추가한 뒤 같은 구간은 1~2초로 줄었다. 현재 Edge VM은 Debian 12의 `certbot.timer → certbot.service`를 사용하므로, 이 수치는 당시 물리 호스트 배치에서 측정한 값으로 구분한다.
## certbot은 성공했는데 서버 인증서는 그대로였다
## 인증서 파일은 갱신됐지만 nginx에는 바로 반영되지 않았다
인증서 갱신은 매번 성공으로 끝나는데 서버가 내보내는 인증서는 옛것이었다.
당시 상태를 나눠 보면 certbot과 nginx가 서로 다른 시점의 인증서를 보고 있었다.
certbot-renew.timer : 정상
certbot-renew.service 의 결과 : SUCCESS
유닛의 ExecStartPost 또는 --deploy-hook : x
nginx 가 새 인증서를 읽었나 : x
갱신에서 서빙까지 : 2305초 (38분 25초)
무엇이 reload 했나 : 사람이 직접
| 확인 항목 | 당시 결과 |
|---|---|
| `certbot-renew.timer` | 정상 동작 |
| `certbot-renew.service` | `SUCCESS` |
| `ExecStartPost` 또는 `--deploy-hook` | 없음 |
| nginx reload | 자동으로 실행되지 않음 |
| 갱신 후 서비스 반영까지 | 2305초(38분 25초) |
| 실제 reload | 사람이 직접 실행 |
발현하는 날의 증상은 인증서 만료이고, 그날에도 로그에는 SUCCESS 라고 적혀 있다.
certbot의 성공 여부만 확인하면 인증서 파일이 갱신됐다는 것까지만 알 수 있었다. nginx가 새 인증서를 읽었는지는 별도로 확인해야 했다.
## 갱신 성공과 nginx reload는 별도 단계였다
certbot-renew.service 는 /usr/bin/certbot -q renew 한 줄이고 인증서를 새로 받는 데까지만 책임진다. nginx 는 인증서를 기동 시점에 읽어 메모리에 들고 있고 certbot 은 live/ 심볼릭 링크만 갈아 끼우므로, 경로는 그대로이고 내용만 바뀌어 nginx 는 바뀐 줄 모른다.
당시 `certbot-renew.service`는 `/usr/bin/certbot -q renew`만 실행했다. certbot은 `live/` 아래의 심볼릭 링크를 새 인증서 파일로 갱신하지만, nginx는 기동하거나 reload할 때 인증서 파일을 읽는다. 따라서 certbot이 성공해도 nginx를 reload하지 않으면 nginx는 기존 인증서를 계속 제공한다.
훅도 사람도 없으면 다음 nginx 재시작까지, 사실상 무기한으로 옛 인증서가 나간다.
이를 해결하기 위해 `/etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh`에서 `nginx -t && nginx -s reload`를 실행하도록 했다. deploy 훅 파일에는 실행 권한이 필요하며, `post/` 대신 `deploy/`를 사용해 실제 갱신이 발생했을 때만 reload하도록 했다. 훅은 호스트를 다시 구성할 때 누락되지 않도록 저장소에서 관리했다.
해결 : /etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh 에 nginx -t && nginx -s reload 를 두고 chmod +x 를 준다
실행 권한이 없으면 : certbot 이 조용히 건너뛴다
post/ 가 아니라 deploy/ 인 까닭 : post/ 는 갱신이 없어도 매번 돌아 하루 두 번 워커를 갈아치운다
훅을 저장소에 두는 까닭 : 호스트에만 두었을 때는 호스트를 초기화하면 아무 오류 없이 사라졌다
판정 : 로그 문구가 아니라 강제 갱신 전후의 nginx 워커 PID 로 한다
적용 여부는 certbot 로그만 보지 않고 강제 갱신 전후의 nginx worker PID로 확인했다. reload 중 새 연결 8856건은 모두 200으로 응답했고 p95는 205.7ms와 204.3ms로 측정됐다.
훅을 넣어도 안전했다. reload 는 무중단이었고 새 연결 8856건이 전부 200, p95 는 205.7ms 대 204.3ms 로 변화가 없었다.
## 과거 측정 배치와 현재 Edge VM 배치
## 과거 측정 배치와 현재 edge 배치
엣지 게스트 : kc-lab-edge, 192.168.122.10, Debian 12
nginx : nginx/1.22.1
certbot 플러그인 : dns-cloudflare
발급 대상 : -d hyeonworks.com -d '*.hyeonworks.com'
lineage 디렉터리 : /etc/letsencrypt/live/auth.hyeonworks.com/ (2026-09-17 현재 관측)
nginx 가 읽는 파일 : fullchain.pem · privkey.pem
과거 측정 배치의 타이머 : `certbot-renew.timer → certbot-renew.service`
현재 edge Debian 12 : `certbot.timer → certbot.service`
인증서 유효기간 : 오늘 + 90일
2305초를 잴 때의 배치 : 훅이 물리 호스트에 있었다
지금의 배치 : certbot · 인증서 · 갱신 타이머 · deploy 훅이 전부 엣지 게스트에 있다
| 항목 | 값 |
|---|---|
| Edge VM | kc-lab-edge, 192.168.122.10, Debian 12 |
| nginx | nginx/1.22.1 |
| certbot 플러그인 | dns-cloudflare |
| 발급 대상 | `-d hyeonworks.com -d '*.hyeonworks.com'` |
| 현재 lineage | `/etc/letsencrypt/live/auth.hyeonworks.com/` (2026-09-17 확인) |
| nginx가 읽는 파일 | `fullchain.pem`, `privkey.pem` |
| 과거 측정 당시 타이머 | `certbot-renew.timer → certbot-renew.service` |
| 현재 Debian 12 타이머 | `certbot.timer → certbot.service` |
| 2305초 측정 당시 배치 | deploy 훅이 물리 호스트에 있던 구성 |
| 현재 배치 | certbot, 인증서, 타이머, deploy 훅을 Edge VM에 배치 |
## worker PID로 reload 여부를 확인하는 순서
@@ -92,9 +89,9 @@ ExecStart=/usr/bin/certbot -q renew --no-random-sleep-on-renew
PrivateTmp=true
```
유닛 이름과 `ExecStart` 옵션은 배포판/패키지 판에 따라 달라질 수 있다. 이 Case의 핵심은 이름이 아니라 **renew 성공과 nginx reload는 별도 상태 전이**라는 점이다.
유닛 이름과 `ExecStart` 옵션은 배포판과 패키지 버전에 따라 달라질 수 있다. 여기서 확인할 것은 certbot 갱신 성공과 nginx reload가 별도 동작이라는 점이다.
`ExecStartPost` 도 `--deploy-hook` 도 없다. 이 유닛은 인증서를 새로 받는 데까지만 책임지고, 받은 것을 nginx 가 읽게 만드는 일은 아무도 하지 않는다. 배포판이 이렇게 준다는 것이 요점이라, 「기본값이니 괜찮겠지」가 이 결함이 사는 곳이다.
현재 확인한 `certbot.service`에는 `ExecStartPost`나 `--deploy-hook`이 없다. 따라서 이 유닛은 인증서 갱신까지만 수행하고 nginx reload는 실행하지 않는다.
그래서 이 글의 훅이 모든 배포판에 필요하지는 않다. 위 유닛에 `ExecStartPost` 나 `--deploy-hook` 이 이미 적혀 있는 배포판이라면 훅을 새로 넣을 것이 아니라 거기 적힌 명령이 nginx 를 reload 하는지만 본다.
@@ -102,11 +99,11 @@ PrivateTmp=true
nginx 는 `ssl_certificate` 에 적힌 파일을 기동과 reload 시점에 읽어 메모리에 들고 있고, certbot 은 `live/` 아래의 심볼릭 링크를 새 파일로 갈아 끼운다. 설정에 적힌 경로는 한 글자도 바뀌지 않고 그 경로가 가리키는 파일만 바뀌므로, nginx 쪽에서는 다시 읽을 계기가 생기지 않는다. 갱신이 끝난 뒤에 nginx 로 reload 를 걸어 주는 것이 없으면 옛 인증서가 계속 나간다.
## 88일 동안 이 결함이 보이지 않는다
## 자동 갱신 상태만 보면 문제를 늦게 발견할 수 있다
타이머는 정상이고 갱신은 매번 `SUCCESS` 로 끝난다. 만료 30일 전까지는 갱신 자체를 하지 않으므로 88일 동안 발현할 기회가 없다. 발현하는 날의 증상은 인증서 만료이고, 그날에도 로그에는 `SUCCESS` 라고 적혀 있다.
타이머가 정상이고 certbot 실행 결과가 `SUCCESS`여도 nginx reload 여부는 별개다. 인증서 갱신이 실제로 발생하지 않는 기간에는 이 차이가 드러나지 않을 수 있으므로, 타이머 상태만으로 서비스 중인 인증서까지 정상이라고 판단하지 않는다.
훅을 저장소에 두는 까닭도 여기에 있다. 호스트에만 두었을 때는 호스트를 초기화하면 아무 오류 없이 사라졌고, 사라진 것도 갱신이 실제로 일어나는 날까지는 드러나지 않는다.
deploy 훅을 저장소에서 관리한 것도 같은 이유다. 호스트에만 파일을 두면 재구성 과정에서 빠질 수 있고, 다음 갱신 전까지 누락을 발견하지 못할 수 있다.
## 훅 두 줄과 실행 권한
@@ -120,7 +117,7 @@ nginx -t && nginx -s reload
sudo chmod +x /etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh
```
실행 권한이 없으면 certbot 이 조용히 건너뛴다. `post/` 가 아니라 `deploy/` 에 넣는 것은 `post/` 가 갱신이 없어도 매번 돌아 하루 두 번 워커를 갈아치우기 때문이다.
deploy 훅 파일에 실행 권한이 없으면 certbot이 해당 스크립트를 실행하지 않는다. `post/` 대신 `deploy/`를 사용한 이유는 실제 인증서 갱신이 있을 때만 nginx를 reload하기 위해서다.
이 실험대에서 잰 차이는 이렇다.
@@ -129,15 +126,15 @@ sudo chmod +x /etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh
| 갱신 → 서빙 | 2305초 (38분 25초) | 1~2초 |
| 무엇이 reload 했나 | 사람이 직접 | certbot deploy 훅 |
훅도 사람도 없었다면 다음 nginx 재시작까지, 사실상 무기한이다.
deploy 훅도 수동 reload도 없다면 nginx는 다음 reload 또는 재시작 전까지 기존 인증서를 계속 사용한다.
## 판정은 로그 문구가 아니라 워커 PID 로 한다
## nginx reload 여부는 worker PID로 확인했다
```bash
sudo certbot renew --dry-run
```
dry-run 은 훅이 호출되는지까지만 말해 준다. 호출된 훅이 nginx 를 정말 갈아 끼웠는지는 따로 본다.
dry-run으로는 deploy 훅이 호출되는지 확인할 수 있다. 실제 nginx reload 여부는 별도로 확인했다.
순서가 dry-run 먼저인 것은 뒤엣것이 상태를 바꾸기 때문이다. `--force-renewal` 은 인증서를 실제로 새로 받아 발급 한도(주당 중복 5장)를 깎으므로, 진짜 판정이 필요할 때 한 번만 쓴다.
@@ -151,7 +148,7 @@ sudo certbot renew --force-renewal
ps -eo pid,lstart,args | grep 'nginx: worker' | grep -v grep
```
reload 는 마스터를 그대로 두고 워커만 갈아 끼우므로, 전후로 워커 PID 가 바뀌면 새 설정이 적용됐다. `lstart` 를 같이 뽑는 것은 PID 가 우연히 재사용됐을 때를 가르기 위해서다.
nginx reload에서는 master 프로세스가 유지되고 worker 프로세스가 교체되므로, 전후의 worker PID와 시작 시각을 비교해 reload 여부를 확인했다. `lstart`를 함께 기록한 것은 PID 재사용 가능성을 구분하기 위해서다.
certbot 이 `Hook 'deploy-hook' ran with error output` 이라고 찍는데 실패가 아니다. nginx 의 `types_hash` 경고가 stderr 로 나갔을 뿐이고 내용은 `test is successful` 과 `signal process started` 다. 로그에서 `error` 를 grep 하는 감시를 걸면 성공한 훅을 실패로 오독한다.
@@ -174,7 +171,7 @@ timedatectl show -p NTP -p NTPSynchronized
2305초는 훅이 물리 호스트에만 있던 시절의 값이다. 지금은 certbot 과 인증서와 갱신 타이머와 deploy 훅이 전부 엣지 게스트에 있고, 그 배치에서 다시 재면 같은 수가 나오는지는 재지 않았다. 그래서 이 글의 2305초는 훅이 없으면 이만큼 벌어진다는 한 번의 측정이고 지금 배치의 값이 아니다. 1~2초 쪽도 같은 시기에 잰 값이다.
당시 측정의 raw 출력 파일은 별도로 보존하지 않았다. 2305초, 8856건, p95 두 값, 845361바이트, 106초와 worker PID 전후 비교는 당시 본문 기록에만 남아 있다. 따라서 이 수치는 현재 raw 출력으로 다시 대조할 수 있는 값이 아니라 **당시 기록 범위의 historical measurement**로 읽는다.
당시 측정의 원본 출력 파일은 별도로 보존하지 않았다. 2305초, 8856건, 두 p95 값, 845361바이트, 106초의 시계 차이와 worker PID 비교는 당시 본문 기록에만 남아 있다. 따라서 이 수치는 현재 원본 출력과 다시 대조할 수 없는 당시 측정값으로 구분한다.
88일이라는 잠복 기간은 만료 30일 전에야 갱신을 시작한다는 동작에서 끌어낸 것이지, 한 주기를 실제로 돌려 본 값이 아니다. 훅을 뺀 채 만료일까지 가 본 기록은 없고 그런 기록이 있을 까닭도 없다.
@@ -24,7 +24,7 @@ source:
# 가이드대로 다시 쳐서 이 실험대가 같은 상태로 서는가
2026-09-21에는 기존 worker 두 대를 실제로 철거한 뒤 cloud-init부터 k3s, Keycloak, observability까지 다시 올리고 power-cycle 뒤 복구 상태까지 확인했다. 따라서 **worker 재생성 이후의 복구 경로는 실제로 재검증됐다.** 다만 물리 호스트와 Edge VM, 인증서 계층을 모두 지운 빈 환경에서 00~06을 처음부터 다시 수행한 것은 아니다. `keycloak-cluster.yaml`, `observability.yaml`, `kc-lab.yaml.example` 원본도 저장소에 아직 없어, "문서만으로 빈 호스트를 완전 재구축할 수 있는가"라는 질문은 아직 확인이 끝나지 않았다.
2026-09-21에는 기존 worker 두 대를 실제로 철거한 뒤 cloud-init부터 k3s, Keycloak, observability까지 다시 올리고 power-cycle 뒤 복구 상태까지 확인했다. 따라서 worker 재생성 이후의 복구 경로는 실제로 재검증됐다. 다만 물리 호스트와 Edge VM, 인증서 계층을 모두 지운 빈 환경에서 00~06을 처음부터 다시 수행한 것은 아니다. `keycloak-cluster.yaml`, `observability.yaml`, `kc-lab.yaml.example` 원본도 저장소에 아직 없어, "문서만으로 빈 호스트를 완전 재구축할 수 있는가"라는 질문은 아직 확인이 끝나지 않았다.
## 2026-09-21에 실제로 재구축한 범위
@@ -33,7 +33,7 @@ source:
- Setup 00은 host 상태를 재확인했고, Setup 01에서는 두 worker의 qcow2·seed ISO를 다시 만든 뒤 SSH, cloud-init `status: done`, 고정 IP를 확인했다. 이어서 k3s server/agent, Keycloak 2노드·PostgreSQL, Prometheus/Grafana를 다시 올렸고 `vendor_cluster_size=2`와 주요 target `up=1`을 확인했다.
- 그 뒤 worker power-cycle과 workload 복구도 수행했고 Keycloak cluster size가 다시 2로 돌아오는 것까지 확인했다. 이 범위에서는 "기존 host/edge를 유지한 worker 재구축 경로"가 실제로 동작했다.
- 재구축 성공 여부는 일곱 가지 상태로 확인한다: `virsh list`가 동작하는가, 세 게스트에 SSH가 붙는가, `kubectl get nodes`에서 두 노드가 `Ready`인가, 외부 요청이 파드까지 닿는가, HTTPS가 열리고 인증서 체인이 기대한 형태인가, 관리 콘솔 로그인이 되는가, `vendor_cluster_size`가 2인가.
- 문서만으로 다시 세울 때 필요한 입력 파일 일부가 이 문서 묶음 안에 완결된 형태로 들어 있지 않다. `keycloak-cluster.yaml`, `observability.yaml`, `kc-lab.yaml.example`의 canonical 파일 자체가 함께 제공되어야 ‘본문을 읽은 기억’ 없이 빈 환경에서 그대로 재구축할 수 있다.
- 문서만으로 다시 세울 때 필요한 입력 파일 일부가 이 문서 묶음 안에 완결된 형태로 들어 있지 않다. `keycloak-cluster.yaml`, `observability.yaml`, `kc-lab.yaml.example`의 실제 원본 파일이 함께 있어야 문서 밖의 기억에 의존하지 않고 빈 환경에서 그대로 재구축할 수 있다.
- 기존 구축 과정에서는 실행 순서와 실행 위치 때문에 여섯 번 막혔다. 각 실패 자체는 실제로 관측했고, 이 여섯 사례를 ‘순서와 위치를 검증하지 않은 문서’라는 공통 원인으로 묶은 것은 사례를 바탕으로 한 해석이다.
- 수정한 가이드의 상당 부분은 2026-09-21 재구축에서 실제 실행 순서로 다시 확인했다. 다만 host 패키지 설치부터 Edge VM·DNS-01 인증서 계층까지 전부 제거한 완전한 빈 환경 재구축은 아직 하지 않았다.
@@ -81,9 +81,9 @@ source:
## 다음 검증
1. `keycloak-cluster.yaml`, `observability.yaml`, `kc-lab.yaml.example`의 canonical source를 저장소에 포함시킨다. 이 셋이 없으면 완전 재구축 검증에 "문서 밖의 기억"이 섞인다.
1. `keycloak-cluster.yaml`, `observability.yaml`, `kc-lab.yaml.example`의 실제 원본 파일을 저장소에 포함시킨다. 이 셋이 없으면 완전 재구축 검증에 "문서 밖의 기억"이 섞인다.
2. 대상을 정한다. 다른 빈 host에서 검증할지, 현재 lab을 계획적으로 철거한 뒤 같은 host에서 다시 세울지 선택한다.
3. 가이드 그대로 00부터 06까지 순서대로 친다. historical command와 현재 따라 할 절차가 함께 있는 곳에서는 현재 절차를 기준으로 실행한다. 각 단계의 통과 조건을 확인하고, 실행한 명령·작업 디렉터리·시각·종료 코드와 원문 출력을 함께 남겨 나중에 같은 실패를 다시 대조할 수 있게 한다.
3. 가이드 그대로 00부터 06까지 순서대로 친다. 과거에 사용한 명령과 현재 절차가 함께 적힌 곳에서는 현재 절차를 기준으로 실행한다. 각 단계의 통과 조건을 확인하고, 실행한 명령·작업 디렉터리·시각·종료 코드와 원문 출력을 함께 남겨 나중에 같은 실패를 다시 대조할 수 있게 한다.
4. 04 단계는 --dry-run 을 먼저 돌린다. 주당 중복 인증서 5장 한도를 dry-run 은 쓰지 않는다.
5. 막힌 단계마다 무엇이 없어서 막혔는지를 「이 구축에서 드러난 문서 결함의 공통 원인」의 두 축으로 분류해 적는다. 그 시점에 리소스가 없었나, 그 셸에서 안 도는 명령이었나. 어느 축에도 안 들어가면 그것을 새 축으로 적는다.
6. 끝나면 판 번호 넷을 적어 지금 실험대의 값과 나란히 둔다. 명령이 pin한 k3s는 동일 버전 여부를 판정하고, package manager가 고정하지 않은 nginx/libvirt/QEMU는 관측값 차이와 동작 차이를 분리해서 적는다.
@@ -1,7 +1,7 @@
---
kind: REFERENCE
slug: check-the-nearest-layer-first
title: 가까운 층부터 한 층씩 건너뛰며 확인한다 — 층마다 성공 신호가 다르다
title: 장애를 확인할 때는 가까운 계층부터 확인한다
topic: build-completion-judgment
topicName: 끝났다는 판정
project: virtualization
@@ -13,9 +13,9 @@ source:
- final/document.md#191-단계-05-keycloak-2노드와-postgresql
---
# 가까운 층부터 한 층씩 건너뛰며 확인한다 — 층마다 성공 신호가 다르다
# 장애를 확인할 때는 가까운 계층부터 확인한다
가장 가까운 층부터 치고 한 칸씩 밖으로 나오며, 층마다 성공 신호를 미리 적는다. 200 이 아닌 층이 있다 — 03 단계 네 칸의 실측은 404 와 301 과 301 과 200 이었다. 밖에서 한 번 쳐서 받은 값 하나로는 여섯 층 가운데 어디서 끊겼는지가 나오지 않는다.
장애 지점을 찾을 때는 서비스에 가장 가까운 구간부터 확인하고, 한 단계씩 외부 방향으로 범위를 넓혔다. 이 실험대의 03 단계에서는 각 구간의 정상 응답이 404, 301, 301, 200으로 서로 달랐다. 외부에서 받은 응답 하나만으로는 어느 구간에서 문제가 생겼는지 구분할 수 없었다.
## 왜 가장 가까운 층부터 보는가
@@ -41,7 +41,7 @@ source:
### 4. 층을 좁힌 뒤에는 그 층이 내는 문구와 errno 와 종료 코드를 읽는다
같은 「안 된다」가 층마다 다른 낱말로 나온다. nginx upstream 의 connect() failed (113: No route to host) 는 네트워크 쪽이고, (111: Connection refused) 는 프로세스 쪽이며, no live upstreams 는 둘 다 죽었다는 판단이다. 노드를 잃었을 때 이 세 줄이 1분 안에 순서대로 나왔다. k3s agent 노드의 dial tcp [::1]:8080: connect: connection refused 는 네트워크 문제가 아니라 kubeconfig 을 하나도 못 찾아 하드코딩된 기본값으로 넘어간 것이다. 파드의 Exit Code 도 그것만으로 말이 된다 — 137 은 OOM 이나 강제 종료, 1 은 애플리케이션이 스스로 끝낸 것, 127 은 명령을 못 찾은 것이다.
같은 「안 된다」가 층마다 다른 낱말로 나온다. nginx upstream 의 connect() failed (113: No route to host) 는 네트워크 쪽이고, (111: Connection refused) 는 프로세스 쪽이며, `no live upstreams`는 nginx가 사용할 수 있는 upstream이 없다고 판단한 상태다. 노드를 잃었을 때 이 세 줄이 1분 안에 순서대로 나왔다. k3s agent 노드의 dial tcp [::1]:8080: connect: connection refused 는 네트워크 문제가 아니라 kubeconfig 을 하나도 못 찾아 하드코딩된 기본값으로 넘어간 것이다. 파드의 Exit Code 도 그것만으로 말이 된다 — 137 은 OOM 이나 강제 종료, 1 은 애플리케이션이 스스로 끝낸 것, 127 은 명령을 못 찾은 것이다.
### 5. 그 층 안에 물어볼 도구가 없으면 밖에서 묻는다
@@ -60,9 +60,9 @@ Keycloak 컨테이너에는 curl 이 없다. 공식 이미지가 최소 구성
네 칸이 다 통과하고도 나중에 터지는 것이 있다. DNAT 규칙의 443 을 433 으로 친 오타가 이 실험대에서 실제로 나왔는데, 433 도 유효한 포트라 nft 가 군말 없이 받고 80 은 멀쩡히 넘어가므로 03 단계의 확인은 다 통과하고 04 단계에서 443 쪽만 안 되는 형태로 뒤늦게 터진다.
이 절차는 어디서 끊겼는지를 좁힐 뿐 왜 끊겼는지를 말하지 않는다. 첫 칸에서 404 가 나와도 그 뒤의 값이 틀렸을 수 있고, 02 단계의 INTERNAL-IP 가 그렇다 — 두 노드가 Ready 인데 보고된 IP 가 우리가 준 값과 다르면 지금은 아무 증상이 없다가 03 단계의 upstream 에서 어긋난다. 로그를 읽어 좁히려다 잘린 문구를 붙들 수도 있다. nginx 에러 로그는 2048바이트에서 잘린다. 이 실험대에서도 502 원인이 error 로그에서는 잘린 채로 있었고, access 로그에는 3492자로 온전히 남아 있었다. 그쪽은 「도구가 낸 출력은 대상의 상태가 아니다」가 받는다.
이 절차는 문제가 생긴 구간을 좁히는 데까지만 사용한다. 예를 들어 두 노드가 `Ready`여도 보고된 `INTERNAL-IP`가 기대한 값과 다르면 당장은 증상이 없다가 nginx upstream 연결에서 문제가 드러날 수 있다. 로그도 잘린 일부만 보면 원인을 놓칠 수 있는데, 이 실험대에서는 nginx error log가 2048바이트에서 잘린 반면 access log에는 3492자의 원문이 남아 있었다. 구간을 좁힌 뒤에는 명령과 로그가 실제로 무엇을 보여 주는지 별도로 확인한다.
제3부의 「packet 이 어디서 끊겼는지는 계층마다 capture 해서 가른다」와는 재는 것이 다르다. 그쪽은 네 지점에서 capture 를 떠 패킷이 사라진 구간을 좁히고, 이쪽은 층을 건너뛴 요청의 응답 코드로 좁힌다. 응답이 아예 안 돌아오고 패킷도 안 보이는 상태에서는 이 절차가 답을 못 내므로 그때 그쪽으로 넘어간다.
응답 코드로 계층을 좁히는 방법과 packet capture는 측정 대상이 다르다. HTTP 응답이 돌아오면 각 계층을 건너뛴 요청의 응답으로 범위를 줄일 수 있고, 응답 자체가 없으면 여러 인터페이스에서 packet capture를 떠 패킷이 사라지는 구간을 찾는다.
## 이 실험대에서 쓴 예
@@ -74,6 +74,6 @@ Keycloak 컨테이너에는 curl 이 없다. 공식 이미지가 최소 구성
- 둘째 칸에서 막힌다 : 막힌 곳이 엣지 안이다
- 첫 칸이 502 : Traefik 은 떴고 뒤에 백엔드가 없다
- 첫 칸이 연결 거부나 타임아웃 : 02 단계의 노드 상태로 돌아간다
- 노드를 잃었을 때 1분 안에 순서대로 나온 세 줄 : 113 은 네트워크, 111 은 프로세스, no live upstreams 는 둘 다 죽었다는 판단
- 노드를 잃었을 때 1분 안에 순서대로 나온 세 줄 : 113은 네트워크 경로 문제, 111은 대상 프로세스 연결 거부, `no live upstreams`는 사용할 수 있는 upstream이 없다는 상태
- Keycloak 컨테이너 안에서 curl 이 exit code 127 : 서버가 아니라 명령이 없다. 밖에서 묻는다
- 04 단계 확인을 엣지 안에서 쳤을 때의 connection refused : 층의 답이 아니라 친 위치의 답이다
@@ -1,7 +1,7 @@
---
kind: REFERENCE
slug: tool-output-is-not-the-subject-state
title: 도구가 낸 출력은 대상의 상태가 아니다 — 그 명령이 무엇을 세는지부터 가른다
title: 명령 출력이 실제 상태를 의미하는지 먼저 확인한다
topic: build-completion-judgment
topicName: 끝났다는 판정
project: virtualization
@@ -13,7 +13,7 @@ source:
- final/document.md#186-단계-00-lab-host-가상화-준비
---
# 도구가 낸 출력은 대상의 상태가 아니다 — 그 명령이 무엇을 세는지부터 가른다
# 명령 출력이 실제 상태를 의미하는지 먼저 확인한다
상태를 묻는 명령의 출력을 대상의 상태로 바로 읽지 않고, 그 명령이 무엇을 세고 무엇을 안 세는지 먼저 적는다. 7800 포트를 끊었을 때 외부 응답은 전부 200 이었고, 503 이 나는 동안에도 up 은 1 이었다.
@@ -80,7 +80,7 @@ kubectl rollout status 는 끝날 때까지 아무것도 안 찍고 그 침묵
이 기준의 근거는 대부분 이 실험대 한 대에서 한 번씩 본 것이다. 다른 판 번호나 다른 배포판에서 같은 명령이 같은 것을 세는지는 재지 않았다.
가이드에 실린 출력이 이 호스트의 것인지도 한 군데에서 어긋났다. 「단계 00 — lab host 가상화 준비」의 과거 출력은 16 코어 전부에서 지원한다고 적었지만, 2026-09-17과 2026-09-21에 `nproc`·`lscpu`로 다시 확인한 현재 `test-server`는 i5-1135G7, 물리 4코어·8 logical CPU다. 따라서 16코어 줄은 **현재 호스트의 관측값이 아니라 다른 환경에서 섞여 들어온 historical output**으로 취급한다.
가이드에 실린 출력이 이 호스트의 것인지도 한 군데에서 어긋났다. 「단계 00 — lab host 가상화 준비」의 과거 출력은 16 코어 전부에서 지원한다고 적었지만, 2026-09-17과 2026-09-21에 `nproc`·`lscpu`로 다시 확인한 현재 `test-server`는 i5-1135G7, 물리 4코어·8 logical CPU다. 따라서 16코어 줄은 현재 호스트의 관측값이 아니라 다른 환경의 출력으로 구분한다.
## 실제 판독 예
@@ -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 분포
@@ -1,7 +1,7 @@
---
kind: CONCEPT
slug: two-l7-hops-and-the-entry-point-recursion
title: L7 이 두 겹인 이유와, 진입점 하나를 이중화하려 할 때 끝나지 않는 재귀
title: 이 실험대에서 L7 프록시를 두 단계로 둔 이유
topic: lab-entry-path-and-measurement-integrity
topicName: 실험대의 진입 경로
project: virtualization
@@ -18,9 +18,9 @@ source:
- final/document.md#258-왜-tls를-끊어서-내용을-보는가
---
# L7 이 두 겹인 이유와, 진입점 하나를 이중화하려 할 때 끝나지 않는 재귀
# 이 실험대에서 L7 프록시를 두 단계로 둔 이유
이 실험대의 요청은 HTTP 를 읽는 서버를 두 번 지난다. 바깥의 nginx 가 TLS 를 끊고 어느 노드로 보낼지 정하고, 그 노드의 Traefik 이 어느 파드로 보낼지 정한다. 한쪽만으로는 안 되는 이유가 서로 다르고, 진입점을 이중화하려 하면 「어느 진입점으로 갈지 누가 정하는가」가 새로 생겨 재귀가 끝나지 않는다.
이 실험대의 요청은 nginx와 Traefik 두 L7 프록시를 지난다. nginx는 TLS를 종료하고 어느 노드로 보낼지 결정하며, Traefik은 Ingress 규칙을 보고 어느 서비스와 파드로 전달할지 결정한다. 두 계층의 역할이 다르기 때문에 하나로 합치지 않았다. nginx 진입점을 여러 대로 늘리려면 그 앞에서 어느 nginx로 보낼지 결정하는 별도의 진입점이나 L4 분산 방식이 추가로 필요하다.
<!-- body:start -->
@@ -95,7 +95,7 @@ ALB 와 NLB 는 AWS 의 두 제품이고 이 실험대에는 없다. 여기서
이 실험대는 두 패턴 중 어느 쪽도 아니다. 바깥의 nginx 가 TLS 를 끊고 `X-Forwarded-*` 를 넣으므로 ALB 에 가까운데, 그 뒤의 Traefik 이 또 HTTP 를 읽는다.
## 진입점을 이중화하려 하면 재귀가 끝나지 않는다
## nginx 진입점을 여러 대로 늘리면 앞단 분산 방식이 하나 더 필요하다
한 머신 안에서 nginx 를 여러 개 띄우는 것은 의미가 없다. nginx 는 이미 master 프로세스 1개와 worker N개 구조이고, worker 들이 리스닝 소켓을 공유하며 CPU 코어 수만큼 병렬로 처리한다. 같은 머신에 인스턴스를 늘려도 그 머신이 내려가면 전부 함께 내려가므로 가용성은 늘지 않는다.
@@ -1,7 +1,7 @@
---
kind: PROJECT_DECISION
slug: no-public-tunnel-because-a-third-hop-pollutes-the-measurement
title: 공개 터널을 쓰지 않고 tailnet 직결로 둔다 — 홉이 하나 늘면 재려던 계약이 오염된다
title: 공개 터널 대신 tailnet 직결을 선택한 이유
topic: lab-entry-path-and-measurement-integrity
topicName: 실험대의 진입 경로
project: virtualization
@@ -15,21 +15,21 @@ source:
- final/document.md#301-전체-지도
---
# 공개 터널을 쓰지 않고 tailnet 직결로 둔다 — 홉이 하나 늘면 재려던 계약이 오염된다
# 공개 터널 대신 tailnet 직결을 선택한 이유
Cloudflare named tunnel 을 앞에 붙이면 브라우저에서 파드까지가 3홉이 되고, 이 실험대가 재려는 것이 정확히 2홉의 forwarded 헤더 계약이라 측정이 오염된다. 그래서 tailnet 직결로 두고 터널 설정 파일은 채택하지 않은 선택지로 남긴다.
Cloudflare named tunnel을 앞에 두면 브라우저에서 파드까지 HTTP 프록시 홉이 하나 늘어난다. 이 실험에서는 nginx와 Traefik 두 홉 사이에서 forwarded 헤더가 어떻게 전달되는지를 확인하려 했기 때문에, 측정 경로를 바꾸지 않도록 tailnet에서 nginx로 직접 연결했다. Cloudflare tunnel은 검토했지만 사용하지 않았다.
## 왜 공개 터널을 후보에서 뺐나
「`tunnel/` — 채택하지 않은 이유를 남긴 자산」에서는 `deploy/` 아래의 `tunnel/cloudflared-config.yml` 을 두고 채택하지 않았다고 적으면서 기각 이유를 전후 홉 그림으로 남겼다. 기각한 파일을 지우지 않는 방침은 「9층. `deploy/` — 무엇이 살아 있고 무엇이 참조인가」부터 「왜 적용하지 않는 것을 남겨두는가」에 따로 있다. 저장소에 있으나 적용되지 않는 설정이 여럿인데, 그것들이 죽은 코드가 아니라 의도적으로 남겨 둔 참조 자산이라고 전체 지도와 함께 적는다.
「`tunnel/` — 채택하지 않은 이유를 남긴 자산」에서는 `deploy/` 아래의 `tunnel/cloudflared-config.yml` 을 두고 채택하지 않았다고 적으면서 기각 이유를 전후 홉 그림으로 남겼다. 기각한 파일을 지우지 않는 방침은 「9층. `deploy/` — 무엇이 살아 있고 무엇이 참조인가」부터 「왜 적용하지 않는 것을 남겨두는가」에 따로 있다. 저장소에는 실제 배포에 사용하지 않는 설정도 남아 있으며, 이런 파일은 채택하지 않은 대안의 설정과 검증 방법을 보존하는 용도로 구분한다.
- **L7 이 두 겹인 이유와, 진입점 하나를 이중화하려 할 때 끝나지 않는 재귀**
- **이 실험대에서 L7 프록시를 두 단계로 둔 이유**
이 결정이 지키려는 2홉이 무엇이고 그 둘의 역할이 왜 다른지를 그 글이 설명한다.
- **신뢰 경계에서는 forwarded 헤더를 덧붙이지 않고 덮어쓴다**
앞에 한 겹이 더 붙으면 경계가 Cloudflare 엣지로 옮겨 가 그 기준을 거기서 다시 세워야 한다.
- **인증서는 DNS-01 로 받는다 — 실험대 주소가 공개 인터넷에 없어 HTTP-01 이 성립하지 않는다**
- **공개 인터넷에 노출되지 않은 실험대에서 DNS-01을 선택한 이유**
이 결정이 청구한 비용 하나를 그 결정이 받는다.
- **엣지 nginx 를 호스트에서 게스트 VM 으로 옮긴다 — 성능이 아니라 더러워지는 층의 격리**
- **Edge Nginx를 호스트에서 게스트 VM으로 분리한 이유**
같은 2홉을 지킨 채 엣지의 위치만 바꾼 결정이라 홉 수를 건드리지 않는다.
- **이 실험대의 certbot 은 HTTP-01 로 받고 있는가 DNS-01 로 받고 있는가**
2026-09-17에 `dns-cloudflare` 사용을 확인했고, 2026-09-21 renewal dry-run까지 성공해 현재 자격증명으로 DNS-01 갱신 시뮬레이션이 가능한 것도 확인했다.
@@ -44,7 +44,7 @@ Cloudflare named tunnel 을 앞에 붙이면 브라우저에서 파드까지가
Cloudflare named tunnel 은 아웃바운드 연결만 쓰므로 포트포워딩 없이 공개 HTTPS 이름을 얻는다. 공유기를 건드릴 수 없는 환경에서는 매력적인 선택지이고, 「`tunnel/` — 채택하지 않은 이유를 남긴 자산」에서는 그 설정의 함정 둘까지 적어 두었다. `service:` 에 `127.0.0.1` 을 쓰면 cloudflared 컨테이너 자신을 가리키므로 Compose 서비스 DNS 이름을 써야 하고, 마지막 catch-all 이 없으면 오류가 난다.
기각 근거는 홉 수다. 터널을 쓰면 브라우저가 Cloudflare 엣지와 nginx 와 Traefik 을 지나 파드에 닿아 3홉이 된다. 지금은 브라우저가 nginx 와 Traefik 만 지나 파드에 닿는 2홉이다. Cloudflare 엣지가 TLS 를 끊고 다시 맺으면서 HTTP 를 읽는 홉이 하나 늘고 `CF-Connecting-IP` 같은 자체 헤더가 섞인다. 이 실험대가 측정하려는 것이 정확히 `nginx → Traefik` 2홉의 forwarded 헤더 계약이므로, 앞에 한 겹이 더 붙으면 측정이 오염된다.
터널을 사용하면 브라우저 요청은 Cloudflare edge, nginx, Traefik을 차례로 지나 파드에 도착한다. 현재 경로는 nginx와 Traefik 두 홉이다. Cloudflare edge가 TLS를 종료하고 다시 연결하면서 `CF-Connecting-IP` 같은 헤더도 추가하므로, 터널을 사용하면 확인하려는 `nginx → Traefik` 헤더 전달 경로 자체가 달라진다.
터널이 무엇을 해 주는지가 아니라 그것이 이 실험대의 측정 대상에 무엇을 하는지를 보고 정했다.
@@ -60,7 +60,7 @@ Cloudflare named tunnel 은 아웃바운드 연결만 쓰므로 포트포워딩
기각한 파일을 지우지 않는 방침에도 근거가 셋 있다.
① 저장소의 목적이 비교다 : 선택지를 나란히 두고 트레이드오프를 적는 것 자체가 산출물이라, 하나만 남기면 왜 이것을 골랐는지를 뒷받침할 근거가 없어진다
② 죽은 코드가 아니라 테스트되는 코드다 : `scripts/verify-public-tunnel-config.sh` 가 붙어 있어 실행되지 않을 뿐 깨지면 드러난다
② 실제 배포에는 사용하지 않지만 검증 스크립트가 있다 : `scripts/verify-public-tunnel-config.sh`로 설정 형식이 깨졌는지 확인할 수 있다
③ 실험대 전용 설정은 `lab/` 아래로 분리했다 : 일반 배포 설정과 섞이지 않는다
재지 않은 것도 있다. 터널을 붙인 상태와 지금을 같은 방법으로 잰 비교는 이 저장소에 없다. 기각의 근거는 홉 수와 추가되는 신뢰 경계이지 두 구성을 벤치마크한 결과가 아니다. 인증 방식은 2026-09-17 `dns-cloudflare`로 확인됐고, 2026-09-21에는 credential 파일이 81 bytes인 상태에서 renewal dry-run도 성공했다.
@@ -16,13 +16,13 @@ source:
# 신뢰 경계에서는 forwarded 헤더를 덧붙이지 않고 덮어쓴다
맨 바깥 프록시는 클라이언트가 보낸 `X-Forwarded-For`를 버리고 자기가 **실제로 본 주소**로 덮어쓴다. nginx에서는 `$proxy_add_x_forwarded_for`가 아니라 `$remote_addr`를 쓰는 이유다. 다만 `$remote_addr`가 원본 client IP라는 보장은 네트워크 계층이 제공해야 한다. 현재 실험대에서는 2026-09-21 packet capture로 Tailscale MASQUERADE가 edge 앞에서 source를 `192.168.122.1`로 바꾸는 것을 확인했다.
맨 바깥 프록시는 클라이언트가 보낸 `X-Forwarded-For`를 버리고 자기가 실제로 본 주소로 덮어쓴다. nginx에서는 `$proxy_add_x_forwarded_for`가 아니라 `$remote_addr`를 쓰는 이유다. 다만 `$remote_addr`가 원본 client IP라는 보장은 네트워크 계층이 제공해야 한다. 현재 실험대에서는 2026-09-21 packet capture로 Tailscale MASQUERADE가 edge 앞에서 source를 `192.168.122.1`로 바꾸는 것을 확인했다.
## forwarded 헤더가 신뢰 경계가 되는 이유
`X-Forwarded-For` 는 누구나 보낼 수 있는 평범한 HTTP 헤더다. 값을 믿을 만하게 만드는 것은 헤더 이름이 아니라 그 값을 쓴 주체이고, 쓰는 주체를 하나로 좁히는 것이 이 기준이다. 맨 바깥 프록시가 클라이언트의 값을 이어 붙이면 위조된 값이 사슬 앞에 남고, 그러면 뒤쪽의 어느 것도 그 헤더를 근거로 쓸 수 없다.
설정 정본이 그 줄 위에 이유를 적어 두었다. 원문은 영어이고 그대로 옮긴다.
실제 nginx 설정에는 이 헤더를 덮어쓰는 이유가 주석으로 남아 있다.
$remote_addr, not $proxy_add_x_forwarded_for. This is the trust boundary: a client-supplied X-Forwarded-For must be discarded, not extended, or nothing downstream can rely on the value.
@@ -1,7 +1,7 @@
---
kind: CASE
slug: declared-memory-and-disk-are-ceilings-not-occupancy
title: 메모리와 디스크의 선언량은 실제 점유량이 아니다 — 서로 다른 지표를 같은 숫자로 읽지 않는다
title: 설정한 메모리·디스크 크기와 실제 사용량을 구분해서 본다
topic: lab-environment-build
topicName: 실험대 환경 구성
project: virtualization
@@ -20,56 +20,62 @@ source:
- final/document.md#211-이-부의-출처와-범위
---
# 메모리와 디스크의 선언량은 실제 점유량이 아니다 — 서로 다른 지표를 같은 숫자로 읽지 않는다
# 설정한 메모리·디스크 크기와 실제 사용량을 구분해서 본다
2026-09-10 기록에는 `kc-lab-1`의 `dommemstat actual-unused` 차이가 353MB, `kc-lab-2`가 301MB로 남아 있고, 두 qcow2 overlay의 `ls -l` 파일 길이는 1.4GiB와 665MiB였다. 당시 문서는 이 값을 ‘실사용/실제 점유’라고 불렀지만 서로 다른 계층의 지표다. `dommemstat` 차이는 host RSS가 아니고, `ls -l` 파일 길이도 host가 실제로 할당한 disk block 양과 같지 않을 수 있다. 2026-09-21 재검증에서는 configured/current memory·guest-visible memory·QEMU RSS와 qcow2 virtual size·disk allocation·file length를 따로 읽어 이 구분을 명확히 했다.
## 선언한 용량과 실제로 관측하는 값이 같은 지표인지부터 확인해야 했다
## 설정값과 실제 사용량은 서로 다른 지표였다
제1~4부에는 이 호스트에서 잰 값이 하나도 없다. 제5·6부는 버전과 주소와 명령까지만 적었다.
게스트 세 대에 메모리 8240MB 와 디스크 40GB 를 선언해 두었는데, 그 선언이 11,648MiB 와 226G 짜리 호스트 한 대에서 실제로 얼마를 먹는지는 어디에도 없었다. 「5GB 를 줬으니 5GB 를 쓴다」와 「20GB 두 장이면 40GB 를 쓴다」가 맞는지 모르는 채로 게스트를 더 띄울지 정해야 했다.
게스트에 설정한 메모리와 디스크 용량만으로는 호스트에서 실제로 사용하는 RAM과 디스크 공간을 알 수 없었다. 추가 게스트를 띄울 수 있는지 판단하려면 libvirt의 메모리 설정값과 QEMU RSS를 구분하고, qcow2의 가상 크기와 호스트 파일시스템 할당량도 따로 측정해야 했다.
## 메모리와 qcow2는 한 숫자로 점유량을 말할 수 없었다
## 메모리와 qcow2는 측정하는 값이 각각 다르다
메모리의 configured/current 값과 qcow2의 virtual size는 **용량을 설명하는 값**이고, host RAM RSS나 host filesystem allocation과는 다른 계층의 지표다. k3s만 떠 있고 Keycloak은 아직 안 올린 상태에서 당시 문서가 여러 값을 한 번에 쟀는데, 지금은 각 값이 무엇을 뜻하는지 분리해 읽는다.
메모리 : `kc-lab-1`은 `actual=5120MB`에서 `unused`를 뺀 차이가 353MB, `kc-lab-2`는 `actual=3120MB`에서 같은 방식의 차이가 301MB
메모리 합계 : 당시 두 차이를 더하면 654MB였지만, 이것을 host physical RSS 합계로 읽지는 않는다
디스크 : `kc-lab-1.qcow2`의 `ls -l` 파일 길이 1.4GiB, `kc-lab-2.qcow2` 665MiB, 바닥 `base.qcow2`는 `virtual size` 3GiB에 `qemu-img info disk size` 335MiB
디스크 합계 : overlay 파일 길이 합은 약 2.1GiB였지만, sparse file의 실제 host allocation 합계라고 단정하지 않는다
철거 : 게스트 셋을 지우자 `df -h /` 가 11G 에서 7.9G 로 내려 3.1GB 가 회수됐다
| 측정 항목 | 2026-09-10에 기록한 값 | 해석 |
|---|---|---|
| `kc-lab-1` `actual-unused` | 353MB | host QEMU RSS가 아니라 libvirt가 제공한 guest memory 통계의 차이 |
| `kc-lab-2` `actual-unused` | 301MB | 위와 동일 |
| 두 값의 합 | 654MB | host physical RSS 합계로 사용하지 않음 |
| `kc-lab-1.qcow2` `ls -l` 길이 | 1.4GiB | 파일 길이 |
| `kc-lab-2.qcow2` `ls -l` 길이 | 665MiB | 파일 길이 |
| `base.qcow2` | virtual size 3GiB, `disk size` 335MiB | backing image의 가상 크기와 할당량 |
| 게스트 삭제 전후 `df -h /` | 11G → 7.9G | 파일시스템 전체 사용량이 약 3.1GB 감소 |
2026-09-10에는 `virt-install --memory 4096`으로 만든 `kc-lab-2`의 `dommemstat actual`이 3120MB로 보였다. 당시 current allocation과 선언값이 달랐다는 관측은 맞지만, 원인을 virtio-balloon 회수로 확정할 근거는 없었다. 2026-09-21 재검증에서는 `dominfo`와 `dommemstat`을 나란히 읽었고 configured/current/actual이 모두 4096MiB였다. virtio-balloon 장치는 실제로 존재하지만, 장치 존재와 active inflation은 같은 사실이 아니다.
## 2026-09-10 측정 환경
측정일 : 2026-09-10
호스트 : `test-server`, Arch Linux
CPU : `11th Gen Intel(R) Core(TM) i5-1135G7 @ 2.40GHz`, 논리 코어 8
RAM : 11,648MiB
루트 파일시스템 : 226G 가운데 9.9G 사용
QEMU : 11.1.1
libvirt : 12.7.0
커널 : `7.2.2-arch1-1`
중첩 가상화 : `nested` 가 `Y` 지만 이 실험대는 쓰지 않는다
게스트 : Debian 12 genericcloud 3대 — 엣지 1대, k3s 2노드
워크로드 : k3s 만 떠 있고 Keycloak · PostgreSQL · Redis · Prometheus 는 올리기 전
| 항목 | 값 |
|---|---|
| 측정일 | 2026-09-10 |
| 호스트 | `test-server`, Arch Linux |
| CPU | `11th Gen Intel(R) Core(TM) i5-1135G7 @ 2.40GHz`, 논리 코어 8 |
| RAM | 11,648MiB |
| 루트 파일시스템 | 226G 가운데 9.9G 사용 |
| QEMU | 11.1.1 |
| libvirt | 12.7.0 |
| 커널 | `7.2.2-arch1-1` |
| 중첩 가상화 | `nested=Y`, 이 실험에서는 사용하지 않음 |
| 게스트 | Debian 12 genericcloud 3대: Edge VM 1대, k3s 노드 2대 |
| 당시 워크로드 | k3s만 실행, Keycloak·PostgreSQL·Redis·Prometheus는 배포 전 |
## 메모리와 디스크를 계층별 지표로 나눠 재는 방법
1. k3s 두 노드만 띄우고 Keycloak · PostgreSQL · Redis · Prometheus 는 올리지 않는다.
2. 게스트마다 `virsh dommemstat`을 돌려 `actual`과 `unused`를 읽는다. 두 값의 차이는 **당시 libvirt가 보고한 guest-side memory 지표의 차이**로 기록하고, host QEMU RSS나 물리 RAM 점유량으로 바꾸어 부르지 않는다.
3. `qemu-img info`로 각 qcow2의 `virtual size`와 `disk size`를 읽고, `du`와 `ls -l`을 함께 사용해 host allocation과 file length를 구분한다. historical 2026-09-10 기록에는 overlay의 `ls -l` 값만 남아 있어 그 시점의 VM별 block allocation은 다시 만들 수 없다.
3. `qemu-img info`로 각 qcow2의 `virtual size`와 `disk size`를 읽고, `du`와 `ls -l`을 함께 사용해 호스트 할당량과 파일 길이를 구분한다. 2026-09-10 기록에는 overlay의 `ls -l` 값만 남아 있어 그 시점의 VM별 실제 블록 할당량은 다시 계산할 수 없다.
4. 철거하기 전에 `df -h /` 를 읽어 둔다.
5. `virsh destroy` 와 `virsh undefine --remove-all-storage` 로 게스트 셋을 지우고 `df -h /` 를 다시 읽는다.
<!-- body:start -->
## 이 호스트에서 처음으로 양을 쟀다
## 호스트 자원 사용량을 실제 값으로 확인했다
이 실험대의 문서는 제5·6부까지 버전과 주소와 명령을 적었고 자원의 양은 적지 않았다. 제7부가 그 양과 시간을 처음 쟀고, 원본이 표기 규약을 스스로 밝혀 두었다.
초기 구축 기록에는 버전과 주소, 명령은 있었지만 호스트에서 실제로 사용하는 메모리와 디스크 양은 측정돼 있지 않았다. 2026-09-10에 처음으로 자원 사용량을 측정했고, 이후 2026-09-21에 같은 항목을 다시 확인했다.
> 여기 적힌 숫자는 전부 2026-09-10 에 `test-server` 에서 실제로 돌려 받은 출력이다. 추정값·예상값은 없다. 없는 값은 「미측정」이라고 쓴다.
@@ -82,7 +88,7 @@ Mem: 11648 5642 2599 4 3776 6005
`available` 이 6005 로 `free` 2599 보다 훨씬 큰데, `buff/cache` 3776 이 필요해지면 회수되기 때문이다. 게스트를 몇 대 더 띄울 수 있는지는 `free` 가 아니라 `available` 로 읽는다.
## 메모리 — 5120MB current에서 `actual-unused` 차이는 353MB였다
## `dommemstat` 값은 QEMU RSS와 같지 않았다
당시 기록은 `dommemstat`의 `actual`에서 `unused`를 뺀 값을 ‘실사용’이라고 불렀다. 지금은 그 표현을 그대로 쓰지 않는다. `actual`은 libvirt가 보는 현재 memory target이고 `unused`는 guest balloon 통계에서 온 값이므로, 그 차이는 **그 시점의 guest memory 상태를 보는 한 지표**이지 host QEMU RSS와 같은 값이 아니다.
@@ -101,11 +107,11 @@ kc-lab-2 actual 3120MB actual-unused 차이 301MB
당시에는 virtio-balloon 회수 가능성을 추론했지만, **3120MB의 직접 원인은 확인되지 않았다.** 2026-09-21에는 세 domain에 virtio-balloon 장치가 있고 worker guest에도 driver가 bind된 것을 확인했지만, `kc-lab-2`의 configured/current/actual은 모두 4096MiB였다. 따라서 과거의 3120MB를 현재도 지속되는 balloon 회수 상태로 설명하지 않는다.
## 디스크 — 20GiB virtual size와 파일 길이는 달랐다
## qcow2의 가상 크기와 호스트 파일 크기는 달랐다
게스트 디스크는 `base.qcow2` 위의 오버레이다. 20GB 짜리를 두 장 만들어도 바닥은 한 벌이고 변경분만 쌓인다.
게스트 디스크는 공통 `base.qcow2`를 backing image로 사용하는 오버레이다. 각 오버레이를 20GiB로 만들더라도 base 이미지를 복제하는 것이 아니라 변경된 블록이 오버레이에 추가된다.
```text label="qemu-img info 가 읽은 바닥 이미지"
```text label="qemu-img info 가 읽은 base 이미지"
image: /var/lib/libvirt/images/base.qcow2
file format: qcow2
virtual size: 3 GiB (3221225472 bytes)
@@ -120,7 +126,7 @@ disk size: 335 MiB
-rw------- seed-kc-lab-2.iso 378880 (370 KiB)
```
바닥 이미지는 virtual size가 3GiB였고 `qemu-img info`의 disk size가 335MiB였다. 두 overlay는 각각 20GiB virtual size로 만들었지만 당시 `ls -l` 파일 길이는 1.4GiB와 665MiB였다. **이 둘의 합 2.1GiB는 파일 길이 합이지 sparse 파일이 host block을 실제로 2.1GiB 할당했다는 측정은 아니다.** host allocation을 말하려면 같은 시점의 `qemu-img info disk size`나 `du`를 따로 읽어야 한다. `kc-lab-1` 쪽 파일이 더 컸다는 관측은 남기되, 그 차이를 컨트롤 플레인과 SQLite 하나로 확정하지 않는다.
base 이미지는 virtual size가 3GiB였고 `qemu-img info`의 disk size가 335MiB였다. 두 overlay는 각각 20GiB virtual size로 만들었지만 당시 `ls -l` 파일 길이는 1.4GiB와 665MiB였다. **이 둘의 합 2.1GiB는 파일 길이 합이지 sparse 파일이 host block을 실제로 2.1GiB 할당했다는 측정은 아니다.** host allocation을 말하려면 같은 시점의 `qemu-img info disk size`나 `du`를 따로 읽어야 한다. `kc-lab-1` 쪽 파일이 더 컸다는 관측은 남기되, 그 차이를 컨트롤 플레인과 SQLite 하나로 확정하지 않는다.
## `virsh pool-info` 의 `Allocation` 은 VM 사용량이 아니다
@@ -137,7 +143,7 @@ Available: 217.46 GiB
`Allocation` 7.84 GiB는 directory storage pool이 놓인 호스트 파일시스템의 사용 상태를 반영하는 풀 단위 값이다. **VM별 실제 block allocation을 말해 주는 값이 아니다.** 반대로 위의 `ls -l`은 VM별 파일 길이를 보여 줄 뿐 sparse qcow2가 host block을 얼마나 실제 할당했는지는 말해 주지 않는다. VM별 host allocation을 비교하려면 `qemu-img info`의 `disk size`나 `du`처럼 그 기준을 직접 읽는 명령을 쓴다.
## 철거 — `df -h /` 가 11G 에서 7.9G 로
## 게스트를 삭제한 뒤 파일시스템 사용량이 11G에서 7.9G로 줄었다
게스트 셋을 `virsh destroy` 로 내리고 `virsh undefine --remove-all-storage` 로 지웠다. 한 대분 출력은 이렇다.
@@ -158,9 +164,9 @@ Volume 'vdb'(/var/lib/libvirt/images/seed-kc-lab-edge.iso) removed.
| `df -h /` | 11G | 7.9G |
| `virbr0` | UP | DOWN |
`df -h /` 기준으로 철거 전후 사용량은 11G에서 7.9G로 내려 약 3.1GB 차이가 보였다. 다만 이 3.1GB를 위의 `ls -l` 파일 길이들로 정확히 분해하지 않는다. sparse qcow2의 파일 길이와 실제 block allocation은 다를 수 있고, `df`는 파일시스템 전체 변화를 본 값이기 때문이다. `base.qcow2`는 철거 뒤에도 남아 다음 overlay의 바닥으로 사용됐다.
`df -h /` 기준으로 철거 전후 사용량은 11G에서 7.9G로 내려 약 3.1GB 차이가 보였다. 다만 이 3.1GB를 위의 `ls -l` 파일 길이들로 정확히 분해하지 않는다. sparse qcow2의 파일 길이와 실제 block allocation은 다를 수 있고, `df`는 파일시스템 전체 변화를 본 값이기 때문이다. `base.qcow2`는 게스트 삭제 뒤에도 남아 다음 overlay의 backing image로 사용됐다.
## 같은 대상의 숫자가 두 벌이다
## 측정 날짜가 다르면 같은 항목의 값도 달라진다
같은 실험대라도 측정 날짜가 다르면 값이 달라진다. 「실험대 전체 배치」는 2026-09-03 스냅샷이고, 여기서 비교하는 값은 2026-09-10 스냅샷이다.
@@ -177,13 +183,13 @@ Volume 'vdb'(/var/lib/libvirt/images/seed-kc-lab-edge.iso) removed.
## 2026-09-21 재검증에서 추가로 확인한 것
2026-09-10의 숫자는 historical snapshot으로 유지한다. 2026-09-21에는 더 진행된 현재 실험대에서 같은 계층을 다시 읽었다.
2026-09-10 값은 당시 측정값으로 그대로 남기고, 2026-09-21에는 현재 실험대에서 같은 항목을 다시 측정했다.
- configured/current memory: `kc-lab-1=5120MiB`, `kc-lab-2=4096MiB`, `kc-lab-edge=1024MiB`
- 같은 시점 QEMU RSS: 약 `3.73GiB / 2.91GiB / 0.84GiB`
- qcow2 virtual/disk size: `kc-lab-1` 20GiB / 약 3.43GiB, `kc-lab-2` 20GiB / 약 2.66GiB, edge 10GiB / 약 345MiB
이 값도 시점값이다. 2026-09-10 표를 새 숫자로 덮어쓰지 않고, **환경이 진행되면서 actual usage가 달라졌다는 별도 관측**으로 둔다.
이 값들도 측정 시점의 상태를 나타낸다. 2026-09-10 값을 새 수치로 덮어쓰지 않고, 실험대에 워크로드가 추가되면서 실제 사용량이 달라진 결과로 별도 기록한다.
여전히 모르는 것은 2026-09-10의 `kc-lab-2 actual=3120MB`가 정확히 무엇 때문에 만들어졌는지다. 현재 남아 있는 증거만으로는 원인을 특정할 수 없으므로, 그 원인은 확인되지 않은 상태로 남긴다.
@@ -1,7 +1,7 @@
---
kind: CASE
slug: nftables-accept-did-not-stop-the-libvirt-reject
title: 호스트 안에서는 404, 밖에서는 connection refused — 앞 체인의 accept 가 libvirt 의 reject 를 막지 못했다
title: libvirt guest_input 체인의 reject로 외부 요청이 차단된 사례
topic: lab-environment-build
topicName: 실험대 환경 구성
project: virtualization
@@ -16,9 +16,9 @@ source:
- final/document.md#178-이-부의-출처와-범위
---
# 호스트 안에서는 404, 밖에서는 connection refused — 앞 체인의 accept 가 libvirt 의 reject 를 막지 못했다
# libvirt guest_input 체인의 reject로 외부 요청이 차단된 사례
밖에서 온 요청은 먼저 돌게 해 둔 forward 체인의 accept 를 지나고도 libvirt 의 guest_input 체인 끝 reject 에서 끊겼다. nftables 가 같은 훅에 붙은 base 체인을 우선순위 순으로 전부 평가하기 때문이다. 그래서 구멍을 libvirt 체인 맨 앞에 넣었다.
외부 요청은 먼저 실행되는 forward 체인에서 accept 되었지만, 이후 libvirt의 `guest_input` 체인 끝에 있는 reject 규칙에서 다시 거절됐다. 같은 hook에 연결된 base chain이 우선순위에 따라 계속 평가되기 때문이다. 외부에서 Edge VM의 80·443 포트로 들어오는 새 연결은 `guest_input` 체인 앞쪽에서 허용하도록 예외 규칙을 추가했다.
## host에서는 되는데 외부 요청만 즉시 거절됐다
@@ -31,11 +31,11 @@ source:
## 앞 체인의 accept 뒤에서 libvirt reject가 다시 평가됐다
밖에서 온 패킷을 거절한 것은 libvirt 가 만든 규칙이다. libvirt 는 자기 테이블 ip libvirt_network 의 guest_input 체인을 ct state established,related accept 다음의 reject 로 끝낸다. 그 reject 규칙의 카운터가 4 패킷 240 바이트로 밖에서 친 curl 횟수와 정확히 일치해서 범인을 확정했다.
밖에서 온 패킷을 거절한 것은 libvirt 가 만든 규칙이다. libvirt 는 자기 테이블 ip libvirt_network 의 guest_input 체인을 ct state established,related accept 다음의 reject 로 끝낸다. 그 reject 규칙의 카운터가 4 packets / 240 bytes였고, 외부에서 실행한 `curl` 횟수와 일치해 실제로 이 규칙이 요청을 거절하고 있음을 확인했다.
DNAT 를 정의한 파일에는 priority filter - 10 을 줘서 먼저 돌게 한 forward 체인이 있는데, 거기 넣은 ct state new accept 가 그 reject 를 막지 못한다. nftables 가 같은 훅에 붙은 base 체인을 우선순위 순으로 전부 평가하기 때문이다. 앞 체인의 accept 는 그 체인을 통과했다는 뜻이지 평가가 끝났다는 뜻이 아니고, 즉시 종결하는 것은 drop 뿐이다.
해결 자체는 구멍을 libvirt 체인 맨 앞에 넣는 것이다. `insert` 가 맨 앞이고 `add` 가 맨 뒤다.
외부에서 Edge VM의 80·443 포트로 들어오는 새 연결을 허용하는 규칙을 `guest_input` 체인 앞쪽에 추가했다. 이때 `insert`는 체인 앞쪽에, `add`는 뒤쪽에 규칙을 추가하므로 순서가 중요했다.
수명은 별도 문제다. libvirt 가 `guest_input` 을 다시 쓰면 이 규칙은 휘발된다. 예전에는 DNAT 유닛의 `ExecStartPost` 에 넣어 두면 충분하다고 보았지만, 2026-09-21 worker VM 재구축에서 그 가정이 깨졌다. libvirt 가 체인을 다시 만든 뒤 기존 accept 규칙 셋이 `reject` 뒤로 밀렸고, 유닛은 계속 `active` 인데 외부 80/443 두 요청이 둘 다 실패했다. 따라서 `ExecStartPost` 한 번은 재작성 이후 복구 장치가 아니다.
## nftables 백엔드인 test-server
@@ -46,7 +46,7 @@ RAM : 11,648MiB
QEMU : 11.1.1
libvirt : 12.7.0
libvirt firewall_backend : nftables
호스트 이더넷 : 없다 — WiFi 만 있다
호스트 유선 이더넷 : 없음, WiFi 사용
게스트 네트워크 : libvirt NAT, virbr0
게스트 : Debian 12 genericcloud 3대 — 엣지 1대(nginx·certbot), k3s 2노드
엣지 게스트 주소 : 192.168.122.10
@@ -57,7 +57,7 @@ libvirt firewall_backend : nftables
2. 호스트에서 curl http://192.168.122.10 을 친다. 엣지 nginx 가 404 로 응답한다.
3. 밖에서 curl http://100.83.212.4 를 친다. connection refused 가 온다.
4. libvirt 테이블 ip libvirt_network 의 guest_input 체인을 규칙과 카운터까지 덤프한다. 마지막 reject 규칙의 패킷 수가 3번을 친 횟수와 맞으면 그 규칙이 그 패킷을 끝냈다.
5. guest_input 맨 앞에 구멍을 넣고 3번을 다시 친다.
5. `guest_input` 앞쪽에 Edge VM 80·443 허용 규칙을 추가하고 3번을 다시 실행한다.
<!-- body:start -->
@@ -73,18 +73,18 @@ libvirt firewall_backend : nftables
L7 홉 수는 전후 모두 2홉이고 늘어난 것은 커널이 하는 L4 전달 한 번이다. 하지만 2026-09-21 실제 packet capture에서는 Tailscale MASQUERADE 때문에 edge에 도착하기 전에 source가 `192.168.122.1`로 바뀌었다. 따라서 **L7 홉 수가 같다는 이유만으로 `X-Forwarded-*` 계약이 그대로라고 볼 수는 없다.** 옮긴 이유는 성능이 아니라 nginx·인증서·certbot·deploy hook 같은 변경이 잦은 층을 물리 호스트에서 분리하는 것이었다.
그 대가로 일곱 가지가 새로 필요해졌는데 그중 둘은 배포판 차이가 아니라 패킷이 지나는 길이 달라져서 생겼다. 하나는 DNAT(Destination NAT) 다. 들어온 패킷의 도착지 주소를 바꿔 다른 기계로 넘기는 것을 말한다. 전에는 호스트가 직접 `:443` 을 들었으니 넘길 일이 없었는데 지금은 호스트에 리스너가 아예 없다. 다른 하나는 libvirt 방화벽에 구멍을 내는 일이다. 호스트가 게스트에 접속할 때는 OUTPUT 경로라 필터를 안 탔지만, 밖에서 게스트로 들어오는 것은 FORWARD 다. 「호스트가 게스트에 접속한다」와 「밖에서 게스트로 들어온다」는 커널이 보기에 완전히 다른 일이다. 그 구멍을 뚫는 데서 이 구축이 가장 오래 막혔다.
그 대가로 일곱 가지가 새로 필요해졌는데 그중 둘은 배포판 차이가 아니라 패킷이 지나는 길이 달라져서 생겼다. 하나는 DNAT(Destination NAT) 다. 들어온 패킷의 도착지 주소를 바꿔 다른 기계로 넘기는 것을 말한다. 전에는 호스트가 직접 `:443` 을 들었으니 넘길 일이 없었는데 지금은 호스트에 리스너가 아예 없다. 다른 하나는 libvirt의 `guest_input` 체인에 Edge VM으로 가는 새 연결을 허용하는 규칙을 추가하는 일이다. 호스트가 게스트에 접속할 때는 OUTPUT 경로라 필터를 안 탔지만, 밖에서 게스트로 들어오는 것은 FORWARD 다. 「호스트가 게스트에 접속한다」와 「밖에서 게스트로 들어온다」는 커널이 보기에 완전히 다른 일이다. 외부 요청이 어느 방화벽 규칙에서 거절되는지 확인하는 데 가장 많은 시간이 들었다.
## 호스트 안에서는 되는데 밖에서만 안 된다
엣지 nginx 는 호스트에서 친 요청에 404 를 돌려줬으니 게스트 안에서 살아 있었는데, 밖에서 친 요청만 끊겼다.
호스트에서 Edge VM으로 직접 보낸 요청은 nginx의 404 응답을 받았지만, 외부에서 tailnet 주소로 보낸 요청은 `connection refused`로 끝났다.
| 어디서 쳤나 | 결과 |
|---|---|
| 호스트에서 `curl http://192.168.122.10` | 404, 엣지 nginx 가 응답 |
| 밖에서 `curl http://100.83.212.4` | connection refused |
패킷을 조용히 버리는 `drop` 이면 클라이언트가 응답을 기다리다 죽으므로, 타임아웃이 아니라 즉시 거절이 돌아왔다는 것이 단서였다.
`drop` 규칙에 걸렸다면 응답 없이 대기하다 타임아웃이 발생했을 가능성이 높다. 여기서는 즉시 `connection refused`가 반환됐기 때문에 reject 계열 규칙을 먼저 확인했다.
## guest_input 체인 끝의 reject 와 카운터 4 패킷
@@ -92,28 +92,28 @@ libvirt 는 자기 테이블 `ip libvirt_network` 안에 `guest_input` 체인을
```text label="libvirt 가 만든 guest_input 체인의 끝"
oif "virbr0" ip daddr 192.168.122.0/24 ct state established,related accept
oif "virbr0" counter packets 4 bytes 240 reject ← 여기서 죽는다
oif "virbr0" counter packets 4 bytes 240 reject ← 외부 요청이 이 규칙에서 거절됐다
```
규칙 하나를 지목해 놓고 시작한 것이 아니다. `nft list ruleset` 에서 `reject` 와 `drop` 이 든 줄만 뽑아 놓고, 밖에서 친 횟수와 카운터가 맞아떨어지는 줄을 찾았다. 이 `reject` 규칙의 카운터가 4 패킷 240 바이트였고, 밖에서 친 `curl` 횟수와 정확히 일치했다. 범인 확정에 쓴 것이 이 숫자다.
규칙 하나를 지목해 놓고 시작한 것이 아니다. `nft list ruleset` 에서 `reject` 와 `drop` 이 든 줄만 뽑아 놓고, 밖에서 친 횟수와 카운터가 맞아떨어지는 줄을 찾았다. 이 `reject` 규칙의 카운터가 4 패킷 240 바이트였고, 밖에서 친 `curl` 횟수와 정확히 일치했다. 이 카운터 값으로 해당 reject 규칙이 외부 요청을 처리했다는 것을 확인했다.
## 왜 앞 체인의 accept 가 안 먹혔나
## 앞선 base chain의 accept만으로 요청이 끝나지 않은 이유
DNAT 를 정의한 파일에는 libvirt 체인보다 먼저 돌도록 `priority filter - 10` 을 준 `forward` 체인을 두고 거기에 `ct state new accept` 를 넣어 두었다. 밖에서 온 패킷은 그 `accept` 를 지나고도 거절됐는데, nftables 가 같은 훅에 붙은 base 체인을 우선순위 순으로 전부 평가하기 때문이다. 앞 체인의 `accept` 는 「이 체인은 통과」라는 뜻이지 「평가 끝」이 아니고, 즉시 종결하는 것은 `drop` 뿐이다. iptables 감각으로 쓰면 정확히 여기서 틀린다.
DNAT 를 정의한 파일에는 libvirt 체인보다 먼저 돌도록 `priority filter - 10` 을 준 `forward` 체인을 두고 거기에 `ct state new accept` 를 넣어 두었다. 밖에서 온 패킷은 그 `accept` 를 지나고도 거절됐는데, nftables 가 같은 훅에 붙은 base 체인을 우선순위 순으로 전부 평가하기 때문이다. 앞선 base chain에서 `accept` verdict가 나와도 이후 우선순위의 base chain이 계속 평가될 수 있다. 반면 `drop` verdict는 이후 체인 평가를 중단한다. 따라서 앞쪽 체인에 accept 규칙을 추가한 것만으로는 libvirt의 뒤쪽 reject를 피할 수 없었다.
그 `forward` 체인은 지금 DNAT 파일에 없다. 남은 체인은 `prerouting` 하나이고, 체인을 그냥 지우는 대신 주석 하나를 남겨 두었다 — 여기에 `forward` 체인을 두지 않은 것이 의도이며 구멍은 유닛의 `ExecStartPost` 가 libvirt 자기 체인 안에 넣는다는 내용이다.
현재 DNAT 파일에는 해당 `forward` 체인을 두지 않고 `prerouting` 체인만 남겼다. 외부 연결 허용 규칙은 DNAT 파일의 별도 base chain이 아니라 libvirt의 `guest_input` 체인에 추가하도록 구성했다.
![밖에서 온 패킷 하나가 forward 훅에 붙은 base 체인 둘을 우선순위 순으로 지나는 경로도. 왼쪽 점선 상자가 priority filter - 10 인 forward 체인이고 그 안에 ct state new accept 가 있다. 오른쪽 점선 상자가 ip libvirt_network 의 guest_input 체인이고 그 안에 맨 앞의 inserted accept 와 맨 끝의 reject 두 상자가 있다. 점선 화살표는 구멍을 넣기 전의 경로로 체인 끝 reject 를 지나 connection refused 로 끝나고, 실선 화살표는 넣은 뒤의 경로로 맨 앞의 구멍을 지나 엣지 nginx 로 간다.](../../../final/assets/diagrams/nftables-forward-hook-chain-order/nftables-forward-hook-chain-order.svg)
![밖에서 온 패킷 하나가 forward 훅에 붙은 base 체인 둘을 우선순위 순으로 지나는 경로도. 왼쪽 점선 상자가 priority filter - 10 인 forward 체인이고 그 안에 ct state new accept 가 있다. 오른쪽 점선 상자가 ip libvirt_network 의 guest_input 체인이고 그 안에 맨 앞의 inserted accept 와 맨 끝의 reject 두 상자가 있다. 점선 화살표는 허용 규칙을 추가하기 전의 경로로 체인 끝 reject를 지나 connection refused로 끝나고, 실선 화살표는 허용 규칙을 추가한 뒤 Edge Nginx로 전달되는 경로다.](../../../final/assets/diagrams/nftables-forward-hook-chain-order/nftables-forward-hook-chain-order.svg)
점선 상자 두 개가 같은 훅에 붙은 base 체인 둘이고, 왼쪽이 먼저 돈다. 점선 화살표는 구멍을 넣기 전의 경로다 — 앞 체인의 `accept` 를 지난 패킷이 `guest_input` 으로 이어지고, 위 덤프에 적힌 `ct state established,related accept` 에 걸리지 못한 채 체인 끝 `reject` 에 닿아 connection refused 로 끝난다.
점선 상자 두 개가 같은 훅에 붙은 base 체인 둘이고, 왼쪽이 먼저 돈다. 점선 화살표는 허용 규칙을 추가하기 전의 경로다 — 앞 체인의 `accept` 를 지난 패킷이 `guest_input` 으로 이어지고, 위 덤프에 적힌 `ct state established,related accept` 에 걸리지 못한 채 체인 끝 `reject` 에 닿아 connection refused 로 끝난다.
실선 화살표는 다음 절에서 뚫을 구멍을 지나는 경로다. `guest_input` 상자 안에 놓인 두 규칙의 위아래가 체인 안의 순서이고, 구멍이 위에 있어서 같은 패킷이 아래의 `reject` 를 보기 전에 그 규칙에서 `accept` 된다.
실선 화살표는 `guest_input` 앞쪽에 추가한 허용 규칙을 지나는 경로다. `guest_input` 상자 안에 놓인 두 규칙의 위아래가 체인 안의 순서이고, 허용 규칙이 reject보다 앞에 있기 때문에 같은 패킷은 reject에 도달하기 전에 accept된다.
## 구멍은 맨 앞에 넣고, 네트워크를 다시 세울 때 다시 넣는다
## 허용 규칙은 reject보다 앞에 있어야 한다
그래서 구멍을 libvirt 체인 맨 앞에 뚫었다. `insert` 가 맨 앞이고 `add` 가 맨 뒤다.
그래서 Edge VM의 80·443 포트로 들어오는 새 연결을 허용하는 규칙을 `guest_input`의 reject보다 앞에 추가했다.
```bash label="guest_input 맨 앞에 구멍을 넣는다"
```bash label="guest_input 앞쪽에 Edge VM 80·443 허용 규칙을 추가한다"
nft insert rule ip libvirt_network guest_input \
oif virbr0 ip daddr 192.168.122.10 tcp dport '{80,443}' ct state new counter accept
```
@@ -122,13 +122,13 @@ nft insert rule ip libvirt_network guest_input \
worker VM 둘을 철거했다 다시 만드는 동안 libvirt 가 `guest_input` 체인을 다시 구성했고, 이미 세 번 누적된 accept 규칙은 모두 `reject` **뒤**에 남았다. 그 상태에서 외부 80·443 연결 두 번이 모두 실패했고 `reject` 카운터가 `0 → 2` 로 증가했다. `lab-edge-dnat.service` 는 여전히 `active` 였다.
즉 `ExecStartPost` 는 **그 유닛이 시작될 때 한 번** 실행될 뿐, 이후 libvirt 가 자기 체인을 다시 쓰는 사건에는 반응하지 않는다. `-` 접두어도 실패를 무시할 뿐 재삽입을 예약하지 않는다. 현재 방식은 persistence 해결책으로는 실패한 상태다.
즉 `ExecStartPost` 는 **그 유닛이 시작될 때 한 번** 실행될 뿐, 이후 libvirt 가 자기 체인을 다시 쓰는 사건에는 반응하지 않는다. `-` 접두어도 실패를 무시할 뿐 재삽입을 예약하지 않는다. 따라서 `ExecStartPost`에서 한 번 규칙을 넣는 방식만으로는 libvirt가 체인을 다시 작성하는 상황을 처리할 수 없었다.
이번 재검증에서는 기존 host firewall/nftables rule을 임의 변경하지 않는 안전 조건 때문에 대체 persistence 방식까지 적용하지 않았다. 따라서 “어떤 이벤트에 묶어 어떻게 idempotent하게 재삽입할 것인가”는 아직 실제로 확인하지 못했다.
이번 재검증에서는 기존 host firewall/nftables rule을 임의 변경하지 않는 안전 조건 때문에 대체 persistence 방식까지 적용하지 않았다. libvirt가 체인을 다시 작성한 뒤 규칙을 어떤 방식으로 다시 적용할지는 아직 실제 환경에서 검증하지 못했다.
## 아직 다른 환경에서는 확인하지 못했다
이 호스트 한 대에서만 봤다. libvirt 의 `firewall_backend` 가 iptables 인 호스트에서도 같은 구멍이 필요한지는 재지 않았고, 이 호스트는 nftables 백엔드다.
이 호스트 한 대에서만 봤다. libvirt 의 `firewall_backend` 가 iptables 인 호스트에서도 같은 예외 규칙이 필요한지는 재지 않았고, 이 호스트는 nftables 백엔드다.
카운터 4 패킷 240 바이트는 당시 본문에 옮긴 규칙 덤프에 찍힌 값이다. 그때의 전체 ruleset과 `curl` 원문은 별도 raw 파일로 남기지 않았다. 2026-09-21에는 같은 nftables backend에서 `reject` 카운터 증가와 외부 실패를 다시 확인했으므로 현재 동작은 후속 증거가 있지만, 과거 숫자 `4 packets / 240 bytes` 자체는 당시 기록 범위로 읽는다.
@@ -1,7 +1,7 @@
---
kind: CONCEPT
slug: a-cloud-image-is-an-installed-disk-and-cloud-init-fills-the-blanks
title: 설치를 안 했는데 왜 뜨는가 — 클라우드 이미지는 설치가 끝난 디스크이고 cloud-init 이 빈칸을 채운다
title: 클라우드 이미지와 cloud-init은 각각 무엇을 준비하는가
topic: lab-environment-build
topicName: 실험대 환경 구성
project: virtualization
@@ -18,9 +18,9 @@ source:
- final/document.md#217-부팅할-때-일어나는-일
---
# 설치를 안 했는데 왜 뜨는가 — 클라우드 이미지는 설치가 끝난 디스크이고 cloud-init 이 빈칸을 채운다
# 클라우드 이미지와 cloud-init은 각각 무엇을 준비하는가
클라우드 이미지는 배포자가 설치를 한 번 끝내 놓은 디스크 파일이라 게스트를 만들 때 설치 단계가 없다. 대신 hostname 과 SSH 호스트키 같은 고유값을 비워 둔 채 배포하고, cloud-init 이 첫 부팅에 그 빈칸을 채운다.
클라우드 이미지는 운영체제가 미리 설치된 디스크 이미지다. 게스트를 만들 때 운영체제 설치 과정을 다시 거치지 않고, 호스트명·사용자·SSH 키처럼 인스턴스마다 달라지는 값은 cloud-init이 첫 부팅 때 적용한다.
<!-- body:start -->
@@ -43,7 +43,7 @@ VM 의 디스크는 호스트의 파일 하나다. `kc-lab-1.qcow2` 라는 파
"부팅 가능한 특정 바이트 배열" 상태의 디스크
```
설치 과정은 수단이고 목적은 마지막 줄의 상태이며, 그 상태는 파일 하나의 내용으로 남는다. Debian 과 Ubuntu 는 자기 빌드 서버에서 이 설치를 한 번 수행하고 완성된 디스크를 qcow2 파일로 떠서 공개한다. 이 실험대에서는 그 파일을 내려받아 게스트 디스크의 바닥 이미지로 사용한다. 소스를 직접 컴파일하는 대신 이미 빌드된 바이너리를 받아 쓰는 것과 같아서, 결과물은 같고 시간만 아낀다.
설치 과정은 수단이고 목적은 마지막 줄의 상태이며, 그 상태는 파일 하나의 내용으로 남는다. Debian 과 Ubuntu 는 자기 빌드 서버에서 이 설치를 한 번 수행하고 완성된 디스크를 qcow2 파일로 떠서 공개한다. 이 실험대에서는 그 파일을 내려받아 게스트 디스크의 base image로 사용한다. 소스를 직접 컴파일하는 대신 이미 빌드된 바이너리를 받아 쓰는 것과 같아서, 결과물은 같고 시간만 아낀다.
## 그대로 복제하면 식별자가 겹치므로 일부러 비워 둔다
@@ -66,7 +66,7 @@ VM 의 디스크는 호스트의 파일 하나다. `kc-lab-1.qcow2` 라는 파
| SSH 호스트 키 | 없음 — 첫 부팅에 새로 생성 |
| machine-id | 비어 있음 |
cloud-init 이 이 빈칸을 첫 부팅에 채우는 장치다. `user-data` 라는 YAML 을 읽어 계정을 만들고 SSH 키를 등록하고 패키지를 깔고 임의의 스크립트를 실행한다.
cloud-init은 인스턴스마다 달라지는 설정을 첫 부팅에 적용한다. `user-data` 라는 YAML 을 읽어 계정을 만들고 SSH 키를 등록하고 패키지를 깔고 임의의 스크립트를 실행한다.
```text label="설치와 개인화를 누가 언제 하나"
전통적 설치 : [설치 + 개인화]를 부팅 전에 대화형으로 수행
@@ -86,19 +86,19 @@ cloud-init 이 이 빈칸을 첫 부팅에 채우는 장치다. `user-data` 라
|---|---|---|
| ISO로 정식 설치 | VM마다 대화형 설치 | 매번 처음부터 반복 |
| 이미지를 미리 개조 (`virt-customize`, `guestfish`) | libguestfs 설치 + 이미지 마운트 | 개조본을 따로 관리해야 함 |
| cloud-init | YAML 한 장 | 명령 한 줄 |
| cloud-init | YAML 설정 파일 | 명령 한 줄 |
이 실험대는 `virsh destroy` 와 오버레이 삭제로 게스트를 반복해서 지우고 다시 만드는 것이 실험 그 자체다. 재생성 비용이 낮아야 실험이 굴러간다. 두 노드가 바이트 단위로 같은 초기 상태로 만들어져야 한다는 조건도 붙는다. 손으로 설치하면 미묘하게 달라지고 그 차이가 실험 결과를 오염시킨다.
이 실험대는 `virsh destroy` 와 오버레이 삭제로 게스트를 반복해서 지우고 다시 만드는 것이 실험 그 자체다. 재생성 비용이 낮아야 실험이 굴러간다. 두 노드가 바이트 단위로 같은 초기 상태로 만들어져야 한다는 조건도 붙는다. 게스트마다 수동으로 설치하면 설정 차이가 생길 수 있어 두 노드의 조건을 동일하게 맞추기 어려워진다.
이미지 종류도 그 축에서 고른다. Debian 은 같은 판을 여러 변종으로 배포한다.
| Debian 변종 | 어디에 쓰나 |
|---|---|
| `genericcloud` | 가상화 환경 전용. virtio 드라이버만 담아 가볍다 → KVM에는 이걸 |
| `generic` | 베어메탈 포함. 드라이버가 많아 더 크다 |
| `nocloud` | cloud-init 없이 기본 계정이 박혀 있는 변종 |
| `genericcloud` | 이 실험대에서 사용한 Debian 12 클라우드 이미지 변종 |
| `generic` | Debian이 별도로 제공하는 다른 cloud image 변종. 이 실험대에서는 사용하지 않음 |
| `nocloud` | Debian이 별도로 제공하는 변종. 이 실험대에서는 사용하지 않음 |
`genericcloud` 가 가벼운 까닭은 물리 하드웨어 드라이버를 뺐다는 데 있고, 시드를 SATA CD-ROM 으로 붙이면 게스트가 그 장치를 보지 못하는 함정도 같은 이유로 생긴다. `virt-install --cloud-init` 은 시드를 `<target dev='sda' bus='sata'/>`, 즉 SATA CD-ROM 으로 붙인다. 그래서 이 조합에서는 게스트가 시드를 아예 장치로 보지 못한다. 「확정된 함정: `--cloud-init` + Debian `genericcloud` 조합은 동작하지 않는다」에서는 성공 판정을 `virsh domblklist` 의 장치 이름으로 잡아 둔 까닭이 여기 있다 — 시드가 `vdb` 로 보여야 하고, `sda` 로 보이면 게스트가 읽지 못한다.
이 실험대에서는 `virt-install --cloud-init`으로 만든 시드 연결에서 기대한 NoCloud 데이터소스를 확인하지 못했다. 이후 seed ISO를 `bus=virtio` 디스크로 연결했고, 정상 부팅한 게스트의 `cloud-init status --long`에서 `DataSourceNoCloud [seed=/dev/vdb]`를 확인했다. 따라서 현재 구성은 실제로 확인한 virtio seed 경로를 사용한다. `--cloud-init` 경로가 동작하지 않았던 원인을 Debian genericcloud의 특정 드라이버 부재로 단정할 증거는 남아 있지 않다.
## 게스트에게 디스크는 두 장이고, 시드는 OS 가 아니다
@@ -109,7 +109,7 @@ cloud-init 이 이 빈칸을 첫 부팅에 채우는 장치다. `user-data` 라
| `vda` | 20G | ext4 루트. 여기서 부팅한다 |
| `vdb` | 370K | `LABEL=CIDATA` 인 iso9660. 읽기 전용이고 마운트되지 않는다 |
`vda` 는 `base.qcow2` 위의 오버레이라 바닥 한 벌을 두 게스트가 공유하고 각자 변경분만 쌓는다. `vdb` 는 원본 YAML 을 구워 만든 ISO 를 풀에 올린 것이다.
`vda`는 공통 `base.qcow2`를 backing image로 사용하는 오버레이라 두 게스트가 같은 초기 이미지를 공유하고 각자 변경분만 저장한다. `vdb` 는 원본 YAML 을 구워 만든 ISO 를 풀에 올린 것이다.
```text label="같은 설정이 존재하는 세 곳"
kc-lab-1.yaml ──①──▶ seed-kc-lab-1.iso ──②③──▶ /var/lib/libvirt/images/seed-kc-lab-1.iso
@@ -119,7 +119,7 @@ kc-lab-1.yaml ──①──▶ seed-kc-lab-1.iso ──②③──▶ /va
같은 내용이 세 곳에 있어서 원본만 고치면 VM 에 반영되지 않는다. 셋을 한 번에 맞추는 것이 `deploy/lab/scripts/rebuild-seed.sh` 다.
## 부팅 다섯 단계 가운데 3번이 실패하면 조용히 끝난다
## cloud-init이 실패해도 VM 자체는 실행 중일 수 있다
```text label="첫 부팅에 일어나는 다섯 단계"
1. QEMU 가 vda 에서 부팅 → Debian 커널 시작
@@ -129,9 +129,9 @@ kc-lab-1.yaml ──①──▶ seed-kc-lab-1.iso ──②③──▶ /va
5. 언마운트 → SSH 로그인 가능
```
cloud-init 은 `cidata` 레이블을 가진 블록 장치를 찾지 못하면 데이터소스 없이 종료하기 때문에, 3번이 실패하면 hostname 이 `localhost` 로 남고 사용자가 생성되지 않는다. 오류 메시지는 어디에도 남지 않는다. `virsh screenshot` 으로 로그인 프롬프트만 봐도 즉시 판정할 수 있다.
NoCloud 시드를 읽지 못하면 `user-data`에 넣은 hostname·사용자·SSH 키 설정도 기대한 상태로 적용되지 않을 수 있다. 이 실험대에서는 `localhost` 호스트명과 SSH 인증 실패가 먼저 보였지만, 원인에 따라 cloud-init 로그와 상태 출력이 달라질 수 있으므로 로그가 남지 않는다고 일반화하지 않는다. SSH가 되지 않으면 `virsh screenshot`으로 콘솔의 호스트명을 확인하고, 가능하면 `cloud-init status --long`과 로그를 함께 확인한다.
`user-data` 파일은 `#cloud-config` 로 시작해야 한다. 이 첫 줄이 없으면 cloud-init 이 YAML 로 인식하지 못하고 무시하며, 증상은 「부팅은 됐는데 계정이 없다」로 나타난다.
이 절차의 `user-data`는 `#cloud-config`로 시작하는 cloud-config 형식을 사용한다. 헤더와 YAML 문법, cloud-init 스키마를 각각 확인하고, 실제 적용 여부는 부팅한 게스트의 hostname·사용자·SSH 상태와 cloud-init 로그에서 다시 확인한다.
「클라우드 이미지와 cloud-init」에서는 비상 접근 수단을 남기라는 항목 하나를 「실제로 겪은 교훈」이라고 따로 적어 두었다. `ssh_pwauth: false` 에 키 인증만 걸어 둔 상태로 3번이 실패하면 사용자가 생성되지 않아 키도 비밀번호도 없고, 콘솔에 붙어도 로그인할 수 없다. 실패 원인을 적어 둔 `/var/log/cloud-init.log` 를 읽을 방법이 그래서 사라지고, VM 을 지우고 다시 만드는 것 말고 남는 선택지가 없어진다. 콘솔 로그인용 비밀번호를 하나 넣어 두면 그 골목을 피하는데, 콘솔 로그인은 sshd 를 거치지 않으므로 `ssh_pwauth: false` 는 그대로 둔다.
@@ -148,7 +148,7 @@ multipass 와 virt-install 과 virsh 는 서로 배포판이 다른 도구가
| 네트워크·DHCP 구성 | `virbr0` + DHCP 예약 |
| `multipass shell` 로 즉시 접속 | `~/.ssh/config` 별칭 작성 |
multipass 를 쓰지 않은 까닭은 배포판이 아니라 범위에 있다. multipass 는 Ubuntu 이미지만 공식 지원해서 Debian 게스트를 띄울 수 없다. 그리고 이 실험대는 `virsh destroy` 로 노드를 죽이고 NetworkPolicy 로 포트를 막고 스냅샷으로 되돌리는 저수준 제어가 실험의 본체라 관리 계층이 필요했다.
multipass 를 쓰지 않은 까닭은 배포판이 아니라 범위에 있다. multipass 는 Ubuntu 이미지만 공식 지원해서 Debian 게스트를 띄울 수 없다. 그리고 이 실험대는 `virsh destroy`로 VM을 중단하고 NetworkPolicy로 포트를 차단하며 스냅샷으로 되돌리는 저수준 제어가 필요했기 때문에 libvirt 기반 구성을 사용했다.
## 이 설명이 걸려 있는 판올림
@@ -1,7 +1,7 @@
---
kind: CONCEPT
slug: inside-a-qcow2-file-the-mapping-table-and-its-clusters
title: qcow2 파일 안 — 매핑표와 클러스터, 그리고 항목이 0 이면 바닥에 다시 묻는다
title: qcow2의 매핑 테이블과 데이터 클러스터
topic: lab-environment-build
topicName: 실험대 환경 구성
project: virtualization
@@ -20,9 +20,9 @@ source:
- final/document.md#234-그래서-마이그레이션과-스냅샷이-된다
---
# qcow2 파일 안 — 매핑표와 클러스터, 그리고 항목이 0 이면 바닥에 다시 묻는다
# qcow2의 매핑 테이블과 데이터 클러스터
qcow2 는 raw 에 매핑표 하나를 더한 것이고, 표가 가리키는 값은 호스트 주소가 아니라 파일 안의 몇 번째 바이트다. 매핑 항목이 0 이면 바닥 파일의 같은 위치를 읽는다. 오버레이와 스냅샷과 압축이 전부 그 규칙 위에서 돈다.
qcow2는 가상 디스크의 블록을 파일 안의 어느 위치에서 읽을지 매핑 테이블로 관리한다. 매핑 항목이 비어 있고 backing file이 설정돼 있으면 같은 게스트 오프셋을 backing file에서 읽는다. 오버레이와 스냅샷도 이 매핑을 이용한다.
<!-- body:start -->
@@ -53,11 +53,11 @@ qcow2 는 「가상 디스크의 이 위치가 파일 안의 어디에 있는가
그리고 표에 적히는 값은 호스트 물리 디스크의 주소가 아니라 파일 안의 몇 번째 바이트다. 그래서 파일을 다른 기계로 통째로 옮겨도 표가 그대로 유효하다. 파일 밖을 가리키는 것은 백킹 파일 경로 하나뿐이라 그것만 따로 챙긴다.
## 클러스터 — 매핑의 최소 단위
## 클러스터는 qcow2 매핑의 최소 단위다
섹터 512B 하나하나를 매핑하면 표가 너무 커지기 때문에 클러스터라는 덩어리 단위로 끊고, 그 기본값이 64KB 다.
```bash label="바닥 이미지의 포맷과 크기를 읽는다"
```bash label="backing image의 포맷과 크기를 읽는다"
qemu-img info /var/lib/libvirt/images/base.qcow2
```
@@ -81,9 +81,9 @@ cluster_size: 65536
다섯 층의 크기가 서로 달라도 상관없고, 각 층이 자기 위층을 자기 단위로 쪼개 담는다. FAT 과 NTFS 도 할당 단위를 클러스터라고 부르는데, 같은 낱말이고 다른 층이다.
## 2단계 매핑 — L1 에서 L2 로
## L1과 L2 테이블로 클러스터 위치를 찾는다
매핑표를 한 장으로 만들면 20GB 디스크 하나에 표만 수 MB 가 되고, 대부분이 비어 있는데도 항상 들고 있어야 한다. 그래서 두 단계로 나눈다.
가상 디스크 전체를 단일 매핑 테이블로 관리하면 비어 있는 영역까지 큰 테이블을 유지해야 한다. qcow2는 이를 L1과 L2 두 단계로 나눠 필요한 영역의 매핑만 사용한다.
```text label="게스트 오프셋이 세 조각으로 쓰인다"
게스트가 읽으려는 위치
@@ -105,19 +105,19 @@ cluster_size: 65536
운영체제의 페이지 테이블과 같은 구조다. 필요한 L2 표만 만들면 되므로 안 쓴 영역은 L1 항목이 0 인 채로 끝난다.
## 항목이 0 이면 바닥에 다시 묻는다
## 매핑이 없으면 backing file을 확인한다
오버레이가 성립하는 규칙이 여기 있다.
| L2 항목이 | 바닥 파일이 | 읽으면 무엇이 돌아오나 |
| L2 항목 | backing file | 읽기 결과 |
|---|---|---|
| 값이 있음 | (무관) | 이 파일의 그 위치를 읽는다 |
| 0 | 없음 | 0 으로 채운 64KB 를 만들어 돌려준다 |
| 0 | 있음 | 바닥 파일의 같은 위치를 읽는다 |
| 0 | 있음 | backing file의 같은 게스트 오프셋을 읽는다 |
그래서 `kc-lab-1.qcow2` 는 자기가 바꾼 클러스터만 들고 있고 나머지는 전부 `base.qcow2` 를 본다. 20GB 를 선언한 파일이 1.4GB 로 잡히는 까닭이 이 규칙에 있다.
바닥 경로는 헤더에 `backing_file_offset` 으로 자리를 잡고 문자열로 들어가서, 바닥을 옮기거나 이름을 바꾸면 게스트가 부팅하지 못한다. 오버레이만 다른 기계로 복사하면 안 되는 까닭도 여기 있고, 경로를 절대경로로 주는 것도 같은 이유다.
backing file 경로는 qcow2 헤더에 저장되므로 파일을 옮기거나 이름을 바꾸면 오버레이가 backing file을 찾지 못할 수 있다. 오버레이만 다른 기계로 복사하면 안 되는 까닭도 여기 있고, 경로를 절대경로로 주는 것도 같은 이유다.
헤더에는 매직값 `QFI\xfb`, 버전, `cluster_bits`, 가상 디스크 크기, `l1_table_offset`, `refcount_table_offset`, `backing_file_offset` 이 들어간다.
@@ -148,7 +148,7 @@ qemu-img map --output=json /var/lib/libvirt/images/base.qcow2
```text label="실측 — Debian 12 genericcloud"
{'start': 0, 'length': 65536, 'data': True, 'compressed': True} ← 압축된 클러스터
{'start': 65536, 'length': 983040, 'data': False, 'zero': True} ← 구멍
{'start': 65536, 'length': 983040, 'data': False, 'zero': True} ← 할당되지 않은 희소 영역
{'start': 1048576, 'length': 65536, 'data': True, 'compressed': True}
compressed 구간: 606개 / 전체 1236개
@@ -156,13 +156,13 @@ compressed 구간: 606개 / 전체 1236개
| 3 GiB 가 324 MiB 가 되는 이유 | 이 이미지에서 |
|---|---|
| ① 안 쓴 공간을 안 적음 (희소) | 3 GiB 중 2.01 GiB 가 구멍 |
| ① 사용하지 않은 영역은 블록을 할당하지 않음 | 3 GiB 중 2.01 GiB가 희소 영역 |
| ② 쓴 부분을 zlib 압축 | 남은 1010 MiB → 324 MiB |
| ③ genericcloud 자체가 작음 | GUI·문서·물리 하드웨어 드라이버 없음 |
| ③ 배포 이미지 자체의 내용 | 어떤 패키지와 파일이 들어 있는지에 따라 사용 블록 양이 달라짐 |
압축도 우리가 한 것이 아니라 Debian 이 배포 시점에 한 것이다. `qemu-img convert -c` 를 돌린 적이 없는데도 `compressed: True` 가 나온다.
압축 클러스터는 읽을 때 자동으로 풀린다. 게스트가 그 클러스터에 쓰면 압축하지 않은 형태로 새로 할당하므로, 오버레이에 쌓이는 것은 비압축 클러스터다. 바닥은 작은데 오버레이가 상대적으로 커 보이는 까닭 가운데 하나가 여기 있다.
압축 클러스터는 읽을 때 자동으로 풀린다. 게스트가 그 클러스터에 쓰면 압축하지 않은 형태로 새로 할당하므로, 오버레이에 쌓이는 것은 비압축 클러스터다. 배포된 base image와 실행 후 오버레이의 파일 크기가 크게 달라질 수 있는 이유 가운데 하나다.
압축 단위가 클러스터이므로 1바이트를 읽어도 그 클러스터 전체를 풀어야 한다. 그래서 쓰기가 잦은 디스크에는 압축을 걸지 않는다.
@@ -179,17 +179,17 @@ base.qcow2 ← k3s-golden.qcow2 ← kc-lab-1.qcow2
|---|---|---|
| 언제 쌓나 | 빌드 시점에 의도적으로 | 주로 런타임 파생 |
| 층의 정체성 | 레이어마다 다이제스트 | 경로 문자열 |
| 배포 단위 | 레이어 tar 여러 개 + 매니페스트 | 파일들 (바닥까지 전부 필요) |
| 배포 단위 | 레이어 tar 여러 개 + 매니페스트 | qcow2 파일과 필요한 backing file |
| 층이 깊어지면 | 읽기 성능 영향 적음 | 읽을 때마다 사슬을 거슬러 올라간다 |
체인이 깊으면 읽기가 느려진다. 클러스터가 어느 층에 있는지 찾으려면 L2 항목이 0 일 때마다 한 층 아래로 내려가기 때문이다. 실험대에서 층을 두세 겹 넘게 쌓지 않는 까닭이 여기 있다.
| 사슬을 끊는 명령 | 무엇을 하나 | 결과 |
|---|---|---|
| `qemu-img commit <오버레이>` | 오버레이의 변경분을 바닥에 병합 | 바닥이 바뀐다. 다른 오버레이가 있으면 그것들이 깨진다 |
| `qemu-img convert -O qcow2 <오버레이> <새파일>` | 사슬 전체를 읽어 단일 파일로 평탄화 | 바닥과 무관해진다. 용량은 늘어난다 |
| `qemu-img commit <오버레이>` | 오버레이 변경분을 backing file에 병합 | backing file 내용이 바뀌므로 이를 공유하는 다른 오버레이에도 영향을 줄 수 있다 |
| `qemu-img convert -O qcow2 <오버레이> <새파일>` | backing chain을 읽어 독립된 파일로 변환 | 원래 backing file이 없어도 사용할 수 있다. 파일 크기는 커질 수 있다 |
다른 기계로 게스트를 보낼 때 오버레이만 복사하면 바닥이 없어 부팅하지 못하므로, 옮길 때는 `convert` 로 평탄화해 파일 하나로 완결시킨다.
다른 기계로 오버레이만 복사하면 backing file을 찾지 못할 수 있으므로, backing chain을 함께 옮기거나 `qemu-img convert`로 독립된 이미지로 변환해야 한다.
## `qemu-img` 는 VM 을 돌리지 않는다
@@ -197,11 +197,11 @@ base.qcow2 ← k3s-golden.qcow2 ← kc-lab-1.qcow2
`virt-install --disk size=20,backing_store=...` 이 내부적으로 `qemu-img create` 를 부른다. 골든 이미지를 만들거나 오버레이만 초기화할 때 이 도구를 직접 쓴다.
포맷을 알아보는 것도 헤더의 매직값이다. `qemu-img info` 가 `file format: raw` 로 읽으면 그 파일은 qcow2 가 아니고, 바닥 이미지를 받다가 끊겨 HTML 오류 페이지를 저장했을 때 그렇게 나온다.
포맷을 알아보는 것도 헤더의 매직값이다. `qemu-img info` 가 `file format: raw` 로 읽으면 그 파일은 qcow2 가 아니고, base image 다운로드가 실패해 HTML 오류 페이지가 저장됐을 때도 이런 식으로 잘못된 포맷이 드러날 수 있다.
## 이 설명이 걸려 있는 것
실측은 배포본 `base.qcow2` 한 장에 대한 것이고 `qemu-img info` 와 `qemu-img map --output=json` 의 출력이 근거다. 오버레이 쪽 매핑을 같은 명령으로 떠 본 기록은 없다.
실측은 배포본 `base.qcow2` 파일 하나에 대한 것이고 `qemu-img info` 와 `qemu-img map --output=json` 의 출력이 근거다. 오버레이 쪽 매핑을 같은 명령으로 떠 본 기록은 없다.
비트 나누기는 `cluster_size` 65536 에서 따라 나오는 계산이라 다른 클러스터 크기로 만든 이미지에서는 숫자가 달라진다.
@@ -1,7 +1,7 @@
---
kind: CONCEPT
slug: what-a-qcow2-file-carries
title: qcow2 파일 한 장이 담는 것 — 매핑표와 데이터 클러스터가 같은 파일 안에 있고, 파일 밖을 가리키는 것은 백킹 파일 경로 하나다
title: qcow2 파일에는 무엇이 저장되는가
topic: lab-environment-build
topicName: 실험대 환경 구성
project: virtualization
@@ -13,16 +13,16 @@ source:
- final/document.md#178-이-부의-출처와-범위
---
# qcow2 파일 한 장이 담는 것 — 매핑표와 데이터 클러스터가 같은 파일 안에 있고, 파일 밖을 가리키는 것은 백킹 파일 경로 하나다
# qcow2 파일에는 무엇이 저장되는가
qcow2 한 장에는 데이터 클러스터와 그것이 파일의 어느 오프셋에 놓였는지 적은 매핑표가 들어 있다. 이 실험대의 오버레이에서 파일 밖으로 이어지는 핵심 의존성은 백킹 파일 경로다. 실행 중인 프로세스와 안 내려간 dirty page, vCPU·RAM·NIC 를 적어 둔 VM 정의 XML 은 없다. 오버레이의 virtual size가 20GiB인데 host allocation이 몇 GiB에 그치는 주된 이유는 아직 쓰지 않은 영역을 파일에 할당하지 않는 sparse allocation이다. 다만 qcow2 포맷 자체는 압축을 지원하고, 이 실험대의 Debian `base.qcow2`에는 실제 압축 클러스터도 있다.
qcow2 파일에는 데이터 클러스터와 각 클러스터가 파일의 어느 오프셋에 놓였는지 기록한 매핑 테이블이 들어 있다. 이 실험대의 오버레이가 파일 밖에서 필요로 하는 정보는 backing file 경로다. 실행 중인 프로세스와 안 내려간 dirty page, vCPU·RAM·NIC 를 적어 둔 VM 정의 XML 은 없다. 오버레이의 virtual size가 20GiB인데 host allocation이 몇 GiB에 그치는 주된 이유는 아직 쓰지 않은 영역을 파일에 할당하지 않는 sparse allocation이다. 다만 qcow2 포맷 자체는 압축을 지원하고, 이 실험대의 Debian `base.qcow2`에는 실제 압축 클러스터도 있다.
<!-- body:start -->
## 파일 한 장 안에 들어 있는 것
## qcow2 파일 안에 들어 있는 것
qcow2 는 가상 디스크 한 장의 블록을 담는 파일이다. 블록의 내용이 들어가는 데이터 클러스터와, 그 클러스터가 파일의 어느 오프셋에 놓였는지 적은 매핑표가 같은 파일 안에 함께 있다.
qcow2는 가상 디스크의 블록을 담는 파일이다. 블록의 내용이 들어가는 데이터 클러스터와, 그 클러스터가 파일의 어느 오프셋에 놓였는지 적은 매핑표가 같은 파일 안에 함께 있다.
매핑표에 적히는 값은 호스트의 물리 주소가 아니라 파일 안의 오프셋이어서, 파일을 다른 디렉터리로 옮기든 다른 호스트로 복사하든 표가 가리키는 곳은 달라지지 않는다. 파일을 통째로 옮기기만 하면 매핑은 그대로 유효하다.
@@ -74,6 +74,6 @@ qcow2 는 가상 디스크 한 장의 블록을 담는 파일이다. 블록의
매핑표가 파일 안에서 어떤 구조로 나뉘는지는 여기서 다루지 않는다. 이식 관점에서 필요한 것은 매핑표가 파일 내부 오프셋을 가리킨다는 데까지다. qcow2 내부 L1/L2 table, blk-mq tag allocator, NVMe submission/completion queue 같은 세부 구현은 이 경로를 더 깊게 볼 때 별도로 다룬다.
온프렘 이미지를 클라우드로 올리는 절차도 이 글 밖이다. 원본 문서가 그 부분을 코드 관측이 아닌 외부 지식이라고 스스로 표시해 두었고 이 실험대에서 한 번도 해 보지 않아서, 원본 문서에만 두고 이 기록으로 옮기지 않았다.
온프렘에서 만든 이미지를 클라우드로 옮기는 절차는 이 실험대에서 수행하지 않았다. 여기서는 로컬 libvirt에서 qcow2 이미지를 생성하고 사용하는 범위까지만 다룬다.
<!-- body:end -->
@@ -1,7 +1,7 @@
---
kind: PROJECT_DECISION
slug: dns-01-because-the-lab-is-not-on-the-public-internet
title: 인증서는 DNS-01 로 받는다 — 실험대 주소가 공개 인터넷에 없어 HTTP-01 이 성립하지 않는다
title: 공개 인터넷에 노출되지 않은 실험대에서 DNS-01을 선택한 이유
topic: lab-environment-build
topicName: 실험대 환경 구성
project: virtualization
@@ -13,19 +13,19 @@ source:
- final/document.md#184-이-부의-출처와-범위
---
# 인증서는 DNS-01 로 받는다 — 실험대 주소가 공개 인터넷에 없어 HTTP-01 이 성립하지 않는다
# 공개 인터넷에 노출되지 않은 실험대에서 DNS-01을 선택한 이유
인증서는 Let's Encrypt 의 DNS-01 로 받는다. HTTP-01 은 80 포트와 공개 A 레코드를 요구하는데 이 실험대의 주소는 공개 인터넷에 없고, certbot 이 DNS 공급자 API 로 나가는 DNS-01 만 성립한다. Cloudflare API 토큰이 엣지 VM 안 평문 파일에 놓이는 비용을 감수한다.
## 왜 HTTP-01이 성립하지 않았나
- **갱신은 매번 SUCCESS 였고 옛 인증서가 계속 나갔다 — 2305초와 1~2초**
이 결정으로 받은 인증서가 갱신 뒤에 실제로 서빙되는지는 이 결정 밖이고 그 기록이 받는다. 발급 방식을 정하는 것과 갱신된 것을 nginx 가 읽게 만드는 것은 다른 일이다.
- **엣지 nginx 를 호스트에서 게스트 VM 으로 옮긴다 — 성능이 아니라 더러워지는 층의 격리**
- **인증서 갱신 후 nginx가 기존 인증서를 계속 제공한 문제**
여기서는 인증서 발급 방식을 DNS-01로 정하는 것까지만 다룬다. 갱신된 인증서를 nginx가 다시 읽게 만드는 deploy hook과 reload는 별도의 운영 단계다.
- **Edge Nginx를 호스트에서 게스트 VM으로 분리한 이유**
그 결정이 새로 요구한 일곱 가지 가운데 7번이 certbot 과 인증서와 갱신 훅을 게스트로 옮기는 것이었다. 이 결정이 세우는 것을 전부 엣지 게스트에 두는 이유가 거기서 왔다.
- **도구가 낸 출력은 대상의 상태가 아니다 — 그 명령이 무엇을 세는지부터 가른다**
- **명령 출력이 실제 상태를 의미하는지 먼저 확인한다**
체인이 이어졌는지를 openssl s_client 의 단계 수로 판정하는 근거다. cert.pem 을 써서 체인이 끊겨도 브라우저는 캐시나 AIA 로 보완해 정상으로 보인다.
- **가까운 층부터 한 층씩 건너뛰며 확인한다 — 층마다 성공 신호가 다르다**
- **장애를 확인할 때는 가까운 계층부터 확인한다**
04 단계의 확인을 어느 기계에서 치는지가 그 기준에 걸려 있다. 엣지 게스트 안에서 치면 층의 답이 아니라 친 위치의 답이 돌아온다.
- **단계별 구축 문서는 작성 시점이 아니라 실행 순서로 검증한다**
이 결정이 남긴 이름 규칙을 가이드가 틀리게 적었고, 「이 구축에서 드러난 문서 결함의 공통 원인」에서는 그것을 결함 여섯 중 하나로 셌다. 결함 여섯을 나란히 적은 표는 그 기록에 있다.
@@ -40,7 +40,7 @@ certbot 과 인증서와 갱신 타이머와 deploy 훅은 전부 엣지 게스
두 방식은 검증이 오가는 방향이 반대다. HTTP-01 은 Let's Encrypt 가 우리 서버로 들어오는 인바운드 검증이라 80 포트와 공개 A 레코드가 있어야 한다. DNS-01 은 certbot 이 DNS 공급자 API 로 나가는 아웃바운드 검증이라 공개 인터넷에서 보일 필요가 없다. 이 실험대의 주소는 공개 인터넷에 없으므로 HTTP-01 은 성립하지 않는다.
「단계 04 — Let's Encrypt 와 인증서 갱신」에서는 이 선택을 우열로 적지 않는다. 공개 서버라면 HTTP-01 이 맞고, 토큰도 DNS 연동도 없어 관리할 것이 적다고 대안 쪽을 먼저 적는다. 이 결정은 더 나은 방식을 고른 것이 아니라 하나만 성립하는 조건에서 그것을 쓴 것이다. 딸려 온 이득이 하나 있는데, DNS-01 은 와일드카드를 받을 수 있어 hyeonworks.com 아래의 이름을 인증서 한 장으로 덮는다. 그 이득은 뒤늦게 챙겼다. 이 실험대는 처음에 와일드카드를 안 쓰고 이름마다 따로 받았고, 네 번째 이름이 없어 다른 실험에서 app2 를 빌려 써야 했다.
「단계 04 — Let's Encrypt 와 인증서 갱신」에서는 이 선택을 우열로 적지 않는다. 공개 서버라면 HTTP-01 이 맞고, 토큰도 DNS 연동도 없어 관리할 것이 적다고 대안 쪽을 먼저 적는다. 이 결정은 더 나은 방식을 고른 것이 아니라 하나만 성립하는 조건에서 그것을 쓴 것이다. 딸려 온 이득이 하나 있는데, DNS-01은 와일드카드 인증서를 발급할 수 있기 때문에 hyeonworks.com 아래의 여러 이름을 하나의 인증서로 처리할 수 있었다. 다만 이것은 DNS-01을 선택한 주된 이유가 아니라 함께 얻은 결과다. 이 실험대는 처음에 와일드카드를 안 쓰고 이름마다 따로 받았고, 네 번째 이름이 없어 다른 실험에서 app2 를 빌려 써야 했다.
정한 대로 현재 엣지 게스트에는 `certbot`과 `python3-certbot-dns-cloudflare`가 설치돼 있고 renewal 설정의 authenticator는 `dns-cloudflare`다. 자격증명 파일은 600 권한으로 두며, 2026-09-21에는 파일 크기 81 bytes 상태에서 `certbot renew --dry-run --no-random-sleep-on-renew`가 DNS 전파 대기 뒤 성공했다. 외부 TLS 확인에서도 인증서 체인과 검증 성공을 확인했다.
@@ -1,7 +1,7 @@
---
kind: PROJECT_DECISION
slug: edge-nginx-moved-into-a-guest-vm
title: 엣지 nginx 를 호스트에서 게스트 VM 으로 옮긴다 — 성능이 아니라 더러워지는 층의 격리
title: Edge Nginx를 호스트에서 게스트 VM으로 분리한 이유
topic: lab-environment-build
topicName: 실험대 환경 구성
project: virtualization
@@ -14,19 +14,19 @@ source:
- final/document.md#180-nftables-는-앞-체인의-accept-로-뒤-체인의-reject-를-막지-못한다
---
# 엣지 nginx 를 호스트에서 게스트 VM 으로 옮긴다 — 성능이 아니라 더러워지는 층의 격리
# Edge Nginx를 호스트에서 게스트 VM으로 분리한 이유
호스트에서 돌던 엣지 nginx 를 게스트 한 대(.10) 안으로 옮기고, 호스트는 커널 DNAT 로 tailnet 의 443 포트를 그 게스트에 넘기기만 한다. 바꾼 이유는 성능이 아니라 자주 갈아엎는 층의 격리다. 밖에서 게스트로 들어오는 경로가 FORWARD 가 되면서 libvirt 방화벽에 구멍이 새로 필요해졌다.
물리 호스트에서 실행하던 Edge Nginx를 `kc-lab-edge` VM으로 옮겼다. nginx 설정, 인증서, certbot처럼 변경이 잦은 구성 요소를 물리 호스트의 SSH·libvirt 환경과 분리하기 위해서다. 이 변경으로 외부 요청이 호스트의 FORWARD 경로를 지나게 됐고, libvirt `guest_input` 체인에는 Edge VM의 80·443 포트를 허용하는 규칙이 추가로 필요해졌다.
## 호스트에 두었을 때 생긴 문제
- **호스트 안에서는 404, 밖에서는 connection refused — 앞 체인의 accept 가 libvirt 의 reject 를 막지 못했다**
- **libvirt guest_input 체인의 reject로 외부 요청이 차단된 사례**
이 결정이 새로 요구한 것 가운데 3번을 실제로 치른 기록이다. 밖에서 게스트로 들어오는 경로가 FORWARD 가 되면서 libvirt 방화벽의 reject 에 막혔고, 「nftables 는 앞 체인의 `accept` 로 뒤 체인의 `reject` 를 막지 못한다」에서는 이곳을 이 구축에서 가장 오래 막힌 곳으로 적었다.
- **단계별 구축 문서는 작성 시점이 아니라 실행 순서로 검증한다**
이 구성을 세운 기반 7단계 가이드를 순서대로 따라가면서 나온 결함 여섯이 그 기준의 근거다. 여섯 중 셋이 여기서 옮긴 nginx 와 인증서를 다룬다.
- **libvirt 의 firewall_backend 가 iptables 일 때도 guest_input 에 구멍이 필요한가**
- **libvirt firewall_backend가 iptables일 때도 guest_input 예외 규칙이 필요한가**
「nftables 는 앞 체인의 `accept` 로 뒤 체인의 `reject` 를 막지 못한다」에서는 미확인으로 남긴 것을 받는 물음이다. 아래 3번은 이 호스트의 nftables 백엔드에서만 확인했다.
- **Guest 의 packet 이 Host Physical NIC 에 닿기까지 — virtio-net · virtqueue · vhost-net · TAP · Bridge**
- **게스트 패킷이 호스트 물리 NIC까지 전달되는 과정**
커널 DNAT 뒤에 이어지는 게스트 쪽 경로를 그 글이 설명한다.
- **이 호스트의 가상 머신 네트워크는 Bridge 인가 NAT 인가 Routing 인가**
「이 부의 출처와 범위」에서는 적은 대로 이 호스트는 이더넷이 없어 libvirt NAT 를 택했다. 그 물음이 실제 구성을 이 호스트에서 확인한다.
@@ -42,7 +42,7 @@ source:
## 성능이 아니라 격리를 택한 이유
바꾼 이유로 「엣지를 물리 호스트에서 VM 으로 옮기면 무엇이 새로 필요해지나」에서는 든 것은 성능이 아니라 더러워지는 층의 격리다. nginx 설정과 인증서와 certbot 과 deploy 훅은 자주 갈아엎는 것들이라 호스트에 있으면 초기화가 불가능하다. 엣지에 장애를 일부러 넣어 보는 실험도 호스트에서 하면 SSH 까지 위험해진다.
nginx를 옮긴 이유는 성능이 아니라 관리 경계를 분리하기 위해서였다. nginx 설정, 인증서, certbot, deploy 훅처럼 변경이 잦은 구성 요소를 Edge VM에 모으면 물리 호스트의 SSH와 libvirt 환경을 건드리지 않고 다시 만들 수 있다. Edge 계층에 장애를 주는 실험도 물리 호스트의 관리 경로와 분리할 수 있다.
성능은 근거가 아니다. L7 홉 수는 전후 모두 2홉이고 늘어난 것은 커널의 L4 전달 한 번이다. 그러나 **홉 수가 같다는 사실만으로 `X-Forwarded-*` 계약이 유지되지는 않았다.** 2026-09-21 packet capture에서 Tailscale ingress의 source가 edge에 도달할 때 `192.168.122.1`로 rewrite되는 것을 확인했다. 전환 전후를 같은 부하로 잰 측정도 없으므로, 이 결정은 성능 향상이나 헤더 보존을 근거로 삼지 않는다.
@@ -52,12 +52,12 @@ source:
## 새로 생긴 네트워크 비용
감수한 비용은 「엣지를 물리 호스트에서 VM 으로 옮기면 무엇이 새로 필요해지나」의 일곱 줄 표에 정리돼 있다. 그중 DNAT과 libvirt 방화벽 구멍을 나머지 다섯과 구분한 것은 경로가 OUTPUT에서 FORWARD로 바뀐 구조를 바탕으로 한 판단이며, 별도 실험으로 둘만 분리 측정한 것은 아니다. 경로가 OUTPUT 에서 FORWARD 로 바뀌면서 생긴 것이 그 둘이다.
감수한 비용은 「엣지를 물리 호스트에서 VM 으로 옮기면 무엇이 새로 필요해지나」의 일곱 줄 표에 정리돼 있다. 그중 DNAT과 libvirt 방화벽 허용 규칙을 나머지 다섯과 구분한 것은 경로가 OUTPUT에서 FORWARD로 바뀐 구조를 바탕으로 한 판단이며, 별도 실험으로 둘만 분리 측정한 것은 아니다. 경로가 OUTPUT 에서 FORWARD 로 바뀌면서 생긴 것이 그 둘이다.
DNAT(2번) : 전에는 호스트가 443 포트를 직접 들었으니 넘길 일이 없었다. 지금은 호스트에 리스너가 아예 없다
libvirt 방화벽에 구멍(3번) : 호스트에서 게스트로 가는 것은 OUTPUT 경로라 필터를 안 탔다. 밖에서 게스트로 들어오는 것은 FORWARD 다
libvirt 방화벽 허용 규칙(3번) : 호스트에서 게스트로 가는 것은 OUTPUT 경로라 필터를 안 탔다. 밖에서 게스트로 들어오는 것은 FORWARD 다
호스트가 게스트에 접속하는 것과 밖에서 게스트로 들어오는 것은 커널이 보기에 완전히 다른 일이다. 3번을 뚫는 데 이 구축에서 가장 오래 걸렸다. 「nftables 는 앞 체인의 `accept` 로 뒤 체인의 `reject` 를 막지 못한다」에서 밖에서 친 curl 은 connection refused 로 돌아왔다. libvirt 의 guest_input 체인을 끝내는 reject 규칙의 카운터 4 패킷이 그때 친 curl 횟수와 정확히 일치했다. 구멍이 필요하다는 것을 몰라서 오래 걸린 것은 아니다. DNAT 파일에는 priority filter - 10 으로 먼저 도는 forward 체인과 거기 넣은 ct state new accept 가 이미 있었고, 그것이면 열린다고 보고 세웠다 — iptables 감각으로 쓰면 정확히 여기서 틀린다고 「nftables 는 앞 체인의 `accept` 로 뒤 체인의 `reject` 를 막지 못한다」에서는 적었다.
호스트가 게스트에 접속하는 것과 밖에서 게스트로 들어오는 것은 커널이 보기에 완전히 다른 일이다. 외부 요청이 어느 규칙에서 거절되는지 확인하는 데 가장 많은 시간이 걸렸다. 「nftables 는 앞 체인의 `accept` 로 뒤 체인의 `reject` 를 막지 못한다」에서 밖에서 친 curl 은 connection refused 로 돌아왔다. libvirt 의 guest_input 체인을 끝내는 reject 규칙의 카운터 4 패킷이 그때 친 curl 횟수와 정확히 일치했다. 허용 규칙의 필요 여부만으로 원인을 찾을 수 있었던 것은 아니다. DNAT 파일에는 priority filter - 10 으로 먼저 도는 forward 체인과 거기 넣은 ct state new accept 가 이미 있었고, 그것이면 열린다고 보고 세웠다 — iptables 감각으로 쓰면 정확히 여기서 틀린다고 「nftables 는 앞 체인의 `accept` 로 뒤 체인의 `reject` 를 막지 못한다」에서는 적었다.
같은 계열의 가드레일이 하나 더 붙는다.
@@ -72,4 +72,4 @@ certbot 과 인증서와 갱신 훅이 게스트로(7번) : 인증서를 읽는
얻은 것은 격리다. 자주 갈아엎는 층이 게스트 한 대 안으로 들어가니 그 게스트를 통째로 다시 세울 수 있고, 엣지에 장애를 넣는 실험이 호스트 SSH를 직접 건드리지 않는다. L7 홉 수는 2홉 그대로지만 **뒤쪽 Traefik이 받는 client-address/header 조건은 바뀌었다.** source rewrite와 proxy trust는 별도로 검증해야 한다.
남은 것은 둘이고, 하나는 2026-09-21 재검증으로 닫혔다. 전환 전후를 같은 부하로 잰 측정은 이 저장소에 없다. libvirt `guest_input` 구멍을 DNAT 유닛의 `ExecStartPost`에 넣은 방식이 재구성을 견디는지는 이번에 실제로 재 봤고 **견디지 못했다.** worker VM 둘을 재구축하자 libvirt가 체인을 다시 쓰면서 accept 규칙 셋이 `reject` 뒤로 밀렸고, 유닛은 `active`인데 외부 80/443이 실패했다. 따라서 현재 persistence 방식은 실패한 구현이고 대체 방식은 아직 실제로 확인하지 않았다. libvirt 의 `firewall_backend` 가 iptables 일 때도 같은 구멍이 필요한지는 여전히 미확인이고, 이 호스트는 nftables 백엔드다.
남은 것은 둘이고, 하나는 2026-09-21 재검증으로 닫혔다. 전환 전후를 같은 부하로 잰 측정은 이 저장소에 없다. libvirt `guest_input` 허용 규칙을 DNAT 유닛의 `ExecStartPost`에서 추가한 방식이 재구성을 견디는지는 이번에 실제로 재 봤고 **견디지 못했다.** worker VM 둘을 재구축하자 libvirt가 체인을 다시 쓰면서 accept 규칙 셋이 `reject` 뒤로 밀렸고, 유닛은 `active`인데 외부 80/443이 실패했다. 따라서 현재 persistence 방식은 실패한 구현이고 대체 방식은 아직 실제로 확인하지 않았다. libvirt의 `firewall_backend`가 iptables일 때도 같은 허용 규칙이 필요한지는 여전히 미확인이고, 이 호스트는 nftables 백엔드다.
@@ -1,7 +1,7 @@
---
kind: PROJECT_DECISION
slug: fix-guest-addresses-with-a-dhcp-reservation
title: 게스트 주소는 libvirt DHCP 예약으로 고정한다 — 바꿀 수 없어서가 아니라 되돌리기가 가장 비싸서
title: 게스트 IP를 libvirt DHCP 예약으로 고정한 이유
topic: lab-environment-build
topicName: 실험대 환경 구성
project: virtualization
@@ -16,7 +16,7 @@ source:
sourceRevision: import-head 9465582b5d1630eb4ae7c4e078021486919bf6b6 · uncommitted-working-tree snapshot
---
# 게스트 주소는 libvirt DHCP 예약으로 고정한다 — 바꿀 수 없어서가 아니라 되돌리기가 가장 비싸서
# 게스트 IP를 libvirt DHCP 예약으로 고정한 이유
게스트 IP 를 libvirt 의 DHCP 예약으로 묶고 예약을 넣은 다음에 게스트를 만든다. 주소가 바뀌면 k3s 가 설정 파일과 인증서에 구워 둔 IP 부터 어긋나, 고치는 값이 한 곳이 아니라 재발급이나 재설치가 된다.
@@ -28,11 +28,11 @@ sourceRevision: import-head 9465582b5d1630eb4ae7c4e078021486919bf6b6 · uncommit
고정한 `192.168.122.11` 과 `192.168.122.12` 를 그대로 받아 쓰는 절차다. `--node-ip` 와 `--tls-san` 과 agent 의 `K3S_URL` 이 그 주소를 담는다.
- **엣지 게스트에 nginx 를 세우고 호스트 DNAT 으로 밖에서 들어오는 길을 연다**
nginx 의 `upstream` 이 뒤쪽 게스트 주소를 적는 곳이다. 주소가 바뀌면 reload 전까지 502 가 이어진다.
- **호스트에 직접 깔지 않고 게스트 VM 두 대로 간다 — 관측자가 실험 대상과 함께 죽으면 안 된다**
이 결정이 서 있는 바닥이다. 게스트를 반복해 죽이는 실험이 전제라서 주소 고정이 필요해졌다.
- **도구가 낸 출력은 대상의 상태가 아니다 — 그 명령이 무엇을 세는지부터 가른다**
- **k3s를 호스트에 직접 설치하지 않고 두 VM으로 구성한 이유**
게스트를 반복해서 삭제하고 다시 만드는 실험에서는 같은 역할의 VM이 매번 같은 주소를 받아야 했다. 그래서 VM을 만들기 전에 MAC 주소와 DHCP 예약을 함께 고정했다.
- **명령 출력이 실제 상태를 의미하는지 먼저 확인한다**
`net-dumpxml` 의 예약과 `net-dhcp-leases` 의 리스가 서로 다른 것을 말한다는 것을 그 기준이 일반화한다.
- **L7 이 두 겹인 이유와, 진입점 하나를 이중화하려 할 때 끝나지 않는 재귀**
- **이 실험대에서 L7 프록시를 두 단계로 둔 이유**
nginx 가 뒤쪽 노드를 주소로 가리키는 구조를 그 글이 설명한다. 여기서 고정한 주소가 그 upstream 에 적힌다.
## 고정 방식
@@ -49,8 +49,8 @@ sourceRevision: import-head 9465582b5d1630eb4ae7c4e078021486919bf6b6 · uncommit
k3s 가 IP 를 설정 파일과 인증서에 굽는다 : `--node-ip` 와 `--tls-san`, agent 의 `K3S_URL=https://192.168.122.11:6443`, kubeconfig 의 `server:` 필드가 전부 IP 를 담는다. server 노드의 IP 가 바뀌면 agent 가 클러스터에 합류하지 못한다. API 서버 인증서의 SAN 도 어긋나서 재발급이나 재설치가 필요해진다. 되돌리기가 가장 비싼 항목이다
nginx 는 upstream 주소를 기동 시점에 한 번만 해석한다 : 오픈소스판은 `upstream` 블록의 이름을 설정 로드 때 풀고 런타임에 다시 조회하지 않는다. 그래서 뒤쪽 IP 가 바뀌면 reload 전까지 계속 502 다. 다시 조회하게 하려면 `resolver` 와 변수 조합을 쓰거나 상용판이 필요하다
VM 을 반복해서 죽이는 것이 실험 그 자체다 : `virsh destroy` 로 노드 상실을 재현하는데 되살릴 때마다 주소가 달라지면 실험이 성립하지 않는다
장애 주입 규칙이 주소 기반이다 : 「kc-lab-2 로 가는 7800 을 막아라」에서 IP 가 어긋나면 조용히 엉뚱한 것을 막는다. 실패가 드러나지 않아 특히 위험하다
VM을 반복해서 중단하고 다시 시작한다 : `virsh destroy`로 노드 상실을 재현한 뒤 다시 시작했을 때 주소가 달라지면 같은 조건으로 실험을 반복하기 어렵다
장애 주입 규칙도 주소를 기준으로 동작한다. 예를 들어 `kc-lab-2`의 7800 포트를 막는 규칙에서 IP가 달라지면 명령 자체는 성공해도 다른 주소를 대상으로 삼을 수 있다.
수단은 셋을 견줬고 「DHCP 예약 (`ip-dhcp-host`)과 MAC `52:54:00`」에서는 표로 적었다. 게스트 안에서 static IP 를 설정하면 cloud-init 이 복잡해지고 libvirt 는 그 사실을 모르므로 주소 설정이 두 곳으로 흩어진다. upstream 에 호스트명을 쓰면 libvirt 의 dnsmasq 가 이름을 풀어 주기는 한다. 다만 호스트의 리졸버가 `virbr0` 를 바라봐야 하고, 기동 시 한 번만 해석한다는 둘째 문제는 이 방법으로 없어지지 않는다.
@@ -58,10 +58,10 @@ DHCP 예약을 고른 까닭은 주소 관리가 libvirt 한 곳에 모이기
## 운영할 때 조심할 점
값이 맞으면 조용히 되고 틀리면 더 조용히 틀린다. 그래서 치른 비용이 셋 다 「오류가 안 나는 실패」다.
DHCP 예약과 MAC, VM 정의가 일치하지 않아도 명령 단계에서 바로 오류가 나지 않는 경우가 있다. 그래서 VM을 만든 뒤 실제 주소가 예약과 일치하는지 다시 확인하도록 했다.
순서가 결과를 바꾼다 : 예약을 넣고 나서 `virt-install` 해야 한다. 게스트를 먼저 만들면 동적 대역(`192.168.122.2`부터 `192.168.122.254`)에서 아무 주소나 받고, 예약이 먹으려면 리스 만료를 기다리거나 재부팅해야 한다
MAC 이 한 글자만 달라도 조용히 무시된다 : 예약의 `mac` 과 `virt-install --network` 에 준 `mac=` 이 정확히 같아야 한다. 다르면 오류 메시지 없이 동적 범위에서 아무 주소나 받고, 증상은 「왜 IP 가 다르지」로만 나타난다
예약의 `mac`과 `virt-install --network`에 지정한 `mac=`이 정확히 같아야 한다. 값이 다르면 예약이 적용되지 않고 동적 DHCP 주소를 받을 수 있으며, 이 과정에서 별도의 설정 오류가 출력되지 않을 수 있다.
플래그 둘을 다 줘야 한다 : `--live` 만 주면 재부팅에 사라지고 `--config` 만 주면 지금 반영이 안 된다. 성공 판정은 출력에 `persistent config` 와 `live state` 두 마디가 다 나오는 것이고, 한쪽만 나온 것을 성공으로 읽으면 「재부팅하니 IP 가 바뀐다」가 된다
예약을 조회하는 두 명령도 서로 다른 것을 말한다. `net-dumpxml` 이 보여 주는 예약은 dnsmasq 에게 준 의도이고, `net-dhcp-leases` 가 보여 주는 리스는 실제로 나간 기록이다. 둘이 다를 수 있으므로 예약을 넣었다는 것만으로 게스트가 그 주소를 받았다고 읽지 않는다.
@@ -1,7 +1,7 @@
---
kind: PROJECT_DECISION
slug: no-docker-on-the-lab-host
title: lab host 에는 Docker 를 깔지 않는다 — 이미지 저장소가 갈리고, 그 위에 네트워크 변수가 하나 더 붙는다
title: lab host에 Docker를 설치하지 않은 이유
topic: lab-environment-build
topicName: 실험대 환경 구성
project: virtualization
@@ -14,13 +14,13 @@ source:
sourceRevision: import-head 9465582b5d1630eb4ae7c4e078021486919bf6b6 · uncommitted-working-tree snapshot
---
# lab host 에는 Docker 를 깔지 않는다 — 이미지 저장소가 갈리고, 그 위에 네트워크 변수가 하나 더 붙는다
# lab host에 Docker를 설치하지 않은 이유
Docker 는 워크스테이션에만 두고 lab host 와 게스트에서는 뺀다. 깔면 containerd 가 둘이 되어 `docker build` 한 이미지를 k3s 가 보지 못하고, 증상이 `docker images` 에는 보이는데 파드는 `ErrImageNeverPull` 인 모양으로 나온다.
Docker는 워크스테이션에서만 사용하고 lab host와 게스트에는 설치하지 않았다. k3s는 자체 containerd를 사용하므로 같은 머신에 Docker를 추가하면 `docker build`로 만든 이미지와 k3s가 보는 이미지 저장소가 분리된다. 이 경우 `docker images`에는 이미지가 있어도 파드는 `ErrImageNeverPull` 상태가 될 수 있다.
## Docker를 host에 넣으면 생기는 충돌
- **호스트에 직접 깔지 않고 게스트 VM 두 대로 간다 — 관측자가 실험 대상과 함께 죽으면 안 된다**
- **k3s를 호스트에 직접 설치하지 않고 두 VM으로 구성한 이유**
같은 축의 결정이다. 호스트를 진입점과 하이퍼바이저로만 남긴다는 그 판단이 컨테이너 런타임 쪽에서 한 번 더 쓰였다.
- **k3s server 와 agent 를 게스트 두 대에 깔고 lab host 에서 kubectl 로 본다**
k3s 가 자체 containerd 를 들고 들어오는 절차다. 그 절차가 끝난 뒤에 「이미지는 어떻게 넣지」가 처음 나온다.
@@ -28,7 +28,7 @@ Docker 는 워크스테이션에만 두고 lab host 와 게스트에서는 뺀
공개 이미지만 쓰는 배포라 반입이 필요 없는 쪽의 예다. 자체 빌드 이미지와 갈리는 지점을 그 절차가 보여 준다.
- **Prometheus 와 Grafana 를 올려 클러스터 안을 밖에서 본다**
같은 이유로 공개 이미지를 그대로 당겨 쓴다. 노드마다 따로 반입해야 하는 일이 여기서는 생기지 않는다.
- **도구가 낸 출력은 대상의 상태가 아니다 — 그 명령이 무엇을 세는지부터 가른다**
- **명령 출력이 실제 상태를 의미하는지 먼저 확인한다**
`docker images` 가 보여 주는 목록이 k3s 의 이미지 목록이 아니라는 것을 그 기준이 일반화한다.
## 런타임 배치
@@ -1,7 +1,7 @@
---
kind: PROJECT_DECISION
slug: two-guest-vms-instead-of-installing-k3s-on-the-host
title: 호스트에 직접 깔지 않고 게스트 VM 두 대로 간다 — 관측자가 실험 대상과 함께 죽으면 안 된다
title: k3s를 호스트에 직접 설치하지 않고 두 VM으로 구성한 이유
topic: lab-environment-build
topicName: 실험대 환경 구성
project: virtualization
@@ -14,13 +14,13 @@ source:
sourceRevision: import-head 9465582b5d1630eb4ae7c4e078021486919bf6b6 · uncommitted-working-tree snapshot
---
# 호스트에 직접 깔지 않고 게스트 VM 두 대로 간다 — 관측자가 실험 대상과 함께 죽으면 안 된다
# k3s를 호스트에 직접 설치하지 않고 두 VM으로 구성한 이유
k3s 를 게스트 VM 두 대에 나눠 깔고 물리 호스트는 진입점과 하이퍼바이저로만 남긴다. 머신이 한 대뿐이라 같은 커널에 두 노드를 올리면 노드 상실 실험이 성립하지 않고, 호스트가 노드를 겸하면 SSH 와 libvirt 와 nginx 가 실험 대상과 같이 내려간다.
k3s 노드는 게스트 VM 두 대에 나눠 구성하고 물리 호스트는 libvirt와 관리 경로를 담당하도록 분리했다. 같은 커널 위에 논리적으로 노드만 둘로 나누면 한 노드만 중단하는 장애 실험을 만들기 어렵고, 물리 호스트 자체를 k3s 노드로 사용하면 노드 장애 실험이 SSH와 libvirt 같은 관리 기능에도 영향을 줄 수 있다.
## 호스트 직접 설치의 문제
- **엣지 nginx 를 호스트에서 게스트 VM 으로 옮긴다 — 성능이 아니라 더러워지는 층의 격리**
- **Edge Nginx를 호스트에서 게스트 VM으로 분리한 이유**
같은 논리를 엣지 한 층에 다시 적용한 결정이다. 그쪽은 게스트 구조가 이미 있다고 놓고 엣지가 어디 사는지를 정했고, 이쪽은 게스트 구조를 쓸 것인지를 정했다.
- **lab host 에 가상화 패키지를 깔고 virsh 가 sudo 없이 돌게 만든다**
이 결정이 요구한 첫 절차다. 호스트에 k3s 대신 libvirt 와 QEMU 가 깔리는 까닭을 이 결정이 댄다.
@@ -28,7 +28,7 @@ k3s 를 게스트 VM 두 대에 나눠 깔고 물리 호스트는 진입점과
결정을 실제로 실행한 절차다. server 와 agent 가 서로 다른 게스트로 들어가고 `kubectl` 은 호스트에서 돈다.
- **Prometheus 와 Grafana 를 올려 클러스터 안을 밖에서 본다**
관측 스택을 server 노드에 못박는 절차가 거기 있다. 관측자를 살려 둔다는 이유가 클러스터 안에서 한 번 더 쓰인다.
- **lab host 에는 Docker 를 깔지 않는다 — 이미지 저장소가 갈리고, 그 위에 네트워크 변수가 하나 더 붙는다**
- **lab host에 Docker를 설치하지 않은 이유**
호스트를 깨끗이 남긴다는 같은 축의 결정을 컨테이너 런타임 쪽에 적용한 것이다.
- **실험대를 껐다 켜고 게스트 메모리를 다시 나눈다**
게스트로 갔기 때문에 가능해진 운영이다. `virsh setmaxmem` 으로 메모리를 다시 나누는 일은 호스트에 직접 깔았으면 생기지 않는다.
@@ -37,7 +37,7 @@ k3s 를 게스트 VM 두 대에 나눠 깔고 물리 호스트는 진입점과
k3s server는 게스트 `kc-lab-1`에, agent는 `kc-lab-2`에 둔다. 물리 호스트 `test-server`에는 k3s를 설치하지 않고 libvirt/KVM과 실험대 진입에 필요한 최소 기능만 남긴다.
2026-09-03 최초 배치에서는 게스트 둘이 `virbr0` 뒤에서 `192.168.122.11`과 `192.168.122.12`를 썼고 nginx는 호스트에 있었다. 이후 `kc-lab-edge`가 추가되면서 nginx도 Edge VM으로 이동했다. 현재도 이 결정의 핵심인 **k3s 노드와 물리 호스트의 커널 분리**는 그대로 유지된다.
2026-09-03 최초 배치에서는 게스트 둘이 `virbr0` 뒤에서 `192.168.122.11`과 `192.168.122.12`를 썼고 nginx는 호스트에 있었다. 이후 `kc-lab-edge`가 추가되면서 nginx도 Edge VM으로 이동했다. 현재 구성에서도 k3s 노드와 물리 호스트는 서로 다른 커널에서 실행된다.
## 두 guest로 나눈 이유
@@ -45,26 +45,26 @@ k3s server는 게스트 `kc-lab-1`에, agent는 `kc-lab-2`에 둔다. 물리 호
독립 커널이 둘 필요하다 : 같은 커널에 k3s server 와 agent 를 올리면 노드가 이름뿐이라 노드 간 방화벽·파티션·노드 상실 실험이 성립하지 않는다
파괴 실험 후 복원 : VM 은 qcow2 오버레이를 지우면 몇 초 만에 초기 상태로 돌아가고, 호스트는 재설치 말고 되돌릴 방법이 없다
관측자를 살려 둔다 : 노드를 죽이는 실험인데 그 노드가 호스트면 SSH 와 libvirt 와 nginx 가 같이 죽는다
호스트 오염 방지 : k3s 는 nftables 규칙과 CNI(Container Network Interface, 컨테이너 네트워크 규격) 인터페이스, 커널 모듈, systemd 유닛을 대량으로 심는다
관리 경로를 실험 대상과 분리한다 : 물리 호스트를 k3s 노드로 사용하면 노드 장애 실험이 SSH와 libvirt 같은 관리 기능에도 영향을 줄 수 있다
물리 호스트의 네트워크·서비스 구성을 분리한다 : k3s는 nftables 규칙, CNI(Container Network Interface) 인터페이스, 커널 모듈, systemd 유닛을 추가한다
운영 배포판과 일치 : 호스트는 Arch 인데 운영 k3s 가 다른 배포판이면 커널과 systemd 차이가 잡음이 된다. 게스트를 운영과 같게 맞추면 그 잡음이 사라진다
netem 격리 : 커널이 분리되어 지연 주입이 게스트 안에 갇힌다. 호스트에서 걸면 SSH 까지 느려진다
견준 쪽은 호스트에 단일 노드 k3s 를 직접 까는 것이다. 「왜 호스트에 직접 깔지 않고 VM 2대인가」에서는 그것을 정직한 반대편으로 직접 적었다 — 계약 검증(2홉 헤더, 쿠키/origin)만 볼 거라면 호스트 직접 설치로 충분하고 그게 더 빠르다. VM 경로가 필요해지는 것은 클러스터와 장애 실험부터다.
절충안도 하나 검토하고 채택하지 않았다. 호스트를 노드 1로 쓰고 VM 을 노드 2로 두는 방법이다. 게스트 운영체제 하나(약 350MB)와 설치 수고를 아끼는 대신 관측자 분리와 호스트 오염 방지를 포기하게 된다. 7.4Gi 예산에서 그 350MB 보다 관측자 분리가 더 값지다고 판단했다.
물리 호스트를 첫 번째 노드로 쓰고 VM 하나만 추가하는 구성도 검토했다. 이 방식은 게스트 운영체제 하나에 필요한 약 350MB와 설치 작업을 줄일 수 있지만, 관리용 호스트와 실험 노드를 분리할 수 없다. 당시 메모리 예산에서는 이 절감보다 관리 경계를 분리하는 쪽을 선택했다.
## 구축 비용과 얻은 격리
실험 범위를 넓히는 대가로 구축 시간과 게스트 운영체제 몫의 메모리를 치렀다. 호스트에 단일 노드로 깔았으면 하루 안에 끝났을 구축이 게스트 생성과 cloud-init 과 k3s 설치로 나뉘었고, 게스트마다 커널과 systemd 가 따로 돌아 그만큼의 메모리를 쓴다.
얻은 것은 되돌릴 수 있는 실험대다. 노드를 죽여도 `virsh start`로 되살릴 수 있고, 게스트를 통째로 지워도 `base.qcow2` 위에 오버레이를 다시 만들어 복구할 수 있다. 2026-09-21에는 worker 두 대를 실제로 `destroy → undefine --remove-all-storage`한 뒤 cloud-init·k3s·Keycloak까지 다시 구축해 이 경로를 확인했다.
이 구성에서는 VM을 중단해도 `virsh start`로 다시 시작할 수 있고, 게스트를 통째로 지워도 `base.qcow2` 위에 오버레이를 다시 만들어 복구할 수 있다. 2026-09-21에는 worker 두 대를 실제로 `destroy → undefine --remove-all-storage`한 뒤 cloud-init·k3s·Keycloak까지 다시 구축해 이 경로를 확인했다.
같은 구분이 클러스터 안에서 한 번 더 나온다. k3s server 와 agent 는 죽였을 때가 다르다.
k3s server와 agent는 중단했을 때 클러스터에 미치는 영향이 다르다.
kc-lab-1(server) 를 죽이면 : `kubectl` 이 안 되고 DNS 와 인그레스도 사라진다
kc-lab-2(agent) 를 죽이면 : 그 노드의 워크로드만 사라지고 클러스터 제어는 살아 있다
kc-lab-1(server)을 중단하면 : `kubectl` 이 안 되고 DNS 와 인그레스도 사라진다
kc-lab-2(agent)을 중단하면 : 그 노드의 워크로드만 사라지고 클러스터 제어는 살아 있다
그래서 노드 상실 실험은 agent 를 죽이는 것이고, server 를 죽이는 것은 노드 상실이 아니라 컨트롤 플레인 상실이다. 「k3s server와 agent — 죽였을 때가 다르다」에서는 이 사실을 모르고 「keycloak 하나만 있는 노드를 죽이자」고 계획했다가 실제 배치를 조회한 뒤 정정했다고 적는다. 노드가 둘뿐이라 관측과 실험을 완전히 갈라놓을 수는 없으므로 「관측 시스템의 장애 도메인」에서는 규칙으로 못박았다 — 관측 스택은 server 쪽에 두고 죽이지 않으며, 장애 주입은 agent 쪽에만 건다. `nodeSelector` 로 배치를 고정해야 그 규칙이 재현된다.
따라서 worker 노드 상실 실험은 agent 노드를 대상으로 하고, server 노드를 중단하는 경우는 control-plane 상실 실험으로 구분한다. 기존 기록에서는 처음에 Keycloak만 있는 노드를 장애 주입 대상으로 잡으려 했지만, 실제 배치를 확인한 뒤 agent 노드를 worker 장애 주입 대상으로 정정했다. 노드가 둘뿐이라 관측과 실험을 완전히 갈라놓을 수는 없으므로 「관측 시스템의 장애 도메인」에서는 규칙으로 못박았다 — 관측 스택은 server 노드에 두고 장애 주입 대상에서 제외하며, 장애 주입은 agent 노드에만 수행한다. `nodeSelector` 로 배치를 고정해야 그 규칙이 재현된다.
확인하지 않은 것이 하나 있다. 호스트 직접 설치와 게스트 두 대를 같은 실험으로 견준 측정은 이 저장소에 없다. 여섯 이유는 무엇이 성립하고 무엇이 성립하지 않는가에 대한 판단이고, 어느 쪽이 얼마나 느린지는 재지 않았다.
@@ -1,7 +1,7 @@
---
kind: QUESTION
slug: guest-input-hole-under-the-iptables-backend
title: libvirt 의 firewall_backend 가 iptables 일 때도 guest_input 에 구멍이 필요한가
title: libvirt firewall_backend가 iptables일 때도 guest_input 예외 규칙이 필요한가
topic: lab-environment-build
topicName: 실험대 환경 구성
project: virtualization
@@ -14,7 +14,7 @@ source:
- final/document.md#180-nftables-는-앞-체인의-accept-로-뒤-체인의-reject-를-막지-못한다
---
# libvirt 의 firewall_backend 가 iptables 일 때도 guest_input 에 구멍이 필요한가
# libvirt firewall_backend가 iptables일 때도 guest_input 예외 규칙이 필요한가
nftables 백엔드에서는 libvirt의 `guest_input` 체인 끝 `reject`가 외부 요청을 `connection refused`로 끊는 것을 2026-09-21에도 다시 재현했다. 다만 `firewall_backend=iptables` 비교는 아직 수행하지 않았다. 전역 libvirt firewall backend를 바꾸고 네트워크를 다시 세우면 현재 edge 진입점까지 끊길 수 있어, 기존 서비스가 함께 있는 이 host에서는 백엔드를 임의 전환하지 않았다.
@@ -22,12 +22,12 @@ nftables 백엔드에서는 libvirt의 `guest_input` 체인 끝 `reject`가 외
- 실제 구축에서 외부 요청이 가장 오래 막힌 지점은 libvirt가 만든 `guest_input` 체인이었다.
- 호스트에서 curl http://192.168.122.10 을 치면 엣지 nginx 가 404 로 응답했다.
- 밖에서 curl http://100.83.212.4 을 치면 connection refused 가 왔다. 드롭이면 기다리다 죽으니, 타임아웃이 아니라 즉시 거절이라는 점이 단서였다.
- 외부에서 `curl http://100.83.212.4`을 실행하면 `connection refused`가 반환됐다. 패킷이 drop된 경우처럼 타임아웃까지 기다리지 않고 즉시 거절됐다는 점 때문에 reject 규칙을 먼저 확인했다.
- libvirt 는 자기 테이블 ip libvirt_network 의 guest_input 체인을 reject 로 끝낸다. 그 앞에는 established,related 를 accept 하는 규칙이 있다.
- 그 reject 규칙의 카운터가 4 패킷 240 바이트였고 밖에서 친 curl 횟수와 정확히 일치했다. 범인은 그 숫자로 확정했다.
- reject 규칙의 카운터는 4 packets / 240 bytes였고 외부에서 실행한 `curl` 횟수와 정확히 일치했다. 이 값으로 해당 규칙이 외부 요청을 거절하고 있음을 확인했다.
- DNAT 파일에는 priority filter - 10 으로 먼저 도는 forward 체인이 있고 거기에 ct state new accept 를 넣어 두었다. 그런데도 패킷은 뒤 체인에서 거절됐다.
- nftables 는 같은 훅에 붙은 base 체인을 우선순위 순으로 전부 평가한다. 앞 체인의 accept 는 이 체인은 통과라는 뜻이고, 평가를 즉시 끝내는 것은 drop 이다. iptables 감각으로 쓰면 정확히 여기서 틀린다.
- 구멍은 libvirt 체인 맨 앞에 뚫었다. insert 가 맨 앞이고 add 가 맨 뒤다.
- nftables 구성에서는 Edge VM 80·443 허용 규칙을 libvirt `guest_input` 체인의 reject보다 앞에 `insert`했다.
- 그 규칙은 휘발성이다. 처음에는 DNAT 유닛의 `ExecStartPost`로 다시 넣는 방식을 썼다. 그러나 2026-09-21 worker 재구축에서 libvirt가 `guest_input`을 다시 구성한 뒤 기존 accept 규칙들이 `reject` 뒤로 밀렸고 외부 80/443이 다시 실패했다. 따라서 `ExecStartPost` 한 번은 persistence 해법으로 충분하지 않다는 것까지 확인됐다.
- 이 호스트는 nftables 백엔드다. firewall_backend 가 iptables 일 때도 같은지는 재지 않았다고 「nftables 는 앞 체인의 `accept` 로 뒤 체인의 `reject` 를 막지 못한다」에서는 미확인으로 표시했다.
@@ -41,21 +41,21 @@ nftables 백엔드에서는 libvirt의 `guest_input` 체인 끝 `reject`가 외
## 아직 모르는 backend 차이
- firewall_backend 를 iptables 로 둔 호스트에서 밖에서 게스트로 가는 FORWARD 경로를 무엇이 끝내는지.
- 그때 forward 체인의 ct state new accept 가 실제로 먹는지, 아니면 거기서도 libvirt 쪽 규칙에 구멍을 따로 뚫어야 하는지.
- 구멍이 필요하다면 그 방법이 nftables 에서 쓴 insert 맨 앞 규칙과 어떻게 다른지, 그리고 그 규칙도 네트워크를 다시 세우면 날아가는지.
- iptables 백엔드에서도 별도의 Edge VM 허용 규칙이 필요한지 확인한다.
- 허용 규칙이 필요하다면 nftables 백엔드에서 사용한 규칙과 무엇이 다른지, libvirt 네트워크 재구성 뒤에도 유지되는지 확인한다.
## 환경별로 달라지는 범위
- 잴 수 있는 호스트가 한 대다. 「이 부의 출처와 범위」에 적은 test-server 는 Arch Linux, i5-1135G7 논리 코어 8, RAM 11,648MiB, QEMU 11.1.1 · libvirt 12.7.0 이다.
- 이더넷 없이 WiFi 만 있어 브리지를 못 쓰고 libvirt NAT(virbr0) + 호스트 진입 구조를 택했다. 밖에서 들어온 패킷이 FORWARD 를 타는 것이 그 구성 때문이라, 네트워크 모드가 달라지면 이 물음이 묻는 상황도 달라진다.
- 백엔드를 바꾸려면 libvirt 네트워크를 다시 세워야 하고, 그때 guest_input 에 뚫어 둔 구멍이 날아간다. 엣지 게스트가 밖에서 들어오는 요청을 받는 진입점이므로 되돌릴 절차를 먼저 준비한다.
- iptables backend 비교 원문은 아직 없다. nftables backend의 과거 `4 packets / 240 bytes` 수치는 당시 본문에 옮긴 덤프에만 남아 있고, 2026-09-21에는 같은 backend에서 외부 요청 실패와 `reject` 카운터 증가를 다시 확인했다. 두 시점의 숫자를 하나의 실행처럼 합치지 않는다.
- 백엔드를 바꾸려면 libvirt 네트워크를 다시 구성해야 하고, 현재 `guest_input`에 런타임으로 추가한 허용 규칙은 사라질 수 있다. 엣지 게스트가 밖에서 들어오는 요청을 받는 진입점이므로 되돌릴 절차를 먼저 준비한다.
- iptables backend에서 같은 비교를 수행한 기록은 아직 없다. nftables backend의 과거 `4 packets / 240 bytes` 수치는 당시 덤프에만 남아 있고, 2026-09-21에는 같은 backend에서 외부 요청 실패와 `reject` 카운터 증가를 다시 확인했다. 두 시점의 숫자를 하나의 실행처럼 합치지 않는다.
## 어떻게 비교할까
### 1. 구멍을 뺀 채 백엔드만 iptables 로 바꾸고 밖에서 한 번 친다
### 1. 별도 허용 규칙 없이 iptables 백엔드의 외부 요청 경로를 확인한다
백엔드를 바꾸면서 libvirt 네트워크를 다시 세우면 현재 `guest_input`에 넣은 허용 규칙은 사라지므로, 별도 구멍이 없는 상태에서 비교를 시작할 수 있다. 그 상태에서 밖에서 엣지로 curl 을 치고 응답인지 connection refused 인지, 그리고 거기까지 걸린 시간을 적는다. 같은 시각에 libvirt 가 만든 규칙을 그대로 덤프해 어느 규칙이 패킷을 끝내는지 본다. 규칙마다 카운터가 붙어 있으면 그 값이 친 횟수와 맞는지도 함께 읽는다. nftables 에서 범인을 지목한 것이 그 카운터였다.
백엔드를 바꾸면서 libvirt 네트워크를 다시 세우면 현재 `guest_input`에 넣은 허용 규칙은 사라지므로, 별도 허용 규칙이 없는 상태에서 비교를 시작할 수 있다. 그 상태에서 밖에서 엣지로 curl 을 치고 응답인지 connection refused 인지, 그리고 거기까지 걸린 시간을 적는다. 같은 시각에 libvirt 가 만든 규칙을 그대로 덤프해 어느 규칙이 패킷을 끝내는지 본다. 규칙마다 카운터가 붙어 있으면 그 값이 친 횟수와 맞는지도 함께 읽는다. nftables 백엔드에서도 reject 규칙의 카운터와 요청 횟수가 일치해 차단 지점을 확인할 수 있었다.
「nftables 는 앞 체인의 `accept` 로 뒤 체인의 `reject` 를 막지 못한다」에 적은 그 forward 체인은 지금 DNAT 파일에 없다. 「단계 03 — 엣지 nginx 라우팅과 호스트 DNAT」에서는 싣는 파일에 남은 체인은 prerouting 하나이고, accept 는 유닛의 ExecStartPost 가 libvirt 체인 안에 넣는다. 그래서 아래 셋 가운데 마지막을 재려면 그 체인을 먼저 되돌려 놓아야 한다.
@@ -65,20 +65,20 @@ nftables 백엔드에서는 libvirt의 `guest_input` 체인 끝 `reject`가 외
패킷을 끝낸 규칙 : 어느 테이블의 어느 체인인가
forward 체인의 accept : 먹었는가 먹지 않았는가
### 2. 구멍을 남겨 둔 채 백엔드만 바꾼다 — 제외
### 2. 기존 허용 규칙을 남긴 채 백엔드만 바꾼다 — 제외
구멍이 이미 열려 있으면 요청은 통과하고, 그 통과가 구멍 덕분인지 백엔드가 원래 막지 않아서인지 가려지지 않는다.
기존 허용 규칙이 남아 있으면 요청이 통과했을 때 iptables 백엔드 자체의 기본 동작과 허용 규칙의 효과를 구분할 수 없다.
### 3. libvirt 가 iptables 백엔드에서 만드는 규칙을 문서로 읽어 견준다 — 제외
호스트를 건드리지 않아도 되지만 답이 나오지 않는다. 「nftables 는 앞 체인의 `accept` 로 뒤 체인의 `reject` 를 막지 못한다」에서도 규칙 목록이 아니라 카운터가 범인을 지목했으니, 우선순위가 다른 base 체인 둘이 한 훅에 붙었을 때 어느 쪽이 패킷을 끝내는지는 이 구성에서 돌려 봐야 나온다.
호스트 설정을 바꾸지 않고 문서만 비교하는 방법으로는 실제 패킷 처리 결과를 알 수 없다. nftables 백엔드에서도 규칙 목록만 본 것이 아니라 reject 카운터와 요청 횟수를 대조해 차단 지점을 확인했다. iptables 백엔드에서도 같은 방식으로 실제 요청과 규칙 카운터를 함께 확인해야 한다.
## 다음 확인
1. libvirt 의 firewall_backend 를 iptables 로 두고 네트워크를 다시 세운다. 이때 guest_input 에 뚫어 둔 구멍이 날아가므로 구멍 없는 상태에서 시작한다.
1. libvirt 의 firewall_backend 를 iptables 로 두고 네트워크를 다시 세운다. 이때 런타임으로 추가한 `guest_input` 허용 규칙이 사라지므로 별도 허용 규칙이 없는 상태에서 시작한다.
2. 밖에서 엣지로 curl 을 치고 결과가 응답인지 connection refused 인지, 그리고 거기까지 걸린 시간을 적는다.
3. 같은 시각에 libvirt 가 만든 규칙을 그대로 덤프해 어느 규칙이 패킷을 끝내는지와 그 카운터가 친 횟수와 맞는지를 본다.
4. 출력 원문과 함께 실행한 명령, 작업 디렉터리, 실행 시각, 종료 코드를 기록한다. backend 전환 전후의 ruleset과 외부 요청 결과를 한 실행 단위로 묶어야 나중에 비교할 수 있다.
5. 백엔드를 nftables 로 되돌린 뒤 현재 외부 경로가 원래 상태로 복구됐는지 직접 확인한다. `ExecStartPost`는 libvirt의 이후 체인 재작성까지 보장하지 못하므로, 유닛 `active`만 보지 않고 `guest_input`에서 edge용 `accept`가 `reject`보다 앞에 있는지와 외부 80/443 응답을 함께 본다.
`iptables` 백엔드에서 별도 허용 규칙 없이 외부 요청이 응답을 받으면 현재의 `guest_input` 구멍은 nftables 백엔드에 한정된 조치로 본다. 여전히 거절되면 패킷을 끝낸 규칙과 필요한 허용 방법을 함께 남긴다. 지금 확인된 범위는 nftables 백엔드뿐이다.
`iptables` 백엔드에서 별도 허용 규칙 없이 외부 요청이 응답을 받으면 현재의 `guest_input` 허용 규칙은 nftables 백엔드에서만 필요했던 조치로 판단할 수 있다. 여전히 거절되면 패킷을 끝낸 규칙과 필요한 허용 방법을 함께 남긴다. 지금 확인된 범위는 nftables 백엔드뿐이다.
@@ -60,7 +60,7 @@ renewal 설정이 `dns-cloudflare`를 직접 가리킨다. 이 질문의 답이
### 2. HTTP-01 — 현재 관측과 불일치
원본 가이드 04에는 `--webroot` 경로가 남아 있었지만, 현재 renewal 설정이 그것을 사용한다는 증거는 없다. historical document branch로만 남긴다.
원본 가이드 04에는 `--webroot` 경로가 남아 있었지만, 현재 renewal 설정이 그것을 사용한다는 증거는 없다. 과거 가이드에 남아 있던 경로로만 구분한다.
## 현재 실험대는 DNS-01로 갱신한다
@@ -60,7 +60,7 @@ source:
### 1. 크기를 먼저 확정하고 그 파일 한 장을 한 번 옮긴다
qemu-img info 와 du 로 가상 크기와 실제 점유를 따로 적는다. 제4부에서 형식과 세 크기를 묻는 물음이 같은 출력을 쓰기 때문에 한 번만 돌려 두 물음이 나눠 쓴다. 그다음 게스트를 멈춘 상태에서 그 파일을 다른 기계로 복사하고 시작 시각과 종료 시각과 평균 전송률을 적는다.
`qemu-img info`와 `du`로 가상 크기와 실제 호스트 할당량을 먼저 기록한다. 같은 출력은 이미지 형식과 사용량 확인에도 함께 사용할 수 있다. 그다음 게스트를 멈춘 상태에서 파일을 다른 기계로 복사하고 시작 시각, 종료 시각, 평균 전송률을 기록한다.
옮기는 것이 파일 한 장이 아니다. 「단계 01 — 게스트 세 대」에 적은 이 실험대의 게스트 디스크 셋은 전부 base.qcow2 위의 오버레이라, 오버레이만 건너가면 헤더에 절대경로로 적힌 그 base 를 받는 쪽에도 같은 경로로 두어야 한다.
@@ -20,7 +20,7 @@ source:
# virsh save 의 RAM 덤프 크기와 소요 시간은 할당 메모리에 어떻게 비례하는가
2026-09-21 `kc-lab-1`에서 current memory를 5120 MiB와 4096 MiB 두 값으로 두고 `virsh save → restore`를 실제로 반복했다. **save 파일은 ‘RAM 크기만큼’ 그대로 생기지 않았다.** 5120 MiB 상태에서는 약 3.33 GB, 4096 MiB 상태에서는 약 3.22 GB였고, 1 GiB의 current-memory 차이가 save 파일 크기에 1 GiB로 그대로 반영되지 않았다.
2026-09-21 `kc-lab-1`에서 current memory를 5120 MiB와 4096 MiB 두 값으로 두고 `virsh save → restore`를 실제로 반복했다. save 파일은 ‘RAM 크기만큼’ 그대로 생기지 않았다. 5120 MiB 상태에서는 약 3.33 GB, 4096 MiB 상태에서는 약 3.22 GB였고, 1 GiB의 current-memory 차이가 save 파일 크기에 1 GiB로 그대로 반영되지 않았다.
## 5120MiB와 4096MiB 비교 결과
@@ -1,7 +1,7 @@
---
kind: REFERENCE
slug: a-config-file-does-not-mean-the-same-thing-on-two-distros
title: 같은 설정 파일이 두 배포판에서 같은 뜻이 아니다 — 옮기기 전에 세 가지를 본다
title: 배포판이 다르면 같은 설정 파일도 그대로 옮기지 않는다
topic: lab-environment-build
topicName: 실험대 환경 구성
project: virtualization
@@ -18,9 +18,9 @@ source:
- final/document.md#209-nginx-keycloak-lab-conf-스티키-스위치와-신뢰-경계
---
# 같은 설정 파일이 두 배포판에서 같은 뜻이 아니다 — 옮기기 전에 세 가지를 본다
# 배포판이 다르면 같은 설정 파일도 그대로 옮기지 않는다
설정 파일을 배포판이 다른 기계로 옮기기 전에 셋을 본다. 그 지시어가 대상의 판올림에 있는가, 패키지가 기본으로 켜 둔 것과 충돌하지 않는가, 그 배포판이 그 관례를 갖고 있는가. 이 실험대의 함정 셋이 전부 여기 걸렸다.
설정 파일을 다른 배포판으로 옮길 때는 해당 지시어를 그 버전에서 지원하는지, 패키지 기본 설정과 충돌하지 않는지, 같은 디렉터리 구조와 패키징 관례를 사용하는지 확인한다. 이 실험대에서도 같은 파일을 그대로 옮겼을 때 이 세 조건에서 차이가 발생했다.
## 같은 파일명이 같은 기능을 뜻하지 않는 이유
@@ -32,7 +32,7 @@ source:
### 1. 그 지시어가 대상의 판올림에 있는가
`http2 on;` 은 nginx 1.25.1 이상이다. Arch 에서 쓰던 설정을 Debian 12 게스트로 그대로 옮기면 `unknown directive "http2"` 가 나면서 설정 전체가 죽는다.
`http2 on;`은 nginx 1.25.1 이상에서 사용하는 지시어다. 이를 지원하지 않는 Debian 12의 nginx에 같은 설정을 적용하면 `unknown directive "http2"` 오류가 발생하고 설정 검사가 실패한다.
없다는 것을 확인하는 데서 멈추면 규칙이 답을 내지 않는다. 양쪽에서 도는 형태가 무엇인지까지 찾는다. `listen 443 ssl http2;` 형태는 1.22 와 1.30 양쪽에서 다 돈다.
@@ -14,7 +14,7 @@ source:
# 단계별 구축 문서는 작성 시점이 아니라 실행 순서로 검증한다
구축 가이드는 1단계의 환경에서 시작해 실행 순서로 검증한다. 단계마다 그 시점에 리소스가 이미 있는지와 그 명령을 어느 기계에서 치는지를 따로 본다. 기반 7단계 가이드를 순서대로 따라가자 결함 여섯이 나왔고, 틀린 명령은 하나도 없었다.
구축 문서는 빈 환경에서 첫 단계부터 순서대로 실행해 봐야 한다. 각 단계에서 필요한 리소스가 이미 만들어져 있는지, 명령을 어느 머신에서 실행해야 하는지까지 함께 확인한다. 이 실험대의 7단계 가이드는 명령 자체의 문법 오류보다 실행 순서와 실행 위치에서 여섯 가지 문제가 드러났다.
## 문장이 맞아도 순서가 틀릴 수 있다
@@ -61,7 +61,7 @@ Debian 12 클라우드 이미지 한 장 위에 오버레이로 게스트 셋을
전제는 한 줄이다 — 앞 단계가 끝나 `virsh list` 가 `sudo` 없이 돈다.
**되돌리는 절차는 원본 가이드 01 에 없다**. 다만 01 이 만드는 것이 무엇인지는 단계 03 이 지나가며 한 줄로 적어 두었다.
세 게스트 전체를 되돌리는 절차는 아직 검증하지 않았다. 게스트 삭제 자체뿐 아니라 DHCP 예약과 seed volume까지 함께 정리해야 하므로 생성 절차와 별도로 확인해야 한다.
```bash label="[lab host] 03 이 엣지를 왜 VM 으로 두는지 설명하며 적어 둔 한 줄"
virsh undefine kc-lab-edge --remove-all-storage
@@ -141,7 +141,7 @@ openssl rand -base64 18
**목적** — 게스트가 첫 부팅에서 읽을 `#cloud-config` 를 게스트 이름별로 하나씩 만든다.
원본 가이드에서 이 단계가 비어 있다. 템플릿으로 `deploy/lab/cloud-init/kc-lab.yaml.example` 을 걸어 두고 곧바로 자리표시자를 바꾸는 치환 명령으로 넘어가는데, 그 파일을 게스트 이름으로 복사하거나 새로 만드는 명령이 원본에도 없다. 템플릿 원문도 반입되지 않아 대조하지 못했다. 그래서 아래는 원본 본문이 실은 내용을 파일로 옮겨 적었다.
`deploy/lab/cloud-init/kc-lab.yaml.example` 원본 파일은 현재 자료에 포함돼 있지 않아 그대로 복사해 사용할 수 없다. 따라서 아래 절차에서는 확인된 cloud-config 항목을 직접 파일에 작성한다. 템플릿 파일과 완전히 같은 내용이라고 단정하지 않는다.
```bash label="[lab host] ① 게스트 이름으로 파일을 연다"
nano kc-lab-1.yaml
@@ -183,7 +183,7 @@ packages: [curl, nftables]
| `plain_text_passwd` | cloud-init 이 실패했을 때의 유일한 탈출구. 키가 안 들어가면 SSH 가 막히므로 콘솔로 들어가 로그를 봐야 한다 |
| 키 두 개 | lab host 에서 자동화가 돌고, 워크스테이션에서는 ProxyJump 로 직접 붙는다 |
들여쓰기에는 공백만 쓴다. YAML 은 탭을 금지하고, cloud-init 은 파싱에 실패해도 아무 오류를 남기지 않아 증상이 「SSH 가 안 붙는다」 하나로만 나타난다. 편집기로 여는 까닭도 여기에 있다 — 배울 것이 `hostname:` 과 `users:` 와 `packages:` 인데 치환 명령의 구분자와 명령 치환을 먼저 읽어야 하면 시선이 그쪽으로 간다.
들여쓰기에는 공백만 사용한다. YAML 문법 오류와 cloud-init 스키마 오류는 별개이므로 파일을 만든 뒤 두 검사를 나눠 실행한다. cloud-init이 사용자나 SSH 키 설정을 적용하지 못하면 결과적으로 SSH 접속 실패가 먼저 보일 수 있으므로, 게스트에서는 `cloud-init status --long`과 로그도 함께 확인한다. 설정 파일은 내용 자체를 확인할 수 있도록 편집기로 작성한다.
이 실험대는 값 셋을 한 번에 치환했다.
@@ -245,7 +245,7 @@ Valid cloud-config: /home/donghyeon/kc-lab-edge.yaml
통과하면 유효하다는 한 줄만 나오고, 아니면 `Invalid cloud-config` 아래에 어느 키가 왜 틀렸는지가 나열된다. `deprecated` 경고와 `error` 는 다르다 — 경고는 지금 동작한다.
YAML 로 파싱되는 것과 cloud-config 로 유효한 것은 다르다. 키 이름 오타(`user` 와 `users`)는 앞의 두 `grep` 도, YAML 파서도 그냥 통과한다. 오류가 나면 그 키는 조용히 무시되고, `users` 를 `user` 로 잘못 쓰면 계정이 안 생기며, 증상은 역시 「SSH 가 안 붙는다」 하나로만 나타난다.
YAML 문법이 맞는 것과 cloud-config 스키마가 맞는 것은 다르다. 예를 들어 `users`를 `user`로 잘못 적어도 YAML 파싱 자체는 성공할 수 있으므로 `cloud-init schema`로 한 번 더 확인한다. 게스트가 기대한 사용자나 SSH 키를 만들지 못했다면 `cloud-init status --long`과 로그에서 적용 결과를 확인한다.
이 파일에는 콘솔 비밀번호가 평문으로 들어 있다. `/tmp` 가 아니라 자기 홈에 `600` 으로 두고 검사가 끝나면 바로 지운다. `scp` 가 만드는 동안에는 파일이 잠깐 기본 권한으로 놓이므로 ⑤ 를 바로 뒤에 둔다.
@@ -309,7 +309,7 @@ stat -c%s seed-kc-lab-1.iso
정상이면 `default` 풀에 `seed-kc-lab-1.iso` 가 잡히고 `Capacity` 가 방금 만든 로컬 파일 크기와 같다.
시드는 `cidata` 라벨이 붙고 안에 `user-data` 와 `meta-data` 라는 정확한 이름의 파일이 있는 볼륨이어야 한다. `vol-create-as` 는 빈 볼륨을 만들 뿐이고 내용은 `vol-upload` 가 채운다. 뒤엣것을 빠뜨리면 목록에는 이름이 보이는데 안이 0 으로 채워져 있고, cloud-init 은 `cidata` 라벨을 못 찾아 조용히 끝난다 — 증상은 또 「SSH 가 안 붙는다」다. `instance-id` 를 매번 다른 값으로 두는 것은 cloud-init 이 인스턴스마다 한 번만 초기화 모듈을 돌리기 때문이고, id 가 같으면 user-data 를 고쳐도 반영되지 않는다.
시드는 `cidata` 라벨과 `user-data`, `meta-data` 파일을 포함해야 한다. `vol-create-as`는 볼륨만 만들고 실제 ISO 내용은 `vol-upload`가 채우므로 두 단계를 모두 수행한다. 업로드가 빠지면 libvirt 목록에는 볼륨 이름이 있어도 유효한 NoCloud 시드가 되지 않는다. `instance-id`는 게스트를 다시 만들 때 바꿔 cloud-init이 새 인스턴스로 처리하도록 한다.
이 실험대는 meta-data 를 명령으로 만들었다.
@@ -428,7 +428,7 @@ Domain creation completed.
:::warning
시드를 `--cloud-init` 으로 붙이지 않는다. 그 옵션은 시드를 SATA CD-ROM 으로 붙이는데 Debian genericcloud 이미지는 크기를 줄이려고 물리 하드웨어 드라이버를 뺐고, AHCI 장치가 보이지 않아 cloud-init 이 데이터소스를 못 찾고 조용히 끝난다. `bus=virtio` 로 디스크로 붙여야 한다.
이 실험대에서는 `--cloud-init`으로 연결한 시드에서 기대한 NoCloud 데이터소스를 확인하지 못했다. 반면 seed ISO를 `bus=virtio` 디스크로 붙인 구성에서는 게스트의 `cloud-init status --long`에서 `DataSourceNoCloud [seed=/dev/vdb]`를 확인했다. 따라서 현재 절차는 실제로 확인한 virtio seed 방식을 사용한다. 현재 증거만으로 `--cloud-init` 경로가 기대대로 동작하지 않은 원인을 특정하지 않는다.
:::
@@ -459,7 +459,7 @@ Domain creation completed.
호스트 RAM 11,648MiB 는 2026-09-10 에 이 호스트에서 `free -m | head -2` 로 받은 `Mem:` 행의 `total` 이다. `free -m` 은 MiB 로 찍으므로, 자기 호스트에서 이 배치를 다시 잡을 때도 같은 명령으로 재고 MiB 로 읽는다.
표의 메모리 칸은 `virt-install --memory`에 준 값이다. 2026-09-10의 historical snapshot에서는 `kc-lab-2`의 `dommemstat actual`이 3120MB로 나왔지만, 그 원인은 당시 확인되지 않았다. 2026-09-21에는 `dominfo`와 `dommemstat`을 나란히 읽어 configured/current/actual이 모두 4096MiB인 것을 확인했다. virtio-balloon 장치는 실제로 존재하지만 **장치 존재만으로 과거 3120MB의 원인을 balloon이라고 귀속하지 않는다.**
표의 메모리 칸은 `virt-install --memory`에 준 값이다. 2026-09-10 기록에서는 `kc-lab-2`의 `dommemstat actual`이 3120MB로 나왔지만, 그 원인은 당시 확인되지 않았다. 2026-09-21에는 `dominfo`와 `dommemstat`을 나란히 읽어 configured/current/actual이 모두 4096MiB인 것을 확인했다. virtio-balloon 장치는 실제로 존재하지만 **장치 존재만으로 과거 3120MB의 원인을 balloon이라고 귀속하지 않는다.**
vCPU 합은 2 + 2 + 1 = 5 이고 이 호스트의 논리 코어는 8 이다. libvirt 는 vCPU 합이 논리 코어 수를 넘어도 막지 않으므로, 더 크게 잡아도 `virt-install` 은 통과한다. 여유를 둘지는 이 표에서 정한다.
@@ -591,7 +591,7 @@ kc-lab-edge.qcow2 Capacity=10.00 GiB Allocation=316.26 MiB
seed-kc-lab-{1,2,edge}.iso Capacity=370.00 KiB Allocation=372.00 KiB
```
`net-dumpxml default --inactive` 는 `virbr0` 과 동적 대역 한 줄과 예약 세 줄을 낸다 — `--inactive` 를 붙여도 예약이 그대로 보이는 것이 `--config` 로 넣었다는 증거다.
`net-dumpxml default --inactive`에서는 `virbr0`, 동적 DHCP 대역, 예약 세 줄이 함께 보였다. `--inactive` 출력에도 예약이 남아 있으므로 해당 예약이 영구 설정에 포함된 것을 확인할 수 있다.
- 2026-09-17의 `cloud-init status --long` 마지막 줄은 이 문서의 7번 설명과 일치했다.
@@ -603,11 +603,11 @@ detail:
DataSourceNoCloud [seed=/dev/vdb][dsmode=net]
```
`seed=/dev/vdb` 가 핵심이다. 시드를 `--cloud-init` 으로 붙였다면 SATA CD-ROM(`sr0`)이 됐을 텐데, `bus=virtio` 로 디스크로 붙였기 때문에 `vdb` 로 잡혔고 cloud-init 이 거기서 데이터소스를 찾았다. 7번이 적은 이유가 이 한 줄로 확인된다.
확인할 값은 `DataSourceNoCloud [seed=/dev/vdb]`다. 현재 구성에서는 seed ISO를 virtio 디스크로 붙였고, cloud-init이 `/dev/vdb`에서 데이터소스를 읽는 것을 실제 게스트에서 확인했다.
- 파일을 옮겨 검사하는 다섯 줄 형태와 `virsh console` 은 가이드가 적어 둔 명령이고 이 실험대가 캡처한 출력이 없다. `virsh console` 은 대화형이라 비대화식으로 밟지 않았다.
- 편집기로 `kc-lab-1.yaml` 과 `meta-kc-lab-1` 을 여는 형태도 이 실험대가 치지 않았다. 이 실험대는 치환 명령과 서식 출력으로 만들었고, 같은 상태에 닿는지는 다시 재지 않았다.
- 원본 가이드에 되돌리는 절차가 없다. 단계 03 이 지나가며 적은 한 줄 말고는 게스트와 시드 볼륨과 DHCP 예약을 걷어내는 순서가 어디에도 없다.
- 세 게스트와 seed volume, DHCP 예약을 모두 제거하는 전체 rollback은 아직 끝까지 검증하지 않았다.
- 2026-09-21에는 `kc-lab-1`과 `kc-lab-2`를 실제로 철거한 뒤 이 절차의 cloud-init·qcow2 overlay·DHCP 예약·`virt-install` 경로로 다시 만들었고, 두 worker가 Debian 12로 부팅해 SSH와 cloud-init을 통과한 뒤 k3s 클러스터에 다시 합류하는 것까지 확인했다. 따라서 **worker 두 대의 재생성 경로는 재검증됐다.** `kc-lab-edge` 전체 삭제·재생성은 실제 TLS 종단점과 인증서를 보존하기 위해 이번 재검증에서 수행하지 않았으므로, 세 VM 전체를 한 번에 비운 뒤 다시 만드는 경로까지 확인됐다고 쓰지는 않는다.
<!-- body:end -->
@@ -39,7 +39,7 @@ sourceRevision: import-head 9465582b5d1630eb4ae7c4e078021486919bf6b6 · uncommit
| 1 | nginx 설치와 기본 사이트 끄기 | `[kc-lab-edge]` |
| 2 · 3 | 라우팅 설정과 링크 · 문법 검사와 reload | `[kc-lab-edge]` |
| 4 | DNAT 파일 | `[lab host]` — 여기만 엣지가 아니다 |
| 5 | systemd 유닛과 libvirt 구멍 | `[lab host]` |
| 5 | systemd 유닛과 libvirt 허용 규칙 | `[lab host]` |
| 판정 | 층별 확인 ①~④ | `[lab host]` 와 `[워크스테이션]` |
**4번과 5번만 호스트에서 치는 까닭이 둘이다.** DNAT 규칙의 첫 줄이 `iifname "tailscale0"` 인데 VM 에는 Tailscale 을 넣지 않기로 했으므로 엣지에는 그 인터페이스 자체가 없고, 넘기는 대상이 `192.168.122.10` 으로 가는 트래픽이라 넘기는 주체는 그 앞에 있는 호스트다. 엣지에 들어가서 치면 `tailscale0` 이 없어 규칙이 의미가 없다.
@@ -76,7 +76,7 @@ sourceRevision: import-head 9465582b5d1630eb4ae7c4e078021486919bf6b6 · uncommit
| 엣지 nginx (`kc-lab-edge`) | 바깥세상과의 접점 — TLS 종단 · 인증서 · `X-Forwarded-*` |
| Traefik | 클러스터 안의 동적 라우팅 — Ingress 를 보고 서비스를 고른다 |
이 2홉이 운영 구조와 같다는 것이 이 배치의 핵심이고, 동시에 헤더 실험이 성립하는 근거가 된다. 1홉을 가정하고 쓴 계약이 2홉에서도 유효한지를 재려면 두 겹이 있어야 한다.
이 배치에서는 nginx와 Traefik 두 L7 홉을 모두 통과한다. forwarded 헤더가 두 프록시를 지나는 동안 어떻게 바뀌는지 확인하려면 두 계층을 그대로 둔 상태에서 측정해야 한다.
## 방화벽과 기존 NAT 규칙을 바꾸기 전에 확인한다
@@ -88,7 +88,7 @@ sourceRevision: import-head 9465582b5d1630eb4ae7c4e078021486919bf6b6 · uncommit
|---|---|---|
| DNAT 만 끈다 | `[lab host]` | `sudo systemctl disable --now lab-edge-dnat.service` |
| 규칙만 즉시 걷어낸다 | `[lab host]` | `sudo nft delete table ip lab_edge` |
| libvirt 에 뚫은 구멍을 막는다 | `[lab host]` | `sudo nft -a list chain ip libvirt_network guest_input` 로 handle 을 보고 `sudo nft delete rule ip libvirt_network guest_input handle <번호>` |
| libvirt에 추가한 허용 규칙을 제거한다 | `[lab host]` | `sudo nft -a list chain ip libvirt_network guest_input` 로 handle 을 보고 `sudo nft delete rule ip libvirt_network guest_input handle <번호>` |
| 엣지 라우팅을 끈다 | `[kc-lab-edge]` | `sudo rm /etc/nginx/sites-enabled/keycloak-lab && sudo nginx -t && sudo systemctl reload nginx` |
| 클러스터 안에 더한 이름을 걷어낸다 | `[lab host]` | `kubectl -n kube-system delete configmap coredns-custom` 하고 `kubectl -n kube-system delete pod -l k8s-app=kube-dns` |
@@ -117,7 +117,7 @@ donghyeon@kc-lab-edge:~$ cd /etc/nginx/
-bash: cd: /etc/nginx/: No such file or directory
```
`/etc/nginx` 디렉터리는 패키지가 만든다. 그것이 없다는 것은 경로를 잘못 짚었다는 뜻이 아니라 설치가 안 됐다는 뜻이다. 앞 단계의 cloud-init 목록에 nginx 가 없으므로 1번에서 깐다.
Debian의 nginx 패키지를 설치하면 `/etc/nginx` 디렉터리가 만들어진다. 이 실험대의 cloud-init에는 nginx 설치가 포함돼 있지 않으므로 1번에서 패키지를 설치하고 디렉터리가 생겼는지 확인한다.
**여기에 `which nginx` 를 쓰지 않는다.** 깔려 있을 때도 똑같이 아무것도 안 찍힌다 — 2026-09-17 에 nginx 가 돌고 있는 엣지에서 직접 쳐서 확인했다.
@@ -196,9 +196,9 @@ server {
ls /etc/nginx/sites-available/
```
정상이면 ③ 의 목록에 `keycloak-lab` 이 보인다. nginx 는 아직 이 파일을 읽지 않고, 읽게 만드는 것이 3번이다.
정상이면 ③의 목록에 `keycloak-lab`이 보인다. 이 시점에는 파일만 만들어졌고 nginx 설정에는 아직 포함되지 않았다. 다음 단계에서 `sites-enabled`에 연결한 뒤 설정 검사를 통과하면 nginx가 읽는다.
이 단계에서는 80 만 세운다. 인증서가 없는데 `ssl_certificate` 줄을 미리 써 두면 설정 전체가 실패해서 80 블록까지 안 뜬다 — nginx 는 그 파일을 나중이 아니라 기동과 reload 시점에 읽는다. `X-Forwarded-Proto` 가 `http` 인 것도 지금이 그렇기 때문이고, 다음 단계에서 `https` 로 바뀐다. 실제로 80 으로 들어오는데 `https` 라고 적으면 Keycloak 이 리다이렉트 주소를 `https://` 로 만들고 로그인 도중에 끊긴다. upstream 이 둘인 것은 두 노드 모두 Traefik 이 뜨기 때문이고, nginx 는 기본 라운드로빈으로 번갈아 보내다가 한쪽이 죽으면 자동으로 뺀다.
이 단계에서는 80 만 세운다. 인증서가 없는데 `ssl_certificate` 줄을 미리 써 두면 설정 전체가 실패해서 80 블록까지 안 뜬다 — nginx 는 그 파일을 나중이 아니라 기동과 reload 시점에 읽는다. `X-Forwarded-Proto` 가 `http` 인 것도 지금이 그렇기 때문이고, 다음 단계에서 `https` 로 바뀐다. 실제로 80 으로 들어오는데 `https` 라고 적으면 Keycloak 이 리다이렉트 주소를 `https://` 로 만들고 로그인 도중에 끊긴다. 두 k3s 노드 모두 Traefik을 실행하므로 nginx upstream에도 두 주소를 등록한다. 별도 분산 알고리즘을 지정하지 않았기 때문에 nginx는 기본 라운드로빈으로 요청을 보내고, 한 upstream에 연결할 수 없으면 다른 upstream을 시도한다.
:::warning
@@ -250,7 +250,7 @@ nginx: configuration file /etc/nginx/nginx.conf test is successful
**판정은 `syntax is ok` 와 `test is successful` 두 마디로만 한다.** `[warn]` 줄은 나오면 무시하고 안 나오면 없는 대로 둔다 — 없다고 설정이 덜 읽힌 것이 아니다. 통과했으면 `&&` 뒤의 reload 가 이어서 돌고 `systemctl reload` 는 아무 말 없이 끝난다.
`&&` 로 이은 것은 문법이 깨진 설정으로 reload 하지 않으려는 것이다. 실패면 `[emerg]` 줄에 파일과 줄 번호가 찍히고 reload 는 아예 안 돌아, 지금 돌고 있는 nginx 는 옛 설정 그대로 멀쩡하다. 경고와 오류를 여기서 갈라 두면 다음 단계에서 같은 `types_hash` 경고를 실패로 오독하지 않는다. ④ 의 프로세스 트리에서 워커 줄의 PID 를 눈에 담아 둔다 — reload 는 마스터를 그대로 두고 워커만 갈아 끼우므로, 전후로 워커 PID 가 바뀌면 새 설정이 적용된 것이다. 다음 단계에서 인증서 갱신이 서빙까지 닿았는지를 똑같은 방법으로 판정한다.
`nginx -t && systemctl reload nginx`처럼 연결하면 설정 검사가 성공했을 때만 reload를 실행한다. 문법 오류가 있으면 `[emerg]`에 파일과 줄 번호가 나오고 현재 nginx 프로세스는 기존 설정으로 계속 동작한다. `types_hash` 같은 `[warn]`과 실제 `[emerg]` 오류를 구분해 확인한다. reload 전후의 worker PID가 바뀌면 새 설정을 읽은 것도 확인할 수 있으며, 인증서 갱신 뒤 reload를 확인할 때도 같은 방법을 사용한다.
실패하면 `unknown directive "http2"` 가 나오면 nginx 판 번호를 본다. Debian 12 는 1.22 이고 그 지시어는 1.25.1 부터다. `systemctl reload` 가 실패하면 reload 말고 `sudo nginx -t` 를 먼저 친다.
@@ -291,7 +291,7 @@ table ip lab_edge {
디렉터리가 없으면 `nano` 가 저장할 곳을 못 찾으므로 ① 을 먼저 친다. `table ip lab_edge` 와 `delete table ip lab_edge` 두 줄이 파일 맨 앞에 있는 것은 없는 테이블을 지우면 에러가 나기 때문이다. 한 번 만들고 지우면 같은 파일을 몇 번 적용해도 안전해진다. tailnet 주소 `100.83.212.4` 의 80 과 443 을 받는 것은 여전히 물리 호스트이고, 그 트래픽을 엣지로 넘기는 일이 물리 호스트가 실험대를 위해 하는 일의 전부다 — 이 규칙 하나와 게스트를 만들 때 넣은 DHCP 예약 세 줄이고, 둘 다 한 번 쓰고 다시 안 건드린다.
`prerouting` 체인 뒤에 빈 줄이 하나 남아 있다. 처음 쓴 파일에는 거기에 `priority filter - 10` 으로 먼저 도는 `forward` 체인이 있었고 `ct state new accept` 를 넣어 두었는데, 밖에서 오는 요청은 그래도 통과하지 못했다. 앞 체인의 `accept` 는 「이 체인은 통과」라는 뜻이지 「평가 끝」이 아니라서, 같은 훅에 붙은 뒤 체인이 그대로 `reject` 한다. 그래서 그 체인을 지웠고, 구멍은 5번에서 libvirt 체인 안에 뚫는다.
`prerouting` 체인 뒤에 빈 줄이 하나 남아 있다. 처음 쓴 파일에는 거기에 `priority filter - 10` 으로 먼저 도는 `forward` 체인이 있었고 `ct state new accept` 를 넣어 두었는데, 밖에서 오는 요청은 그래도 통과하지 못했다. 앞 체인의 `accept` 는 「이 체인은 통과」라는 뜻이지 「평가 끝」이 아니라서, 같은 훅에 붙은 뒤 체인이 그대로 `reject` 한다. 그래서 해당 `forward` 체인은 제거했고, 외부에서 Edge VM의 80·443 포트로 들어오는 새 연결은 5번에서 libvirt `guest_input` 체인에 허용 규칙으로 추가한다.
:::warning
@@ -307,7 +307,7 @@ grep dport /etc/nftables.d/lab-edge-dnat.nft
### 5. 호스트에 systemd 유닛을 쓰고 켠다
**목적** — DNAT 테이블을 부팅할 때 적용한다. 아래 `ExecStartPost` 는 과거에 libvirt `guest_input`의 `reject` 앞에 구멍을 함께 넣기 위해 사용한 형태다. 하지만 2026-09-21 재검증에서 libvirt가 나중에 체인을 다시 구성하면 이 규칙이 `reject` 뒤로 밀릴 수 있음이 확인됐다. 따라서 이 줄은 현재 동작을 설명하는 임시 구성이지, 검증이 끝난 persistence 해법이 아니다. 대체 방식은 아직 확인하지 않았다.
**목적** — DNAT 테이블을 부팅할 때 적용한다. 아래 `ExecStartPost`는 과거에 libvirt `guest_input`의 `reject` 앞에 허용 규칙을 추가하기 위해 사용한 형태다. 하지만 2026-09-21 재검증에서 libvirt가 나중에 체인을 다시 구성하면 이 규칙이 `reject` 뒤로 밀릴 수 있음이 확인됐다. 따라서 이 줄은 현재 동작을 설명하는 임시 구성이지, 검증이 끝난 persistence 해법이 아니다. 대체 방식은 아직 확인하지 않았다.
```bash label="[lab host] ① 유닛 파일을 연다. 경로를 system 까지 끝까지 친다"
sudo nano /etc/systemd/system/lab-edge-dnat.service
@@ -352,15 +352,15 @@ sudo systemctl enable --now lab-edge-dnat.service
| tailnet 으로 들어온 80 과 443 을 `192.168.122.10` 으로 넘긴다 | 우리 테이블 `lab_edge` (`.nft` 파일) |
| 그 주소로 가는 새 연결을 통과시킨다 | libvirt 테이블 `libvirt_network` 의 `guest_input` 체인 (유닛의 `ExecStartPost`) |
libvirt 는 게스트 대역으로 새로 들어오는 연결을 거절한다. 자기 테이블의 `guest_input` 체인이 `established,related` 만 받고 나머지를 `reject` 로 끝내기 때문인데, 우리 테이블에 아무리 먼저 `accept` 를 놔도 소용이 없다. 그래서 처음에는 구멍을 libvirt 체인 맨 앞에 `insert` 하고, 유닛의 `ExecStartPost` 로 다시 넣는 방식을 썼다. `add` 로 맨 뒤에 붙이면 `reject` 뒤라 의미가 없기 때문이다.
libvirt 는 게스트 대역으로 새로 들어오는 연결을 거절한다. 자기 테이블의 `guest_input` 체인이 `established,related` 만 받고 나머지를 `reject` 로 끝내기 때문인데, 우리 테이블에 아무리 먼저 `accept` 를 놔도 소용이 없다. 그래서 처음에는 Edge VM 80·443 허용 규칙을 libvirt 체인의 `reject` 앞에 `insert`하고, 유닛의 `ExecStartPost`에서 다시 추가하는 방식을 썼다. `add` 로 맨 뒤에 붙이면 `reject` 뒤라 의미가 없기 때문이다.
문제는 이 방식이 **유닛이 시작되는 순간에만** 규칙을 넣는다는 점이다. 2026-09-21 worker 재구축에서는 유닛이 계속 `active` 인 동안 libvirt가 `guest_input`을 다시 만들었고, 기존 accept 규칙이 `reject` 뒤로 밀렸다. 따라서 `ExecStartPost`를 persistence 해법으로 보지 않는다. 아래 명령은 현재 장애를 복구하거나 동작을 확인하는 임시 수단으로만 읽는다.
`ExecStartPost` 앞의 `-` 는 그 명령이 실패해도 유닛을 실패로 보지 않는다는 뜻이다. `libvirt_network` 테이블은 가상 네트워크가 떠 있어야 존재하는데 부팅 순서에 따라 이 유닛이 먼저 돌 수 있고, `-` 가 없으면 구멍이 안 들어가면서 DNAT 까지 같이 안 실린다. `-` 를 두고 감수한 것이 그 반대쪽이다 — DNAT 만 실리고 구멍이 빠진 상태에서도 유닛은 `active` 이고 아무 오류도 안 남는다. 그래서 `systemctl is-active` 가 `active` 라는 것은 DNAT 이 실렸다는 뜻이지 구멍이 뚫렸다는 뜻이 아니고, 그 상태는 호스트 안에서는 되는데 밖에서만 안 되는 형태로 아래 확인 ③ 에서야 드러난다. 이 실험대가 그 상태를 일부러 만들어 확인해 보지는 않았다.
`ExecStartPost` 앞의 `-` 는 그 명령이 실패해도 유닛을 실패로 보지 않는다는 뜻이다. `libvirt_network` 테이블은 가상 네트워크가 떠 있어야 존재하는데 부팅 순서에 따라 이 유닛이 먼저 돌 수 있고, `-`가 없으면 허용 규칙 추가 명령의 실패 때문에 DNAT 유닛 전체가 실패할 수 있다. 반대로 `-`를 두면 DNAT만 적용되고 허용 규칙이 없는 상태에서도 유닛은 `active`일 수 있다. 따라서 `systemctl is-active`의 `active`만으로 `guest_input` 허용 규칙까지 적용됐다고 판단하지 않고, 그 상태는 호스트 안에서는 되는데 밖에서만 안 되는 형태로 아래 확인 ③ 에서야 드러난다. 이 실험대가 그 상태를 일부러 만들어 확인해 보지는 않았다.
손으로 한 번 넣어 볼 때와 날아갔을 때 다시 넣을 때는 이렇다.
```bash label="[lab host] 손으로 구멍을 한 번 넣어 본다"
```bash label="[lab host] guest_input 앞에 Edge VM 허용 규칙을 추가한다"
sudo nft insert rule ip libvirt_network guest_input oif virbr0 ip daddr 192.168.122.10 tcp dport '{80,443}' ct state new counter accept
```
@@ -395,7 +395,7 @@ sudo nft list table ip lab_edge
| nginx (엣지) | Debian 12 의 `nginx/1.22.1` |
| upstream | `192.168.122.11:80` · `192.168.122.12:80` — 기본 라운드로빈 |
| DNAT | `iifname "tailscale0" tcp dport { 80, 443 } dnat to 192.168.122.10` |
| libvirt 구멍 | 유닛의 `ExecStartPost` 가 `guest_input`에 `insert`. **2026-09-21에는 libvirt가 체인을 다시 만든 뒤 이 규칙이 reject 뒤로 밀려 외부 경로가 다시 끊겼다** |
| libvirt 허용 규칙 | 유닛의 `ExecStartPost`가 `guest_input`에 `insert`. **2026-09-21에는 libvirt가 체인을 다시 만든 뒤 이 규칙이 reject 뒤로 밀려 외부 경로가 다시 끊겼다** |
| source rewrite | `lab_edge` 자체에는 SNAT 없음. 그러나 현재 host의 Tailscale `ts-postrouting` MASQUERADE 때문에 edge에서 source가 `192.168.122.1`로 관측됨 |
PREROUTING nat 은 라우팅 결정보다 먼저 도므로 이 규칙이 호스트 자신의 443 소켓보다 우선한다. 그래서 물리 호스트에 nginx 가 아직 떠 있어도 트래픽은 엣지로 가고, 전환이 원자적이며 되돌리기도 한 줄이 된다.
@@ -434,7 +434,7 @@ curl -s -o /dev/null -w '%{http_code}\n' http://192.168.122.11
curl -s -o /dev/null -w '%{http_code}\n' http://192.168.122.12
```
`.11` 에서 잰 값이 `404` 였다. 둘이 같으면 nginx 가 어느 쪽으로 보내도 같은 결과가 나온다. 한쪽만 다르면 upstream 둘 중 하나가 죽은 것이고, 그 상태에서는 요청의 절반만 실패해서 「가끔 안 된다」로 보인다.
`.11` 에서 잰 값이 `404` 였다. 둘이 같으면 nginx 가 어느 쪽으로 보내도 같은 결과가 나온다. 한쪽만 다르면 upstream 둘 중 하나가 정상 응답을 내지 못하는 상태이고, 그 상태에서는 요청의 절반만 실패해서 「가끔 안 된다」로 보인다.
### 확인 ② 엣지 nginx 가 직접 응답하나
@@ -457,7 +457,7 @@ Content-Length: 19
404 page not found
```
`Server:` 가 `nginx/1.22.1` 이고 본문이 Traefik 의 `404 page not found` 라는 것이 엣지가 받아서 Traefik 으로 넘겼다는 증거다. **이 층의 통과 기준은 코드값이 아니라 「`curl: (7)` 없이 응답이 온다」와 `Server: nginx` 두 가지다.** 여기서 막히면 문제는 엣지 안이다. 통과하는데 아래 ③ 이 안 되면 문제는 DNAT 이다. 이 한 층을 끼워 두면 그 둘을 헷갈리지 않는다.
응답의 `Server:`가 `nginx/1.22.1`이고 본문이 Traefik의 `404 page not found`라면 요청이 Edge Nginx를 거쳐 Traefik까지 전달된 상태다. **이 층의 통과 기준은 코드값이 아니라 「`curl: (7)` 없이 응답이 온다」와 `Server: nginx` 두 가지다.** 여기서 막히면 문제는 엣지 안이다. 통과하는데 아래 ③ 이 안 되면 문제는 DNAT 이다. 이 한 층을 끼워 두면 그 둘을 헷갈리지 않는다.
### 확인 ③ 밖에서, 즉 DNAT 을 거쳐 닿나
@@ -500,7 +500,7 @@ curl -s -o /dev/null -w '%{http_code} %{redirect_url}\n' http://auth.hyeonworks.
마지막 줄이 중요하다 — **TLS 를 얹기 전에도 `/realms/master` 는 `200` 이다.** 층 ④ 의 `200` 은 「TLS 가 섰다」가 아니라 「끝까지 이어졌다」를 재는 값이고, `https` 로 그 값을 받는 것이 04 의 몫이다.
밖에서 닿지 않을 때의 모양도 적어 둔다. 2026-09-17 에 구멍을 뚫기 전에는 이랬다.
외부 요청이 차단될 때의 상태도 확인했다. 2026-09-17 허용 규칙을 추가하기 전에는 다음과 같았다.
```text
curl: (7) Failed to connect to auth.hyeonworks.com port 80 after 54 ms
@@ -539,12 +539,12 @@ journalctl -u nginx -f # 지금 벌어지는 것
각 줄의 괄호 안 errno 와 그 뒤의 upstream 주소, 그리고 타임스탬프. 방금 친 요청 시각과 안 맞으면 지금 보고 있는 것은 옛 사고다.
`-p err` 로 걸러도 아무것도 안 나오면 nginx 는 정상이고 문제는 더 위에 있다. 둘째 명령은 띄워 놓은 채로 다른 창에서 요청을 치는 용도이고, 끝내려면 Ctrl+C 를 누른다. upstream 이 둘이라 한쪽이 죽으면 nginx 가 자동으로 빼는데, 2026-09-17에는 그 동작이 아래 세 줄로 남았다.
`-p err` 로 걸러도 아무것도 안 나오면 nginx 는 정상이고 문제는 더 위에 있다. 둘째 명령은 띄워 놓은 채로 다른 창에서 요청을 치는 용도이고, 끝내려면 Ctrl+C 를 누른다. upstream이 둘이라 한쪽에 연결할 수 없으면 nginx가 다른 upstream을 사용하며, 2026-09-17에는 그 동작이 아래 세 줄로 남았다.
```text
connect() failed (113: No route to host) ← 호스트에 못 닿는다
connect() failed (111: Connection refused) ← 포트에 아무도 없다
no live upstreams ← 둘 다 죽었다고 판단
no live upstreams ← 사용할 수 있는 upstream이 없다고 판단
```
113 과 111 은 대응이 다르다 — 113 은 네트워크고 111 은 프로세스다. 노드를 잃었을 때 이 세 줄이 1분 안에 순서대로 나왔다.
@@ -569,7 +569,7 @@ grep oauth2/callback /var/log/nginx/access.log | tail -1 | wc -c
|---|---|---|
| nginx 문법 | `sudo nginx -t` | `syntax is ok` · `test is successful` |
| 링크 | `ls -l /etc/nginx/sites-enabled/` | `keycloak-lab` 이 있고 `default` 가 없다 |
| 유닛 | `systemctl is-active lab-edge-dnat.service` | `active` — 이것만으로 `guest_input` 구멍까지 정상이라는 뜻은 아니다 |
| 유닛 | `systemctl is-active lab-edge-dnat.service` | `active` — 이것만으로 `guest_input` 허용 규칙까지 정상이라는 뜻은 아니다 |
| libvirt 체인 | `sudo nft -a list chain ip libvirt_network guest_input` | edge용 `accept`가 `reject`보다 앞에 있는지 직접 확인 |
| 우리 테이블 | `sudo nft list table ip lab_edge` | `dnat to 192.168.122.10` · 포트 `80, 443` · **이 테이블 안에는** SNAT 없음 |
| host 전체 source rewrite | `sudo nft list ruleset` | 출력에서 `masquerade`·`snat` 규칙을 찾는다. 현재 환경에는 Tailscale `ts-postrouting` MASQUERADE가 존재하므로 원본 IP 보존을 별도 판정 |
@@ -584,7 +584,7 @@ grep oauth2/callback /var/log/nginx/access.log | tail -1 | wc -c
| 증상 | 어디서 끊겼나 | 확인 |
|---|---|---|
| ① 이 연결 거부 | Traefik 이 안 떴거나 게스트가 죽음 | `kubectl get pods -n kube-system` |
| ① 이 연결 거부 | Traefik 미기동 또는 게스트 중단 | `kubectl get pods -n kube-system` |
| ① 이 `502` | Traefik 은 떴는데 백엔드가 없음 | Ingress 확인 |
| ② 가 응답 없음 | nginx 가 안 떴거나 방화벽 | `systemctl status nginx` |
| ③ 이 `502` | 인증서 문제 또는 upstream 다운 | 다음 단계 · 위 확인 ⑤ |
@@ -596,7 +596,7 @@ grep oauth2/callback /var/log/nginx/access.log | tail -1 | wc -c
| `cp: cannot stat 'deploy/...'` | 엣지에서 쳤거나 lab host 에 저장소가 없다 | `ls ~/workspace` |
| `Unit lab-edge-dnat.service does not exist` | 유닛이 없거나 `/etc/systemd/` 에 썼거나 `daemon-reload` 를 안 했다 | `find /etc/systemd -name 'lab-edge-dnat*'` |
| 80 은 되는데 HTTPS 만 안 된다 | `.nft` 의 포트가 `433` 오타 | `grep dport /etc/nftables.d/lab-edge-dnat.nft` |
| 호스트 안에서는 404 인데 밖에서만 connection refused | libvirt `guest_input` 의 `reject`. 구멍이 빠졌거나 날아갔다 | `sudo nft -a list chain ip libvirt_network guest_input` — `reject` 줄의 카운터가 올라가면 여기다 |
| 호스트 안에서는 404 인데 밖에서만 connection refused | libvirt `guest_input`의 `reject`. Edge VM 허용 규칙이 없거나 libvirt 체인 재작성 뒤 순서가 바뀌었다 | `sudo nft -a list chain ip libvirt_network guest_input` — `reject` 줄의 카운터가 올라가면 여기다 |
| `Error: syntax error, unexpected ct` | 셸이 `{80,443}` 을 펼쳤다 | `'{80,443}'` 로 따옴표 |
## 배포된 것과 적어 둔 것이 다르다
@@ -608,7 +608,7 @@ grep oauth2/callback /var/log/nginx/access.log | tail -1 | wc -c
| `lab-edge-dnat.nft` | `prerouting` 뒤에 `forward` 체인이 그대로 있다 (`priority filter - 10` · `ct state new accept`) | 그 체인이 없다. 자리에 왜 뺐는지 주석만 남겼다 |
| `lab-edge-dnat.service` | `ExecStartPost` 줄이 없다 | `ExecStartPost=-…insert rule ip libvirt_network guest_input…` 이 있다 |
**이것이 위 확인 ③ 의 `curl: (7)` 을 그대로 설명한다.** 고친 쪽의 요점은 앞 체인의 `accept` 로는 뒤 체인의 `reject` 를 못 막으니 구멍은 libvirt 체인 안에 뚫는다는 것인데, 호스트에는 **효과가 없는 쪽만 깔려 있고 효과가 있는 쪽은 안 깔려 있다.** 게다가 그 구멍은 런타임 상태라 libvirt 가 네트워크를 다시 세우면 날아가고, 다시 넣어 줄 `ExecStartPost` 가 유닛에 없으니 **실험대를 다시 세운 직후에는 밖에서 못 들어온다.**
**이것이 위 확인 ③ 의 `curl: (7)` 을 그대로 설명한다.** 앞 base chain의 `accept`만으로는 뒤쪽 libvirt `reject`를 피할 수 없으므로 허용 규칙은 `guest_input` 안에서 `reject`보다 앞에 있어야 한다. 당시 호스트에는 앞쪽 `forward` accept만 있고 `guest_input` 허용 규칙을 다시 넣는 `ExecStartPost`가 배포되지 않아, 재구성 직후 외부 요청이 차단됐다.
**그래서 4번과 5번은 「이미 있으니 건너뛴다」로 넘기지 않는다.** 파일이 있는 것과 그 파일이 이 문서가 싣는 내용인 것은 다르다. 두 파일을 연 다음 위 본문과 한 줄씩 대조한다.
@@ -640,7 +640,7 @@ oif "virbr0" counter packets 5 bytes 300 reject
oif "virbr0" ip daddr 192.168.122.10 tcp dport { 80, 443 } ct state new counter packets 10 bytes 600 accept
```
**구멍이 하나가 아니라 셋이다.** `ExecStartPost` 가 `nft insert` 를 실행할 때마다 같은 규칙이 하나씩 더 생겼다. 이 명령은 재실행 안전하지 않다.
같은 허용 규칙이 세 개 중복돼 있었다. `ExecStartPost`가 실행될 때마다 조건 확인 없이 `nft insert`를 수행했기 때문에 같은 규칙이 누적됐다. 이 명령은 재실행 안전하지 않다.
2026-09-21에 worker VM 둘을 철거했다 다시 만드는 과정에서 더 큰 문제가 실제로 재현됐다. libvirt 가 `guest_input` 체인을 다시 구성하면서 세 accept 규칙이 `reject` 뒤로 밀렸다.
@@ -658,7 +658,7 @@ oif "virbr0" ip daddr 192.168.122.10 tcp dport { 80, 443 } ... accept
이 재검증에서는 기존 host firewall 을 임의 변경하지 않는 안전 조건 때문에 새 규칙 설계까지 적용하지 않았다. 현재 방식의 대체안은 아직 실제로 확인하지 않았다.
## 클러스터 안에서도 공개 이름에 못 닿는다 — 이 문서에 없던 또 한 단계
## 클러스터 내부에서도 공개 도메인이 Edge Nginx를 거치도록 설정한다
랩 호스트만의 일이 아니다. **파드 안에서도 같은 이름이 같은 이유로 막혔다.** 2026-09-17에 파드 안에서 직접 확인했다. 이름은 호스트의 tailnet 주소로 풀리는데 그 포트를 듣는 것이 없다.
@@ -706,7 +706,7 @@ kubectl -n kube-system delete pod -l k8s-app=kube-dns --wait=false
이 실험대는 같은 매니페스트를 `kubectl apply -f - <<'YAML'` 힙독으로 흘려 넣었다. 힙독은 ConfigMap 을 명령 안에 묻어 버려서, 서버 블록을 한 줄 고치려면 같은 힙독을 처음부터 다시 친다. 파일로 두면 열어 보고 고쳐서 ④ 를 다시 치면 된다. 이 나눈 형태는 이 실험대에서 치지 않았다.
**파일 이름이 `.server` 인 것이 핵심이다.** k3s 는 `*.override` 를 기본 서버 블록 안에 끼워 넣는데, 그 블록은 이미 `hosts /etc/coredns/NodeHosts` 로 `hosts` 를 한 번 쓰고 있다. `.override` 에 `hosts` 를 또 쓰면 CoreDNS 가 안 뜬다.
여기서는 파일 이름의 `.server` 접미사가 필요하다. k3s 는 `*.override` 를 기본 서버 블록 안에 끼워 넣는데, 그 블록은 이미 `hosts /etc/coredns/NodeHosts` 로 `hosts` 를 한 번 쓰고 있다. `.override` 에 `hosts` 를 또 쓰면 CoreDNS 가 안 뜬다.
```text label="`.override` 로 넣었을 때 — CrashLoopBackOff"
plugin/hosts: this plugin can only be used once per Server Block
@@ -800,9 +800,9 @@ chain ts-forward { iifname "tailscale0" counter ... xt target "MARK" }
libvirt 의 마스커레이드는 이 일과 무관하다. 그 규칙은 `ip saddr 192.168.122.0/24 ip daddr != 192.168.122.0/24` 이라 **게스트에서 밖으로 나가는** 것만 고르고, 밖에서 게스트로 들어오는 이 패킷은 목적지가 그 대역 안이라 안 걸린다.
범인보다 결과가 먼저다. `proxy_set_header X-Forwarded-For $remote_addr` 는 시키는 대로 동작하고 있고, 다만 `$remote_addr` 가 이미 호스트의 브리지 주소다. 그래서 **이 실험대의 `X-Forwarded-For` 는 진짜 클라이언트를 담지 않는다.** 통과 조건에 「엣지 로그의 출발지가 밖에서 친 기계다」를 넣으면 늘 실패한다.
`proxy_set_header X-Forwarded-For $remote_addr` 자체는 설정대로 동작하고 있다. 문제는 Edge Nginx에 도착한 시점의 `$remote_addr`가 이미 호스트의 브리지 주소라는 점이다. 따라서 현재 실험대의 `X-Forwarded-For`에는 원래 tailnet 클라이언트 주소가 남지 않는다. 이 상태에서는 Edge 로그의 출발지 주소를 외부 클라이언트 주소와 같다고 판정할 수 없다.
## Traefik 이 그 헤더를 다시 덮는다 — 이 문서에 없던 한 단계
## Traefik이 전달 헤더를 다시 쓰지 않도록 신뢰할 프록시를 지정한다
위 2번이 세운 헤더가 앱까지 가는지를 처음으로 재 봤다. **안 간다.** Traefik 은 자기가 신뢰하지 않는 곳에서 온 `X-Forwarded-*` 를 자기 연결 기준으로 다시 쓰고, 기본값에는 신뢰 목록이 비어 있다.
@@ -840,7 +840,7 @@ kubectl -n kube-system rollout status deploy/traefik --timeout=180s
- 이 이동으로 L7 홉 수가 2홉 그대로라는 판정이 이 배치의 전제다. 늘어난 것은 커널이 하는 L4 전달 한 번뿐이라 홉 수 자체는 맞다. 다만 **홉 수가 그대로여도 `X-Forwarded-*` 계약은 성립하지 않았다** — 위 두 절에서 실제로 재 보니 클라이언트 주소가 엣지에 닿기 전에 덮이고, Traefik 이 신뢰 목록 없이 한 번 더 덮었다.
- `curl -I http://192.168.122.11` 의 전체 출력은 캡처해 두지 않았다. 가이드도 봐야 할 줄만 적었다.
- `systemctl status nginx` 두 번과 `ls -l /etc/nginx/sites-enabled/`, 파일 찾기, 체인 조회, `journalctl -u nginx`, access 로그 두 줄은 가이드가 적어 둔 명령이고 출력이 남아 있지 않다.
- libvirt 의 `firewall_backend` 가 iptables 일 때도 `guest_input` 구멍이 필요한지는 재지 않았다. 이 호스트는 nftables 백엔드다.
- libvirt 의 `firewall_backend` 가 iptables 일 때도 `guest_input`에 같은 허용 규칙이 필요한지는 재지 않았다. 이 호스트는 nftables 백엔드다.
- 되돌리기 네 줄은 가이드 원문 그대로이고, 그 네 줄을 실제로 쳐서 걷어내 본 기록이 없다.
- 2026-09-21에는 worker 두 대를 실제 철거한 뒤 cloud-init → k3s → Keycloak/observability → power-cycle 복구까지 다시 수행했다. 다만 물리 host·edge VM·certificate 계층까지 비운 **완전한 00~06 재구축**은 아직 수행하지 않았다.
@@ -34,7 +34,7 @@ evidence:
기본은 `[lab host]` 다. 게스트에 로그인해서 치지 않는다.
까닭이 셋이다. 게스트에는 lab host 의 개인키도 `~/.ssh/config` 도 없어서 게스트 안에서 `ssh kc-lab-1` 을 치면 `Host key verification failed.` 로 끝난다. 그 실패를 셸 변수 대입으로 감싸면 오류는 화면으로 새고 변수에는 빈 문자열이 담기는데, 셸은 아무 불평도 하지 않는다. 그래서 토큰이 비고, agent 설치가 `--token is required` 로 죽는데도 설치 스크립트는 그 전까지를 다 성공으로 찍고 끝난다.
까닭이 셋이다. 게스트에는 lab host 의 개인키도 `~/.ssh/config` 도 없어서 게스트 안에서 `ssh kc-lab-1` 을 치면 `Host key verification failed.` 로 끝난다. 그 실패를 셸 변수 대입으로 감싸면 오류는 화면으로 새고 변수에는 빈 문자열이 담기는데, 셸은 아무 불평도 하지 않는다. 그 결과 토큰 변수가 비어 있었고, 설치 스크립트는 종료됐지만 실제 agent 프로세스는 `--token is required` 오류로 시작하지 못했다.
셸을 하나만 쓰면 이 문제가 통째로 없어진다. 예외가 둘이다.
@@ -77,7 +77,7 @@ k3s 가 따로 설치하지 않아도 딸려 오는 것이 다섯이다. 뒤 단
전제는 한 줄이다 — 앞 단계가 끝나 lab host 에서 두 게스트에 SSH 가 붙는다.
**되돌리는 절차는 원본 가이드 02 에 없다**. k3s 설치 스크립트는 `k3s-uninstall.sh` 와 `k3s-agent-uninstall.sh` 를 함께 깔지만 가이드가 그 이름을 한 번도 적지 않았고 이 실험대도 부른 적이 없다. 가이드가 재설치를 말하는 곳은 두 군데인데 둘 다 되돌리는 명령이 아니라 뒤처리를 적어 두었다.
k3s 전체 제거 절차는 아직 이 실험대에서 실행해 검증하지 않았다. 설치 스크립트가 `k3s-uninstall.sh`와 `k3s-agent-uninstall.sh`를 설치하지만, 이 두 스크립트를 사용해 server와 agent를 제거한 뒤 다시 구성하는 경로는 확인하지 않았다.
| 어디서 | 무엇을 적었나 |
|---|---|
@@ -298,11 +298,11 @@ exit
정상이면 설치가 끝나면 `k3s-agent.service` 가 그 노드에 서고, lab host 의 `kubectl get nodes` 에 `kc-lab-2` 가 한 줄 더 붙는다.
**⑦ 을 편집기로 여는 까닭** — 이 실험대는 `sudo sed -i "s|$HOME/node-token|/etc/rancher/node-token|" /etc/systemd/system/k3s-agent.service` 로 고쳤다. `sed -i` 는 패턴이 안 맞아도 조용히 성공하고, 이 패턴에는 `$HOME` 이 들어 있어 설치할 때와 다른 계정으로 치면 아무 줄도 안 바뀐 채 ⑨ 가 이어서 돈다. 그러면 지금 떠 있는 노드는 멀쩡해 보이고 다음 재부팅에서야 `Waiting for file` 로 멎는다. 유닛을 열면 고칠 줄이 눈에 보이고, 고쳤는지도 저장하기 전에 눈으로 본다. 이 편집기 형태는 이 실험대에서 치지 않았다.
**⑦ 을 편집기로 여는 까닭** — 이 실험대는 `sudo sed -i "s|$HOME/node-token|/etc/rancher/node-token|" /etc/systemd/system/k3s-agent.service` 로 고쳤다. `sed -i`는 치환할 패턴이 없어도 종료 코드 0으로 끝날 수 있고, 이 패턴에는 `$HOME` 이 들어 있어 설치할 때와 다른 계정으로 치면 아무 줄도 안 바뀐 채 ⑨ 가 이어서 돈다. 그러면 지금 떠 있는 노드는 멀쩡해 보이고 다음 재부팅에서야 `Waiting for file` 로 멎는다. 유닛을 열면 고칠 줄이 눈에 보이고, 고쳤는지도 저장하기 전에 눈으로 본다. 이 편집기 형태는 이 실험대에서 치지 않았다.
설치 스크립트는 `sudo` 아래 root 로 도니 홈의 `600` 파일도 읽는다. `--token` 대신 `--token-file` 을 쓰면 토큰이 명령줄에 안 들어가므로 프로세스 목록과 셸 히스토리에 남지 않고, 토큰을 꺼낸 셸과 같은 셸에서 쳐야 한다는 제약도 없어진다.
이 실험대는 두 줄로 했다. 아래는 당시 실행을 보존한 historical/reference block이고, 따라 하는 절차는 위 ①~⑪처럼 검증과 삭제를 분리한다.
이 실험대는 두 줄로 했다. 아래는 당시 실행한 명령을 남긴 블록이고, 따라 하는 절차는 위 ①~⑪처럼 검증과 삭제를 분리한다.
```bash label="[lab host] [reference] 이 실험대가 실제로 친 형태"
ssh kc-lab-1 'sudo cat /var/lib/rancher/k3s/server/node-token' \
@@ -314,7 +314,7 @@ ssh kc-lab-2 "curl -sfL https://get.k3s.io | sudo sh -s - agent \
두 줄 안에 원격 셸 둘과 `sudo` 둘, 파이프 하나, 설치 스크립트 하나, 마지막 삭제 하나가 겹쳐 있다. 실패했을 때 어느 쪽이 실패했는지 갈리지 않아 위에서는 ① 부터 ⑪ 까지로 나눴다. 토큰이 `/tmp/token` 대신 자기 홈에 놓이고 `sudo tee` 대신 `scp` 와 `chmod 600` 이 그 파일을 만드는 것도 그래서 달라진다. 이 나눈 형태는 이 실험대에서 치지 않았다.
실패하면 agent 설치는 성공했는데 노드가 안 보이면 로그에 `--token is required` 가 있는지 본다. 토큰이 빈 값이었으면 설치 스크립트는 내려받기와 유닛 생성과 활성화까지 다 성공으로 찍고 끝나고, 유닛은 `Restart=always` 라 5초마다 조용히 재시도한다.
실패하면 agent 설치는 성공했는데 노드가 안 보이면 로그에 `--token is required` 가 있는지 본다. 토큰이 빈 값이었으면 설치 스크립트는 내려받기와 유닛 생성과 활성화까지 다 성공으로 찍고 끝나고, 유닛은 `Restart=always` 설정 때문에 약 5초 간격으로 다시 시작한다.
```bash label="[lab host] agent 가 왜 못 붙었는지 본다"
ssh kc-lab-2 'sudo journalctl -u k3s-agent -n 30 --no-pager'
@@ -361,7 +361,7 @@ ssh test-server "ssh kc-lab-1 'sudo cat /etc/rancher/k3s/k3s.yaml'" > ~/.kube/kc
따옴표가 두 겹이라 어느 기계에서 어느 명령이 도는지가 한 줄에 묻힌다. 기계마다 한 명령이 되게 나눈 형태는 이 실험대에서 치지 않았다.
실패하면 타임아웃이면 ① 의 터널 창이 닫힌 것이고, `connection refused` 면 터널은 살아 있는데 반대편 API 서버가 죽은 것이다. 터널이 닫히면 `kubectl` 이 통째로 멎어 터널 상태와 클러스터 상태가 섞인다. 노드를 죽이고 살리는 실험은 lab host 에서 치는 편이 낫다.
실패하면 타임아웃이면 ① 의 터널 창이 닫힌 것이고, `connection refused`이면 터널 자체는 열려 있지만 반대편 API 서버가 요청을 받지 못하는 상태다. 터널이 닫히면 `kubectl` 이 통째로 멎어 터널 상태와 클러스터 상태가 섞인다. 노드를 중단하고 다시 시작하는 실험은 lab host에서 실행한다.
## kubeconfig와 systemd unit의 위치
@@ -515,7 +515,7 @@ Node authorizer 와 NodeRestriction admission 은 이 신원이 자기 노드에
## 이 k3s 구성에서 실제로 확인한 범위
- 2026-09-17 당시 stable installer가 선택한 `v1.36.4+k3s1`, 두 노드 `Ready`, INTERNAL-IP 두 개, 토큰 길이, `ExecStart` 두 줄, agent 의 `localhost:8080` 오류와 인증서 subject. 위 canonical 설치 명령은 재실행 때도 같은 k3s를 받도록 `INSTALL_K3S_VERSION=v1.36.4+k3s1`을 명시한다.
- 2026-09-17 당시 stable installer가 선택한 `v1.36.4+k3s1`, 두 노드 `Ready`, INTERNAL-IP 두 개, 토큰 길이, `ExecStart` 두 줄, agent 의 `localhost:8080` 오류와 인증서 subject. 위 현재 설치 명령은 재실행 때도 같은 k3s 버전을 받도록 `INSTALL_K3S_VERSION=v1.36.4+k3s1`을 명시한다.
- 2026-09-17 실제 출력에서는 `kube-system` 파드 여덟 줄과 `local-path (default)` StorageClass 를 확인했다. `svclb-traefik-` 두 줄이 DaemonSet 이 두 노드에 모두 뜬 상태를 보여 줬다.
- 쿠버네티스 1.20 이전의 평문 8080과 Node authorizer·NodeRestriction 동작은 이 실험대에서 재현한 값이 아니라 쿠버네티스 쪽 동작을 설명한 것이다.
- 3번과 4번의 나눈 형태는 이 실험대에서 치지 않았다. 이 실험대가 친 것은 원격 셸 둘을 파이프로 이은 두 줄이고, 나눈 형태로 같은 클러스터가 서는지는 다시 재지 않았다.
@@ -540,7 +540,7 @@ E0917 07:42:16.919786 conn.go:353] "Error on socket receive" err="read tcp 127.0
```
`kubectl exec` 나 `logs` 로 연결했다가 끊을 때마다 한 줄씩 남는다. **봐야 할 것은 `E` 인지가 아니라 문구다** — 토큰이나 주소가 틀렸으면 `failed to get CA certs` 나 `401 Unauthorized` 가 나온다.
- 원본 가이드에 되돌리는 절차가 없다. `k3s-uninstall.sh` 라는 이름이 가이드에 한 번도 안 나오고 이 실험대도 부른 적이 없다.
- `k3s-uninstall.sh`와 `k3s-agent-uninstall.sh`를 사용한 전체 제거·재설치 경로는 아직 확인하지 않았다.
- 2026-09-21 worker 재구축에서는 k3s server와 agent 설치 경로를 다시 실행해 두 노드가 `Ready`로 돌아오는 것까지 확인했다. 다만 이 검증은 기존 lab host 위에서 worker VM을 다시 만든 구간 재구축이고, 빈 물리 host에서 단계 00부터 전체 가이드를 다시 실행한 것은 아니다. 과거 토큰 108자는 시점값이라 판올림이나 재설치 뒤에도 같은 길이라고 가정하지 않는다.
<!-- body:end -->
@@ -39,7 +39,7 @@ source:
`kubectl` 이 lab host 에서 도는 까닭은 앞 단계에 있다. kubeconfig 를 게스트에서 호스트로 가져다 두었으므로 게스트에 들어갈 일이 없다. `deploy/...` 로 시작하는 상대경로는 저장소 루트 기준이라, 다른 디렉터리에서 치면 `error: the path ... does not exist` 로 막힌다.
이 단계에는 손으로 쓰는 파일이 없다. 세우는 것이 전부 매니페스트 한 장에 들어 있고, 그 원문은 저장소의 `deploy/lab/k8s/keycloak-cluster.yaml` 이다.
이 단계에서 사용하는 리소스 정의는 저장소의 `deploy/lab/k8s/keycloak-cluster.yaml`에 들어 있다. 적용 전에 실제 매니페스트를 열어 이미지 태그와 Secret, PVC, Deployment 설정을 확인한다.
**랩 호스트와 클러스터 내부의 이름 해석을 같은 것으로 보지 않는다.** 랩 호스트에서 `auth.hyeonworks.com`을 풀면 자신의 tailnet 주소 `100.83.212.4`가 나오고, host가 스스로 낸 패킷은 `iifname "tailscale0"` DNAT 규칙을 타지 않으므로 이름 그대로 `curl`하면 실패할 수 있다. 그래서 lab host의 외부 경로 확인에는 `--resolve <이름>:443:192.168.122.10`으로 edge를 직접 짚는다.
@@ -79,7 +79,7 @@ image: quay.io/keycloak/keycloak:26.7.0
전제는 한 줄이다 — 앞 단계까지 끝나 `https` 가 열린다.
**되돌리는 절차는 원본 가이드 05 에 없다**. `kubectl delete -f` 도, 지우는 순서도 적혀 있지 않다. 이 단계가 클러스터에 남기는 것은 `keycloak-lab` 네임스페이스와 그 안의 전부이고, 그중 PVC 는 성격이 다르다 — StorageClass 가 `local-path` 라 데이터가 파드가 스케줄된 그 노드의 디스크에 놓인다. 네임스페이스를 지울 때 그 디렉터리가 어떻게 되는지는 가이드가 적지 않았고 이 실험대도 확인하지 않았다.
Keycloak과 PostgreSQL을 모두 제거하는 절차는 아직 검증하지 않았다. 이 단계는 `keycloak-lab` 네임스페이스와 그 안의 리소스를 만들며, `local-path` StorageClass를 사용하는 PVC 데이터는 노드 디스크에 놓인다. 네임스페이스와 PVC를 삭제했을 때 노드의 실제 데이터 디렉터리가 어떻게 정리되는지는 확인하지 않았다.
## 두 노드와 기본 StorageClass가 준비됐는지 확인한다
@@ -166,7 +166,7 @@ partitioned roll out complete: 2 new pods have been updated...
| 네임스페이스 이름 | 매니페스트 첫 문서 |
| 파드 이름의 순번 | StatefulSet 이라 `keycloak-0` · `keycloak-1` |
| 파드 이름의 해시 | Deployment 가 만든 ReplicaSet 이름에서 물려받는다 |
| Secret 의 바이트 수 | 매니페스트가 넣은 값의 길이. 이 문서는 값을 적지 않는다 |
| Secret 의 바이트 수 | 매니페스트가 넣은 값의 길이. 실제 비밀 값은 출력하지 않는다 |
| PVC 가 붙는 노드 | `local-path` 가 파드 스케줄을 기다렸다 그 노드에 만든다 |
| Ingress 의 HOSTS | 앞 단계에서 발급한 인증서의 이름과 같아야 한다 |
@@ -188,7 +188,7 @@ kubectl -n keycloak-lab get all
kubectl -n keycloak-lab get secret,configmap,pvc,ingress
```
① 은 종류별로 묶여 나오는 왼쪽 이름 열을 훑고, 파드 줄에서는 READY 칸의 `1/1` 과 RESTARTS 칸을 본다. RESTARTS 가 0 이 아니면 지금은 `Running` 이어도 한 번 죽었다 살아난 것이다. ② 는 네 종류가 하나씩이라도 있는가, PVC 줄의 STATUS 가 `Bound` 인가, Ingress 줄의 HOSTS 칸이 `auth.hyeonworks.com` 인가.
① 은 종류별로 묶여 나오는 왼쪽 이름 열을 훑고, 파드 줄에서는 READY 칸의 `1/1` 과 RESTARTS 칸을 본다. RESTARTS가 0이 아니면 현재 `Running` 상태더라도 컨테이너가 이전에 재시작된 기록이 있다는 뜻이다. ② 는 네 종류가 하나씩이라도 있는가, PVC 줄의 STATUS 가 `Bound` 인가, Ingress 줄의 HOSTS 칸이 `auth.hyeonworks.com` 인가.
`get all` 은 이름과 달리 전부가 아니다. Secret 과 ConfigMap 과 PVC 와 Ingress 가 ① 의 출력에 나오지 않으므로, 첫 명령만 보고 「다 만들어졌다」로 판정하면 빠진 것을 모른 채 다음으로 간다. 매니페스트에 있는데 ② 에 없는 종류가 있다면 `apply` 가 부분적으로만 먹었다.
@@ -367,7 +367,7 @@ NAME STATUS VOLUME CAPACITY S
postgres-data Bound pvc-fe269834-3dd1-4b1f-82f6-a53413310a30 5Gi local-path
```
그래서 **Keycloak 파드는 볼륨을 안 갖는다.** 세션이 어디 사는지를 묻는 이 실험대의 질문에서 그것이 중요하다 — 파드가 죽으면 그 안의 것은 사라지고 `postgres-data` 만 남는다.
Keycloak 파드에는 별도 영구 볼륨을 연결하지 않았다. 파드 로컬 파일시스템은 영구 저장소로 사용하지 않으며, PostgreSQL 데이터는 `postgres-data` PVC에 남는다.
`Bound` 면 볼륨이 붙었다. `Pending` 이면 StorageClass 가 없거나 노드에 자리가 없다. `local-path` 는 파드가 스케줄될 때까지 기다리므로, 파드가 안 뜨면 PVC 도 `Pending` 인 것이 정상이다. 둘이 서로를 기다리는 것처럼 보이지만 파드 쪽 원인을 먼저 본다. 사유는 PVC 의 이벤트에 적혀 있다.
@@ -491,11 +491,11 @@ curl -s -o /dev/null -w '%{http_code}\n' -H 'Host: auth.hyeonworks.com' http://1
가이드가 적은 「이 단계가 끝나면」의 앞 절반.
브라우저로 `https://auth.hyeonworks.com/admin` 에 들어가 관리자로 로그인한다. 비밀번호는 확인 ③ 의 Secret 에 있고, 이 문서는 그 값을 적지 않는다 — 이 실험대의 확인은 전부 길이까지만 본다.
브라우저로 `https://auth.hyeonworks.com/admin` 에 들어가 관리자로 로그인한다. 비밀번호는 확인 ③의 Secret에 있으며 실제 값은 출력하지 않고 길이만 확인한다.
세션 저장 위치는 관리 콘솔 로그인 성공과 별개의 질문이다. DB 테이블 한 번 조회한 결과만으로 `DB 저장` 또는 `메모리 저장`을 확정하지 않는다. Keycloak 버전과 persistent-session 설정에 따라 저장 구조와 시점이 달라질 수 있기 때문이다.
원문에는 `offline_user_session`을 로그인 전후로 비교하는 확인이 남아 있지만, 현재 `persistent-user-sessions` 설정값과 해당 조회 결과를 이 기록에서 다시 대조하지 못했다. 따라서 이 Setup의 통과 조건은 **두 노드가 클러스터를 이루고 외부 요청과 관리 콘솔이 동작하는 것**까지로 둔다. 세션 저장 위치와 파드 재시작 뒤 생존 여부는 별도 세션 실험의 증거로 판정한다.
원문에는 `offline_user_session`을 로그인 전후로 비교하는 확인이 남아 있지만, 현재 `persistent-user-sessions` 설정값과 해당 조회 결과를 이 기록에서 다시 대조하지 못했다. 현재 확인한 범위는 두 Keycloak 노드가 클러스터를 이루고 외부 요청과 관리 콘솔이 동작하는 것까지다. 세션 저장 위치와 파드 재시작 뒤 생존 여부는 별도 세션 실험의 증거로 판정한다.
## Keycloak 두 노드 확인표
@@ -516,7 +516,7 @@ curl -s -o /dev/null -w '%{http_code}\n' -H 'Host: auth.hyeonworks.com' http://1
kubectl -n keycloak-lab get events --sort-by=.lastTimestamp | tail -20
```
맨 아랫줄부터 거꾸로 읽는다. `--sort-by` 를 준 까닭이 그것이다. TYPE 이 `Warning` 인 줄, REASON 칸, 그리고 OBJECT 칸이 어느 파드인가를 본다. 이벤트는 기본 한 시간만 남으므로 아무것도 없다고 문제가 없는 것은 아니다. REASON 하나가 다음 행동을 정한다 — `FailedScheduling` 은 노드에 자리가 없는 것이라 파드가 아니라 클러스터를 봐야 하고, `ErrImagePull` 은 이미지 이름 문제라 로그를 볼 것도 없으며, `BackOff` 는 컨테이너가 떴다가 죽는 중이라 ③ 으로 간다.
맨 아랫줄부터 거꾸로 읽는다. `--sort-by` 를 준 까닭이 그것이다. TYPE 이 `Warning` 인 줄, REASON 칸, 그리고 OBJECT 칸이 어느 파드인가를 본다. 이벤트는 기본 한 시간만 남으므로 아무것도 없다고 문제가 없는 것은 아니다. REASON 하나가 다음 행동을 정한다 — `FailedScheduling` 은 노드에 자리가 없는 것이라 파드가 아니라 클러스터를 봐야 하고, `ErrImagePull` 은 이미지 이름 문제라 로그를 볼 것도 없으며, `BackOff`는 컨테이너가 시작 후 반복 종료되는 상태이므로 ③의 로그 확인으로 간다.
**② describe.** 그 파드에 한정된 이벤트와 상태를 함께 본다.
@@ -526,14 +526,14 @@ kubectl -n keycloak-lab describe pod keycloak-0
위에서부터 세 곳이다. `Conditions` 절에서 `Ready` 가 `False` 인가, 컨테이너 절의 `State` 와 `Last State` 와 그 안의 `Exit Code`, 그리고 맨 아래 `Events`. Exit Code 는 그것만으로 말이 된다 — `137` 은 OOM 이나 강제 종료, `1` 은 애플리케이션이 스스로 끝낸 것, `127` 은 명령을 못 찾았다는 뜻이다. `137` 이면 로그에 아무 단서도 없을 수 있어 메모리 한도를 본다. `Ready` 만 `False` 이고 컨테이너는 살아 있으면 readiness 프로브 문제이므로 확인 ④ 로 돌아간다.
**③ 로그.** 컨테이너가 떴는데 죽는 경우를 본다.
**③ 로그.** 컨테이너가 시작된 뒤 종료되는 경우를 확인한다.
```bash label="[lab host] 지금 로그와 재시작 직전 로그"
kubectl -n keycloak-lab logs keycloak-0
kubectl -n keycloak-lab logs keycloak-0 --previous # 재시작 직전 로그
```
첫 명령에서는 마지막 줄들, 둘째 명령에서는 스택 트레이스의 맨 윗줄을 본다. Keycloak 은 기동에 성공하면 `Keycloak ... started in` 한 줄을 남기므로, 그 줄이 있는지 없는지가 기동 중과 기동 실패를 가른다. `--previous` 가 중요하다 — CrashLoopBackOff 면 지금 컨테이너는 방금 뜬 것이라 죽은 까닭은 이전 컨테이너 로그에 있다. `--previous` 가 `not found` 를 내면 아직 한 번도 재시작하지 않은 것이고, 그러면 지금 로그가 곧 전부다.
첫 명령에서는 마지막 줄들, 둘째 명령에서는 스택 트레이스의 맨 윗줄을 본다. Keycloak 은 기동에 성공하면 `Keycloak ... started in` 한 줄을 남기므로, 그 줄이 있는지 없는지가 기동 중과 기동 실패를 가른다. `--previous` 가 중요하다 — CrashLoopBackOff 면 지금 컨테이너는 방금 뜬 것이라 종료 원인은 이전 컨테이너 로그에서 확인한다. `--previous` 가 `not found` 를 내면 아직 한 번도 재시작하지 않은 것이고, 그러면 지금 로그가 곧 전부다.
**④ 그래도 모르면 안에서 본다.**
@@ -558,9 +558,9 @@ kubectl -n keycloak-lab exec -it keycloak-0 -- sh
- 디스커버리 테이블에는 둘 다 있는데 메시지가 안 가는 상태를 실제로 겪었다.
- `kubectl get endpoints` 의 v1.33 deprecation 은 쿠버네티스 쪽 규격이다. 이 실험대에서는 해당 버전 위에서 명령 선택에 반영했을 뿐, deprecation 자체를 측정한 것은 아니다.
- Infinispan 이 파드 이름에 임의의 접미사를 붙여 클러스터 노드 식별자로 쓰는 것은 Infinispan 쪽 동작이다. 2026-09-17 실제 로그에는 `keycloak-0-10001` 과 `keycloak-0-46674` 가 그런 형태로 나타났다.
- 이 글은 `keycloak-cluster.yaml` 전체를 본문에 복제하지 않는다. 이미지 태그와 현재 검증에 필요한 주요 설정은 확인했지만, 파드 자원 한도·프로브·`persistent-user-sessions` 설정값은 이 Setup의 설명 범위에 모두 옮기지 않았다. 그 값이 필요한 실험에서는 실제 매니페스트를 다시 확인한다.
- `keycloak-cluster.yaml`의 모든 필드를 여기 옮기지는 않았다. 파드 자원 한도, 프로브, `persistent-user-sessions`처럼 이 절차에서 직접 확인하지 않은 값은 실제 매니페스트에서 확인한다.
- `get all` 과 `get deploy` 와 `get pvc` 와 `describe pvc` 와 디스커버리 테이블 조회와 `get events` 와 `describe pod` 와 `logs` 의 출력은 가이드가 봐야 할 줄만 적었고 값이 남아 있지 않다.
- 원본 가이드 05 에 되돌리는 절차가 없다. `local-path` PVC 가 노드 디스크에 남긴 데이터가 네임스페이스를 지울 때 어떻게 되는지도 확인하지 않았다.
- `local-path` PVC를 포함한 전체 제거 절차와 삭제 뒤 노드 디스크의 데이터 상태는 아직 확인하지 않았다.
- 이 단계에는 「이 실험대는 이렇게 했다」와 「따라 하는 사람은」 두 갈래가 없다. 05 는 파일을 직접 쓰지 않고 저장소의 매니페스트를 적용한다.
- 2026-09-17 에 갓 세운 클러스터에서 이 절차를 처음부터 다시 밟았다. 같은 값이 다시 나온 것 — `postgres-7b474b88c8` 이라는 ReplicaSet 해시, Secret 의 19·22 bytes 와 주입된 길이 19·복호 길이 22, Endpoints 두 개와 `ready` 두 줄, `jgroups_ping` 2 행, 임시 파드가 읽은 `vendor_cluster_size … 2.0`, Keycloak 이미지에 `curl` 이 없다는 것과 exit code 127, `kubectl get endpoints` 의 deprecation 경고. **파드 IP 와 Infinispan 접미사만 달랐다** — 그것들은 매번 새로 붙는다.
- 같은 날 실제 출력에서 문서와 달랐던 것은 다음과 같다 — `rollout status` 가 `Waiting for …` 를 찍는다는 것, PVC 가 `postgres-data` 하나라는 것, 환경변수 목록이 열세 줄이라는 것, `ISPN000094` 이름에 `(v=16.0.12)` 가 붙는다는 것, 인증서 단계를 건너뛰면 밖에서가 `000` 이라는 것.
@@ -212,13 +212,13 @@ database system is ready to accept connections
첫 명령에서 `kc-lab-1` 의 `CP` 열에 값이 있고 `kc-lab-2` 는 비어 있는지, 종료 직후 pid 파일은 `absent`인지, 재기동 로그가 clean shutdown 시각을 읽고 바로 ready가 되는지 본다. **재기동 뒤 `postmaster.pid` 존재 여부를 crash 판정으로 쓰면 안 된다.** 이전 문서의 그 판정은 2026-09-21 실험에서 틀린 것으로 확인됐다.
노드 역할 구분은 그대로 중요하다. `kc-lab-2` 를 죽이면 워커 워크로드가 사라지지만 제어면은 남고, `kc-lab-1` 을 죽이면 `kubectl` 과 control-plane도 함께 사라진다.
노드 역할 구분은 그대로 중요하다. `kc-lab-2`를 중단하면 해당 worker의 워크로드가 사라지지만 control-plane은 남고, `kc-lab-1`을 중단하면 `kubectl`이 연결할 control-plane도 함께 사용할 수 없게 된다.
## 이 절차만으로 판단하지 않는 장애 범위
관측 스택을 어느 노드에 둘지는 여기서 정하지 않는다. server 와 agent 가 왜 다른지만 위에서 한 번 적었고, 그래서 관측을 server 쪽에 두는 판단은 게스트 두 대를 고른 결정과 Prometheus 를 올리는 편이 받는다.
이 절차에서는 server와 agent를 중단했을 때 영향 범위만 확인한다. Prometheus와 Grafana의 배치 위치는 전원 순환 과정에서 변경하지 않는다.
이 절차의 근거는 제9부의 개념 문서이고, 그 문서의 실측 스냅샷은 2026-09-03, 재배분 기록은 2026-09-11 이다. 제7부가 2026-09-10 에 잰 게스트 메모리 값과 날짜가 엇갈리므로, 게스트 메모리 수치는 각각 그 시점의 것으로 읽는다.
게스트 메모리 값은 측정 시점이 서로 다르다. 초기 배치 스냅샷은 2026-09-03, 자원 사용량 측정은 2026-09-10, 메모리 재배분 기록은 2026-09-11이므로 서로 다른 날짜의 값을 같은 상태로 합치지 않는다.
2026-09-21에 이 순서를 worker VM 두 대에 다시 실행했다. Keycloak→PostgreSQL 순으로 replica를 0까지 내리고 두 VM을 `virsh shutdown`으로 정상 종료한 뒤 다시 시작했다. 두 노드는 `Ready`로 복귀했지만 Keycloak과 PostgreSQL의 replica는 0 그대로였고, PostgreSQL을 먼저 1로 올린 뒤 Keycloak을 2로 올려야 원래 상태가 복구됐다. PostgreSQL 기동 로그는 clean shutdown을 확인했고 Keycloak 두 파드도 다시 Ready가 됐다. 물리 `test-server` 자체의 `systemctl poweroff`는 edge의 실제 서비스와 SSH/Tailscale까지 끊으므로 이번 재검증에서는 안전 조건 때문에 실행하지 않았다. 따라서 물리 호스트 전원 차단 뒤 복구 절차는 아직 확인하지 못했다.
@@ -71,7 +71,7 @@ sourceRevision: import-head 9465582b5d1630eb4ae7c4e078021486919bf6b6 · uncommit
전제는 가이드가 두 줄로 적었다 — 물리 기계 한 대가 있고, 배포판은 상관없다. 이 실험대는 Arch Linux 로 세웠고 배포판이 다르면 패키지 이름만 달라진다. 앞 단계가 없으므로 이 절차는 다른 무엇도 전제하지 않는다.
**되돌리는 절차는 원본 가이드 00 에 없다**. 가이드 7편 가운데 되돌리기를 적은 편은 단계 03 하나다. 이 단계가 호스트에 남기는 것은 여섯이다.
이 단계에서 설치·변경하는 항목을 모두 원래 상태로 되돌리는 절차는 아직 검증하지 않았다. 호스트에는 다음 항목이 남는다.
| 남는 것 | 어디에 |
|---|---|
@@ -405,7 +405,7 @@ lscpu | grep -E "^Model name|^CPU\(s\):|^Core\(s\)|^Thread\(s\)"
```
`Triggers` 가 `libvirtd.service` 를 가리키는 것이 소켓 활성화가 걸렸다는 뜻이다. 소켓이 먼저 뜨고 첫 접속이 올 때 서비스가 깨어난다 — 그래서 `.service` 가 아니라 `.socket` 을 `enable` 한다.
- 원본 가이드에 되돌리는 절차가 없다. 패키지와 그룹과 유닛과 `~/.config/libvirt/libvirt.conf` 와 네트워크 autostart 를 모두 걷어내는 전체 rollback은 수행하지 않았다.
- 패키지, 사용자 그룹, libvirt 유닛, `~/.config/libvirt/libvirt.conf`, 네트워크 autostart까지 모두 원래 상태로 되돌리는 전체 rollback은 수행하지 않았다.
- `sudo modprobe kvm_intel` 은 막혔을 때 치라고 가이드가 적어 둔 명령이고, 이 실험대에서는 모듈이 이미 올라와 있어 치지 않았다.
- 2026-09-21 재검증에서는 실제 로그인 셸이 `/bin/zsh`, 비대화식 SSH의 `LIBVIRT_DEFAULT_URI`는 빈 값인데도 `virsh uri`가 `qemu:///system`임을 다시 확인했다. 따라서 과거 `.bashrc`까지 함께 수정하던 절차는 current procedure에서 제외했다.
- Debian과 Ubuntu의 패키지 이름은 가이드가 참고용으로 적어 둔 것이고, 이 실험대는 Arch에서만 확인했다.
@@ -45,7 +45,7 @@ source:
**마지막 포트포워드만 예외다.** 그 터널은 명령을 친 기계에서만 열리므로, 브라우저로 볼 기계에서 쳐야 한다.
이 단계에도 손으로 쓰는 파일이 없다. 세우는 것이 전부 매니페스트 한 장에 들어 있고, 그 원문은 저장소의 `deploy/lab/k8s/observability.yaml` 이다.
관측 스택의 리소스 정의는 저장소의 `deploy/lab/k8s/observability.yaml`에 들어 있다. 적용 전에 DaemonSet, Deployment, Service와 스크레이프 대상을 실제 매니페스트에서 확인한다.
**랩 호스트와 파드 내부의 DNS 경로는 다르다.** lab host에서 `auth.hyeonworks.com`을 풀면 자신의 tailnet 주소 `100.83.212.4`가 나오고, host가 스스로 낸 패킷은 `tailscale0` ingress DNAT을 타지 않으므로 여기서 하는 외부 경로 확인에는 `--resolve <이름>:443:192.168.122.10`을 붙인다. 반면 앞 단계의 CoreDNS 보정을 적용한 현재 클러스터에서는 파드 내부의 `auth.hyeonworks.com`이 `192.168.122.10` edge를 가리키는 것을 2026-09-21에 확인했다. tailnet에 붙은 다른 기계에서는 DNS 이름 그대로 외부 진입 경로를 확인한다.
@@ -73,7 +73,7 @@ source:
전제는 한 줄이다 — 앞 단계가 끝나 Keycloak 두 노드가 떴다.
**되돌리는 절차는 원본 가이드 06 에 없다**. 이 단계가 남기는 것은 `observability` 네임스페이스와 그 안의 전부이고, `node-exporter` 는 DaemonSet 이라 노드마다 하나씩 붙어 있다. 지우는 순서도 지운 뒤의 확인도 가이드에 없다.
`observability` 네임스페이스 전체를 제거하고 삭제 상태까지 확인하는 절차는 아직 검증하지 않았다. `node-exporter`는 DaemonSet이므로 두 노드에 각각 파드가 있으며, 제거할 때 이 리소스까지 함께 없어지는지 확인해야 한다.
## 수집 대상과 현재 파드 상태를 먼저 확인한다
@@ -138,7 +138,7 @@ node-exporter 가 둘인 것은 DaemonSet 이라 노드마다 하나씩 뜨기
kubectl -n observability get pods -o wide
```
NODE 열에서 Prometheus 와 Grafana 가 어느 노드에 있는지 본다. 죽는 순간을 기록해야 하는 쪽이 대상과 함께 내려가면 기록이 남지 않으므로, 관측 스택은 관측 대상과 같이 죽으면 안 된다. 노드가 둘뿐인 실험대에서는 완전히 갈라 둘 수 없어서 규칙으로 정했다 — 관측 스택은 server 노드인 `kc-lab-1` 에 두고 장애 주입은 agent 노드인 `kc-lab-2` 에 한다. `nodeSelector` 로 못박아 두면 실험을 다시 돌려도 같은 노드에 뜬다. node-exporter 는 DaemonSet 이라 이 규칙 밖이고 두 노드에 다 떠 있어야 한다.
NODE 열에서 Prometheus 와 Grafana 가 어느 노드에 있는지 본다. 장애가 발생한 구간을 기록하려면 관측 스택이 장애 주입 대상과 같은 노드에서 함께 중단되지 않도록 배치해야 한다. 노드가 둘뿐인 실험대에서는 완전히 갈라 둘 수 없어서 규칙으로 정했다 — 관측 스택은 server 노드인 `kc-lab-1` 에 두고 장애 주입은 agent 노드인 `kc-lab-2` 에 한다. `nodeSelector` 로 못박아 두면 실험을 다시 돌려도 같은 노드에 뜬다. node-exporter 는 DaemonSet 이라 이 규칙 밖이고 두 노드에 다 떠 있어야 한다.
## scrape 대상과 접근 경로
@@ -318,7 +318,7 @@ kubectl -n observability port-forward svc/grafana 3000:3000
- 2026-09-21 재검증에서는 raw `/api/v1/targets` 응답을 먼저 보존한 뒤 확인하니 `keycloak`·`kubelet`·`node-exporter`·`prometheus` 네 job이 모두 `health=up`이었다. `vendor_cluster_size`는 두 결과가 모두 `2`, `up`은 두 Keycloak·두 node-exporter·두 kubelet·Prometheus 모두 `1`이었다.
- 2026-09-21 재검증에서는 Grafana를 임시 `port-forward`로 `127.0.0.1:3001`에만 열고 `/api/health` 응답을 확인한 뒤 포트포워드를 종료했다.
- `get pods -o wide` 와 targets 의 `health` 훑기, `query=up`, `port-forward` 의 출력은 가이드가 봐야 할 줄만 적었고 값이 남아 있지 않다.
- 원본 가이드 06 에 되돌리는 절차가 없다. DaemonSet 이 노드마다 남긴 것을 걷어내 본 적이 없다.
- observability 리소스 전체를 삭제하고 DaemonSet 파드가 두 노드에서 모두 제거되는지까지 확인한 기록은 없다.
- 이 단계에는 「이 실험대는 이렇게 했다」와 「따라 하는 사람은」 두 갈래가 없다. 06 은 파일을 직접 쓰지 않고 저장소의 매니페스트를 적용한다.
- node-exporter가 재는 값은 게스트 커널에서 본 값이다. 스크레이프 대상 네 개가 모두 클러스터 안에 있으므로 이 실험대가 호스트 쪽 지표를 수집하지 않는다는 점은 구성에서 확인할 수 있다. 호스트에서 같은 항목을 재면 다른 값이 나올 수 있다는 부분은 이 구조에서 한 추론이며 직접 비교 측정하지 않았다.
- 2026-09-17 에 이 절차를 갓 세운 클러스터에서 다시 밟았다. 파드 네 줄과 job 네 개가 그대로 나왔고 ReplicaSet 해시 `845b5678cf`·`6774f94f7c` 까지 같았다. 달랐던 것 — `rollout status` 직후에는 Grafana 가 `0/1` 이었고 Keycloak 대상의 `health` 가 `unknown` 이라 `vendor_cluster_size` 의 원소가 하나뿐이었다. 약 2분 뒤에 둘 다 `2` 가 됐다.
@@ -30,7 +30,7 @@ evidence:
# 실험대를 철거하고 무엇이 남는지 확인한다
게스트 세 대와 DHCP 예약을 지우고 무엇이 남았는지까지 확인하는 절차다. 세우는 가이드에는 이 부분이 없어서 2026-09-10 에 직접 돌리며 명령과 출력을 적었다. 되돌리는 명령은 이 절차에 없다.
2026-09-10에 게스트 세 대와 DHCP 예약을 실제로 삭제한 뒤 남는 파일과 설정을 확인했다. 이 절차는 실험대를 철거하는 데까지만 다루며, 삭제한 환경을 다시 복구하는 과정은 포함하지 않는다.
<!-- body:start -->
@@ -43,7 +43,7 @@ evidence:
## 삭제한 VM과 overlay는 되돌릴 수 없다고 가정한다
`virsh undefine --remove-all-storage` 는 도메인 정의와 오버레이 디스크와 시드 ISO 를 한 번에 지운다. 지운 뒤에 되살리는 명령이 libvirt 에 없다. 실험대를 다시 쓰려면 `base.qcow2` 위에 오버레이를 새로 만들고 시드 ISO 를 다시 구워야 하고, 그 절차는 게스트 세 대를 만드는 편이 받는다.
`virsh undefine --remove-all-storage`는 도메인 정의와 오버레이 디스크, seed ISO를 함께 삭제한다. 삭제한 도메인을 그대로 되살리는 명령은 없으므로 다시 사용할 때는 `base.qcow2`에서 오버레이를 만들고 seed ISO와 VM 정의를 새로 생성해야 한다.
지우기 전에 알아 둘 것은 이 절차가 건드리지 않는 쪽이다. `base.qcow2` 와 `~/workspace/cloud/kc-lab-{1,2}.yaml` 과 `~/.ssh/config` 의 `kc-lab-*` 항목은 그 자체로 살아 있어서 재구축 때 다시 쓴다. 무엇이 어느 쪽인지는 아래 표가 아홉 행으로 가른다.
@@ -251,7 +251,7 @@ seed-kc-lab-{1,2,edge}.iso Capacity=370.00 KiB Allocation=372.00 KiB
| 무엇 | 어떻게 되나 | 왜 |
|---|---|---|
| `base.qcow2` (335MB) | 남는다 | 다음 오버레이의 바닥 |
| `base.qcow2` (335MB) | 남는다 | 다음 오버레이의 backing image |
| host 패키지 (`libvirt` · `qemu` · `kubectl`, 쓰이지 않는 host `certbot`) | 남는다 | guest 삭제와 무관한 host 설치 상태 |
| edge guest의 `nginx` · `certbot` | 사라진다 | `kc-lab-edge` 디스크와 함께 삭제된다 |
| `~/workspace/cloud/kc-lab-{1,2}.yaml` | 남는다 | 키와 비밀번호가 들어 있다 |
@@ -91,7 +91,7 @@ source:
전제는 한 줄이다 — 앞 단계가 끝나 엣지 nginx 가 Traefik 으로 프록시한다.
**되돌리는 절차는 원본 가이드 04 에 없다**. 되돌리기에 가장 가깝게 적힌 문장은 배치의 까닭 한 줄뿐이다.
certbot 패키지, Cloudflare 자격증명, 발급된 인증서, deploy hook, timer, nginx 443 설정까지 모두 제거하는 전체 rollback은 아직 검증하지 않았다.
> 인증서·certbot·갱신 타이머·deploy 훅이 전부 엣지 게스트에 산다. 물리 호스트에는 아무것도 두지 않는다 —
> 그래야 `virsh undefine kc-lab-edge` 한 줄로 이 계층을 통째로 되돌릴 수 있다.
@@ -211,7 +211,7 @@ certbot plugins 2>/dev/null | grep -E '^\*'
정상이면 토큰 값이 화면에 한 번 나온다. 창을 닫으면 복구가 없으므로 바로 3번으로 넘어간다.
`All zones` 로 두면 계정의 모든 도메인에 대한 DNS 수정 권한이 엣지 게스트 안 평문 파일에 놓인다. Global API Key 는 더 나쁘다 — 계정 전체 만능 키라 폐기하면 그 키를 쓰던 다른 것들이 전부 같이 죽는다. 권한을 어디까지 좁히고 무엇을 감수했는지는 이 절차를 부른 결정이 갖고 있다.
`All zones` 로 두면 계정의 모든 도메인에 대한 DNS 수정 권한이 엣지 게스트 안 평문 파일에 놓인다. Global API Key는 계정 전체 범위의 권한을 가지므로 사용하지 않는다. 하나의 키를 여러 곳에서 공유하면 키를 폐기하거나 교체할 때 다른 사용처도 함께 수정해야 한다. 권한을 어디까지 좁히고 무엇을 감수했는지는 이 절차를 부른 결정이 갖고 있다.
실패하면 값을 놓쳤으면 다시 발급받는다. 이 문서에도 터미널에도 값을 적지 않는다.
@@ -356,7 +356,7 @@ sudo nginx -t && sudo systemctl reload nginx
`ssl_certificate` 에 적는 것은 `cert.pem` 이 아니라 `fullchain.pem` 이다. 서버 인증서만 보내면 중간 인증서가 빠져 체인이 끊기는데, 브라우저는 대개 캐시나 AIA 로 보완해서 정상으로 보이고 캐시가 없는 클라이언트에서만 깨지므로 발견이 늦다. 4번 ③ 에서 certbot 이 찍어 준 경로와 한 글자도 다르면 안 된다.
**★ 원본 가이드 04 의 5단계에는 잘못된 경로가 있었다.** 2026-09-17에 실제 파일 위치와 `nginx -t` 결과로 확인했다. 가이드는 `live/hyeonworks.com/` 을 적었지만 실제 `live/` 아래에는 `auth.hyeonworks.com` 이 있었고, 그 잘못된 경로로 `nginx -t` 를 돌리면 아래처럼 실패했다. 위 절차는 이 관측을 반영해 처음부터 `live/auth.hyeonworks.com/` 을 쓴다.
2026-09-17 실제 파일 위치와 `nginx -t` 결과를 확인했을 때 lineage는 `/etc/letsencrypt/live/auth.hyeonworks.com/`이었다. `/etc/letsencrypt/live/hyeonworks.com/`을 사용하면 인증서 파일을 찾지 못해 `nginx -t`가 실패했다. 따라서 현재 절차는 `certbot certificates`가 출력한 실제 `Certificate Path`를 기준으로 nginx 경로를 설정한다.
```text label="문서 그대로 쳤을 때"
[emerg] cannot load certificate "/etc/letsencrypt/live/hyeonworks.com/fullchain.pem":
@@ -375,7 +375,7 @@ auth.hyeonworks.com
Certificate Path: /etc/letsencrypt/live/auth.hyeonworks.com/fullchain.pem
```
현재 truth는 하나다 — **이 실험대의 lineage는 `live/auth.hyeonworks.com/`이고, `live/hyeonworks.com/`은 원본 가이드에 남았던 historical wrong path**다. 다른 실험대에서 이름을 추측하지 말고 `certbot certificates` 가 찍은 `Certificate Path`를 그대로 nginx에 옮긴다.
현재 실험대에서 확인한 lineage는 `live/auth.hyeonworks.com/`이다. `live/hyeonworks.com/`은 과거 가이드에 남아 있던 잘못된 경로다. 다른 실험대에서 이름을 추측하지 말고 `certbot certificates` 가 찍은 `Certificate Path`를 그대로 nginx에 옮긴다.
실패하면 `cannot load certificate` 로 막히면 경로를 본다. 자기 실험대의 디렉터리 이름은 `sudo ls /etc/letsencrypt/live/` 가 답한다. 확인 ② 에서 본 판 번호가 1.25.1 미만인데 `http2` 를 지시어로 썼다면 여기서 `unknown directive "http2"` 가 나온다.
@@ -424,7 +424,7 @@ ls -l /etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh
정상이면 ① 은 `NEXT` 와 `LEFT` 가 채워져 있고 `ACTIVATES` 가 `certbot.service` 를 가리킨다. ③ 에는 `ExecStartPost` 도 `--deploy-hook` 도 없고, 여기 없는 것을 보는 것이 그 명령의 목적이다. ⑦ 의 권한 문자열에는 `x` 가 세 번 보인다.
타이머가 `active` 여도 갱신된 인증서가 서빙되지는 않는다. nginx 는 인증서를 기동 시점에 읽어 메모리에 들고 있고 certbot 은 `live/` 심볼릭 링크만 갈아 끼우므로, 설정에 적힌 경로는 그대로이고 그 경로가 가리키는 파일만 바뀌어 nginx 에는 다시 읽을 계기가 생기지 않는다. 배포판 기본 유닛은 인증서를 새로 받는 데까지만 책임지고 받은 것을 누가 읽게 만드는 일은 아무도 하지 않는다. 훅이 그 둘을 잇는다. 훅을 `post/` 가 아니라 `deploy/` 에 넣는 것은 `post/` 가 갱신이 없어도 매번 돌아 하루 두 번 워커를 갈아치우기 때문이고, `deploy/` 는 실제로 갱신됐을 때만 실행된다. 실행 권한이 없으면 certbot 이 이 훅을 조용히 건너뛴다.
타이머가 `active` 여도 갱신된 인증서가 서빙되지는 않는다. nginx 는 인증서를 기동 시점에 읽어 메모리에 들고 있고 certbot 은 `live/` 심볼릭 링크만 갈아 끼우므로, 설정에 적힌 경로는 그대로이고 그 경로가 가리키는 파일만 바뀌어 nginx 에는 다시 읽을 계기가 생기지 않는다. 배포판 기본 유닛은 인증서를 새로 받는 데까지만 책임지고 받은 것을 누가 읽게 만드는 일은 아무도 하지 않는다. 훅이 그 둘을 잇는다. `post/` 훅은 갱신 여부와 관계없이 certbot 실행 뒤에 호출될 수 있지만, `deploy/` 훅은 인증서가 실제로 갱신됐을 때 실행된다. 불필요한 nginx reload를 피하기 위해 deploy 훅을 사용하며, 훅 파일에는 실행 권한이 필요하다.
실패하면 ③ 에 무엇인가 적혀 있는 배포판이라면 이 훅은 필요 없고, 대신 그 명령이 nginx 를 reload 하는지만 확인한다. 갱신은 됐는데 옛 인증서가 나가면 ⑦ 부터 다시 본다.
@@ -466,7 +466,7 @@ curl -v https://auth.hyeonworks.com/ -o /dev/null
< HTTP/1.1 404 Not Found
```
별표로 시작하는 줄 넷이다. 어떤 TLS 판으로 협상했는가, `subject` 의 CN 이 무엇인가, `issuer` 가 Let's Encrypt 인가, 그리고 `SSL certificate verify ok.` 가 있는가. 그 아래 `<` 로 시작하는 첫 줄이 응답 상태다. CN 모양은 합격 조건으로 쓰지 않는다. 지금 접속한 `auth.hyeonworks.com`이 SAN에 포함돼 있고 클라이언트 검증이 성공하는지가 핵심이다. 인증서 발급 방식과 CA 동작에 따라 CN은 달라질 수 있다.
별표로 시작하는 줄 넷이다. 어떤 TLS 판으로 협상했는가, `subject` 의 CN 이 무엇인가, `issuer` 가 Let's Encrypt 인가, 그리고 `SSL certificate verify ok.` 가 있는가. 그 아래 `<` 로 시작하는 첫 줄이 응답 상태다. CN 모양은 합격 조건으로 쓰지 않는다. 확인할 값은 `auth.hyeonworks.com`이 SAN에 포함돼 있고 클라이언트 인증서 검증이 성공하는지다. 인증서 발급 방식과 CA 동작에 따라 CN은 달라질 수 있다.
**★ 그런데 2026-09-17에 이 실험대에서 확인한 CN 은 `auth.hyeonworks.com` 이었다.** 가이드대로 와일드카드를 받으면 위 두 문단처럼 보인다. 이 실험대는 와일드카드를 안 받았고(「가이드는 여기에 값을 하나 더 적어 두었다」), 계보도 `auth.hyeonworks.com` 하나만 있다.
@@ -484,7 +484,7 @@ notAfter=Dec 3 11:29:17 2026 GMT
**CN 은 합격 조건이 아니다.** 와일드카드를 받았으면 `hyeonworks.com`, 이름을 나열해 받았으면 첫 번째 `-d` 의 이름이 CN 이 된다. 보는 것은 `SSL certificate verify ok.` 한 줄과, 지금 친 이름이 SAN 에 있는가다.
**이름 셋 밖은 TLS 단계에서 끝난다.** `curl` 은 종료 코드 `60` 을 내고 `%{http_code}` 는 `000` 이 되는데, 화면에서는 「서버가 죽었다」와 같아 보인다. A-4 의 Grafana 탐침이 그렇게 쓸모없어졌다.
현재 인증서의 SAN에 포함되지 않은 이름으로 접속하면 TLS 검증 단계에서 실패한다. 이때 `curl`은 종료 코드 `60`, `%{http_code}`는 `000`을 내므로 애플리케이션 HTTP 오류와 구분해야 한다. A-4의 Grafana 탐침도 이 인증서 이름 불일치 때문에 사용할 수 없었다.
네 줄이 다 나오면 인증서가 붙었고 체인이 클라이언트 기준으로 검증됐다. 인증서를 처음 붙인 직후에는 코드 한 칸이 아니라 이 화면을 본다. `verify` 줄 대신 `unable to get local issuer certificate` 가 나오면 중간 인증서가 빠진 것이고, 원인은 5번의 인증서 파일 이름이라 확인 ② 로 간다.
@@ -618,9 +618,9 @@ sudo sh -c 'grep -H "authenticator\|dns_cloudflare_credentials\|server =" /etc/l
- `100.64.0.0/10` 이 CGNAT 예약 대역이라는 점과 Let's Encrypt 의 발급 한도·유효기간 90일은 외부 규격과 정책에 따른다. 이 실험대가 직접 측정한 값으로 취급하지 않는다.
- Cloudflare 토큰은 계정 쪽 자격증명이므로 엣지를 지운다고 함께 없어지지 않는다. 이 동작은 Cloudflare 쪽 관리 범위이고, 가이드에는 토큰 폐기 절차가 적혀 있지 않다.
- 2305초라는 수치는 훅이 물리 호스트에만 있던 시절의 측정이다. 지금 엣지 게스트 배치에서는 다시 재지 않았으므로 같은 시간이 나올지는 알 수 없다. 이 값은 현재 배치로 일반화하지 않는다.
- 2026-09-21 재검증에서 확인한 현재 서빙 인증서는 와일드카드가 아니라 `auth.hyeonworks.com` · `app1.hyeonworks.com` · `app2.hyeonworks.com` 세 이름을 SAN으로 가진 한 장이다. CN은 `auth.hyeonworks.com`, 만료는 2026-12-16 `09:37:57 UTC`이고, direct SNI 검증에서 체인 0~3과 `Verify return code: 0 (ok)`를 다시 확인했다. 이 값은 이 Setup이 목표로 하는 와일드카드 발급 절차와 현재 배포 상태를 구분해서 읽는다.
- 2026-09-21 재검증에서 확인한 현재 서빙 인증서는 와일드카드가 아니라 `auth.hyeonworks.com` · `app1.hyeonworks.com` · `app2.hyeonworks.com` 세 이름을 SAN으로 가진 한 장이다. CN은 `auth.hyeonworks.com`, 만료는 2026-12-16 `09:37:57 UTC`이고, direct SNI 검증에서 체인 0~3과 `Verify return code: 0 (ok)`를 다시 확인했다. 이 절차는 와일드카드 인증서 발급을 설명하지만, 2026-09-21 현재 실제로 서빙 중인 인증서는 세 개의 SAN을 가진 인증서였다. 두 상태를 같은 것으로 기록하지 않는다.
- `curl -v` 의 전체 출력, `certbot certificates` 의 실제 화면, 타이머 목록의 출력, 확인 ③ 의 일련번호 세 줄은 가이드가 봐야 할 줄만 적었고 값이 남아 있지 않다.
- 원본 가이드 04 에 되돌리는 절차가 없다. 패키지와 자격증명과 인증서와 훅과 타이머와 443 블록을 걷어내 본 적이 없다.
- 패키지, 자격증명, 인증서, deploy hook, timer, nginx 443 설정까지 모두 제거하는 전체 rollback은 아직 수행하지 않았다.
- 이 단계에는 「이 실험대는 이렇게 했다」와 「따라 하는 사람은」 두 갈래가 없다. 04 는 설정 파일 셋을 전부 편집기로 쓴다.
<!-- body:end -->
@@ -2,7 +2,7 @@
id: 2f2ffafc-91ff-4971-a6a8-7c0e7d844ca2
kind: CONCEPT
slug: guest-memory-address-translation
title: Guest 메모리 주소가 물리 RAM 에 닿기까지 — GVA · GPA · HPA
title: 게스트 가상 주소가 물리 메모리 주소로 변환되는 과정
topic: memory-virtualization
topicName: 메모리 가상화
project: virtualization
@@ -37,14 +37,14 @@ source:
- final/document.md#88-결론
---
# Guest 메모리 주소가 물리 RAM 에 닿기까지 — GVA · GPA · HPA
# 게스트 가상 주소가 물리 메모리 주소로 변환되는 과정
가상 머신 안의 프로세스가 메모리를 한 번 읽으면 그 주소는 이름이 두 번 바뀐다. 게스트 페이지 테이블이 GVA(Guest Virtual Address)를 GPA(Guest Physical Address)로 바꾼다. 그 GPA 를 EPT 가 다시 HPA(Host Physical Address)로 바꾼 뒤에야 접근이 실제 호스트 RAM 에 닿는다. 게스트 Linux 는 GPA 를 자기 물리 주소로 여기지만, 그 값이 서버 RAM 의 주소와 같을 필요는 없다. 메모리를 마련하는 쪽과 주소를 바꾸는 쪽도 갈린다. QEMU 가 게스트 RAM 을 자기 호스트 가상 주소 공간에 마련해 KVM 에 등록하고, 접근마다 일어나는 변환은 CPU 의 MMU 가 맡는다. 가상 머신 위에서 Keycloak 실험을 돌리는 동안 「가상 머신에 RAM 을 몇 GiB 줬다」가 호스트 RAM 에서 무엇을 뜻하는지 가르려면 이 경로가 먼저 필요하다.
<!-- body:start -->
## GVA · GPA · HPA — 주소 이름이 두 번 바뀐다
## GVA가 GPA를 거쳐 HPA로 변환된다
KVM/QEMU 가상 머신에서 게스트 애플리케이션이 메모리를 한 번 읽는 길을 가장 단순하게 그리면 이렇다.
@@ -74,7 +74,7 @@ Physical RAM
게스트 안에서 도는 Keycloak 이 변수 하나를 읽는다고 하면, 그 한 번의 접근이 세 주소를 차례로 지난다.
```text label="Guest 안의 Keycloak 이 변수를 읽을 때 (기존 문서의 예시 주소)"
```text label="Guest 안의 Keycloak 이 변수를 읽을 때의 예시 주소"
Keycloak
│
│ GVA 0x7f001234
@@ -90,7 +90,7 @@ EPT
Physical RAM
```
게스트 Linux 는 GPA 를 자기 실제 물리 주소라고 여긴다. 가상 머신이므로 그 GPA 가 실제 서버의 HPA 와 같을 필요는 없고, KVM 과 CPU 가상화 계층이 둘을 갈라 둔다. 위 주소 값은 원문이 설명하려고 든 예시이고 이 서버에서 읽은 값이 아니다.
게스트 Linux는 GPA를 자신의 물리 주소 공간으로 사용하지만, 그 값이 실제 서버의 HPA와 같을 필요는 없다. 위 주소 값은 변환 과정을 설명하기 위한 예시이며 이 서버에서 직접 읽은 값은 아니다.
## 일반 Linux 프로세스도 물리 주소를 직접 쓰지 않는다
@@ -166,7 +166,7 @@ TLB 에 없으면 TLB Miss 가 나고, 페이지 테이블을 조회해 정상
게스트 페이지 테이블과 EPT 는 같은 테이블이 아니다. 하나는 게스트 OS 가 자기 프로세스를 위해 관리하고, 다른 하나는 가상화 계층이 게스트 전체의 물리 주소 공간을 호스트 RAM 에 이으려고 관리한다.
두 번째 변환이 왜 필요한지는 가상 머신 두 대를 놓고 보면 드러난다. 원문이 든 예에서는 각각 8 GiB RAM 을 가진 VM1 과 VM2 가 둘 다 GPA `0x1000` 을 쓸 수 있고, EPT 가 그 둘을 서로 다른 HPA 로 잇는다. 그래서 게스트가 보는 물리 메모리 주소 공간을 실제 호스트 RAM 에서 격리해 구현할 수 있다.
두 번째 변환이 필요한 이유는 가상 머신 두 대를 놓고 보면 분명하다. 각각 8 GiB RAM을 가진 VM1과 VM2가 둘 다 GPA `0x1000`을 사용할 수 있고, EPT는 두 GPA를 서로 다른 HPA에 매핑한다. 이 방식으로 각 게스트의 물리 주소 공간을 실제 호스트 RAM에서 서로 분리할 수 있다.
하드웨어가 두 번째 변환을 맡아 주지 않던 시절에는 방식이 달랐다. 하이퍼바이저가 게스트 페이지 테이블 변경을 추적하면서, GVA 에서 실제 호스트 메모리까지 이어지는 shadow mapping 을 관리하는 방식이 쓰일 수 있었다. 게스트 페이지 테이블이 바뀔 때마다 하이퍼바이저가 관련 매핑을 유지해야 하므로 관리 비용과 복잡성이 커질 수 있다. EPT 와 NPT 는 그 두 단계 변환을 CPU 가 하드웨어로 지원하게 한다.
@@ -234,9 +234,9 @@ HPA
## 정상 메모리 접근은 매번 VM Exit 하지 않는다
원문은 이 대목을 「잘못된 이해」라고 이름 붙인 그림으로 먼저 연다.
일반 메모리 접근이 매번 VM Exit을 일으킨다고 이해하면 실제 동작과 다르다.
```text label="원문이 먼저 놓은 「잘못된 이해」"
```text label="일반 메모리 접근을 잘못 이해한 예"
잘못된 이해
Guest Memory Access
@@ -248,7 +248,7 @@ KVM
RAM
```
게스트의 메모리 접근이 곧장 VM Exit 을 거쳐 KVM 으로 가고 거기서 RAM 에 닿는 경로다. 제1부에서 VM Exit 을 읽고 온 사람이 메모리 접근에 그대로 옮겨 붙일 그림이라, 원문은 맞는 경로를 그리기 전에 이것부터 아니라고 적었다. 정상 매핑이 있으면 CPU 하드웨어가 직접 변환을 수행한다.
일반적인 게스트 메모리 접근이 매번 VM Exit을 일으켜 KVM을 거친 뒤 RAM에 도달하는 것은 아니다. 페이지 테이블과 EPT 매핑이 준비돼 있으면 CPU의 MMU가 주소 변환을 하드웨어에서 직접 수행한다.
```text label="정상 mapping 이 있을 때의 실행 경로"
Guest instruction
@@ -295,7 +295,7 @@ QEMU
![Guest 구역 안의 Keycloak 과 PostgreSQL 에서 나온 GVA 가 Guest TLB 를 지나고, TLB Miss 이면 Guest Page Table 을 조회해 GPA 가 되며, 그 GPA 가 VM Boundary 를 넘어 EPT 에서 HPA 로 바뀐 뒤 Host RAM 구역의 Host Physical Memory 에 닿고 마지막에 NUMA Node 0 과 NUMA Node 1 로 갈라지는 주소 변환 경로도. 상자 안의 작은 글씨는 그 단계가 어느 계층인지와 무엇을 무엇으로 바꾸는지를 적은 것이다.](../../../final/assets/diagrams/guest-memory-address-translation-path/guest-memory-address-translation-path.svg)
위쪽 점선 상자 안에서 끝나는 것이 첫 번째 변환이고, 그 상자를 나온 뒤의 EPT 가 두 번째 변환을 맡는다. 관리 경로는 이 그림에 없다 — 위의 `virsh` 목록이 그쪽을 그린 것이다.
게스트 페이지 테이블이 GVA를 GPA로 바꾸는 것이 첫 번째 변환이고, EPT가 GPA를 HPA로 바꾸는 것이 두 번째 변환이다. QEMU가 메모리를 할당하고 KVM에 등록하는 관리 경로는 주소 변환 경로와 구분한다.
## 이 호스트에서 실제로 확인한 메모리 크기
@@ -309,7 +309,7 @@ virsh dommemstat <VM_NAME>
ps -o pid,rss,vsz,cmd -p <QEMU_PID>
```
원문이 커널·QEMU·libvirt 버전을 한 번도 적지 않아 이 글도 특정 버전에 고정하지 않았다. 여기 적은 것은 그 문서가 서술한 구성이고, 버전이 달라져 서술이 낡았는지는 위 확인을 실제 호스트에서 돌릴 때 드러난다.
이 설명은 특정 커널·QEMU·libvirt 버전에 고정하지 않는다. 실제 환경에서는 사용 중인 버전과 domain XML, QEMU 메모리 매핑 상태를 함께 확인해 구현 차이를 검증한다.
범위 밖으로 미룬 것도 있다. 호스트 메모리 압박과 회수, 스왑, ballooning, OOM(Out Of Memory), NUMA 배치는 이 경로 위에서 벌어지는 자원 압박 쪽이라 각각 다른 글이 다룬다. Huge Page 도 마찬가지로 이 경로의 두 변환 단계에 걸리는 선택이어서 따로 뺐다.
@@ -2,7 +2,7 @@
id: efce9a6e-5f5d-45ec-86e5-056d8cb1b8d2
kind: CONCEPT
slug: huge-pages-in-a-vm
title: Huge Page 를 VM 에서 볼 때 갈라지는 세 자리
title: 가상 머신에서 Huge Page를 확인할 때 구분해야 하는 세 계층
topic: memory-virtualization
topicName: 메모리 가상화
project: virtualization
@@ -21,7 +21,7 @@ source:
- final/document.md#82-핵심-claim-registry
---
# Huge Page 를 VM 에서 볼 때 갈라지는 세 자리
# 가상 머신에서 Huge Page를 확인할 때 구분해야 하는 세 계층
페이지 크기를 키우면 같은 메모리 범위를 더 적은 매핑으로 표현할 수 있고, TLB(Translation Lookaside Buffer, 주소 변환 캐시) 엔트리 하나가 덮는 범위도 넓어진다. 그런데 가상 머신에는 주소 변환 단계가 둘이라 「Huge Page 를 쓴다」는 말만으로는 어디를 말하는지 정해지지 않는다. 게스트 페이지 테이블 단계인지, QEMU 가 마련한 호스트 쪽 메모리인지, EPT(Extended Page Tables) 매핑인지를 나누어 물어야 그 말이 뜻을 갖는다. Linux 가 큰 페이지를 마련하는 방법도 THP(Transparent Huge Pages)와 HugeTLB 두 가지인데, 둘은 관리 주체도 사전 예약 여부도 다르다.
@@ -30,7 +30,7 @@ source:
## 페이지가 커지면 매핑 수가 준다
같은 메모리 범위라도 페이지 크기에 따라 필요한 매핑 수가 달라진다. 원문은 8 GiB 를 예로 들어 셋을 나란히 계산했다.
같은 메모리 범위라도 페이지 크기에 따라 필요한 매핑 수가 달라진다. 8 GiB를 예로 들면 페이지 크기별 차이를 바로 비교할 수 있다.
| 페이지 크기 | 8 GiB 를 표현하는 데 필요한 페이지 수 |
|---|---|
@@ -38,7 +38,7 @@ source:
| 2 MiB | 4,096 pages |
| 1 GiB | 8 pages |
큰 페이지는 더 적은 매핑으로 넓은 메모리 범위를 표현할 수 있다. 위 8 GiB 는 계산을 보이려고 원문이 든 예시 값이고 이 서버 가상 머신의 설정이 아니다.
큰 페이지는 더 적은 매핑으로 넓은 메모리 범위를 표현할 수 있다. 위 8 GiB는 계산을 위한 예시 값이며 이 서버 가상 머신의 실제 설정은 아니다.
## TLB 엔트리 하나가 덮는 범위
@@ -76,7 +76,7 @@ HPA
게스트와 호스트의 페이지 크기 선택을 같은 설정 하나로 묶어 다루면 안 된다. 게스트 안에서 THP 가 켜져 있어도 그것은 첫 질문에 대한 답이고, 그 가상 머신의 RAM 을 호스트가 무엇으로 받치는지는 두 번째 질문이 따로 받는다.
## THP — 커널이 조건이 맞을 때 알아서 쓰는 방식
## THP는 커널이 조건에 따라 큰 페이지를 사용한다
THP 는 Linux 가 가능한 메모리 영역에 대해 Huge Page 를 투명하게 활용하려는 기능이다. 애플리케이션이 평소처럼 `malloc()` 이나 `mmap()` 을 부르면 커널이 조건이 맞는 영역에 Huge Page 활용을 시도한다. 애플리케이션이 큰 페이지를 달라고 따로 요청하지 않는다는 뜻에서 투명하다.
@@ -90,7 +90,7 @@ cat /sys/kernel/mm/transparent_hugepage/enabled
always [madvise] never
```
이 값은 커널과 배포판, 호스트 설정에 따라 다르므로 실제 시스템에서 확인한다. 그래서 원문은 메모리 실험마다 반드시 같이 남길 조건 목록에 THP policy 를 Host 항목으로, Memory backing 설정을 VM 항목으로 넣어 두었다. 조건을 남기지 않으면 "Memory pressure에서 느려졌다"는 결과를 다른 환경에 재사용하기 어렵다는 것이 그 목록에 붙은 이유다.
THP policy와 VM memory backing 설정은 커널과 호스트 구성에 따라 달라질 수 있으므로 메모리 실험마다 함께 기록한다. 이 조건이 빠지면 같은 memory pressure 결과를 다른 환경과 비교하기 어렵다.
## THP 가 치르는 비용
@@ -108,9 +108,9 @@ Compaction 가능
Latency 영향 가능
```
그래서 THP 는 항상 성능을 높인다고 단정할 수 없다. 특히 지연에 민감한 워크로드에서는 측정이 필요하다고 원문이 직접 적었고, 이 서버에서 그 측정을 하지 않았다.
THP가 항상 성능을 높인다고 단정할 수는 없다. 특히 지연에 민감한 워크로드에서는 실제 latency를 비교해야 하며, 이 서버에서는 THP on/off 성능 비교를 수행하지 않았다.
## HugeTLB — 미리 확보해 둔 풀
## HugeTLB는 큰 페이지를 미리 예약한다
HugeTLB 는 Huge Page 풀을 명시적으로 두고 쓸 수 있는 Linux 메커니즘이다. 커널이 알아서 활용하는 THP 와 달리, 관리자가 풀을 준비하고 애플리케이션이나 가상 머신이 그 풀을 명시적으로 쓴다.
@@ -137,7 +137,7 @@ Physical RAM
| 관리 | 커널이 투명하게 활용 | 명시적인 풀 |
| 애플리케이션 개입 | 상대적으로 적음 | 명시적 구성 가능 |
| 유연성 | 상대적으로 높음 | 상대적으로 낮음 |
| 사전 예약 | 핵심 방식 아님 | 가능 |
| 사전 예약 | 기본 동작 아님 | 가능 |
| compaction 영향 | 발생 가능 | 미리 확보해 일부 상황 회피 가능 |
| 가상 머신 RAM backing | 사용 가능 | 명시적으로 사용 가능 |
@@ -28,7 +28,7 @@ source:
# Host 메모리 압박이 Guest 와 스토리지까지 내려가는 경로
가상 머신들에 설정한 메모리 총량이 호스트의 물리 RAM 보다 클 수 있다. 설정한 용량과 지금 실제로 쓰는 양이 같지 않다 보니 그런 구성이 성립하는데, 가상 머신들의 수요가 동시에 오르면 Linux 는 회수와 스왑으로 대응한다. CPU 가 모자랄 때는 스케줄러가 실행 시간을 나눠 주지만, RAM 이 모자랄 때는 나눌 시간이 없고 지금 존재해야 하는 페이지를 어디에 둘 것인가만 남는다. 그래서 호스트의 메모리 압박은 게스트 안에서 단순한 메모리 접근으로 보이던 동작을 스토리지 I/O 대기로 바꾸고, 여러 갈래의 I/O 가 한 물리 장치로 몰리면 DB 와 애플리케이션 지연까지 올린다. 회수로도 모자라면 OOM(Out Of Memory)으로 가는데, 그것을 게스트 커널이 처리했는지 호스트 커널이 처리했는지에 따라 멈추는 범위가 다르다.
가상 머신에 설정한 메모리와 호스트에서 실제로 사용하는 메모리는 같은 값이 아니다. 여러 VM의 메모리 수요가 동시에 증가하면 Linux는 reclaim과 swap으로 물리 RAM을 확보하려고 한다. 이 과정에서 파일 재읽기나 swap I/O가 발생하면 메모리 압박이 스토리지 지연으로 이어질 수 있다. 메모리를 더 확보하지 못하면 OOM이 발생하며, guest OOM인지 host OOM인지에 따라 영향을 받는 범위도 달라진다.
<!-- body:start -->
@@ -37,7 +37,7 @@ source:
## CPU 가 모자랄 때와 RAM 이 모자랄 때
가상 머신들에 설정한 메모리 총량이 호스트의 물리 RAM 보다 큰 구성을 메모리 초과 할당(memory overcommit)이라고 한다. 원문은 이 구성을 예시 숫자로 설명한다.
가상 머신들에 설정한 메모리 총량이 호스트의 물리 RAM보다 큰 구성을 메모리 초과 할당(memory overcommit)이라고 한다. 설정 메모리의 합이 물리 RAM보다 크더라도 각 VM이 동시에 최대치까지 사용하지 않으면 실행 자체는 가능하다.
```text label="설정 총량이 Host RAM 을 넘는 구성 — 개념 예시"
Host Physical RAM = 32 GiB
@@ -71,11 +71,11 @@ QEMU 가 게스트 RAM 으로 잡아 둔 호스트 물리 페이지가 스왑으
게스트 스왑은 게스트 애플리케이션의 메모리 압박을 게스트 커널이 받아 `/dev/vda` 로 내려보내는 경로다. 그 요청은 `virtio-blk` 와 virtqueue 를 거쳐 QEMU 로 가고 호스트 스토리지에 닿는다. 호스트 스왑은 시작하는 곳이 다르다. QEMU 가 게스트 RAM 으로 잡아 둔 호스트 메모리가 호스트 메모리 압박 아래에서 호스트 커널에 눌려 호스트 스왑으로 나간다. 시작하는 곳도 지나는 계층도 달라서 한쪽 값으로 다른 쪽을 짐작할 수 없다. 게스트가 메모리에 여유가 있어 보이는 동안에도 호스트에서는 스왑과 회수가 심할 수 있다.
## 네 갈래 I/O 가 한 장치로 몰릴 때
## 여러 I/O가 같은 저장장치를 공유할 때
게스트와 호스트가 동시에 메모리 압박을 겪으면 게스트 스왑 I/O 와 호스트 스왑 I/O, DB I/O, 파일 시스템 writeback 이 하나의 물리 NVMe 로 몰릴 수 있다. 그러면 호스트 메모리 압박이 회수와 스왑을 부르고, 늘어난 스토리지 I/O 가 스토리지 경쟁이 되고, DB 지연이 오르고, 그 위의 애플리케이션 지연까지 오른다.
메모리는 CPU 와 네트워크, 스토리지 실행을 모두 받치는 계층이라 압박이 메모리 안에서 끝나지 않는다. CPU 사용률이 낮은 구간에도 이 경로가 돌고 있을 수 있다.
호스트 메모리가 부족해 reclaim이나 swap이 발생하면 스토리지 I/O가 늘어날 수 있고, 그 영향이 게스트 응답 지연으로 이어질 수도 있다. 따라서 CPU 사용률이 낮더라도 메모리와 스토리지 지표를 함께 확인해야 한다.
그림에서는 호스트 메모리 압박 뒤에 갈라지는 경로만 남겼다. 깨끗한 파일 페이지 회수, 호스트 스왑과 스토리지 경쟁, 호스트 OOM은 같은 시작점에서 갈라지지만 게스트 OOM은 다른 커널에서 일어난다. 그래서 게스트 OOM은 같은 화살표에 억지로 붙이지 않고 아래에서 따로 구분한다.
@@ -43,7 +43,7 @@ RAM 을 하나의 균일한 자원처럼 다루면 어느 CPU 가 읽든 비용
한 가상 머신의 vCPU 스레드가 노드 0 의 CPU 에서 실행되는데 그 가상 머신을 받치는 호스트 물리 페이지가 노드 1 에 있다고 하자. 그러면 노드 0 의 CPU 가 인터커넥트를 지나 노드 1 의 RAM 을 읽게 된다. 게스트 안에서는 그냥 메모리 접근 한 번이고 게스트 OS 는 그 요청이 소켓을 건넜는지 알지 못하는데, 비용은 그 아래 하드웨어에서 붙는다.
## vCPU pinning 만으로는 끝나지 않는다
## NUMA에서는 vCPU와 메모리 배치를 함께 맞춘다
vCPU 를 특정 CPU 집합에 묶는 설정을 pinning 이라고 한다. 어떤 가상 머신의 vCPU 를 노드 0 의 CPU 에 pinning 했는데 그 가상 머신의 RAM 이 주로 노드 1 에 배치되어 있으면, pinning 이후에도 원격 접근이 많아질 수 있다. 묶은 것은 실행 위치이고 메모리가 어디에 있는지는 그 설정이 정하지 않기 때문이다.
@@ -47,7 +47,7 @@ Page Table을 조회
Page Fault 는 조건이 다르다. 페이지 테이블 상태로는 지금 접근을 정상으로 끝낼 수 없어서, 커널이 끼어들어 페이지를 마련하거나 매핑을 고쳐야 명령을 다시 시도할 수 있다. TLB Miss 는 테이블을 한 번 더 읽으면 풀리는데, 이쪽은 커널 처리를 부른다.
## 첫 번째 단계 — Guest Page Fault
## 게스트 페이지 폴트
이 fault 는 GVA 를 GPA 로 바꾸는 첫 번째 변환 단계에서 일어난다.
@@ -87,7 +87,7 @@ Instruction 재시도
## Guest Page Fault 를 부르는 다섯 가지
원문은 대표적인 원인을 다섯으로 나눈다. 앞의 넷은 커널이 처리해 실행이 이어지고, 마지막 하나만 프로세스로 신호가 간다.
게스트 page fault의 대표적인 원인은 demand paging, copy-on-write, file-backed page 재읽기, swap-in, 잘못된 주소 접근으로 나눌 수 있다. 앞의 경우들은 커널이 페이지를 준비한 뒤 실행을 이어갈 수 있지만, 유효하지 않은 주소 접근은 프로세스에 신호가 전달될 수 있다.
| 원인 | 게스트 커널이 무엇을 하나 |
|---|---|
@@ -108,7 +108,7 @@ Executable: 0
이 엔트리로 매핑된 페이지에 쓰기가 들어가면 fault 가 날 수 있고, Copy-on-Write 는 그 성질을 거꾸로 이용해 쓰기가 들어온 순간에만 페이지를 복제한다. 다섯 가운데 Invalid Access 만 결과가 다르다. 게스트 커널이 정상적인 매핑으로 해결할 수 없는 접근이면 `SIGSEGV` 로 이어질 수 있고, 그래서 Page Fault 와 Segmentation Fault 는 같은 것이 아니다.
## 두 번째 단계 — EPT Violation
## EPT Violation
이번에는 게스트 페이지 테이블 변환이 성공해 GPA 까지 얻었다고 하자. 그런데 그 GPA 에 대한 두 번째 단계 접근을 지금 EPT(Extended Page Tables) 조건으로 끝낼 수 없으면 EPT Violation 이 된다.
@@ -142,7 +142,7 @@ KVM
Guest Page Fault 는 게스트가 자기 가상 메모리를 처리하는 사건이고, EPT Violation 은 두 번째 단계 가상화 변환에서 하이퍼바이저 처리가 필요한 사건이다. 마지막 줄이 둘 다 「반드시 아님」인 까닭은 앞에서 본 대로다. demand paging 이나 copy-on-write 처럼 정상 동작이 두 계층 모두에서 fault 를 만든다.
## 세 번째 — Host Page Fault
## 호스트 페이지 폴트
QEMU 도 호스트의 일반 사용자 공간 프로세스이므로 QEMU 가 마련한 메모리에는 호스트의 가상 메모리 관리가 그대로 적용된다. 게스트 RAM 을 담고 있는 그 영역도 호스트 페이지 테이블을 지나 호스트 물리 주소로 이어지고, 그 경로에서 demand allocation 이나 reclaim, swap 때문에 fault 가 날 수 있다.
@@ -45,7 +45,7 @@ source:
2026-09-21 재검증에서 세 VM의 domain XML에 모두 `<memballoon model='virtio'>`가 있었고, worker guest 둘에서는 `/sys/bus/virtio/drivers/virtio_balloon` 아래에 `virtio5`가 bind된 것도 확인했다. 따라서 이 프로젝트의 가상 머신에는 virtio-balloon 장치가 실제로 붙어 있다.
## Inflate — 게스트 안의 balloon 이 커진다
## Inflate에서 게스트 메모리가 balloon에 할당된다
호스트가 게스트 메모리를 회수하려고 하면 balloon target 을 조정해 balloon 을 부풀린다. 이 동작을 inflate 라고 한다. 그 요청이 `virtio-balloon` 을 지나 게스트 안의 balloon 드라이버에 닿으면 드라이버가 게스트 페이지를 확보한다. 게스트 안의 balloon 이 커지기 때문에 게스트가 쓸 수 있는 RAM 이 그만큼 줄고, 호스트 쪽에서는 회수할 수 있는 메모리가 는다.
@@ -53,7 +53,7 @@ source:
![virtio-balloon Driver 와 virtqueue, QEMU virtio-balloon Device, Host Memory Management 네 참여자 사이를 여섯 개의 메시지가 오가는 순서도. 1번부터 3번까지는 Host 쪽에서 정한 balloon target 조정이 QEMU device 와 virtqueue 를 지나 VM Boundary 를 넘어 Guest kernel 의 driver 에 닿는 방향이고, 4번부터 6번까지는 driver 가 확보한 Guest page 가 같은 경계를 반대로 건너 Host 의 회수 가능 backing 이 되는 방향이다.](../../../final/assets/diagrams/virtio-balloon-inflate-deflate/virtio-balloon-inflate-deflate.svg)
## Deflate — target 을 줄이면 되돌아온다
## Deflate에서 balloon 메모리를 게스트에 돌려준다
호스트가 게스트에게 메모리를 다시 내줄 수 있으면 balloon target 을 줄인다. 그러면 게스트 balloon 드라이버가 붙잡고 있던 페이지를 반환하고 게스트가 쓸 수 있는 메모리가 늘어난다.
@@ -21,7 +21,7 @@ source:
# 게스트 page fault 증가는 workload 변화를 따라가는가
2026-09-21 `kc-lab-2`에서 anonymous 512 MiB를 `mmap()`한 뒤 4 KiB마다 한 번씩 touch하는 workload를 실행했다. 131,072 page를 처음 접근하는 동안 해당 Python process의 minor fault는 131,073 증가했고 major fault는 증가하지 않았다. 같은 구간의 guest 전체 `pgfault`는 131,177 증가했지만 `pgmajfault`, `pswpin`, `pswpout`은 0 증가였다. **workload가 새 page를 실제로 접근하자 정상 demand paging에 해당하는 minor fault가 함께 증가**하는 것을 확인했다.
2026-09-21 `kc-lab-2`에서 anonymous 512 MiB를 `mmap()`한 뒤 4 KiB마다 한 번씩 touch하는 workload를 실행했다. 131,072 page를 처음 접근하는 동안 해당 Python process의 minor fault는 131,073 증가했고 major fault는 증가하지 않았다. 같은 구간의 guest 전체 `pgfault`는 131,177 증가했지만 `pgmajfault`, `pswpin`, `pswpout`은 0 증가였다. workload가 새 page를 실제로 접근하자 정상 demand paging에 해당하는 minor fault가 함께 증가하는 것을 확인했다.
## 512MiB demand paging 결과
@@ -25,7 +25,7 @@ source:
# 호스트 major fault 와 스토리지 지연은 같은 시간축에서 함께 움직이는가
2026-09-21 단계형 host memory pressure 실험에서 major fault, swap 상태, NVMe `iostat`, guest OIDC latency를 같은 실행으로 기록했다. host major fault는 증가했지만 zswap이 swap-out을 압축 메모리에서 흡수해 NVMe 지연이 함께 상승하지 않았다. 따라서 **현재 압박 수준에서는 major fault 증가와 storage latency 상승의 동행이 관측되지 않았다.**
2026-09-21 단계형 host memory pressure 실험에서 major fault, swap 상태, NVMe `iostat`, guest OIDC latency를 같은 실행으로 기록했다. host major fault는 증가했지만 zswap이 swap-out을 압축 메모리에서 흡수해 NVMe 지연이 함께 상승하지 않았다. 따라서 현재 압박 수준에서는 major fault 증가와 storage latency 상승의 동행이 관측되지 않았다.
## host major fault와 storage를 같이 본 결과
@@ -2,7 +2,7 @@
id: a05fe2a6-eb7c-4bcc-a7da-58e729436468
kind: QUESTION
slug: host-memory-pressure-vs-guest-latency
title: 호스트 메모리 압박이 게스트 애플리케이션 지연을 실제로 밀어 올리는가
title: 호스트 메모리 압박이 게스트 애플리케이션 지연에 영향을 주는가
topic: memory-virtualization
topicName: 메모리 가상화
project: virtualization
@@ -27,9 +27,9 @@ source:
- final/document.md#62-memory-pressure와-storage-contention의-연결
---
# 호스트 메모리 압박이 게스트 애플리케이션 지연을 실제로 밀어 올리는가
# 호스트 메모리 압박이 게스트 애플리케이션 지연에 영향을 주는가
2026-09-21 host에서 anonymous memory를 256 MiB씩 늘려 최대 3.5 GiB를 추가 할당했고 `MemAvailable`을 약 512 MiB까지 낮춘 뒤 12초 유지했다. 이 구간에서 host swap 사용량과 major fault는 증가했지만, zswap이 swap-out을 압축 메모리에서 흡수해 NVMe storage pressure로 크게 이어지지 않았고 OIDC discovery 지연도 baseline보다 악화되지 않았다. 따라서 **현재 압박 수준에서는 host memory pressure가 guest application latency를 밀어 올리는 경로가 재현되지 않았다.**
2026-09-21 host에서 anonymous memory를 256 MiB씩 늘려 최대 3.5 GiB를 추가 할당했고 `MemAvailable`을 약 512 MiB까지 낮춘 뒤 12초 유지했다. 이 구간에서 host swap 사용량과 major fault는 증가했지만, zswap이 swap-out을 압축 메모리에서 흡수해 NVMe storage pressure로 크게 이어지지 않았고 OIDC discovery 지연도 baseline보다 악화되지 않았다. 현재 압박 수준에서는 host memory pressure와 함께 guest application latency가 증가하는 현상은 관측되지 않았다.
## 압박 전후 guest latency 결과
@@ -22,7 +22,7 @@ source:
# NUMA remote access 가 이 작업의 지연을 실제로 바꾸는가
2026-09-21 현재 `test-server`는 NUMA node가 하나뿐이다. CPU `0-7`과 QEMU memory가 모두 `node0`에 있으므로 이 host에서는 local 배치와 remote 배치를 만들어 비교하는 실험 자체가 성립하지 않는다. 따라서 이 질문은 **현재 환경에는 적용되지 않는 것으로 해소**한다.
2026-09-21 현재 `test-server`는 NUMA node가 하나뿐이다. CPU `0-7`과 QEMU memory가 모두 `node0`에 있으므로 이 host에서는 local 배치와 remote 배치를 만들어 비교하는 실험 자체가 성립하지 않는다. 이 호스트에서는 remote NUMA 배치를 만들 수 없으므로 local/remote NUMA에 따른 지연 차이를 비교할 수 없다.
## 이 호스트에서 실험이 성립하지 않는 이유
@@ -2,7 +2,7 @@
id: fa5b3782-9fcf-4113-8f51-a55c8023b2db
kind: QUESTION
slug: qemu-resident-memory-distribution
title: QEMU 프로세스가 실제로 붙잡고 있는 호스트 메모리는 얼마이고 어떻게 나뉘어 있는가
title: QEMU 프로세스의 호스트 메모리 사용량은 얼마인가
topic: memory-virtualization
topicName: 메모리 가상화
project: virtualization
@@ -20,7 +20,7 @@ source:
- final/document.md#42-configured-memory와-실제-physical-ram-사용량은-같지-않을-수-있다
---
# QEMU 프로세스가 실제로 붙잡고 있는 호스트 메모리는 얼마이고 어떻게 나뉘어 있는가
# QEMU 프로세스의 호스트 메모리 사용량은 얼마인가
2026-09-21 세 QEMU 프로세스의 `smaps_rollup`을 직접 읽었다. configured memory와 host RSS는 같지 않았고, resident memory의 대부분은 anonymous이며 큰 부분이 THP `AnonHugePages`로 backing돼 있었다. exact RSS는 workload와 시점에 따라 달라지는 관측값이다.
@@ -60,7 +60,7 @@ smaps_rollup 을 읽을 권한이 있다고 전제한다. 다른 사용자의
2026-09-21에는 세 QEMU 프로세스의 RSS를 실제로 읽었다. `kc-lab-1`은 약 3.73GiB, `kc-lab-2`는 약 2.91GiB, edge는 약 0.84GiB였다. 개념 설명에 쓰인 8GiB·16GiB 예시는 이 측정값과 구분한다.
설정한 메모리를 옆에 놓지 않으면 얼마나 벌어져 있는지 적을 수 없다. 그 값은 「이 호스트의 가상 머신들은 설정한 메모리와 지금 잡고 있는 메모리가 얼마나 다른가」가 받는다.
QEMU RSS는 VM에 설정한 메모리와 함께 기록해야 차이를 해석할 수 있다. configured/current memory와 RSS는 같은 시각에 측정하되 서로 다른 지표로 남긴다.
「Configured Memory와 실제 Physical RAM 사용량은 같지 않을 수 있다」에서는 게스트 사용량과 호스트 resident 를 다른 값으로 갈라 놓았기 때문에, resident 크기 하나로는 게스트가 그 메모리를 지금 쓰고 있는지 알 수 없다.
@@ -22,7 +22,7 @@ source:
# 지금 게스트와 호스트에서 swap 이 실제로 오가고 있는가
2026-09-21 짧은 관측 구간에서 worker guest 둘의 swap은 0이고, host에는 약 260 MiB의 swap 사용량이 남아 있었지만 `vmstat 1 5`의 `si/so`는 host와 worker 둘 모두 계속 0이었다. 따라서 **swap 사용량이 남아 있다는 사실과 현재 swap I/O가 진행 중이라는 사실은 다르다**는 것을 이 host에서 직접 확인했다.
2026-09-21 짧은 관측 구간에서 worker guest 둘의 swap은 0이고, host에는 약 260 MiB의 swap 사용량이 남아 있었지만 `vmstat 1 5`의 `si/so`는 host와 worker 둘 모두 계속 0이었다. 따라서 swap 사용량이 남아 있다는 사실과 현재 swap I/O가 진행 중이라는 사실은 다르다는 것을 이 host에서 직접 확인했다.
## host와 guest swap 관찰 결과
@@ -23,7 +23,7 @@ source:
# 이 가상 머신들에 virtio-balloon 이 붙어 있는가
2026-09-21 세 domain XML 모두 `<memballoon model='virtio'>`를 가지고 있고, worker guest 둘에서도 virtio-balloon driver에 `virtio5` 장치가 bind돼 있었다. 따라서 장치 구성 여부는 확인됐다. 다만 현재 `dommemstat actual`은 configured/current memory와 같아서 **장치가 존재한다는 사실만으로 지금 balloon이 메모리를 회수 중이라고 말할 수는 없다.**
2026-09-21 세 domain XML 모두 `<memballoon model='virtio'>`를 가지고 있고, worker guest 둘에서도 virtio-balloon driver에 `virtio5` 장치가 bind돼 있었다. 따라서 장치 구성 여부는 확인됐다. 다만 현재 `dommemstat actual`은 configured/current memory와 같아서 장치가 존재한다는 사실만으로 지금 balloon이 메모리를 회수 중이라고 말할 수는 없다.
## 세 VM의 balloon 장치 상태
@@ -41,7 +41,7 @@ source:
- 「자원 — 할당과 실사용은 다르다」에서는 virsh dommemstat 으로 k3s 게스트 두 대를 재서 아래 값을 받았다. k3s 만 떠 있고 Keycloak 은 올리기 전 상태다.
kc-lab-1 : 할당 5120MB · 실사용 353MB
kc-lab-2 : 할당 3120MB · 실사용 301MB
- 2026-09-10 historical snapshot에서는 `virt-install --memory 4096`으로 만든 `kc-lab-2`의 `dommemstat actual`이 3120MB였다. 당시 문서는 balloon 가능성을 추론했지만 원인을 검증하지 않았다. 2026-09-21 재검증에서는 actual이 4096MiB로 configured/current와 같았다.
- 2026-09-10 기록에서는 `virt-install --memory 4096`으로 만든 `kc-lab-2`의 `dommemstat actual`이 3120MB였다. 당시 문서는 balloon 가능성을 추론했지만 원인을 검증하지 않았다. 2026-09-21 재검증에서는 actual이 4096MiB로 configured/current와 같았다.
- 「자원 — 할당과 실사용은 다르다」에서는 dommemstat 의 actual 이 현재 할당이고 선언한 상한은 virsh dominfo 의 Max memory 에 있다고 적으면서, 이 실험대에서 그 두 값을 나란히 찍어 보지 않았다고 미측정으로 남겼다.
- 「단계 01 — 게스트 세 대」에 적은 게스트는 kc-lab-edge · kc-lab-1 · kc-lab-2 세 대이고, 「자원 — 할당과 실사용은 다르다」의 측정에 kc-lab-edge 는 들어 있지 않다.
- 이 호스트의 가상 머신 설정에서 balloon 관련 요소를 읽은 기록이 개념 문서에 없다.
@@ -81,7 +81,7 @@ Configured RAM과 Current RAM은 이후 memory pressure나 balloon 실험에서
이 질문에서 확인한 것은 configured/current와 실제 점유가 다르다는 사실까지다. 메모리 압박이 생겼을 때 reclaim·swap·guest latency가 어떻게 변하는지는 별도 pressure 실험에서 본다.
QEMU 프로세스 쪽 값은 여기서 닫지 않는다. virsh 가 보고하는 값과 프로세스가 실제로 잡고 있는 크기는 다른 관측이고, 그것은 「QEMU 프로세스가 실제로 붙잡고 있는 호스트 메모리는 얼마이고 어떻게 나뉘어 있는가」가 받는다.
`virsh`가 보고하는 configured/current memory와 QEMU 프로세스의 RSS는 서로 다른 값이다. 여기서는 VM 설정값과 guest-visible memory를 확인하고, QEMU RSS는 같은 시각에 별도 호스트 지표로 기록한다.
## 설정값과 live 값, guest-visible memory를 나란히 봤다
@@ -101,7 +101,7 @@ VM 하나로 표 모양을 먼저 정하는 방법은 가능하지만, VM별 값
호스트에 한 번 붙는 김에 ps 로 QEMU 프로세스의 크기까지 받아 적자는 방법이다. 실행 횟수는 줄어든다.
QEMU 쪽은 별도의 물음이 이미 받고 있고 그쪽은 anonymous 인지 huge page 인지까지 보기 때문에, 여기서 함께 읽으면 어느 물음의 기준으로 닫혔는지가 남지 않는다. 두 물음의 실행 시각을 맞추고 싶으면 같은 접속에서 순서대로 돌리고 각각의 기록에 남긴다.
QEMU RSS의 anonymous memory와 `AnonHugePages` 구성은 VM 설정값과 구분해 기록한다. 두 값을 비교하려면 같은 시각에 순서대로 측정해 시점 차이를 줄인다.
## 메모리를 바꾸면 설정값·현재값·guest 값을 다시 비교한다
@@ -21,7 +21,7 @@ source:
# 가상 머신 RAM 이 HugeTLB 로 명시적으로 backing 되어 있는가
2026-09-21 현재 세 VM은 **명시적 HugeTLB backing을 사용하지 않는다.** domain XML에 `memoryBacking/hugepages`가 없고 host는 `HugePages_Total=0`, `Hugetlb=0 kB`다. QEMU `smaps_rollup`의 큰 `AnonHugePages` 값은 THP이며 HugeTLB pool 사용의 증거가 아니다.
2026-09-21 현재 세 VM은 명시적 HugeTLB backing을 사용하지 않는다. domain XML에 `memoryBacking/hugepages`가 없고 host는 `HugePages_Total=0`, `Hugetlb=0 kB`다. QEMU `smaps_rollup`의 큰 `AnonHugePages` 값은 THP이며 HugeTLB pool 사용의 증거가 아니다.
## 현재 HugeTLB backing 상태
@@ -20,7 +20,7 @@ source:
# 메모리 증상 하나로 계층을 단정하지 않는다
메모리 지연이나 OOM 이 보이면 「메모리 부족」으로 닫지 말고 「문제를 진단할 때의 분류」의 다섯 갈래로 먼저 가른다. Guest Virtual Memory · Virtualization Translation · Host Memory · Dynamic Memory · NUMA 다섯이다. 「Swap Used만 보고 장애를 판단하면 안 된다」· 「NUMA는 실제 장비 topology부터 확인한다」· 「결론」에서는 따로 요구한 판독도 이 한 절차로 묶었다.
메모리 지연이나 OOM을 분석할 때는 게스트 가상 메모리, 주소 변환, 호스트 메모리, 동적 메모리 회수, NUMA를 구분해서 본다. 예를 들어 swap 사용량이 남아 있다는 사실과 현재 swap I/O가 발생한다는 사실은 다르고, NUMA 문제도 실제 호스트가 여러 NUMA node를 가질 때만 비교할 수 있다.
## 메모리 증상 하나로 결론내리면 안 되는 이유
@@ -67,7 +67,7 @@ storage latency 가 같이 증가하는가?
### 4. OOM 은 발생 계층을 확인한 뒤에 부른다
「Guest OOM과 Host OOM」에서는 게스트 OOM 과 호스트 OOM 을 갈랐다. 게스트 RAM 이 모자라서 게스트 커널이 프로세스를 죽이면 Keycloak 프로세스 종료 같은 결과가 된다. 호스트 물리 RAM 이 모자라서 호스트 커널이 QEMU 를 victim 으로 고르면 그 VM 전체가 중단될 수 있다.
「Guest OOM과 Host OOM」에서는 게스트 OOM 과 호스트 OOM 을 갈랐다. 게스트 RAM이 부족해 게스트 커널의 OOM killer가 프로세스를 종료하면 Keycloak 프로세스가 종료될 수 있다. 호스트 물리 RAM 이 모자라서 호스트 커널이 QEMU 를 victim 으로 고르면 그 VM 전체가 중단될 수 있다.
cgroup memory limit 이 걸린 환경은 예외로 둔다. 호스트 전체 RAM 에 여유가 있어도 그 cgroup 경계에서 OOM 이 발생할 수 있다고 같은 절이 적었다.
@@ -103,7 +103,7 @@ NUMA node 가 하나인 호스트에서는 NUMA 갈래의 우선순위를 낮춰
- 게스트에서 Swap Used 만 보고 「메모리 부족」으로 닫은 판독 : swap-in/out 이 지속되는지를 재지 않았다
- 게스트 free -h 에 여유가 보여 호스트를 보지 않은 판독 : 호스트 reclaim 과 호스트 스왑을 확인하지 않았다
- Keycloak 프로세스가 죽었는데 호스트 커널 로그를 보지 않은 판독 : 게스트 OOM 인지 호스트 OOM 인지 갈리지 않는다
- Keycloak 프로세스가 종료됐는데 호스트 커널 로그를 확인하지 않은 판독 : 게스트 OOM 인지 호스트 OOM 인지 갈리지 않는다
- 호스트 RAM 에 여유가 있다는 이유로 OOM 을 다른 갈래로 넘긴 판독 : cgroup 경계를 확인하지 않았다
- 토폴로지를 재지 않고 vCPU pinning 부터 손댄 조치 : NUMA 갈래가 이 호스트에 걸리는지 모른다
- 게스트와 호스트를 다른 시각에 찍어 한 표로 놓은 기록 : 같은 시간축이 아니다
@@ -17,7 +17,7 @@ source:
# 메모리 실험 결과에는 Host · VM · Workload 조건을 함께 남긴다
메모리 측정은 값만 남기면 다음 사람이 그 값을 어디에 쓸 수 있는지 알 수 없다. 「실험 시 반드시 같이 기록할 것」에서는 실험마다 함께 적을 조건을 Host 여덟 · VM 일곱 · Workload 다섯으로 못박았다. 이유도 한 줄로 적었는데, 조건을 남기지 않으면 「Memory pressure에서 느려졌다」는 결과를 다른 환경에 재사용하기 어렵다는 것이다.
메모리 실험 결과에는 측정값과 함께 호스트, VM, 워크로드 조건을 남긴다. 같은 메모리 압박이라도 호스트 RAM, swap·zswap 상태, VM 메모리 설정, NUMA 구성, 워크로드가 다르면 결과가 달라질 수 있기 때문이다.
## 조건표가 결과만큼 중요한 이유
@@ -2,7 +2,7 @@
id: 5b1de31c-0495-4226-8607-73ed7284b314
kind: CONCEPT
slug: guest-packet-path-to-physical-nic
title: Guest 의 packet 이 Host Physical NIC 에 닿기까지 — virtio-net · virtqueue · vhost-net · TAP · Bridge
title: 게스트 패킷이 호스트 물리 NIC까지 전달되는 과정
topic: network-virtualization
topicName: 네트워크 가상화
project: virtualization
@@ -48,7 +48,7 @@ source:
- final/document.md#124-핵심-claim
---
# Guest 의 packet 이 Host Physical NIC 에 닿기까지 — virtio-net · virtqueue · vhost-net · TAP · Bridge
# 게스트 패킷이 호스트 물리 NIC까지 전달되는 과정
가상 머신 안의 Keycloak 이 HTTP 요청 하나를 받으려면 그 패킷이 호스트의 물리 NIC 에서 Linux Bridge 와 TAP, vhost-net, virtqueue 를 지나 게스트 커널의 TCP/IP 스택까지 올라와야 한다. virtio-net 은 그 경로에 놓인 프로그램 하나가 아니라 게스트 쪽 프런트엔드 드라이버와 호스트 쪽 백엔드를 잇는 I/O 계약이고, 그 백엔드 자리는 QEMU 사용자 공간이 맡을 수도 호스트 커널의 vhost-net 이 맡을 수도 있다. 가상 머신 두 대로 Keycloak 멀티 노드 실험을 돌리다 요청이 느려지거나 아예 닿지 않으면, 이 경로를 알아야 그 증상을 애플리케이션·저장소 쪽 문제와 네트워크 가상화 계층 문제로 갈라 볼 수 있다.
@@ -57,7 +57,7 @@ source:
## virtio-net 은 어디에 있는가
virtio 는 명령어가 아니고 프로그램 하나도 커널 모듈 하나도 아니다. 게스트와 호스트/하이퍼바이저가 가상 I/O 장치를 효율적으로 쓰려고 정해 둔 표준화된 인터페이스이자 프로토콜이다. 그 계열에는 네트워크의 virtio-net 과 블록 I/O 의 virtio-blk 가 있다. SCSI(Small Computer System Interface) 의 virtio-scsi 와 메모리 벌룬의 virtio-balloon 도 같은 계열이고, 이 글은 그중 virtio-net 을 다룬다.
virtio 는 명령어가 아니고 프로그램 하나도 커널 모듈 하나도 아니다. 게스트와 호스트/하이퍼바이저가 가상 I/O 장치를 효율적으로 쓰려고 정해 둔 표준화된 인터페이스이자 프로토콜이다. 그 계열에는 네트워크의 virtio-net 과 블록 I/O 의 virtio-blk 가 있다. SCSI(Small Computer System Interface)의 virtio-scsi와 메모리 벌룬의 virtio-balloon도 같은 계열이다.
가상 NIC 를 성립시키는 구현은 게스트와 호스트로 나뉘어 있다. 게스트 커널 쪽에는 TCP/IP 스택과 virtio-net 프런트엔드 드라이버, virtqueue 가 들어 있다.
@@ -31,12 +31,12 @@ source:
# 외부 요청은 Host DNAT와 Edge Nginx를 거쳐 Keycloak까지 어디를 지나는가
2026-09-21 같은 OIDC discovery 요청을 `tailscale0`, `virbr0`, edge의 `vnet13/enp1s0`, worker의 `vnet18/vnet19/enp1s0`에서 추적했다. 실제 경로는 **Tailscale ingress → host DNAT/source rewrite → edge Nginx → virbr0 L2 forwarding → worker Traefik**으로 확인됐다. edge Nginx가 TLS를 종료한 뒤 worker로 새 HTTP 연결을 만들기 때문에 ingress TLS 연결과 worker HTTP 연결은 같은 TCP flow가 아니다.
2026-09-21 같은 OIDC discovery 요청을 `tailscale0`, `virbr0`, edge의 `vnet13/enp1s0`, worker의 `vnet18/vnet19/enp1s0`에서 추적했다. 실제 경로는 Tailscale ingress → host DNAT/source rewrite → edge Nginx → virbr0 L2 forwarding → worker Traefik으로 확인됐다. edge Nginx가 TLS를 종료한 뒤 worker로 새 HTTP 연결을 만들기 때문에 ingress TLS 연결과 worker HTTP 연결은 같은 TCP flow가 아니다.
## 2026-09-21에 캡처한 실제 경로
- 2026-09-21 재검증에서 workmachine의 요청은 `tailscale0`에서 `100.92.240.34:42996 → 100.83.212.4:443`으로 보였다. 같은 TCP sequence가 `vnet13`에서는 `192.168.122.1:42996 → 192.168.122.10:443`으로 보였다. destination DNAT뿐 아니라 source rewrite도 실제로 발생했다.
- host `ip nat`에는 Tailscale의 `ts-postrouting` chain이 있고 fwmark `0x00040000` 패킷을 `MASQUERADE`하는 규칙이 존재했다. 따라서 기존 문서의 “lab_edge에 SNAT 규칙이 없으므로 edge가 원래 Tailscale client IP를 그대로 본다”는 설명은 현재 전체 netfilter 경로를 설명하지 못한다.
- host `ip nat`에는 Tailscale의 `ts-postrouting` chain이 있고 fwmark `0x00040000` 패킷을 `MASQUERADE`하는 규칙이 존재했다. 따라서 Edge VM이 항상 원래 Tailscale client IP를 그대로 본다고 가정할 수 없으며, 현재 netfilter 전체 경로를 기준으로 source address를 확인해야 한다.
- edge Nginx는 요청을 `192.168.122.10:<ephemeral> → 192.168.122.11:80` 또는 `.12:80`의 새 HTTP 연결로 전달했다. 6회 요청에서 `worker-1/3/5`는 `vnet18 → kc-lab-1 enp1s0`, `worker-2/4/6`은 `vnet19 → kc-lab-2 enp1s0`에서 동일 GET path가 확인됐다.
- packet capture 전에 `lab-edge-dnat.service`가 active였는데도 libvirt `guest_input`의 generic reject가 allow rule보다 앞에 있어 외부 443가 `connection refused`였다. service를 restart해 allow rule을 chain 앞쪽으로 다시 삽입한 뒤 같은 OIDC 요청이 HTTP 200으로 복구됐다. service active 여부만으로 forwarding 가능 여부를 판단할 수 없다.
- 이번 캡처 시점에는 host와 guest에서 `ethtool` feature 값을 확보하지 못했다. `79-network-offload-state.txt`에도 대상 이름만 남고 feature 출력은 없다. 따라서 `tcpdump`의 packet size/checksum을 wire-level 값으로 일반화하지 않고, 경로 판정에는 주소·포트·동일 HTTP path를 사용했다.
@@ -59,15 +59,15 @@ source:
전 : `tailnet:443` → 호스트 nginx → Traefik(게스트 .11/.12)
후 : `tailnet:443` → 호스트 커널 DNAT → 엣지 nginx(.10) → Traefik(.11/.12)
- 「엣지를 물리 호스트에서 VM 으로 옮기면 무엇이 새로 필요해지나」에서는 그렇게 옮겨도 L7 홉 수는 2홉 그대로라고 관측으로 적었다. 늘어난 것은 커널이 하는 L4 전달 한 번이다. 지금 호스트에는 `:443` 을 듣는 리스너가 없다.
- 「엣지를 물리 호스트에서 VM 으로 옮기면 무엇이 새로 필요해지나」에서는 옮긴 이유를 성능이 아니라 더러워지는 층의 격리로 적었다. nginx 설정과 인증서, certbot, deploy 훅은 자주 갈아엎는 것들인데 호스트에 있으면 초기화가 불가능하고, 엣지 장애 실험이 SSH 까지 위험하게 만든다. 그 대가로 일곱 가지가 새로 필요해졌고 「엣지를 물리 호스트에서 VM 으로 옮기면 무엇이 새로 필요해지나」에서는 그중 DNAT 와 libvirt 방화벽 구멍 둘을 이 이동의 본질로 꼽았다. 그 둘을 본질로 본 것은 추론이라고 밝혔다.
- Edge Nginx를 VM으로 분리하면서 외부 요청은 물리 호스트의 DNAT과 libvirt FORWARD 경로를 새로 지나게 됐다. 그래서 호스트 DNAT 규칙과 `guest_input`의 Edge VM 허용 규칙이 추가로 필요해졌다. nginx 설정과 인증서, certbot은 Edge VM에서 관리한다.
- 「엣지를 물리 호스트에서 VM 으로 옮기면 무엇이 새로 필요해지나」에서는 호스트에서 게스트로 가는 요청이 OUTPUT 경로라 필터를 타지 않는다고 적었다. 밖에서 게스트로 들어오는 요청은 FORWARD 경로라 libvirt 의 guest_input 체인을 지난다.
- 「`lab-edge-dnat.nft` — DNAT 파일이 자기 안에 적어 둔 네 가지」에서는 DNAT 파일에 forward 체인을 두지 않은 이유를 그 파일의 주석으로 적어 두었다. libvirt 의 guest_input 체인은 virbr0 으로 나가는 프레임을 reject 하며 끝난다. nftables 에서는 앞 base 체인의 accept 가 뒤 체인의 reject 를 멈추지 못하므로 구멍을 libvirt 체인 맨 앞에 뚫었고, 그래서 그 파일에 forward 체인이 없는 것은 실수가 아니다.
- 「`lab-edge-dnat.nft` — DNAT 파일이 자기 안에 적어 둔 네 가지」에서는 DNAT 파일에 forward 체인을 두지 않은 이유를 그 파일의 주석으로 적어 두었다. libvirt 의 guest_input 체인은 virbr0 으로 나가는 프레임을 reject 하며 끝난다. nftables에서는 앞 base chain의 accept가 뒤쪽 libvirt reject를 막지 못하므로 Edge VM 허용 규칙을 `guest_input`의 reject보다 앞에 추가했고, 그래서 그 파일에 forward 체인이 없는 것은 실수가 아니다.
- 「`lab-edge-dnat.nft` — DNAT 파일이 자기 안에 적어 둔 네 가지」에서는 이 DNAT 가 PREROUTING nat 에 있어 라우팅 결정보다 먼저 돌고 호스트의 로컬 소켓보다 이긴다고 적었다. 그래서 엣지를 띄운 채 전환하고, 되돌릴 때는 테이블 하나를 지운다.
- 「`lab-edge-dnat.nft` — DNAT 파일이 자기 안에 적어 둔 네 가지」에서는 DNAT 만 하고 SNAT 는 하지 않는다고 적었다. 게스트의 기본 경로가 호스트여서 응답이 이 경로를 다시 지나고 conntrack 이 변환을 알아서 되돌린다. masquerade 를 붙이면 엣지가 모든 클라이언트를 192.168.122.1 로 보게 된다.
- 「`lab-edge-dnat.service` — `ExecStartPost` 앞의 `-` 가 무엇을 봐주나」에서는 초기 설계의 의도를 설명했다. `ExecStartPost` 실패를 무시해 DNAT 자체는 살리고, 필요하면 유닛을 재시작해 accept 규칙을 다시 넣는 방식이었다. 하지만 2026-09-21 재검증에서 **유닛이 이미 active인 뒤 libvirt가 체인을 다시 쓰면 규칙 순서가 깨질 수 있음**이 확인됐다. 따라서 재시작은 현재 상태를 복구하는 수단일 뿐, 이후 libvirt chain rewrite까지 보장하는 persistence 해법으로 보지 않는다.
- 「`lab-edge-dnat.service` — `ExecStartPost` 앞의 `-` 가 무엇을 봐주나」에서는 그 상태에서 유닛이 active 이고 아무 오류도 없다고 적고, 유닛이 active 라는 것은 DNAT 가 실렸다는 뜻이지 구멍이 뚫렸다는 뜻이 아니라고 추론으로 밝혔다. 그 상태를 실제로 재현해 보지는 않았다고 적혀 있다.
- 「nftables 는 앞 체인의 `accept` 로 뒤 체인의 `reject` 를 막지 못한다」에서는 구멍이 빠졌을 때의 출력을 관측으로 남겼다. 호스트에서 게스트 주소로 친 curl 은 404 였고, 밖에서 tailnet 주소로 친 curl 은 connection refused 였다. reject 규칙의 카운터는 packets 4 bytes 240 으로 밖에서 친 횟수와 맞았다.
- 「엣지를 물리 호스트에서 VM 으로 옮기면 무엇이 새로 필요해지나」에서는 안쪽과 바깥쪽을 한 번씩 쳐서 같은 값이 나오는지 보는 확인을 적었다. 둘 다 404 면 경로가 이어진 것이고, 안쪽만 404 면 nginx 설치 · DNAT · libvirt 구멍 셋 가운데 하나가 빠진 것이다.
- 「`lab-edge-dnat.service` — `ExecStartPost` 앞의 `-` 가 무엇을 봐주나」에서는 그 상태에서 유닛이 active 이고 아무 오류도 없다고 적고, 유닛이 active라는 것은 DNAT가 적용됐다는 뜻이지 `guest_input` 허용 규칙까지 적용됐다는 뜻은 아니라고 추론으로 밝혔다. 그 상태를 실제로 재현해 보지는 않았다고 적혀 있다.
- 「nftables 는 앞 체인의 `accept` 로 뒤 체인의 `reject` 를 막지 못한다」에서는 `guest_input` 허용 규칙이 없을 때의 출력을 관측으로 남겼다. 호스트에서 게스트 주소로 친 curl 은 404 였고, 밖에서 tailnet 주소로 친 curl 은 connection refused 였다. reject 규칙의 카운터는 packets 4 bytes 240 으로 밖에서 친 횟수와 맞았다.
- 「엣지를 물리 호스트에서 VM 으로 옮기면 무엇이 새로 필요해지나」에서는 안쪽과 바깥쪽을 한 번씩 쳐서 같은 값이 나오는지 보는 확인을 적었다. 둘 다 404면 해당 경로가 이어진 것이고, 안쪽만 404면 nginx 설정, DNAT, libvirt `guest_input` 허용 규칙 가운데 하나를 확인한다.
- 2026-09-21에는 host ingress, edge vnet/guest NIC, worker vnet/guest NIC에서 같은 OIDC 요청을 캡처해 실제 경로를 이어 붙였다. 따라서 과거의 기준 구조 그림과 현재 Edge VM 구조를 구분해 읽을 수 있게 됐다.
## capture를 해석한 기준
@@ -25,7 +25,7 @@ source:
# 이 호스트에서 vhost-net 이 실제로 packet datapath 를 맡고 있는가
2026-09-21 실제 `test-server`에서 세 VM의 QEMU 실행 인자를 읽었다. `kc-lab-1`·`kc-lab-2`·`kc-lab-edge` 모두 TAP netdev에 `vhost:true`와 `vhostfd`가 설정돼 있었다. 따라서 현재 세 VM의 packet datapath backend는 **vhost-net**이다. `lsmod`에 모듈이 올라와 있다는 사실만으로 결론내리지 않고 VM별 QEMU 구성까지 확인했다.
2026-09-21 실제 `test-server`에서 세 VM의 QEMU 실행 인자를 읽었다. `kc-lab-1`·`kc-lab-2`·`kc-lab-edge` 모두 TAP netdev에 `vhost:true`와 `vhostfd`가 설정돼 있었다. 따라서 현재 세 VM의 packet datapath backend는 vhost-net이다. `lsmod`에 모듈이 올라와 있다는 사실만으로 결론내리지 않고 VM별 QEMU 구성까지 확인했다.
## runtime에서 확인한 backend
@@ -43,8 +43,8 @@ source:
Feature negotiation · Queue configuration · Backend 연결
Device reset · Control/configuration handling
- 「vhost-net 미사용 또는 비효율적 datapath」에서는 초당 지나는 패킷이 많은데 QEMU 사용자 공간이 데이터 경로를 직접 처리하면 CPU 오버헤드가 커질 수 있다고 밝혔다. 관찰 대상으로는 QEMU CPU usage · vhost thread · packet rate · latency · context switch 를 들었다.
- 원문의 3번째 확인 항목과 「실제 Linux에서 확인할 명령어」에 적힌 명령은 `lsmod | grep vhost` 하나다. 이어서 QEMU arguments 와 libvirt domain XML 도 확인한다고 적혀 있지만, 그 둘을 읽는 구체적인 명령은 제3부에 없었다.
- 원문은 개념에서 질문을 만들고 실제 환경에서 확인하는 흐름의 예로 이 항목을 들었다. 출발점은 「vhost-net은 QEMU userspace를 우회해 packet datapath를 처리할 수 있다」였고, 실제 환경에서 확인할 내용은 「현재 테스트 Host에서 vhost-net이 실제 활성화되어 있는가?」였다.
- `lsmod | grep vhost`만으로는 VM별 backend 사용 여부를 확정할 수 없다. QEMU arguments와 libvirt domain XML까지 함께 확인한다.
- vhost-net은 QEMU userspace를 거치는 패킷 처리 비용을 줄일 수 있지만, 기능이 존재한다는 사실과 현재 VM이 실제로 사용하는지는 별개다. 이 환경에서는 QEMU 실행 인자와 libvirt XML을 함께 확인해 현재 backend를 판정한다.
- 「이 부의 출처와 범위」에서는 이 실험대의 게스트를 3대로 적었고, 「철거 — 실제 출력 전문」의 철거 출력에는 domain 이름이 kc-lab-edge · kc-lab-1 · kc-lab-2 로 남아 있다. 원문의 `vm1`, `vm2` 표기는 이 가운데 k3s 노드 두 대를 가리킨다.
- 「측정 환경」에서는 이 호스트의 판 번호를 실측으로 적었다. libvirt 12.7.0 · QEMU emulator version 11.1.1 · 커널 7.2.2-arch1-1 이다. 어느 backend 로 도는지는 그 줄에서 나오지 않는다.
- 기존 구축 기록만으로는 backend를 확정할 수 없었지만, 2026-09-21 재검증에서 모듈 적재와 VM별 QEMU 인자를 함께 읽어 세 VM 모두 vhost-net을 사용하는 것을 확인했다.
@@ -65,7 +65,7 @@ source:
- 백엔드가 무엇인지를 확정하는 데서 끊는다. 두 백엔드의 성능 차이는 그것을 비교하는 물음이 받는다.
- 2026-09-21 이후에는 vhost-net 경로를 이 호스트의 확인된 현재 구성으로 사용할 수 있다. 다만 VM NIC backend 설정을 바꾸면 다시 확인해야 한다.
- 명령을 기존 문서가 하나만 주었으므로, 나머지 둘을 무엇으로 읽었는지 실행한 명령과 출력을 함께 남긴다.
- VM별로 같은 항목을 확인할 수 있도록 실행한 명령과 출력을 함께 남긴다.
## QEMU 실행 인자에서 vhost를 확인했다
@@ -77,7 +77,7 @@ source:
두 가상 머신의 libvirt domain 설정과 QEMU arguments 에서 백엔드 지정을 먼저 읽고, lsmod 출력으로 그 설정이 실제로 성립할 수 있는지 뒷받침한다. 가상 머신마다 다른 답이 나오는 경우까지 한 번에 잡힌다.
설정을 읽는 명령을 기존 문서가 주지 않아서 무엇으로 읽었는지 따로 적어야 한다.
설정값을 확인할 때 사용한 명령과 런타임 출력을 함께 기록한다.
### 3. 「vhost-net 미사용 또는 비효율적 datapath」의 관찰 대상으로 되짚는다 — 제외
@@ -26,7 +26,7 @@ source:
# 부하 중 network 가상화가 지연을 바꿀 만큼 호스트 CPU 를 쓰는가
2026-09-21 외부 `auth.hyeonworks.com` 경로에 OIDC discovery 4000회, concurrency 40 부하를 걸고 host의 vhost thread, QEMU vCPU, `/proc/softirqs`, `/proc/stat`, `vmstat`과 별도 probe latency를 함께 기록했다. 부하 중 vhost CPU와 NET_RX softirq는 실제로 증가했지만 host에는 39~56% idle CPU가 남았다. **현재 부하 수준에서는 network virtualization CPU cost가 관측되지만 host CPU를 포화시켜 지연을 지배했다는 근거는 없다.**
2026-09-21 외부 `auth.hyeonworks.com` 경로에 OIDC discovery 4000회, concurrency 40 부하를 걸고 host의 vhost thread, QEMU vCPU, `/proc/softirqs`, `/proc/stat`, `vmstat`과 별도 probe latency를 함께 기록했다. 부하 중 vhost CPU와 NET_RX softirq는 실제로 증가했지만 host에는 39~56% idle CPU가 남았다. 현재 부하 수준에서는 network virtualization CPU cost가 관측되지만 host CPU를 포화시켜 지연을 지배했다는 근거는 없다.
## 부하 중 vhost와 softirq CPU 결과
@@ -39,7 +39,7 @@ source:
- 「Host CPU Contention으로 network latency 증가」에서는 vhost-net · QEMU thread · softirq 도 호스트 CPU 를 쓰고, 따라서 네트워크 문제처럼 보여도 CPU 스케줄링 문제일 수 있다고 적었다.
- 「vhost-net 최적화」에서는 QEMU 사용자 공간이 패킷마다 I/O 를 처리하면 호스트 커널과 사용자 공간을 오가는 전환 비용이 쌓인다고 밝혔다. 초당 지나는 패킷이 많아질수록 userspace/kernel transition · scheduling · copy · notification 비용이 커질 수 있다.
- 「Interrupt / Notification 최적화」에서는 게스트와 호스트가 큐에 새 패킷이나 버퍼가 있음을 서로 알려야 한다고 적었다. 패킷마다 인터럽트나 알림이 지나치게 많이 발생하면 오버헤드가 커지므로 batching · interrupt moderation · queueing 이 중요하다고 밝혔다.
- 「Keycloak Refresh Token 실험과의 관계」의 핵심은 refresh 경쟁과 네트워크 가상화 문제를 섞지 않는 것이다. 현재 lab에서는 클라이언트부터 PostgreSQL까지의 경로를 검증하고, Redis를 사용하는 별도 구조에서는 Redis 구간을 추가한다.
- Refresh token 경쟁과 네트워크 가상화 비용은 별도로 측정한다. 현재 lab에서는 클라이언트부터 PostgreSQL까지의 경로를 확인하고, Redis를 사용하는 별도 구조에서는 Redis 구간을 추가한다.
- 「Keycloak Refresh Token 실험과의 관계」에서는 Refresh Token 경쟁이나 DB lock 으로 오해할 수 있다고 든 다섯
Node1 요청만 지연
VM2 packet loss
@@ -103,7 +103,7 @@ vhost 스레드와 softirq 가 올라도 지연이 그대로면 이 부하 수
### 4. 제외 — 초당 패킷 수를 따로 올려 vhost를 포화시킨다
그렇게 하면 vhost 처리 한계는 보기 쉽지만 현재 Keycloak 부하 시험의 영향 여부와는 다른 실험이 된다. 먼저 실제 Keycloak 부하 조건을 그대로 두고 측정하고, vhost 자체의 한계를 보려면 별도 네트워크 부하 실험으로 분리한다.
그렇게 하면 vhost 자체의 처리 한계를 측정할 수 있지만 현재 Keycloak 부하 조건과는 다른 실험이 된다. 먼저 실제 Keycloak 부하 조건을 그대로 두고 측정하고, vhost 자체의 한계를 보려면 별도 네트워크 부하 실험으로 분리한다.
## 비용은 보였지만 host CPU 병목으로 보이지 않았다
@@ -28,7 +28,7 @@ source:
# QEMU backend 와 vhost-net 의 차이가 이 호스트에서 실제로 보이는가
현재 세 VM의 packet datapath backend는 vhost-net으로 확인됐다. 2026-09-21 `kc-lab-2`에 libvirt 문서가 설명하는 `<driver name='qemu'/>`를 persistent XML로 넣고 실제 재부팅까지 했지만, **실행 중 QEMU argv는 여전히 `vhost:true`였다.** 따라서 이 세션에서는 QEMU userspace backend 조건 자체를 만들지 못했고, 두 backend 성능 비교는 아직 수행하지 않았다. XML 설정값만으로 runtime backend 전환을 성공했다고 처리하지 않는다.
현재 세 VM의 packet datapath backend는 vhost-net으로 확인됐다. 2026-09-21 `kc-lab-2`에 libvirt 문서가 설명하는 `<driver name='qemu'/>`를 persistent XML로 넣고 실제 재부팅까지 했지만, 실행 중 QEMU argv는 여전히 `vhost:true`였다. 따라서 이 세션에서는 QEMU userspace backend 조건 자체를 만들지 못했고, 두 backend 성능 비교는 아직 수행하지 않았다. XML 설정값만으로 runtime backend 전환을 성공했다고 처리하지 않는다.
## 현재 baseline backend
@@ -63,11 +63,11 @@ source:
커널 : 7.2.2-arch1-1
- 그래서 「Data Copy 최적화」에서 든 조건 여섯 가운데 kernel version 과 QEMU version 은 이제 적을 수 있다. vhost configuration 과 offload, NIC capability 는 이 호스트에서 읽은 값이 없다.
- 「철거 — 실제 출력 전문」와 「재구축할 때 무엇이 남아 있나」에서는 게스트를 지우고 다시 세울 때 무엇이 사라지고 무엇이 남는지 적었다. 게스트 디스크와 시드 ISO 는 사라지고 base.qcow2 와 libvirt 의 default 네트워크 정의는 남으며, 재구축해도 IP 가 같다. 다만 백엔드를 바꿔 다시 세운 기록은 없다.
- 이 호스트에서 두 백엔드를 재 본 값은 기존 문서에 없다.
- 이 호스트에서는 아직 QEMU userspace backend와 vhost-net을 같은 조건으로 비교한 측정값이 없다.
## A/B 비교 조건
- 같은 가상 머신을 다른 백엔드로 다시 구성해 띄울 수 있다고 본다. 그것이 이 실험 환경에서 되는지는 기존 문서에 적혀 있지 않다.
- 같은 가상 머신을 다른 backend로 재구성할 수 있는지부터 확인한 뒤 성능 비교를 진행해야 한다.
- 두 구성에 같은 부하를 걸 수 있다고 전제한다. 부하 도구와 요청 구성이 같아야 여섯 축을 견줄 수 있기 때문이다.
- 부하를 걸기 전 값과 부하 중 값의 차이가 백엔드 차이보다 작다고 전제하지 않는다. 그래서 부하 전 값을 먼저 찍어 둔다.
- 두 구성을 같은 시각에 나란히 돌릴 수 없다고 보고 차례로 잰다. 그 사이에 호스트의 다른 부하가 달라지면 값이 흔들릴 수 있다.
@@ -77,7 +77,7 @@ source:
- 같은 부하를 두 백엔드로 돌렸을 때 여섯 축이 실제로 얼마나 달라지는지.
- 그 차이가 이 실험의 결과를 다르게 읽어야 할 만큼인지, 아니면 측정 흔들림 안인지.
- 이 호스트가 내는 초당 패킷 수가 「vhost-net 최적화」에서 말한 「높아질수록 비용이 커지는」 구간에 들어가는지.
- 여섯 축을 이 환경에서 무엇으로 재는지. 제3부가 도구를 적지 않아 실행하는 쪽이 정한다.
- backend 전환 전후에 CPU, latency, throughput, softirq 등 어떤 지표를 사용할지 먼저 고정하고 같은 도구로 비교한다.
## 다른 환경의 수치는 제외한다
@@ -54,7 +54,7 @@ source:
kc-lab-edge : `52:54:00:aa:bb:10` · 192.168.122.10
kc-lab-1 : `52:54:00:aa:bb:11` · 192.168.122.11
kc-lab-2 : `52:54:00:aa:bb:12` · 192.168.122.12
- 「DHCP 예약 (`ip-dhcp-host`)과 MAC `52:54:00`」에서는 `52:54:00` 이 QEMU/KVM 에 할당된 OUI(제조사 식별 접두사)라고 적고, 예약의 mac 과 VM 을 만들 때 준 mac 이 정확히 같아야 한다고 밝혔다. 다르면 예약이 조용히 무시되고 게스트가 동적 범위에서 아무 주소나 받는다.
- 「DHCP 예약 (`ip-dhcp-host`)과 MAC `52:54:00`」에서는 `52:54:00` 이 QEMU/KVM 에 할당된 OUI(제조사 식별 접두사)라고 적고, 예약의 mac 과 VM 을 만들 때 준 mac 이 정확히 같아야 한다고 밝혔다. 값이 다르면 예약이 적용되지 않고 게스트가 동적 DHCP 범위의 주소를 받을 수 있다.
- 「네트워크 — DHCP 예약의 실제 동작」에서는 예약과 리스를 다른 것으로 갈라 적었다. virsh net-dumpxml 의 예약은 줄 의도이고 virsh net-dhcp-leases 는 실제로 준 기록이라 둘이 다를 수 있다. 실제로 준 기록에는 `52:54:00:aa:bb:11` 이 192.168.122.11/24 을, `52:54:00:aa:bb:12` 가 192.168.122.12/24 을 각각 kc-lab-1 과 kc-lab-2 이름으로 받은 줄이 남아 있다.
- 「이 부의 출처와 범위」와 「libvirt `default` 네트워크와 `virbr0`」에서는 게스트가 libvirt 의 default 네트워크에 붙는다고 적었다. 「libvirt `default` 네트워크와 `virbr0`」에서는 VM 이 한 대라도 뜨면 그 VM 의 vnetN 인터페이스가 virbr0 에 붙으면서 브리지가 UP 으로 바뀐다고 덧붙였다.
- 「네트워크 — DHCP 예약의 실제 동작」에서는 VM 세 대가 돌 때 virbr0 이 UP 이고 전부 철거한 뒤에는 DOWN 이라는 출력을 남겼다. 상태가 갈린 이유를 브리지에 붙은 tap 인터페이스가 하나도 없어서라고 적었다.
@@ -65,7 +65,7 @@ source:
- 호스트에 붙어 virsh 와 ip 계열 명령을 실행할 수 있다고 본다.
- 원문의 명령에는 `vm1`, `vm2`가 쓰였지만 「철거 — 실제 출력 전문」에 남은 실제 domain 이름은 `kc-lab-1`, `kc-lab-2`다. 따라서 실제 확인 명령에는 뒤쪽 이름을 쓴다. 「TAP의 역할」와 「실제 Linux에서 확인할 명령어」에서는 같은 명령의 domain 이름을 비워 두었다.
- virsh domiflist 출력에 인터페이스 이름과 MAC 주소가 함께 나온다고 전제한다. 「TAP의 역할」도 「실제 Linux에서 확인할 명령어」도 이 명령의 출력 형식은 적지 않았다.
- 두 가상 머신이 켜져 있는 동안 읽는다고 전제한다. 꺼진 가상 머신의 TAP 이 호스트에 남아 있는지는 기존 문서에 적혀 있지 않다.
- TAP/vnet 매핑은 가상 머신이 실행 중인 상태에서 확인한다. 종료한 가상 머신의 인터페이스 상태는 이 측정에서 확인하지 않았다.
## runtime interface 이름의 수명
@@ -24,7 +24,7 @@ source:
# 이 호스트의 가상 머신 네트워크는 Bridge 인가 NAT 인가 Routing 인가
2026-09-21 실제 libvirt network 정의를 읽었다. 이 실험대는 게스트를 `virbr0` Linux bridge에 붙이고 `default` network의 `forward mode='nat'`를 사용한다. 따라서 libvirt 분류로는 NAT network이고, 계층을 정확히 쓰면 **guest L2 연결은 bridge, 외부 egress는 NAT**다.
2026-09-21 실제 libvirt network 정의를 읽었다. 이 실험대는 게스트를 `virbr0` Linux bridge에 붙이고 `default` network의 `forward mode='nat'`를 사용한다. 따라서 libvirt 분류로는 NAT network이고, 계층을 정확히 쓰면 guest L2 연결은 bridge, 외부 egress는 NAT다.
## 현재 libvirt network 구조
@@ -58,7 +58,7 @@ source:
macvtap : LAN 에서 직접 IP(호스트↔VM 은 제외), WiFi 라 불가
- 「libvirt `default` 네트워크와 `virbr0`」에서는 libvirt 의 default 네트워크를 소프트웨어 브리지 virbr0 과 거기 붙은 NAT 규칙으로 적었다. 기본 대역은 192.168.122.0/24 이고 호스트가 .1 을 가지며, VM 들은 이 브리지에 연결되어 서로 직접 통신하고 외부로 나갈 때만 호스트 IP 로 마스커레이딩된다. NAT 가 막는 것은 외부에서 VM 으로 들어오는 방향이다.
- 「네트워크 — DHCP 예약의 실제 동작」에서는 이 호스트에서 ip -br addr show virbr0 을 돌린 출력을 남겼다. VM 세 대가 돌 때는 virbr0 이 UP 이고 192.168.122.1/24 을 갖고, 전부 철거한 뒤에는 주소는 그대로인 채 DOWN 이다.
- 「nftables 는 앞 체인의 `accept` 로 뒤 체인의 `reject` 를 막지 못한다」와 「nftables 는 앞 체인의 `accept` 로 뒤 체인의 `reject` 를 막지 못한다」에서는 밖에서 게스트로 들어오는 방향이 FORWARD 경로라 libvirt 의 guest_input 체인을 지난다고 적었다. 그 체인이 oif "virbr0" reject 로 끝나 게스트 대역으로 새로 들어오는 연결을 거절했고, 밖에서 친 curl 은 connection refused 를 받았다. 호스트 안에서 같은 게스트 주소로 친 curl 은 OUTPUT 경로라 forward 를 타지 않아 404 로 응답했다. 그 reject 줄을 범인으로 확정한 것은 카운터다. 밖에서 curl 을 네 번 쳤을 때 그 줄에 packets 4 bytes 240 이 찍혀 있었다.
- 「nftables 는 앞 체인의 `accept` 로 뒤 체인의 `reject` 를 막지 못한다」와 「nftables 는 앞 체인의 `accept` 로 뒤 체인의 `reject` 를 막지 못한다」에서는 밖에서 게스트로 들어오는 방향이 FORWARD 경로라 libvirt 의 guest_input 체인을 지난다고 적었다. 그 체인이 oif "virbr0" reject 로 끝나 게스트 대역으로 새로 들어오는 연결을 거절했고, 밖에서 친 curl 은 connection refused 를 받았다. 호스트 안에서 같은 게스트 주소로 친 curl 은 OUTPUT 경로라 forward 를 타지 않아 404 로 응답했다. 외부에서 `curl`을 네 번 실행했을 때 해당 reject 규칙의 카운터가 `packets 4 bytes 240`으로 증가했다. 이 값으로 외부 요청이 그 규칙에서 거절됐음을 확인했다.
- 2026-09-21 재검증에서 `net-dumpxml`, `bridge link`, `ip route`를 직접 읽어 NAT network와 `virbr0` 내부 L2 연결을 확인했다.
## bridge와 NAT를 같이 읽는 기준
@@ -2,7 +2,7 @@
id: 68a848c7-eaff-4421-ad25-de21673ca40c
kind: REFERENCE
slug: bisect-the-packet-path-with-capture-points
title: packet 이 어디서 끊겼는지는 계층마다 capture 해서 가른다
title: 패킷 경로는 구간별 캡처로 확인한다
topic: network-virtualization
topicName: 네트워크 가상화
project: virtualization
@@ -21,7 +21,7 @@ source:
- final/document.md#99-tap의-역할
---
# packet 이 어디서 끊겼는지는 계층마다 capture 해서 가른다
# 패킷 경로는 구간별 캡처로 확인한다
가상 머신이 밖과 통신하지 못하면 게스트부터 뒤지지 말고 패킷이 지나야 할 지점에 캡처를 걸어 어디까지 보였는지로 구간을 좁힌다. 첫 지점은 물리 NIC일 수도 있고 `tailscale0` 같은 host ingress 인터페이스일 수도 있다. 그 뒤로 브리지, 가상 머신에 붙은 TAP/vnet, 게스트 인터페이스를 따라간다. 보이지 않은 첫 지점의 앞 구간이 의심 구간이 된다.
@@ -113,7 +113,7 @@ KVM(Kernel-based Virtual Machine)/QEMU/libvirt 로 만든 가상 머신이 외
2026-09-21에는 실제 요청을 여러 지점에서 캡처해 이 절차를 다시 확인했다. 따라서 아래 판독은 개념 설명만이 아니라 현재 실험대에서 확보한 패킷 캡처와 함께 읽는다.
「nftables 는 앞 체인의 `accept` 로 뒤 체인의 `reject` 를 막지 못한다」의 사건에서도 구간을 좁힌 것은 네 지점 캡처가 아니었다. 호스트에서 친 curl 은 404 를 받는데 밖에서 친 curl 만 connection refused 를 받았다는 차이가 단서였고, 범인은 그 reject 규칙의 카운터가 4 패킷 240 바이트로 밖에서 친 횟수와 맞아떨어져서 확정했다.
nftables 문제를 확인할 때도 먼저 호스트 내부 요청과 외부 요청의 결과 차이로 구간을 좁혔다. 호스트에서 보낸 요청은 404를 받았지만 외부 요청만 `connection refused`였고, reject 규칙의 카운터가 외부 요청 횟수와 일치해 실제 차단 지점을 확인했다.
## 어디서 끊겼는지 판정하는 예
@@ -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)
@@ -41,7 +41,7 @@ source:
실제 점유량 : du -h
파일 크기 : ls -lh
- 백엔드가 파일이라는 것은 「단계 01 — 게스트 세 대」의 `virt-install` 세 줄과 「디스크 — 오버레이는 얼마나 쓰나」의 `ls -l` 출력이 보여 준다.
- 형식과 바닥 이미지의 크기는 「디스크 — 오버레이는 얼마나 쓰나」에서는 2026-09-10 에 `test-server` 에서 재 두었다. `qemu-img info /var/lib/libvirt/images/base.qcow2` 가 낸 값은 `file format: qcow2`, `virtual size: 3 GiB (3221225472 bytes)`, `disk size: 335 MiB` 다.
- 형식과 base image의 크기는 「디스크 — 오버레이는 얼마나 쓰나」에서는 2026-09-10 에 `test-server` 에서 재 두었다. `qemu-img info /var/lib/libvirt/images/base.qcow2` 가 낸 값은 `file format: qcow2`, `virtual size: 3 GiB (3221225472 bytes)`, `disk size: 335 MiB` 다.
- 같은 절의 `ls -l /var/lib/libvirt/images/` 가 선언한 크기와 파일 크기를 나란히 보인다.
base.qcow2 : 351404032 (335 MiB)
kc-lab-1.qcow2 : 1521025024 (1.4 GiB) — 선언 20GB
@@ -49,7 +49,7 @@ source:
시드 ISO 두 장 : 각 378880 (370 KiB)
- 「디스크 — 오버레이는 얼마나 쓰나」에서는 그 결과를 한 줄로 정리했다. 20GB 씩 둘, 합쳐 40GB 를 선언했지만 실제로는 2.1GB 를 썼다.
- 「디스크 — 오버레이는 얼마나 쓰나」에서는 두 오버레이가 두 배 넘게 갈린 이유도 함께 적었다. k3s server 가 agent 보다 두 배 이상 쓰는 것은 컨트롤 플레인 바이너리와 SQLite 때문이다. 그래서 오버레이 크기는 이미지 형식이 아니라 그 게스트가 무엇을 도는지를 따라간다.
- 「qcow2 파일 내부는 어떻게 생겼나 — 매핑표가 전부다」에서는 같은 바닥 이미지에 `qemu-img map --output=json` 을 돌려 `compressed: True` 인 구간이 606개이고 전체가 1236개라고 적었다. 3 GiB 가운데 2.01 GiB 가 구멍이고 남은 1010 MiB 를 압축해 324 MiB 가 된다. 배포본 qcow2 는 배포 시점에 이미 zlib 로 압축돼 있어서, 바닥 쪽 차이에는 희소 할당과 압축이 겹쳐 있다. 오버레이에 쌓이는 클러스터는 압축되지 않는다.
- 「qcow2 파일 내부는 어떻게 생겼나 — 매핑표가 전부다」에서는 같은 base image에 `qemu-img map --output=json` 을 돌려 `compressed: True` 인 구간이 606개이고 전체가 1236개라고 적었다. 3 GiB 가운데 2.01 GiB가 할당되지 않은 희소 영역이고 남은 1010 MiB 를 압축해 324 MiB 가 된다. 배포본 qcow2 는 배포 시점에 이미 zlib 로 압축돼 있어서, base image의 크기 차이에는 희소 할당과 압축이 함께 영향을 준다. 오버레이에 쌓이는 클러스터는 압축되지 않는다.
## virtual size와 host 사용량은 같은 시점에 재었다
@@ -69,7 +69,7 @@ source:
- 측정 조건에 캐시 모드와 백엔드 형식과 장치 이름을 함께 적는다. 이 셋이 없으면 같은 값을 다른 환경과 견줄 수 없다.
- 측정하는 동안 다른 스토리지 실험을 같은 장치 위에서 겹쳐 돌리지 않는다.
- 호스트 지연이 오른 이유까지 이 물음이 가르지 않는다. 다른 가상 머신의 부하인지 호스트 메모리 압박인지는 그것을 재는 두 물음이 받는다.
- host memory pressure 실험에서도 storage 지표를 보지만 목적이 다르다. 그쪽은 major fault/reclaim이 storage를 밀어 올리는지 보고, 여기서는 guest `fsync()`/DB write 구간이 host storage latency와 연결되는지를 본다.
- host memory pressure 실험에서도 storage 지표를 보지만 목적이 다르다. 그쪽은 major fault/reclaim 구간에서 host storage latency가 함께 증가하는지를 보고, 여기서는 guest `fsync()`/DB write 지연과 host storage latency가 같은 시간 구간에서 함께 변하는지를 본다.
## 어떻게 겹쳐 봤나
@@ -33,8 +33,8 @@ source:
그 요청은 Host Kernel, Host Filesystem, Host Block Layer, NVMe Driver 를 지나 Physical NVMe 로 내려간다. 게스트의 스토리지 스택 아래에 호스트의 스토리지 스택이 한 번 더 존재할 수 있다.
- 「Host Block Layer」에서는 qcow2 와 RAW 의 파일 입출력이 호스트 파일시스템을 거쳐 실제 호스트 블록 입출력이 된다고 적고 경로를 이렇게 그렸다.
QEMU, vm1.qcow2, Host ext4/XFS, Host Block Layer, /dev/nvme0n1
- 「Host Block Layer」에서는 Host Block Layer 가 그 입출력을 가상 머신 안의 PostgreSQL 이 냈는지 호스트 프로세스가 냈는지 본질적으로 구분해서 처리하는 계층이 아니라고 밝혔다. 모두 호스트의 블록 요청이다.
- 「여러 VM이 하나의 NVMe를 공유하면」의 핵심은 여러 QEMU와 host 프로세스의 I/O가 같은 Host Block Layer와 물리 NVMe로 수렴한다는 점이다. 초기 그림에는 Host Nginx가 따로 있었지만 현재 Nginx는 Edge VM 안에 있으므로 그 I/O도 edge QEMU 경로에 포함된다.
- Host Block Layer에 도달한 I/O는 게스트의 PostgreSQL에서 시작했든 호스트 프로세스에서 시작했든 호스트의 블록 요청으로 처리된다.
- 여러 QEMU와 호스트 프로세스의 I/O는 같은 Host Block Layer를 거쳐 물리 NVMe로 전달된다. 초기 그림에는 Host Nginx가 따로 있었지만 현재 Nginx는 Edge VM 안에 있으므로 그 I/O도 edge QEMU 경로에 포함된다.
- 「실제 테스트 서버에서 확인할 확인할 항목」의 5번째 확인 항목에서는 확인 명령으로 lsblk 와 findmnt 를 들었다.
- 「Storage 관측 명령어」의 호스트 관측 명령 목록에도 lsblk 가 들어 있다.
- 「Host Block Layer」의 vm1.qcow2 와 /dev/nvme0n1 은 경로를 설명하려고 든 예시 이름이고 이 호스트에서 읽은 값이 아니다.
@@ -59,7 +59,7 @@ source:
- 확인만 한다. 마운트를 바꾸거나 이미지를 다른 장치로 옮기지 않는다. 배치를 바꾸면 지금 구성에서 무엇을 공유하는지 못 본다.
- 「Host Block Layer」에서는 예로 든 이름을 이 호스트의 값으로 옮겨 적지 않는다. 출력에 나온 이름만 적는다.
- 여기서 나온 장치 이름이 다음 두 물음의 입력이므로, 가상 머신마다 한 행으로 남기고 어느 이미지에서 나온 이름인지 함께 적는다.
- 장치를 나눌지 말지는 이 물음이 정하지 않는다. 공유하고 있다는 사실과 그것이 지연을 실제로 밀어 올리는지는 다른 물음이 받는다.
- 여기서는 세 VM이 같은 NVMe를 공유한다는 사실까지만 확인한다. 이 공유가 지연에 미치는 영향은 별도 부하 실험에서 측정한다.
- VM의 `vda → qcow2` mapping과 `qcow2 → host block device` mapping은 서로 다른 계층이다. 앞쪽은 libvirt/QEMU 설정으로, 뒤쪽은 host mount와 block topology로 확인한다.
## 어떻게 따라 내려갔나
@@ -23,7 +23,7 @@ source:
# 이 호스트의 I/O Scheduler 는 무엇인가
이미지가 올라간 host 장치는 `nvme0n1`이고, 2026-09-21 `/sys/block/nvme0n1/queue/scheduler`의 현재 선택값은 **`none`**이다. 같은 출력에 `mq-deadline`, `kyber`, `bfq`가 선택지로 보였다.
이미지가 올라간 host 장치는 `nvme0n1`이고, 2026-09-21 `/sys/block/nvme0n1/queue/scheduler`의 현재 선택값은 `none`이다. 같은 출력에 `mq-deadline`, `kyber`, `bfq`가 선택지로 보였다.
## 현재 nvme0n1 scheduler
@@ -31,7 +31,7 @@ source:
- 2026-09-21 재검증에서 `kc-lab-1`·`kc-lab-2`·`kc-lab-edge`의 QEMU monitor `info block`을 읽었다. 주 qcow2 디스크 모두 `Cache mode: writeback`과 `Backing file: /var/lib/libvirt/images/base.qcow2 (chain depth: 1)`가 나왔고, domain XML의 `<driver>`에는 `cache=` 속성이 없었다.
「QEMU Cache Mode」에서는 QEMU/libvirt 디스크에서 대표적으로 볼 수 있는 설정으로 cache=none 과 cache=writeback 둘을 들었다. 이름만 보고 none = cache 자체가 없음 · writeback = 무조건 위험으로 해석하면 부정확하다. 핵심은 QEMU 가 Host Page Cache 와 write completion/flush semantics 를 어떤 방식으로 사용할 것인가라고 적었다.
「QEMU Cache Mode」에서는 QEMU/libvirt 디스크에서 대표적으로 볼 수 있는 설정으로 cache=none 과 cache=writeback 둘을 들었다. `cache=none`은 캐시가 전혀 없다는 뜻이 아니고, `writeback`도 그 자체로 영속성 실패를 뜻하지 않는다. 각 모드는 QEMU가 Host Page Cache를 어떻게 사용하고 write completion과 flush를 어떻게 처리하는지에 차이가 있다.
「`cache=none`」에서는 cache=none 을 개념적으로 Host Page Cache 를 우회하는 방향의 I/O 구성으로 놓았다. 이중 caching 은 줄일 수 있지만, Host Page Cache 우회가 무조건 즉시 durable media 반영을 뜻하지는 않는다.
@@ -43,13 +43,13 @@ source:
그 `virt-install` 세 줄은 게스트마다 디스크를 둘씩 붙인다. 하나는 `--disk size=20,backing_store=/var/lib/libvirt/images/base.qcow2` 로 만든 오버레이이고, 다른 하나는 `--disk vol=default/seed-kc-lab-1.iso,device=disk,bus=virtio,readonly=on` 으로 붙인 시드 볼륨이다. 엣지만 `--disk size=10` 이다.
「VM 한 대의 디스크 구성」에서는 그 결과를 게스트 쪽 이름으로 그렸다. `vda` 는 20G 이고 ext4 로 마운트돼 거기서 부팅한다. `vdb` 는 370K 이고 레이블이 CIDATA 인 iso9660 이라 마운트되지 않는다. `vda` 뒤에 `kc-lab-1.qcow2` 가 있고 그 아래 backing 으로 `base.qcow2` 가 있어서, 게스트 두 대가 그 바닥 하나를 공유한다.
「VM 한 대의 디스크 구성」에서는 그 결과를 게스트 쪽 이름으로 그렸다. `vda` 는 20G 이고 ext4 로 마운트돼 거기서 부팅한다. `vdb` 는 370K 이고 레이블이 CIDATA 인 iso9660 이라 마운트되지 않는다. `vda` 뒤에 `kc-lab-1.qcow2` 가 있고 그 아래 backing 으로 `base.qcow2` 가 있어서, 게스트 두 대의 overlay가 같은 `base.qcow2`를 backing image로 사용한다.
「디스크 — 오버레이는 얼마나 쓰나」에서는 2026-09-10 에 `ls -l /var/lib/libvirt/images/` 를 돌린 출력을 남겼고 거기에 `base.qcow2`, `kc-lab-1.qcow2`, `kc-lab-2.qcow2`, 시드 ISO 둘이 파일로 보이므로 이 호스트의 백엔드는 「Host Block Device를 직접 backend로 사용 가능」에서는 가른 셋 가운데 파일 쪽이다.
「그래서 마이그레이션과 스냅샷이 된다」에서는 그 파일들이 게스트에 어떻게 붙는지를 한 줄로 적었다. 이 실험대의 게스트는 `vda`(qcow2 오버레이)와 `vdb`(raw 시드 ISO) 두 디스크다. 그래서 한 게스트 안에서도 Target 둘의 형식이 갈리고, 한 행만 읽고 백엔드를 정하면 나머지 한 행이 빠진다.
시드에 `bus=virtio` 가 붙은 이유는 「확정된 함정: `--cloud-init` + Debian `genericcloud` 조합은 동작하지 않는다」에서는 확정된 함정으로 적어 두었다. `virt-install --cloud-init` 은 시드 ISO 를 SATA CD-ROM 으로 붙이는데 Debian `genericcloud` 변종에는 물리 하드웨어 드라이버가 빠져 있어 게스트가 그 장치를 보지 못하고, 오류 메시지는 어디에도 남지 않은 채 hostname 이 `localhost` 로 남는 것으로만 드러난다. 그래서 「확정된 함정: `--cloud-init` + Debian `genericcloud` 조합은 동작하지 않는다」에서는 이 확인의 성공 판정을 시드 ISO 가 `sda` 가 아니라 `vdb` 로 보이는 것이라고 적었다. Target 이름 자체가 판정 대상이다.
cloud-init 시드는 현재 `bus=virtio` 디스크로 연결돼 있고 게스트에서는 `vdb`로 보인다. 이 구성에서는 `cloud-init status --long`에 `DataSourceNoCloud [seed=/dev/vdb]`가 남아 실제로 시드를 읽은 것을 확인했다. 과거 `--cloud-init` 연결에서는 기대한 NoCloud 데이터소스를 확인하지 못했지만, 그 원인을 Debian genericcloud의 드라이버 구성으로 특정할 근거는 없다. 따라서 여기서는 현재 동작하는 `vdb` 연결만 확인된 사실로 사용한다.
2026-09-21에는 `virsh domblklist --details`와 live XML을 직접 읽어 Target·Source·format·backing chain을 현재 세 VM 기준으로 다시 확인했다.
@@ -2,7 +2,7 @@
id: ed64d4ff-aa01-48cc-ae68-6a683b025cde
kind: QUESTION
slug: vm1-storage-load-vs-vm2-latency
title: VM1 의 storage 부하가 VM2 의 지연을 실제로 밀어 올리는가
title: VM1의 스토리지 부하가 VM2의 지연에 영향을 주는가
topic: storage-virtualization
topicName: 스토리지 가상화
project: virtualization
@@ -22,11 +22,11 @@ source:
- final/document.md#168-cpu가-정상이어도-storage-때문에-느릴-수-있다
---
# VM1 의 storage 부하가 VM2 의 지연을 실제로 밀어 올리는가
# VM1의 스토리지 부하가 VM2의 지연에 영향을 주는가
2026-09-21 VM1(`kc-lab-1`)에서 64 MiB 임시 파일을 반복 overwrite한 뒤 `fdatasync`하는 controlled I/O load를 약 10초간 걸고, 같은 NVMe를 공유하는 VM2(`kc-lab-2`)에서 128회 `fsync()` microbenchmark를 실행했다. VM2 단독 평균은 약 8~9 ms였지만 VM1 load와 겹친 첫 run은 평균 58.46 ms, p95 314 ms, max 631 ms까지 상승했다. VM1 load가 끝난 뒤 다음 두 run은 다시 약 8 ms로 회복했다. **현재 환경에서 한 VM의 storage 부하가 다른 VM의 durability latency를 실제로 밀어 올릴 수 있음을 확인했다.**
2026-09-21 VM1(`kc-lab-1`)에서 64 MiB 임시 파일을 반복 overwrite한 뒤 `fdatasync`하는 controlled I/O load를 약 10초간 걸고, 같은 NVMe를 공유하는 VM2(`kc-lab-2`)에서 128회 `fsync()` microbenchmark를 실행했다. VM2 단독 평균은 약 8~9 ms였지만 VM1 load와 겹친 첫 run은 평균 58.46 ms, p95 314 ms, max 631 ms까지 상승했다. VM1 load가 끝난 뒤 다음 두 run은 다시 약 8 ms로 회복했다. 현재 환경에서는 VM1의 스토리지 부하와 겹친 구간에서 VM2의 `fsync()` 지연이 크게 증가했다.
## VM1 load가 VM2 fsync를 밀어 올린 결과
## VM1 부하 구간에서 VM2 fsync 지연이 증가했다
- 2026-09-21 재검증에서 VM2 isolated fsync 평균은 반복 3회에서 `8.2397 / 8.2676 / 9.1264 ms`였다.
- 2026-09-21 재검증에서 VM1 load는 64 MiB 파일을 10초 동안 20회 overwrite+fdatasync했다. 같은 시간 VM2 first run은 평균 `58.4576 ms`, p95 `314.0799 ms`, max `631.0144 ms`였다.
@@ -45,7 +45,7 @@ Storage Contention : IOPS / bandwidth / queue / device 처리시간 경쟁
「Storage 관측 명령어」에서는 device I/O 관측으로 iostat -xz 1 을, 어떤 프로세스가 I/O 를 발생시키는지 볼 때는 iotop 을 들었다. iostat 에서 볼 대상으로 read/write throughput, IOPS, request latency, queue 상태, device utilization 성격의 지표를 적었다.
실험의 핵심은 VM1의 별도 테스트 파일이나 디스크에 controlled I/O load를 만들고, 같은 시간에 VM2 latency와 host `iostat`을 보는 것이다. 부하 도구·크기·지속 시간은 재현 조건으로 명시해야 한다.
VM1에 controlled I/O load를 만들고 같은 시간에 VM2 latency와 host `iostat`을 기록했다. 부하 도구·크기·지속 시간은 재현 조건으로 명시해야 한다.
2026-09-21 `findmnt`와 `lsblk`로 `/var/lib/libvirt/images/`가 `/dev/nvme0n1p3`의 ext4 루트 파일시스템에 있고, 상위 물리 장치가 `nvme0n1`임을 확인했다. 세 VM의 주 디스크가 같은 장치를 공유한다는 전제는 더 이상 가정이 아니다.
@@ -67,7 +67,7 @@ host와 guest clock은 실제로 약 90초 어긋나 있었다. 따라서 절대
## load 종료 뒤 회복한 값
이번 controlled load에서 VM1 storage pressure가 VM2 fsync latency를 크게 밀어 올리고, host storage latency/util도 같은 overlap 구간에서 상승하며, load 종료 직후 VM2 지연이 baseline 수준으로 회복하는 것까지 확인됐다.
이번 controlled load에서는 VM1 부하 구간에 VM2 fsync latency와 host storage latency/util이 함께 증가했고, 부하가 끝난 뒤 VM2 지연이 baseline 수준으로 돌아왔다.
어느 IOPS/throughput 임계점부터 간섭이 시작되는지와 실제 Keycloak/PostgreSQL request latency가 얼마나 영향을 받는지는 별도 단계 부하 실험으로 남긴다.
@@ -2,7 +2,7 @@
id: decbab8d-9c98-45c6-b5b8-e6162e407299
kind: REFERENCE
slug: a-speedup-that-removed-durability-is-not-an-optimization
title: 빨라진 구성이 durability contract 를 지운 것은 아닌지 먼저 가른다
title: 성능 개선 전후로 데이터 영속성 보장이 달라졌는지 확인한다
topic: storage-virtualization
topicName: 스토리지 가상화
project: virtualization
@@ -20,9 +20,9 @@ source:
- final/document.md#174-핵심-claim
---
# 빨라진 구성이 durability contract 를 지운 것은 아닌지 먼저 가른다
# 성능 개선 전후로 데이터 영속성 보장이 달라졌는지 확인한다
durability 는 전원이 나가도 데이터가 남아 있는 영속성을 말한다. 쓰기 지연이 줄면 그 변경은 성능 개선으로 기록되지만, 무엇을 더 이상 보장하지 않게 됐는지는 아무 데도 적히지 않는다. 개념 문서는 fsync() 를 없애서 빨라졌다면 그것이 최적화가 아니라 durability contract 를 제거한 것일 수 있다고 적었다. 게스트가 요청한 FLUSH 에 완료로 응답했는데 데이터는 호스트 RAM 에만 있는 상태도 성능 문제가 아니라 correctness 문제로 놓았다. 이 기준은 빨라진 구성을 평가할 때 어느 단계가 빠졌는지를 먼저 적게 한다.
데이터 영속성은 쓰기 지연과 별도로 확인한다. 예를 들어 `fsync()`를 제거해 응답 시간이 줄었다면 성능은 좋아질 수 있지만 전원 장애 후 데이터 보장은 달라진다. 가상 머신에서는 게스트의 flush 요청이 QEMU와 호스트 스토리지 계층을 거쳐 실제 저장장치까지 전달되는지도 함께 확인해야 한다.
## 빠름과 durability를 분리하는 이유
@@ -67,7 +67,7 @@ PostgreSQL 은 WAL 등의 durability protocol 을 사용하며 필요한 시점
## 빨라도 제외해야 하는 구성
- 영속성을 실제로 포기해도 되는 데이터가 있다. 다시 만들 수 있는 캐시나 파생 파일이 그렇고, 그때는 빨라진 것이 정당한 선택이다. 이 기준이 요구하는 것은 포기를 막는 것이 아니라 무엇을 포기했는지 적게 하는 것이다.
- cache=none 이나 Direct I/O 를 골랐다고 영속성이 확보되지도 않는다. 개념 문서는 Direct I/O 의 핵심이 페이지 캐시 우회이며 호스트 페이지 캐시를 우회하는 것이 즉시 durable media 반영을 뜻하지 않는다고 적었고, 그 뒤에 스토리지 컨트롤러나 장치가 휘발성 쓰기 캐시를 가질 수 있다고 덧붙였다.
- `cache=none`이나 Direct I/O를 사용해도 영속성이 자동으로 보장되지는 않는다. Direct I/O는 페이지 캐시를 우회하지만, 그 사실만으로 데이터가 즉시 비휘발성 저장장치에 기록됐다고 볼 수는 없다. 스토리지 컨트롤러나 장치에도 휘발성 쓰기 캐시가 있을 수 있다.
- 개념 문서는 실제 순서 보장과 영속성의 의미가 더 복잡하다고 밝혔다. 그래서 이 기준으로 특정 설정이 안전하다는 결론을 내지 않는다. 실제 운영에서는 장치의 flush 와 FUA semantics, power-loss protection 여부도 함께 본다.
- 이 저장소에는 영속성을 실제로 재 본 실험이 없다. 여기 적은 것은 개념 문서가 서술한 구분이고 이 호스트에서 확인된 동작이 아니다.
@@ -2,7 +2,7 @@
id: 274c5636-33f6-4c19-a54b-d2a96af31289
kind: REFERENCE
slug: confirm-the-disk-backend-on-the-host
title: Guest 안에서 본 disk 로 backend 를 단정하지 않는다
title: 디스크 백엔드는 호스트에서 확인한다
topic: storage-virtualization
topicName: 스토리지 가상화
project: virtualization
@@ -19,9 +19,9 @@ source:
- final/document.md#169-storage-관측-명령어
---
# Guest 안에서 본 disk 로 backend 를 단정하지 않는다
# 디스크 백엔드는 호스트에서 확인한다
백엔드는 게스트가 디스크로 쓰는 그 장치를 호스트 쪽에서 실제로 대 주는 것을 말한다. 게스트에 로그인해 lsblk 를 돌리면 /dev/vda 와 그 파티션이 나오고, 거기까지는 물리 머신과 같은 화면이다. 개념 문서는 그 이름이 호스트의 실제 SSD 를 뜻하지 않으며 아래에 qcow2 파일과 RAW 파일과 호스트 블록 장치 셋이 올 수 있다고 적었다. 이 기준은 용량과 성능과 영속성을 판단하기 전에 호스트 쪽에서 무엇에 붙어 있는지를 먼저 확정하게 한다.
게스트의 `lsblk`에서 `/dev/vda`가 보이더라도 그것이 호스트의 물리 SSD를 직접 뜻하지는 않는다. QEMU 백엔드는 qcow2 파일, RAW 파일, 호스트 블록 장치가 될 수 있으므로 libvirt XML과 `qemu-img info`, 호스트 파일시스템을 함께 확인해 실제 연결을 찾는다.
## Guest의 vda만으로 부족한 이유
@@ -55,7 +55,7 @@ qcow2 는 가상 디스크 크기와 실제 호스트 할당량이 다를 수
백엔드가 qcow2 파일이면 QEMU 는 결국 호스트 리눅스에 파일 입출력을 요청한다. 그 요청은 Host Filesystem 과 Host Block Layer 와 NVMe Driver 를 지나 Physical NVMe 로 내려간다. 게스트의 스토리지 스택 아래에 호스트의 스토리지 스택이 한 번 더 있으므로, 어느 파일시스템과 어느 블록 장치 위에 있는지를 lsblk 로 함께 적는다.
적을 파일이 하나가 아닐 수 있다. qemu-img info 출력에 backing file 줄이 있으면 그 파일은 오버레이이고, 자기가 들고 있지 않은 클러스터를 읽을 때마다 바닥 파일을 읽는다. 바닥까지 같은 항목으로 적어야 그 게스트가 실제로 읽는 파일이 모두 덮인다.
확인해야 할 파일이 하나가 아닐 수 있다. `qemu-img info` 출력에 backing file이 있으면 해당 이미지는 오버레이이며, 오버레이에 없는 블록은 backing file에서 읽는다. 따라서 오버레이와 backing file을 함께 확인해야 게스트가 실제로 사용하는 이미지 체인을 알 수 있다.
## backend를 먼저 확인해야 하는 작업
@@ -68,7 +68,7 @@ qcow2 는 가상 디스크 크기와 실제 호스트 할당량이 다를 수
- 백엔드가 호스트 블록 장치면 qcow2 쪽 확인은 걸리지 않는다. 가상 크기와 실제 할당량의 차이도, 매핑과 메타데이터 처리도 그 구성에는 없다.
- 백엔드를 확정해도 성능은 예측되지 않는다. 개념 문서는 RAW 는 무조건 빠르고 qcow2 는 무조건 느리다는 식으로 일반화하지 말라고 못박고, 실제 성능은 캐시 모드, 스토리지 백엔드, 부하 패턴, 큐 깊이, 스냅숏 체인, 그 아래 파일시스템, 물리 장치에 영향을 받는다고 적었다. 이 기준은 무엇 위에서 재고 있는지까지만 확정한다.
- 2026-09-21에는 이 절차의 host-side 핵심 연결을 실제로 확인했다. VM별 `vda → qcow2 overlay`, overlay → `base.qcow2`, image directory → `/dev/nvme0n1p3` ext4 → `nvme0n1` 순서가 이어진다. `qemu-img info --force-share`, `du`, `ls`도 base와 세 overlay 모두에 실행해 virtual size와 실제 host allocation 차이를 확인했다.
- 2026-09-21에는 이 절차의 host-side 연결을 실제로 확인했다. VM별 `vda → qcow2 overlay`, overlay → `base.qcow2`, image directory → `/dev/nvme0n1p3` ext4 → `nvme0n1` 순서가 이어진다. `qemu-img info --force-share`, `du`, `ls`도 base와 세 overlay 모두에 실행해 virtual size와 실제 host allocation 차이를 확인했다.
- 이 확인으로 backend 구조는 확정되지만 성능까지 예측되지는 않는다. cache mode·scheduler·workload·queue depth·다른 VM의 load는 별도 조건으로 봐야 한다.
## 현재 host에서 확인한 mapping
@@ -2,7 +2,7 @@
id: b1cda8c4-d31d-4ae4-a4d9-4103a0ab3109
kind: REFERENCE
slug: read-storage-before-blaming-cpu-for-latency
title: 지연 원인을 CPU 로 읽기 전에 storage 계층을 따로 잰다
title: 지연 분석에서는 CPU와 스토리지를 함께 측정한다
topic: storage-virtualization
topicName: 스토리지 가상화
project: virtualization
@@ -17,9 +17,9 @@ source:
- final/document.md#177-최종-요약
---
# 지연 원인을 CPU 로 읽기 전에 storage 계층을 따로 잰다
# 지연 분석에서는 CPU와 스토리지를 함께 측정한다
요청이 느린데 CPU 사용률이 낮으면 CPU 는 원인이 아니라고 읽고 다음 후보로 넘어가기 쉬운데, 그 사이에 스토리지 대기는 어느 지표에도 나타나지 않는다. 개념 문서는 애플리케이션이 스토리지 완료를 기다리는 동안 CPU 사용률이 높지 않을 수 있다고 적고 CPU 30% 인데 요청 지연 2초인 조합을 들었다. 이 기준은 자원을 CPU 와 스토리지로 가르는 순서와, 그때 같은 시간축에 무엇을 남길지를 고정한다.
CPU 사용률이 낮아도 애플리케이션은 스토리지 I/O 완료를 기다리고 있을 수 있다. 지연 원인을 확인할 때는 CPU 사용률만 보지 않고 게스트의 `fsync()` 지연과 호스트 `iostat`의 await·util 같은 스토리지 지표를 같은 시간 구간에 기록한다.
## CPU가 낮다고 storage가 정상인 것은 아니다
@@ -76,7 +76,7 @@ Host : virsh domblklist <VM_NAME> · qemu-img info 에 disk image 경로 · lsbl
- 이 기준은 어느 자원인지를 좁힐 뿐 원인을 확정하지 않는다. 스토리지 지표가 깨끗하게 나와도 CPU 쪽을 배제하려면 vCPU 경쟁과 steal time 을 따로 본다. 그것은 CPU 가상화 쪽 기준이 받는다.
- iostat -xz 1 이 보여 주는 device utilization 성격의 지표는 NVMe 처럼 병렬성이 큰 장치에서 포화도로 그대로 읽히지 않는다. 개념 문서가 NVMe 는 높은 병렬성과 큐 깊이를 지원한다고 적었다. 이 저장소의 실측 기록은 이 호스트의 루트를 /dev/nvme0n1p3 로 적었고 게스트 이미지가 전부 그 아래에 모여 있다고 적었으므로, 이 예외는 이 환경에 그대로 걸린다.
- 호스트에서 잰 값은 어느 가상 머신의 입출력인지 갈라 주지 않는다. 개념 문서는 Host Block Layer 가 그 입출력을 가상 머신 안의 프로세스가 시작했는지 호스트 프로세스가 시작했는지 본질적으로 구분해서 처리하는 계층이 아니라고 밝혔다. 가상 머신별로 가르려면 iotop 이나 게스트 쪽 관측을 같은 시각에 함께 찍는다.
- 호스트 블록 지표만으로는 어느 가상 머신에서 시작한 I/O인지 구분하기 어렵다. Host Block Layer에 도달한 요청은 게스트 프로세스에서 시작했든 호스트 프로세스에서 시작했든 호스트의 블록 I/O로 처리된다. 가상 머신별 영향을 구분하려면 `iotop`이나 게스트 지표를 같은 시간에 함께 기록한다.
- static storage path와 runtime cache/scheduler는 실제 host에서 확인됐다. 2026-09-21에는 cross-VM storage contention도 baseline·load·recovery 구간으로 나눠 측정했다. VM1에서 쓰기 부하를 겹친 동안 VM2의 fsync 지연과 host NVMe의 `w_await`·`%util`·iowait가 함께 상승했고, 부하가 끝난 뒤 VM2 지연도 baseline 수준으로 돌아왔다. 따라서 이 환경에서는 같은 NVMe를 공유하는 다른 VM의 storage load가 guest latency와 함께 악화되는 경로를 실제로 확인했다.
## 현재 host에서 확인한 조건
@@ -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",