fix(setup): 실험대를 새로 세워 setup 35편을 밟고 어긋난 명령과 결과를 고친다

기반 가이드 7단계로 실험대를 철거하고 다시 세운 뒤 virtualization setup 9편과 keycloak-session-store 26편을 순서대로 밟았다. 24편은 끝까지, 11편은 되는 데까지 밟았고 밟은 범위를 편마다 적었다. 명령이 못 도는 것을 고쳤다. - kubectl 을 `kc-lab-1` 에서 치라고 적었는데 그 기계에 kubeconfig 가 없다. 라벨 639개와 각 편의 「어디서 치는가」를 `[lab host]` 로 옮겼다 - `-o custom-columns=…[0]…` 이 zsh 에서 글로브로 읽혀 안 돈다. 28곳에 따옴표 - busybox `sed` 가 끝 개행을 안 붙여 A-3 의 측정이 언제나 0 이었다 - `--token-file ~/node-token` 뒤에 그 파일을 지우면 k3s agent 가 재부팅을 못 견딘다. `/etc/rancher/node-token` 으로 옮기는 처방을 재서 넣었다 - 게스트에 없는 도구를 전제로 한 명령 넷 — `conntrack`·`dig`·`strings`·`nginx -v` - `echo` 와 JWT 헤더가 `"이름" : [ 값 ]` 으로 찍는데 문서는 공백 없이 옮겨 적어 그 실측으로 만든 grep·sed 가 한 줄도 못 잡는다 - B-0 이 `directAccessGrantsEnabled` 와 계정 완성을 빠뜨려 B-3 이 못 돈다 - D-4·D-4a 가 `test-server` 와 `certbot-renew.*` 를 가리키는데 실제로는 `kc-lab-edge` 의 `certbot.service` 다 - `virsh setmaxmem --config` 를 `dominfo` 로 판정하면 틀린다. `--inactive` 로 - `LIBVIRT_DEFAULT_URI` 를 rc 에만 넣으면 `ssh host '명령'` 에서 안 먹는다 결과가 조건부인 것을 갈랐다. - readiness 는 즉시 안 뒤집힌다. A-1·A-2 의 60초 창을 적었다 - 03 의 층 ②③ `301` 은 04 이후의 값이고 그 단계에서는 `404` 다 - A-0 의 로그 필터를 요청 직후에 치면 정반대 결론이 나온다 - A-5 의 한 방향 차단은 잠깐 `1` 이었다 `2` 로 돌아온다 증거는 두 프로젝트의 `evidence/raw/` 에 99벌을 README 와 함께 남겼다. 비밀은 길이만 적었고 화면에 찍힌 토큰은 가렸다. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-09-17 15:59:42 +09:00
parent ab59130196
commit 024362d096
197 changed files with 8336 additions and 960 deletions
@@ -22,7 +22,7 @@

 | 무엇 | 지금 |
 |---|---|
-| 증거 | `evidence/raw` 1 · `evidence/meta` 1 — 두 폴더에 있는 것은 폴더를 설명하는 `README.txt` 한 장씩이고 캡처한 원문은 0건이다 (`rendered`·`browser` 도 같다) |
+| 증거 | **2026-09-17 기준** `evidence/raw` 43 · `evidence/meta` 1. 2026-09-16 까지는 두 폴더에 `README.txt` 한 장씩뿐이고 캡처한 원문이 0건이었다. 2026-09-17 에 실험대를 철거하고 다시 세우며 `raw/lab-state-before-rebuild/` 에 42건을 남겼다 (`rendered`·`browser` 는 여전히 0건이다) |

 제5~9부의 코드 블록에 있는 명령 출력은 전부 **사람이 문서에 옮겨 적은 것**이다. 실행한 명령·cwd·실행 시각·종료 코드를 짝지어 남긴 `evidence/meta/` 항목이 하나도 없으므로, 그 값들이 언제 어느 상태에서 나왔는지는 **문서가 스스로 밝힌 날짜**(제7부 2026-09-10, §218 2026-09-03)까지만 확인된다. 반입한 `source/` 에도 캡처 원문은 없었다 — 원본 문서들도 출력을 본문에 옮겨 적는 방식이었다.

@@ -8277,6 +8277,34 @@ echo 'export LIBVIRT_DEFAULT_URI=qemu:///system' >> ~/.bashrc
 virsh uri
 ```

+**★ rc 파일에만 넣으면 `ssh lab-host '명령'` 에서는 안 먹는다**(2026-09-17, observed).
+그 형태는 비대화형 셸이라 `.bashrc`·`.zshrc` 를 안 읽는다.
+
+```
+ssh 로 한 줄     LIBVIRT_DEFAULT_URI=[(비어 있음)]
+대화형 셸        LIBVIRT_DEFAULT_URI=qemu:///system
+```
+
+셸과 무관하게 고정하려면 libvirt 자기 설정에 넣는다. 이 실험대에는 그 파일도
+있었다(observed).
+
+```bash
+mkdir -p ~/.config/libvirt
+echo 'uri_default = "qemu:///system"' >> ~/.config/libvirt/libvirt.conf
+virsh uri
+```
+
+```
+/home/donghyeon/.config/libvirt/libvirt.conf:uri_default = "qemu:///system"
+qemu:///system
+```
+
+**둘 중 하나만 있으면 어디선가 어긋난다.** rc 만 있으면 `ssh` 한 줄에서
+`qemu:///session` 을 보게 되고 — 그쪽에는 VM 이 없으므로 목록이 빈 채로 나와
+「VM 이 죽었다」로 읽힌다 — libvirt 설정만 있으면 대화형 셸의
+`echo $LIBVIRT_DEFAULT_URI` 가 비어서 「설정이 안 됐다」로 읽힌다.
+
+
 **따라 하는 사람은** 편집기로 연다. `echo >>` 는 가이드를 두 번 따라 하면 같은
 줄을 한 번 더 붙이고, 파일에 이미 무엇이 들어 있는지도 보여 주지 않는다.

