chore: 실행 환경 구성 문서 추가 및 수정

docs/guides/README.md

@@ -41,6 +41,46 @@ echo "${#TOKEN} 자"      # 값이 아니라 길이만 확인한다
 비밀은 길이나 존재 여부만 확인하고 값을 찍지 않는다. 터미널 스크롤백과
 화면 공유에 남기 때문이다.
 
+## 어느 기계에서 치는가
+
+이 실험대에는 셸이 네 개 있고, **같은 명령이 어디서 도느냐에 따라 결과가
+달라진다.** 그래서 모든 코드 블록 앞에 어디서 치는지를 붙인다.
+
+| 표시 | 어느 기계 | 어떻게 들어가나 |
+|---|---|---|
+| `[워크스테이션]` | 평소 쓰는 개발 머신 | — |
+| `[lab host]` | `test-server`. `virsh` 가 도는 곳 | `ssh test-server` |
+| `[kc-lab-edge]` | 엣지 게스트 — nginx · certbot | `ssh kc-lab-edge` (**lab host 에서만**) |
+| `[kc-lab-1]` | k3s server 게스트 | `ssh kc-lab-1` (**lab host 에서만**) |
+| `[kc-lab-2]` | k3s agent 게스트 | `ssh kc-lab-2` (**lab host 에서만**) |
+
+**기본은 `[lab host]` 다.** 게스트는 libvirt NAT(`192.168.122.0/24`) 안에
+있어서 워크스테이션에서 직접 닿지 않는다. `ssh kc-lab-1` 이라는 별칭도
+lab host 의 `~/.ssh/config` 에만 있다.
+
+```bash
+[워크스테이션] $ ping -c1 192.168.122.11
+1 packets transmitted, 0 received, 100% packet loss     # 경로가 없다
+```
+
+**게스트 안에 들어가서 다음 단계를 치지 않는다.** 게스트에는 lab host 의
+개인키도 `~/.ssh/config` 도 없으므로, 게스트 안에서 `ssh kc-lab-1` 을 치면
+이렇게 끝난다.
+
+```bash
+[kc-lab-1] $ ssh kc-lab-1 'sudo cat /var/lib/rancher/k3s/server/node-token'
+Host key verification failed.
+```
+
+**이 실패가 조용한 이유** — 위 명령을 `TOKEN=$(...)` 로 감싸면 오류는
+stderr 로 흘러가고 `TOKEN` 에는 **빈 문자열**이 담긴다. 셸은 아무 불평도
+하지 않는다. 그래서 게스트에 로그인한 채 다음 단계를 치면 몇 단계 뒤에
+가서야 증상이 나타난다.
+
+그래서 이 가이드는 게스트에 **로그인하지 않고** lab host 에서
+`ssh kc-lab-1 '...'` 형태로 원격 실행한다. 셸이 하나뿐이면 「지금 어디
+있더라」가 생기지 않는다.
+
 ## 순서
 
 앞 단계가 끝나야 다음이 된다. 각 단계 첫머리에 「이 단계가 끝나면」이 있고,
@@ -49,9 +89,9 @@ echo "${#TOKEN} 자"      # 값이 아니라 길이만 확인한다
 | 단계 | 무엇을 세우나 | 끝나면 확인되는 것 |
 |---|---|---|
 | [00](00-lab-host/) | lab host 가상화 준비 | `virsh list` 가 돈다 |
-| [01](01-vms/) | VM 두 대 | 두 게스트에 SSH 가 붙는다 |
+| [01](01-vms/) | VM 세 대 (엣지 + k3s 2노드) | 세 게스트에 SSH 가 붙는다 |
 | [02](02-k3s/) | k3s server + agent | `kubectl get nodes` 에 둘 다 Ready |
-| [03](03-nginx/) | 호스트 nginx 라우팅 | 밖에서 요청이 파드까지 닿는다 |
+| [03](03-nginx/) | 엣지 nginx 라우팅 + 호스트 DNAT | 밖에서 요청이 파드까지 닿는다 |
 | [04](04-tls/) | Let's Encrypt | `https://` 가 열리고 체인이 4단계 |
 | [05](05-keycloak/) | Keycloak 2노드 + PostgreSQL | 관리 콘솔 로그인이 된다 |
 | [06](06-observability/) | Prometheus · Grafana | `vendor_cluster_size` 가 2 |