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: 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 -->