@@ -9297,8 +9325,40 @@ rm ~/node-token

 토큰이 `/tmp/token` 대신 자기 홈에 놓이고, `sudo tee` 대신 `scp` 와 `chmod 600`
 이 그 파일을 만든다. 설치 스크립트는 `sudo` 아래 root 로 도니 홈의 `600` 파일도
-읽는다. 설치가 끝나면 지우는 것은 양쪽이 같다. 이 여덟 줄 형태는 이 실험대에서
-치지 않았다(unknown).
+읽는다.
+
+**★ 그런데 마지막 줄의 `rm ~/node-token` 만 치면 이 노드는 다시 못 뜬다.** 설치
+스크립트가 `--token-file` 에 준 경로를 유닛의 `ExecStart` 에 **그대로 굽기**
+때문에, 파일이 사라지면 agent 가 영원히 그 파일을 기다린다. 2026-09-17 에 A-4 를
+돌려 노드 전원을 뽑았다 다시 켜면서 그대로 겪었다(observed) — VM 은 떴는데 노드가
+`NotReady` 에서 안 돌아왔다.
+
+```
+k3s[522]: level=info msg="Waiting for file \"/home/donghyeon/node-token\" to be created"
+k3s-agent.service: Scheduled restart job, restart counter is at 1.
+```
+
+**지우기 전에 토큰을 root 만 읽는 자리로 옮기고 유닛을 그쪽으로 돌린다.** 그렇게
+하고 홈의 사본을 지우자 agent 를 완전히 세웠다 다시 켜도 `active` 였고 노드도
+`Ready` 로 돌아왔다(observed).
+
+```bash
+sudo install -m 600 -o root -g root ~/node-token /etc/rancher/node-token
+sudo ls -l /etc/rancher/node-token
+sudo sed -i "s|$HOME/node-token|/etc/rancher/node-token|" /etc/systemd/system/k3s-agent.service
+sudo systemctl daemon-reload
+sudo systemctl restart k3s-agent
+rm ~/node-token
+```
+
+```
+-rw------- 1 root root 109 /etc/rancher/node-token
+	'--token-file' \
+	'/etc/rancher/node-token' \
+```
+
+이 여덟 줄 형태는 2026-09-17 에 쳤다 — 설치 자체는 이 판으로 다시 돌리지 않았고,
+유닛을 고쳐 다시 시작하는 쪽만 확인했다(observed).

 **확인** — agent 가 클러스터에 들어왔는가, 그리고 **제 주소로** 들어왔는가

@@ -9627,7 +9687,7 @@ kubectl get nodes
 **확인 ① nginx 가 깔려 있는가** — `[kc-lab-edge]`

 ```bash
-which nginx
+ls /etc/nginx/
 ```

 **관측** — 2026-09-11, 새로 만든 `kc-lab-edge` 에서 실제로 나온 것(observed)
@@ -9637,10 +9697,25 @@ donghyeon@kc-lab-edge:~$ cd /etc/nginx/
 -bash: cd: /etc/nginx/: No such file or directory
 ```

-**어디를 봐야 하는가** — `which nginx` 가 **아무것도 안 찍으면** 미설치다.
+**어디를 봐야 하는가** — `No such file or directory` 가 나오면 미설치다.
 `/etc/nginx` 디렉터리는 패키지가 만든다. 그것이 없다는 것은 **경로를 잘못 찾은
 것이 아니라 설치가 안 된 것**이다.

+**★ 여기에 `which nginx` 를 쓰지 않는다.** 처음에는 그렇게 적어 두었는데 **깔려
+있을 때도 똑같이 아무것도 안 찍힌다.** 2026-09-17 에 nginx 가 돌고 있는
+`kc-lab-edge` 에서 직접 쳐서 확인했다(observed).
+
+```
+which nginx   -> (아무것도 안 찍고 exit 1)
+PATH          -> /usr/local/bin:/usr/bin:/bin:/usr/games
+sudo nginx -v -> nginx version: nginx/1.22.1
+```
+
+실행 파일은 `/usr/sbin/nginx` 인데 데비안의 일반 사용자 `PATH` 에 `/usr/sbin` 이
+없다. 그래서 `which nginx` 의 빈손은 **「안 깔렸다」가 아니라 「이 PATH 에서는 안
+보인다」**이고, 깔린 경우와 안 깔린 경우가 같은 출력이라 **판정에 쓸 수 없다.**
+판 번호를 볼 때도 `nginx -v` 가 아니라 `sudo nginx -v` 로 친다.
+
 **실행 절차**

 번호는 가이드 03 의 것을 그대로 쓴다.
@@ -9783,7 +9858,8 @@ ls -l /etc/nginx/sites-enabled/
 sudo nginx -t && sudo systemctl reload nginx
 ```

-통과하면 이런 형태다. Debian 12 는 `[warn]` 한 줄을 늘 같이 내놓는다(observed).
+통과하면 이런 형태다. 2026-09-11 의 엣지에서는 `[warn]` 한 줄이 앞에 붙어 세
+줄이었다(observed).

 ```
 nginx: [warn] could not build optimal types_hash, you should increase either
@@ -9792,6 +9868,20 @@ nginx: configuration file /etc/nginx/nginx.conf syntax is ok
 nginx: configuration file /etc/nginx/nginx.conf test is successful
 ```

