refactor: 문서 사람처럼 작성하기
This commit is contained in:
+10
-10
@@ -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 -->
|
||||
|
||||
+28
-28
@@ -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 재구축**은 아직 수행하지 않았다.
|
||||
|
||||
|
||||
+8
-8
@@ -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 -->
|
||||
|
||||
+12
-12
@@ -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` 이라는 것.
|
||||
|
||||
+3
-3
@@ -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까지 끊으므로 이번 재검증에서는 안전 조건 때문에 실행하지 않았다. 따라서 물리 호스트 전원 차단 뒤 복구 절차는 아직 확인하지 못했다.
|
||||
|
||||
|
||||
+2
-2
@@ -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에서만 확인했다.
|
||||
|
||||
+4
-4
@@ -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` 가 됐다.
|
||||
|
||||
+3
-3
@@ -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` | 남는다 | 키와 비밀번호가 들어 있다 |
|
||||
|
||||
+9
-9
@@ -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 -->
|
||||
|
||||
Reference in New Issue
Block a user