+**★ 그 `[warn]` 은 늘 나오지는 않는다.** 처음에는 「Debian 12 는 늘 같이
+내놓는다」고 적었는데, 2026-09-17 에 같은 Debian 12 · 같은 `nginx/1.22.1` 엣지를
+새로 세우고 `sudo nginx -t` 를 세 번 쳤더니 **한 번도 안 나왔다**(observed). 두
+줄뿐이었다.
+
+```
+nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
+nginx: configuration file /etc/nginx/nginx.conf test is successful
+```
+
+그러니 이 줄이 안 보인다고 설정이 덜 읽힌 것이 아니다. **판정은 `syntax is ok`
+와 `test is successful` 두 마디로만 하고**, `[warn]` 줄은 나오면 무시하고 안
+나오면 없는 대로 둔다.
+
 **어디를 봐야 하는가** — `nginx -t` 가 내놓는 **마지막 줄**이다. `syntax is ok`
 와 `test is successful` 두 마디가 다 나와야 통과다. 앞에 나오는 `[warn]` 줄(예:
 `types_hash_max_size`)은 통과를 막지 않는다 — **04 에서 이 경고를 실패로
@@ -10035,9 +10125,32 @@ curl -s -o /dev/null -w '%{http_code}\n' http://192.168.122.12
 curl -s -o /dev/null -w '%{http_code} %{redirect_url}\n' http://192.168.122.10
 ```

-**어디를 봐야 하는가** — `301` 과 `Location` 이 나오는가. 여기서 막히면 문제는
-**엣지 안**이다(설정·기동). 통과하는데 아래 ③ 이 안 되면 문제는 **DNAT** 이다.
-이 한 층을 끼워 두면 그 둘을 헷갈리지 않는다.
+**어디를 봐야 하는가** — **엣지가 답을 하는가.** 여기서 막히면 문제는 **엣지
+안**이다(설정·기동). 통과하는데 아래 ③ 이 안 되면 문제는 **DNAT** 이다. 이 한
+층을 끼워 두면 그 둘을 헷갈리지 않는다.
+
+**★ 이 단계에서 나오는 코드는 `301` 이 아니라 `404` 다.** 처음에는 `301` 이라고
+적었는데, 2026-09-17 에 이 절을 그대로 따라 엣지를 다시 세우고 재 보니 이렇게
+나왔다(observed).
+
+```
+HTTP/1.1 404 Not Found
+Server: nginx/1.22.1
+Content-Type: text/plain; charset=utf-8
+Content-Length: 19
+```
+
+```
+404 page not found
+```
+
+`Server:` 가 `nginx/1.22.1` 이고 본문이 Traefik 의 `404 page not found` 라는 것이
+**엣지가 받아서 Traefik 으로 넘겼다**는 증거다. 이 단계의 설정에는 리다이렉트를 낼
+블록이 없다 — 위 「② 에 쓸 내용」은 `listen 80` 블록 하나뿐이고 그 안은
+`proxy_pass` 다. `301` 은 **04 가 443 블록과 80→443 리다이렉트를 얹은 뒤**의
+값이고, 처음 적은 `301` 은 다 끝난 실험대에서 잰 것을 이 자리로 옮겨 적은
+것이었다. 그래서 이 층의 통과 기준은 코드값이 아니라 **「`curl: (7)` 없이 응답이
+온다」와 `Server: nginx`** 두 가지다.

 **확인 ③ 밖에서, 즉 DNAT 을 거쳐 닿나**

@@ -10073,6 +10186,21 @@ curl -s -o /dev/null -w '%{http_code} %{redirect_url}\n' http://auth.hyeonworks.
 301 https://auth.hyeonworks.com/
 ```

+**★ 이 `301` 도 04 이후의 값이다.** 03 까지만 한 상태라면 ② 와 같은 `404` 가
+정상이고, 이 층이 묻는 것은 코드값이 아니라 **「밖에서 친 것이 엣지까지
+닿았는가」**다 — ② 와 같은 응답이 밖에서도 오면 DNAT 과 구멍이 살아 있다는 뜻이다.
+
+2026-09-17 에 밖에서 재 보니 **닿지 않았다**(observed).
+
+```
+curl: (7) Failed to connect to auth.hyeonworks.com port 80 after 54 ms
+```
+
+같은 시각에 호스트 안에서 친 `http://192.168.122.10` 은 `404` 로 답했다. 아래
+「막히면」 표의 마지막 줄이 가리키는 상태 그대로이고, 원인도 거기 적힌 대로였다 —
+**이 호스트에 실제로 깔려 있는 유닛에 `ExecStartPost` 줄이 없다.** 아래 「배포된
+것과 적어 둔 것이 다르다」를 본다.
+
 **확인 ④ 끝까지 닿나** (TLS 이후)

 ```bash
@@ -10153,10 +10281,10 @@ error 로그에 있었는데 잘려 있었고, access 로그에는 **3492자**
 | ① 이 `502` | Traefik 은 떴는데 백엔드가 없음 | Ingress 확인 |
 | ② 가 응답 없음 | nginx 가 안 떴거나 방화벽 | `systemctl status nginx` |
 | ③ 이 `502` | 인증서 문제 또는 upstream 다운 | 04 · 위 로그 |
-| `/etc/nginx: No such file or directory` | **nginx 미설치.** cloud-init 은 안 깐다 | `which nginx` |
+| `/etc/nginx: No such file or directory` | **nginx 미설치.** cloud-init 은 안 깐다 | `ls /etc/nginx/` — `which nginx` 는 깔려 있어도 빈손이라 못 가른다 |
 | `nginx -t` 가 `duplicate default server` | `sites-enabled/default` 가 살아 있다 | `ls -l /etc/nginx/sites-enabled/` |
 | 설정을 썼는데 아무 변화가 없다 | 경로 오타 — `site-available`(단수)에 썼다 | `ls /etc/nginx/sites-available/` |
-| `unknown directive "http2"` | nginx < 1.25.1. Debian 12 는 1.22 다 | `nginx -v` → `listen 443 ssl http2` 형태로 |
+| `unknown directive "http2"` | nginx < 1.25.1. Debian 12 는 1.22 다 | `sudo nginx -v` → `listen 443 ssl http2` 형태로 |
 | `systemctl reload` 가 실패한다 | 설정이 `nginx -t` 를 못 통과했다 | **reload 말고 `sudo nginx -t` 를 먼저** 친다 |
 | `cp: cannot stat 'deploy/...'` | 엣지에서 쳤거나, lab host 에 리포가 없다 | `ls ~/workspace` → 없으면 00 의 0번으로 |
 | `Unit lab-edge-dnat.service does not exist` | 유닛 파일이 없거나, `/etc/systemd/` 에 썼거나, `daemon-reload` 를 안 했다 | `find /etc/systemd -name 'lab-edge-dnat*'` — `system/` 아래여야 한다 |
@@ -10169,7 +10297,8 @@ error 로그에 있었는데 잘려 있었고, access 로그에는 **3492자**
 - (observed) 2026-09-11 새로 만든 엣지에서 `/etc/nginx` 가 없던 것, `nginx -t`
  출력 세 줄, 층별 확인 ①~④ 의 코드, `301 https://auth.hyeonworks.com/`,
  upstream 실패 errno 세 줄, access 로그 3492자
- (observed) `.nft` 와 유닛 파일의 내용은 저장소 원본과 같다
+- (observed) 위에 실은 `.nft` 와 유닛의 내용은 **저장소 원본**과 같다. 다만
+  **호스트에 실제로 깔려 있는 두 파일은 그것이 아니다** — 바로 아래를 본다
 - (unknown) `curl -I http://192.168.122.11` 의 전체 출력은 캡처해 두지 않았다.
  가이드도 봐야 할 줄만 적었다
 - (unknown) `systemctl status nginx` 두 번, `ls -l /etc/nginx/sites-enabled/`,
@@ -10181,6 +10310,43 @@ error 로그에 있었는데 잘려 있었고, access 로그에는 **3492자**
 - **되돌리기는 가이드 7편 가운데 이 편에만 있다.** 위 네 줄이 원문 그대로이고,
  그 네 줄을 실제로 쳐서 걷어내 본 기록은 없다(unknown)

+**배포된 것과 적어 둔 것이 다르다**
+
+2026-09-17 에 이 절을 따라 실험대를 다시 세우다 호스트의 두 파일을 열어 봤더니
+**위에 실은 내용과 달랐다**(observed). 저장소 원본을 고친 뒤 호스트에 다시
+배포하지 않았다 — 파일 시각이 그렇게 말한다.
+
+| 파일 | 호스트에 깔린 것 (`11:00` · `10:52`) | 저장소 원본과 위 본문 (`13:30`) |
+|---|---|---|
+| `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 체인 안에
+뚫는다」(§180)인데, 호스트에는 **효과가 없는 쪽만 깔려 있고 효과가 있는 쪽은 안
+깔려 있다.** 게다가 그 구멍은 런타임 상태라 libvirt 가 네트워크를 다시 세우면
+날아가고, 다시 넣어 줄 `ExecStartPost` 가 유닛에 없으니 **실험대를 다시 세운
+직후에는 밖에서 못 들어온다.**
+
+**그래서 03 을 다시 밟을 때 4·5 번을 「이미 있으니 건너뛴다」로 넘기지 않는다.**
+파일이 있는 것과 그 파일이 위 본문의 내용인 것은 다르다. 두 파일을 열어 위와 한
+줄씩 대조하거나, 갈린 두 자리만 세어 본다.
+
+```bash
+grep -c 'chain forward' /etc/nftables.d/lab-edge-dnat.nft
+grep -c ExecStartPost /etc/systemd/system/lab-edge-dnat.service
+```
+
+`0` 과 `1` 이 나와야 맞다. 반대로 나오면 고치기 전 판이 깔려 있는 것이고, 다시
+써서 `sudo systemctl daemon-reload && sudo systemctl restart lab-edge-dnat.service`
+로 올린다.
+
+**그런데 고쳤는지는 이번에 확인하지 못했다**(unknown). 이 호스트의 `sudo` 는
+비밀번호를 묻고 이번 작업에는 그 비밀번호가 없었다. 그래서 `nft list table ip
+lab_edge` 도 `guest_input` 체인 조회도 못 돌렸고, 두 파일을 다시 배포하지도
+않았다. 위 표는 **파일 내용과 타임스탬프만으로** 적은 것이고, `reject` 줄의
+카운터가 실제로 올라갔는지는 안 봤다.
+
 ## 190. 단계 04 — Let's Encrypt 와 인증서 갱신

 **어디서 치는가** — 이 단계도 셸이 갈린다. 1~3·5 번은 전부 `[kc-lab-edge]` 에서
@@ -10278,13 +10444,29 @@ DNS 연동도 없어 관리할 것이 적다. 감수한 비용은 Cloudflare API
 **확인 ① 이 도메인이 무엇으로 풀리는가**

 ```bash
-dig +short auth.hyeonworks.com
+getent hosts auth.hyeonworks.com
 ```

 **실측**(observed)

 ```
-100.83.212.4
+100.83.212.4    auth.hyeonworks.com
+```
+
+**★ 여기에 `dig` 를 바로 쓰지 않는다.** 처음에는 `dig +short auth.hyeonworks.com`
+이라고 적었는데 **엣지 게스트에 `dig` 가 없다.** 2026-09-17 에 cloud-init 으로
+갓 만든 `kc-lab-edge` 에서 쳐서 확인했다(observed).
+
+```
+dig: command not found
+```
+
+cloud-init 이 까는 것은 `curl` 과 `nftables` 뿐이라 `dnsutils` 가 안 들어간다.
+`getent hosts` 는 `libc` 가 주는 것이라 어디서나 있고, 주소와 이름을 한 줄로 낸다.
+`dig` 의 형태가 꼭 필요하면 먼저 깐다 — 둘 다 같은 `100.83.212.4` 를 냈다(observed).
+
+```bash
+sudo apt install -y dnsutils && dig +short auth.hyeonworks.com
 ```

 **어디를 봐야 하는가** — 주소 한 줄. 그 주소가 공개 인터넷 대역인가,
@@ -10299,9 +10481,14 @@ dig +short auth.hyeonworks.com
 **확인 ② nginx 판 번호는 몇인가**

 ```bash
-nginx -v
+sudo nginx -v
 ```

+**★ `sudo` 가 붙는 까닭은 §189 확인 ① 과 같다.** 실행 파일이 `/usr/sbin/nginx`
+인데 데비안 일반 사용자 `PATH` 에 그 디렉터리가 없다. `sudo` 없이 치면
+`nginx: command not found` 다 — 안 깔린 것처럼 보이지만 아니다(2026-09-17,
+observed).
+
 **실측**(observed) — 같은 설정인데 배포판에서 갈린다.

 ```
@@ -10899,7 +11086,7 @@ timedatectl show -p NTP -p NTPSynchronized

 | 증상 | 원인 | 확인 |
 |---|---|---|
-| certbot 검증 실패 | DNS 가 이 호스트를 안 가리킴 · 80 이 막힘 | `dig +short auth.hyeonworks.com` · 밖에서 `curl -I http://auth.hyeonworks.com` |
+| certbot 검증 실패 | DNS 가 이 호스트를 안 가리킴 · 80 이 막힘 | `getent hosts auth.hyeonworks.com` · 밖에서 `curl -I http://auth.hyeonworks.com` |
 | 체인 단계가 1개 | `cert.pem` 을 씀 | 위 확인 ② |
 | 갱신은 됐는데 옛 인증서가 나감 | **deploy 훅 없음** | 워커 PID · `sudo ls /etc/letsencrypt/renewal-hooks/deploy/` |
 | 훅이 실패한 것처럼 보임 | stderr 경고를 error 로 표시 | 문구 말고 **워커 PID** |
@@ -10966,11 +11153,19 @@ timedatectl show -p NTP -p NTPSynchronized
 | PostgreSQL | Deployment `postgres` — ReplicaSet `postgres-7b474b88c8` |
 | Service | `keycloak` → Endpoints `10.42.0.67:8080,10.42.1.155:8080` |
 | Secret | `keycloak-lab-secrets` — `KC_BOOTSTRAP_ADMIN_PASSWORD` 19 bytes · `POSTGRES_PASSWORD` 22 bytes |
-| PVC | StorageClass `local-path`, 이름 끝에 파드 번호가 붙는다 |
+| PVC | `postgres-data` 하나. StorageClass `local-path` — **파드 번호가 붙지 않는다**(아래) |
 | Ingress | HOSTS 가 `auth.hyeonworks.com` |
 | 클러스터링 | JGroups — 디스커버리 테이블 `jgroups_ping`, 메시지 포트 7800 |
 | 관리 포트 | `9000` — `/metrics` 가 거기 있다 |

+**★ 이미지 태그는 이제 안다.** 2026-09-17 에 `keycloak-pattern` @ `9465582b` 의
+`deploy/lab/k8s/keycloak-cluster.yaml` 을 열어 읽었다(observed).
+
+```
+image: postgres:16-alpine
+image: quay.io/keycloak/keycloak:26.7.0
+```
+
 **판 번호는 여기 없다.** 가이드 05 는 Keycloak 과 PostgreSQL 의 이미지 태그를 적지
 않았고 `keycloak-cluster.yaml` 원문은 `source/` 에 반입되지 않았다. 이 두 판 번호는
 이 문서에서 대조하지 못한다(unknown). 가이드 안에 태그가 찍힌 이미지는 아래 임시
@@ -11012,8 +11207,20 @@ ls deploy/lab/k8s/
 curl -s -o /dev/null -w '%{http_code} tls=%{ssl_verify_result}\n' https://auth.hyeonworks.com/
 ```

-**어디를 봐야 하는가** — 04 에서 잰 `404 tls=0` 이 그대로인가. `tls=0` 이 아니면
-05 를 시작할 때가 아니라 04 로 돌아갈 때다.
+**어디를 봐야 하는가** — 04 에서 잰 `404 tls=0` 이 그대로인가. **앞의 코드를 같이
+본다.**
+
+**★ `tls=0` 만 보면 안 된다.** 연결이 **아예 안 됐을 때도** `tls=0` 이 나온다 —
+`%{ssl_verify_result}` 는 TLS 검증까지 갔을 때만 뜻이 있고 못 갔으면 초기값 `0` 이
+그대로 찍힌다. 2026-09-17 에 04 를 건너뛴 상태에서 재 보니 이렇게 나왔다(observed).
+
+```
+000 tls=0
+```
+
+`000` 은 응답이 없었다는 뜻이다. **판정은 코드가 `404` 인 것과 `tls=0` 이 같이
+나오는 것으로 한다.** `000 tls=0` 이면 04 가 아직 안 됐거나 밖에서 들어오는 길이
+막힌 것이라 05 를 시작할 때가 아니다.

 **이 결과가 의미하는 것** — 가이드 04 가 이 값 옆에 한 줄을 적어 두었다 —
 「앞의 `404` 는 05 이후에 `200` 으로 바뀐다.」 지금 재 두면 아래 5번의 `200` 이
@@ -11047,9 +11254,21 @@ kubectl -n keycloak-lab rollout status statefulset/keycloak --timeout=300s
 partitioned roll out complete: 2 new pods have been updated...
 ```

-**어디를 봐야 하는가** — 이 명령은 **끝날 때까지 아무것도 안 찍고 멈춰 있다.** 그
-침묵이 정상이다. 마지막에 나오는 한 줄에서 `complete` 라는 낱말과 파드 개수 `2` 를
-본다. 300초를 다 쓰고 타임아웃으로 끝나면 그것도 답이다 — 「안 떴다」가 확정된 것이니
+**어디를 봐야 하는가** — 마지막에 나오는 한 줄에서 `complete` 라는 낱말과 파드 개수
+`2` 를 본다. 그 줄이 나올 때까지 명령이 안 끝나고 멈춰 있는 것이 정상이다.
+
+**★ 다만 아무것도 안 찍고 멈춰 있지는 않다.** 처음에는 「끝날 때까지 아무것도 안
+찍는다」고 적었는데, 2026-09-17 에 갓 세운 클러스터에서 재 보니 기다리는 동안 줄이
+먼저 나왔다(observed).
+
+```
+Waiting for 2 pods to be ready...
+Waiting for 1 pods to be ready...
+partitioned roll out complete: 2 new pods have been updated...
+```
+
+`Waiting for …` 줄은 진행 상황이지 오류가 아니다. 숫자가 줄어들수록 파드가 하나씩
+Ready 가 된다. 300초를 다 쓰고 타임아웃으로 끝나면 그것도 답이다 — 「안 떴다」가 확정된 것이니
 아래 「막히면」으로 간다.

 **이 결과가 의미하는 것** — `complete` 면 두 파드가 다 Ready 가 됐다는 뜻이라 2번의
@@ -11326,8 +11545,24 @@ kubectl -n keycloak-lab get pvc
 ```

 **어디를 봐야 하는가** — STATUS 칸(`Bound`/`Pending`)과 VOLUME 칸(비어 있는지),
-그리고 STORAGECLASS 칸이 `local-path` 인가. StatefulSet 이면 PVC 이름 끝에 파드
-번호가 붙어 있어(`...-keycloak-0`) 어느 파드 것인지 바로 보인다.
+그리고 STORAGECLASS 칸이 `local-path` 인가.
+
+**★ 이 실험대에는 파드 번호가 붙은 PVC 가 없다.** 처음에는 「StatefulSet 이면 PVC
+이름 끝에 파드 번호가 붙어 있어 어느 파드 것인지 바로 보인다」고 적었는데, 그것은
+`volumeClaimTemplates` 를 쓰는 StatefulSet 의 이야기이고 **이 매니페스트의
+`keycloak` StatefulSet 에는 그 칸이 없다.** PVC 는 PostgreSQL 이 쓰는
+`postgres-data` 하나뿐이고 그것도 StatefulSet 이 아니라 별도 문서로 선언되어
+Deployment 가 `claimName` 으로 가리킨다. 2026-09-17 에 매니페스트와 클러스터
+양쪽에서 확인했다(observed).
+
+```
+NAME            STATUS   VOLUME                                     CAPACITY   STORAGECLASS
+postgres-data   Bound    pvc-fe269834-3dd1-4b1f-82f6-a53413310a30   5Gi        local-path
+```
+
+그래서 **Keycloak 파드는 볼륨을 안 갖는다.** 세션이 어디 사는지를 묻는 이 실험대의
+질문에서 그것이 중요하다 — 파드가 죽으면 그 안의 것은 사라지고
+`postgres-data` 만 남는다.

 **이 결과가 의미하는 것** — `Bound` 면 볼륨이 붙었다. `Pending` 이면 StorageClass 가
 없거나 노드에 자리가 없다. **`local-path` 는 파드가 스케줄될 때까지
@@ -11364,6 +11599,17 @@ ISPN000094: Received new cluster view for channel ISPN:
 **이름 목록**, 그리고 `|1` 이 **뷰 번호**(멤버가 들고 날 때마다 올라간다).
 `tail -1` 을 붙였으므로 지금 보고 있는 것은 **가장 최근 뷰** 하나다.

+**★ 이름 뒤에 `(v=…)` 가 붙어 나오기도 한다.** 2026-09-17 에 새로 세운 클러스터에서
+같은 줄을 뽑아 보니 이랬다(observed).
+
+```
+[keycloak-1-3159(v=16.0.12)|1] (2) [keycloak-1-3159(v=16.0.12), keycloak-0-13057(v=16.0.12)]
+```
+
+`(v=16.0.12)` 는 JGroups 가 붙인 판 번호이고, 볼 것은 그대로 `(2)` 와 이름 목록과
+`|1` 이다. **맨 앞의 이름이 `keycloak-0` 이 아니어도 정상이다** — 맨 앞에는 코디네이터가 오고
+먼저 뜬 쪽이 그 일을 맡는다. 이 판에서는 `keycloak-1` 이었다.
+
 **이 결과가 의미하는 것** — `(2)` 면 이 노드는 상대를 봤다. `(1)` 이면 혼자 있다고
 알고 있다. 뷰 번호가 계속 오르고 있으면 멤버가 붙었다 떨어지기를 반복하는 중이라,
 「지금 2 다」라는 스냅숏보다 그 사실이 더 중요하다. **이 줄은 과거형이다** — 지금
@@ -11466,6 +11712,26 @@ Service 뒤에 파드가 있는지(2-4), 파드가 Ready 인지(2-2) 순서다.
 curl -I https://auth.hyeonworks.com/realms/master
 ```

+**★ 이 `200` 은 04 를 끝냈을 때의 값이다.** 04 를 건너뛰고 05 만 했다면 443 을 듣는
+것이 없으므로 여기는 `000` 이다. 2026-09-17 에 그 상태에서 재 보니 이렇게
+나왔다(observed).
+
+```
+curl: (7) Failed to connect to auth.hyeonworks.com:443 after 2 ms: Could not connect to server
+```
+
+**그때도 05 가 세운 것까지는 잴 수 있다.** TLS 를 빼고 `Host` 헤더를 실어 80 으로
+치면 nginx → Traefik → Ingress → Service → 파드가 이어졌는지가 그대로 나온다. 둘 다
+`200` 이었다(observed).
+
+```bash
+curl -s -o /dev/null -w '%{http_code}\n' -H 'Host: auth.hyeonworks.com' http://192.168.122.10/realms/master
+curl -s -o /dev/null -w '%{http_code}\n' -H 'Host: auth.hyeonworks.com' http://192.168.122.11/realms/master
+```
+
+앞엣것은 엣지 nginx 를 지나고 뒤엣것은 Traefik 에 바로 친다. 둘이 같으면 남은 것은
+TLS 뿐이다.
+
 **확인 ⑤ 관리 콘솔에 로그인된다**

 브라우저로 `https://auth.hyeonworks.com/admin` 에 들어가 관리자로 로그인한다.
@@ -11478,7 +11744,7 @@ curl -I https://auth.hyeonworks.com/realms/master
 |---|---|---|
 | 롤아웃 | `kubectl -n keycloak-lab rollout status statefulset/keycloak --timeout=300s` | `complete` · 파드 `2` |
 | Service 뒤 | `kubectl -n keycloak-lab describe svc keycloak \| grep -i endpoints` | 주소 두 개 |
-| 클러스터 | `… query=vendor_cluster_size` | 원소 둘 · 값 둘 다 2 |
+| 클러스터 | `… query=vendor_cluster_size` | 원소 둘 · 값 둘 다 2 — **`health` 가 `up` 이 된 뒤에 잰다** |
 | 밖에서 | `curl -s -o /dev/null -w '%{http_code}\n' https://auth.hyeonworks.com/realms/master` | `200` |

 **근거를 재려면 (선택)** — 세션이 실제로 어디 저장되는지는 DB 를 직접 본다.
@@ -11573,9 +11839,17 @@ kubectl -n keycloak-lab exec -it keycloak-0 -- sh
 - (observed) 디스커버리 테이블에는 둘 다 있는데 메시지가 안 가는 상태를 실제로 겪었다
 - (external) `kubectl get endpoints` 의 v1.33 deprecation 은 쿠버네티스 쪽 규격이고
  이 실험대가 잰 값이 아니다
- (unknown) `keycloak-cluster.yaml` 원문은 `source/` 에 없다. **Keycloak 과
-  PostgreSQL 의 이미지 태그**, 파드 자원 한도, 프로브 설정, `persistent-user-sessions`
-  설정값은 여기서 대조하지 못했다
+- (observed) 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 접미사만 달랐다** — 그것들은 매번 새로 붙는다
+- (observed) `keycloak-cluster.yaml` 원문을 `keycloak-pattern` @ `9465582b` 에서
+  읽었다. 이미지 태그는 `postgres:16-alpine` 과 `quay.io/keycloak/keycloak:26.7.0`
+  이다
+- (unknown) 파드 자원 한도, 프로브 설정, `persistent-user-sessions` 설정값은 아직
+  이 문서로 옮기지 않았다
 - (unknown) `get all`·`get deploy`·`get pvc`·`describe pvc`·`jgroups_ping` 조회·
  `get events`·`describe pod`·`logs` 의 출력은 가이드가 봐야 할 줄만 적었고 값이 남아
  있지 않다
@@ -11731,6 +12005,19 @@ kubectl -n observability exec deploy/prometheus -- \
 준다(연결 거부·타임아웃·404). 확인 ③ 에서 값이 한 노드만 나오는 증상의 원인이 대개
 여기 있고, 그때 **클러스터가 아니라 스크레이프가 문제다.**

+**★ `down` 말고 `unknown` 도 있다.** 스택을 막 올린 직후에는 `health` 가 `unknown`
+이고 `lastError` 는 빈 문자열이다 — 실패한 것이 아니라 **아직 한 번도 안 긁은**
+것이다. 2026-09-17 에 `rollout status` 직후에 잡힌 모습이다(observed).
+
+```
+"job":"keycloak"
+"lastError":""
+"health":"unknown"
+```
+
+한 주기 뒤에 같은 줄이 `"health":"up"` 으로 바뀌었다. `unknown` 을 보고 권한이나
+네트워크를 뒤지기 전에 한 번 더 친다.
+
 **확인 ③ 클러스터 상태 — 두 노드가 각각 몇 명을 보고 있는가**

 ```bash
@@ -11746,9 +12033,40 @@ keycloak-0 → 2
 ```

 **어디를 봐야 하는가** — 응답은 **줄바꿈 없는 JSON 한 줄**이다. `data.result` 배열의
-원소가 **몇 개인가**(보고하는 노드 수), 각 원소에서 두 군데만 읽는다 — `"metric"`
-안의 `node` 라벨과 `"value"` 배열의 **둘째 원소**(따옴표에 싸인 값). `jq` 가 없으므로
-눈으로 읽는다.
+원소가 **몇 개인가**(보고하는 노드 수), 각 원소에서 두 군데만 읽는다 — 어느 Keycloak
+파드가 보고한 것인지와 `"value"` 배열의 **둘째 원소**(따옴표에 싸인 값). `jq` 가
+없으므로 눈으로 읽는다.
+
+**★ 어느 파드인지는 `node` 라벨이 아니라 `pod` 라벨이 말한다.** 처음에는 「`node`
+라벨을 읽는다」고 적었는데, Prometheus 를 거쳐 나온 응답에서 `node` 는 **쿠버네티스
+노드 이름**(`kc-lab-1`)이다. Keycloak 이 자기 지표에 붙인 `node` 는 스크레이프할 때
+이름이 겹쳐 `exported_node` 로 밀린다. 2026-09-17 에 원소 하나를 그대로 옮기면
+이렇다(observed).
+
+```
+"metric":{"__name__":"vendor_cluster_size","cache_manager":"keycloak",
+ "exported_node":"keycloak-1-3159","instance":"10.42.0.9:9000","job":"keycloak",
+ "node":"kc-lab-1","pod":"keycloak-1"},"value":[1789620021.097,"2"]
+```
+
+세 라벨이 각각 다른 것을 말한다 — `pod` 가 Keycloak 파드(`keycloak-1`),
+`exported_node` 가 Infinispan 멤버 식별자(`keycloak-1-3159`), `node` 가 그 파드가 떠
+있는 쿠버네티스 노드(`kc-lab-1`)다. 앞의 확인에서 본 `ISPN000094` 의 이름과 견줄
+것은 `exported_node` 이고, 어느 노드를 끊었을 때 무엇이 바뀌는지를 볼 때는 `node` 다.
+
+**★ 스택을 막 올린 직후에는 원소가 모자란다.** 1번의 `rollout status` 가 성공한
+직후에 이 질의를 치면 Keycloak 대상이 아직 한 번도 안 긁혀서 원소가 하나뿐이거나
+아예 없다. 2026-09-17 에 38초 시점과 약 2분 시점에 같은 질의를 쳐서
+확인했다(observed).
+
+| 언제 | 확인 ② 의 keycloak `health` | 이 질의의 원소 |
+|---|---|---|
+| `rollout status` 직후(38초) | `"health":"unknown"` | 1 개 |
+| 약 2분 뒤 | `"health":"up"` | 2 개 · 둘 다 `2` |
+
+**`unknown` 은 실패가 아니라 아직 안 긁었다는 뜻이다.** 원소가 모자라면 분단을
+의심하기 전에 확인 ② 의 `health` 를 먼저 보고, `unknown` 이면 한 주기 기다렸다 다시
+친다.

 **이 결과가 의미하는 것** — **두 노드가 각각 자기가 아는 멤버 수를 보고한다.** 둘 다
 2 면 클러스터가 온전하다. 분단되면 한쪽은 2, 다른 쪽은 1 이 된다 — **한 노드만 보면
@@ -11838,6 +12156,11 @@ kubectl -n observability port-forward svc/grafana 3000:3000

 **이 절차가 성립하는 범위**

+- (observed) 2026-09-17 에 이 절차를 갓 세운 클러스터에서 다시 밟았다. 파드 네 줄과
+  job 네 개가 그대로 나왔고 ReplicaSet 해시 `845b5678cf`·`6774f94f7c` 까지 같았다.
+  달랐던 것 — `rollout status` 직후에는 Grafana 가 `0/1` 이었고 Keycloak 대상의
+  `health` 가 `unknown` 이라 `vendor_cluster_size` 의 원소가 하나뿐이었다. 약 2분
+  뒤에 둘 다 `2` 가 됐다
 - (observed) 파드 네 줄과 job 네 개, `vendor_cluster_size` 2·2, 503 중에도 `up` 이
  1 이었던 것
 - (observed) Redis·BFF·PostgreSQL 이 스크레이프 대상에 없다는 것. 「안 찍은 것」이
@@ -16770,6 +17093,16 @@ kubectl auth can-i get nodes/proxy --as=system:serviceaccount:observability:prom
 kubectl describe clusterrole prometheus
 ```

+**★ 첫 명령은 답 앞에 경고 한 줄을 같이 낸다**(2026-09-17, observed). 실패가 아니라
+`nodes` 가 네임스페이스에 속한 자원이 아니라는 안내이고, 볼 것은 그 아래의 `yes`
+또는 `no` 다.
+
+```
+Warning: resource 'nodes' is not namespace scoped
+
+yes
+```
+
 ## 312. 배치 제어 — nodeSelector · 라벨 · taint

 ```yaml
@@ -17131,6 +17464,23 @@ virsh setmem    kc-lab-1 5120M --config
 `setmaxmem --live`는 대개 거부된다 — 게스트가 부팅 시 메모리 맵을 정하기
 때문이다. **상한을 바꾸려면 게스트를 껐다 켜야 한다.**

+**★ 바꾼 것이 들어갔는지는 `dominfo` 로 판정하지 않는다.** `--config` 는 다음 기동부터
+쓸 설정만 바꾸는데 `dominfo` 는 **지금 돌고 있는 값**을 보여 준다. 그래서 명령이 제대로
+먹어도 `dominfo` 의 숫자는 안 바뀌고, 그 화면을 「안 먹었다」로 읽게 된다. 2026-09-17 에
+같은 순간을 두 명령으로 나란히 찍었다(observed).
+
+```
+virsh dominfo kc-lab-1 | grep -i memory
+  Max memory:     5242880 KiB          ← 돌고 있는 값
+
+virsh dumpxml kc-lab-1 --inactive | grep -E '<memory|<currentMemory'
+  <memory unit='KiB'>4194304</memory>  ← 방금 바꾼 설정
+  <currentMemory unit='KiB'>4194304</currentMemory>
+```
+
+같은 도메인, 같은 시각, 다른 숫자다. **바꾼 것이 들어갔는지는 `--inactive` 가 답하고,
+`dominfo` 는 지금 무엇으로 돌고 있는지를 답한다.**
+
 ```bash
 virsh dominfo kc-lab-1 | grep -i memory
 ssh kc-lab-1 free -m        # 게스트가 실제로 인식한 값