refactor: 문서 사람처럼 작성하기
This commit is contained in:
+42
-40
@@ -1,7 +1,7 @@
|
||||
---
|
||||
kind: CASE
|
||||
slug: an-empty-token-installed-the-agent-anyway
|
||||
title: 빈 토큰이 조용히 흘러갔다 — 설치 출력은 성공이었고 agent 만 5초마다 다시 죽었다
|
||||
title: k3s agent 설치 후 두 번째 노드가 등록되지 않은 원인
|
||||
topic: build-completion-judgment
|
||||
topicName: 끝났다는 판정
|
||||
project: virtualization
|
||||
@@ -17,44 +17,46 @@ source:
|
||||
- final/document.md#184-이-부의-출처와-범위
|
||||
---
|
||||
|
||||
# 빈 토큰이 조용히 흘러갔다 — 설치 출력은 성공이었고 agent 만 5초마다 다시 죽었다
|
||||
# k3s agent 설치 후 두 번째 노드가 등록되지 않은 원인
|
||||
|
||||
이 Case는 **과거 셸 변수 방식에서 생긴 실패**를 기록한다. k3s agent 설치 출력은 끝까지 진행됐지만 `kubectl get nodes`에는 노드가 하나뿐이었고, 뒤에서 `--token is required`가 드러났다. 현재 Setup은 이 경로를 그대로 쓰지 않는다. node-token을 파일로 내려받아 크기가 0이 아닌지 확인하고 `--token-file`로 넘기므로, 이 글은 왜 그 절차로 바뀌었는지를 설명하는 실패 기록으로 읽는다.
|
||||
`kc-lab-2`에 k3s agent를 설치했을 때 설치 스크립트는 오류 없이 끝났지만, `kubectl get nodes`에는 `kc-lab-1`만 보였다. `k3s-agent` 로그를 확인하니 `--token is required`가 반복되고 있었고, agent에 전달한 토큰 변수가 비어 있던 것이 원인이었다. 현재 Setup에서는 토큰을 파일로 전달해 같은 문제가 생기지 않도록 절차를 바꿨다.
|
||||
|
||||
## 설치는 끝났는데 두 번째 노드가 없었다
|
||||
## 설치 스크립트는 끝났지만 노드가 등록되지 않았다
|
||||
|
||||
k3s agent 설치가 끝까지 돌았고 출력에 오류가 없었다. 그런데 두 노드가 Ready 로 나와야 할 kubectl get nodes 에 두 번째 노드가 나타나지 않았다.
|
||||
agent 설치 스크립트는 오류 없이 종료됐다. 하지만 두 노드가 `Ready` 상태로 보여야 하는 `kubectl get nodes`에는 `kc-lab-1`만 나왔다.
|
||||
|
||||
설치 출력의 오류 : x
|
||||
kubectl get nodes 의 노드 수 : 1
|
||||
k3s-agent 유닛 : 5초마다 재시작
|
||||
journalctl -u k3s-agent : level=fatal msg="Error: --token is required"
|
||||
| 확인 항목 | 결과 |
|
||||
|---|---|
|
||||
| agent 설치 스크립트 | 오류 없이 종료 |
|
||||
| `kubectl get nodes` | `kc-lab-1`만 표시 |
|
||||
| `k3s-agent` 서비스 | 5초 간격으로 재시작 |
|
||||
| `journalctl -u k3s-agent` | `level=fatal msg="Error: --token is required"` |
|
||||
|
||||
실패가 화면에 나오지 않아 설치는 끝난 것으로 읽힌다.
|
||||
설치 스크립트가 끝났다는 사실만으로는 agent가 정상적으로 클러스터에 등록됐다고 판단할 수 없었다.
|
||||
|
||||
## 빈 토큰이 설치 단계까지 조용히 흘렀다
|
||||
## 토큰 변수에 빈 문자열이 들어간 원인
|
||||
|
||||
토큰을 꺼내는 ssh 를 게스트 안에서 쳤고 그 명령이 Host key verification failed. 로 끝났다. 명령 치환으로 감싸면 오류는 stderr 로 흘러가고 변수에는 빈 문자열이 담긴다. 셸은 아무 불평도 하지 않는다.
|
||||
토큰을 읽는 `ssh` 명령을 lab host가 아니라 게스트 안에서 실행했고, 해당 명령은 `Host key verification failed.`로 실패했다. 이 명령을 `TOKEN=$(...)` 형태로 실행하면 표준 출력만 변수에 들어가기 때문에 `TOKEN`에는 빈 문자열이 남는다.
|
||||
|
||||
agent 는 --token '' 을 받아 level=fatal msg="Error: --token is required" 로 죽지만, 설치 스크립트는 그 전까지를 다 성공으로 찍고 끝난다. 그래서 설치 출력만 보면 성공이고, 유닛이 Restart=always 라 5초마다 조용히 재시도한다.
|
||||
그 상태로 agent 설치 명령을 실행하면 `--token ''`이 전달된다. 설치 스크립트는 서비스 파일 생성과 enable 단계까지 끝내지만, 실제 `k3s-agent` 프로세스는 `level=fatal msg="Error: --token is required"`를 남기고 종료됐다. `Restart=always` 설정 때문에 서비스는 5초 간격으로 다시 시작됐다.
|
||||
|
||||
당시 바로잡은 방향 : 게스트 안에서 다시 `ssh kc-lab-1`을 부르지 않고 lab host에서 server token을 읽는다
|
||||
당시 가드 : 비밀 값을 화면에 찍지 않고 비어 있지 않은지만 확인한다. 108자는 그 실행의 관측값이지 고정 규격이 아니다
|
||||
현재 Setup : token을 파일로 받아 `wc -c`로 비어 있지 않은지 확인한 뒤 `--token-file`로 넘긴다. 셸 변수와 같은 셸 제약을 없앴다
|
||||
당시에는 게스트 안에서 다시 `ssh kc-lab-1`을 실행하지 않고 lab host에서 server token을 읽도록 수정했다. 토큰 값 자체는 출력하지 않고 비어 있는지만 확인했으며, 108자는 당시 실행에서 관측한 길이일 뿐 고정 규격으로 사용하지 않았다. 현재 Setup에서는 토큰을 파일로 받아 `wc -c`로 크기를 확인한 뒤 `--token-file`로 전달한다.
|
||||
|
||||
## 당시 k3s 실험 환경
|
||||
|
||||
호스트 : test-server, Arch Linux
|
||||
CPU : i5-1135G7, 논리 코어 8
|
||||
RAM : 11,648MiB
|
||||
QEMU : 11.1.1
|
||||
libvirt : 12.7.0
|
||||
게스트 : Debian 12 genericcloud
|
||||
k3s : v1.36.4+k3s1
|
||||
server 노드 : kc-lab-1, 192.168.122.11
|
||||
agent 노드 : kc-lab-2, 192.168.122.12
|
||||
토큰 길이 : 108자
|
||||
토큰 형식 : K10<해시>::server:<비밀번호>
|
||||
| 항목 | 값 |
|
||||
|---|---|
|
||||
| 호스트 | test-server, Arch Linux |
|
||||
| CPU | i5-1135G7, 논리 코어 8 |
|
||||
| RAM | 11,648MiB |
|
||||
| QEMU | 11.1.1 |
|
||||
| libvirt | 12.7.0 |
|
||||
| 게스트 | Debian 12 genericcloud |
|
||||
| k3s | v1.36.4+k3s1 |
|
||||
| server 노드 | kc-lab-1, 192.168.122.11 |
|
||||
| agent 노드 | kc-lab-2, 192.168.122.12 |
|
||||
| 당시 토큰 길이 | 108자 |
|
||||
| 토큰 형식 | K10<해시>::server:<비밀번호> |
|
||||
|
||||
## 같은 실패를 다시 만들려면
|
||||
|
||||
@@ -73,7 +75,7 @@ agent 노드 : kc-lab-2, 192.168.122.12
|
||||
|
||||
k3s server 는 `kc-lab-1` 에, agent 는 `kc-lab-2` 에 깔고 둘 다 lab host 에서 `ssh` 로 원격 실행한다. 가이드가 코드 블록마다 어느 기계에서 치는지를 붙여 둔 까닭이 여기에 있다 — 게스트는 libvirt NAT(`192.168.122.0/24`) 안에 있어 워크스테이션에서 직접 닿지 않고, `ssh kc-lab-1` 이라는 별칭도 lab host 의 `~/.ssh/config` 에만 있다.
|
||||
|
||||
당시 절차는 agent가 사용할 node-token을 lab host의 셸 변수에 담아 설치 명령으로 넘겼다. 바로 이 변수 전달이 실패 지점이 됐다. 현재 Setup은 token file을 사용하므로 아래 블록은 **historical failure path**다.
|
||||
당시에는 agent가 사용할 node-token을 lab host의 셸 변수에 담아 설치 명령으로 넘겼다. 문제가 생긴 지점도 이 변수 전달 과정이었다. 현재 설치 절차는 토큰 파일을 사용하므로 아래 명령은 당시 문제를 설명하기 위한 예시다.
|
||||
|
||||
```bash
|
||||
TOKEN=$(ssh kc-lab-1 'sudo cat /var/lib/rancher/k3s/server/node-token')
|
||||
@@ -89,7 +91,7 @@ ssh kc-lab-2 "curl -sfL https://get.k3s.io | sudo sh -s - agent \
|
||||
--node-ip 192.168.122.12"
|
||||
```
|
||||
|
||||
## 게스트 안에서 친 ssh 는 빈 문자열이 된다
|
||||
## 게스트에서 실행한 ssh 명령은 토큰을 가져오지 못했다
|
||||
|
||||
토큰을 꺼내려고 게스트에 먼저 들어가면 같은 명령이 다르게 끝난다. 게스트에는 lab host 의 개인키도 `~/.ssh/config` 도 없다.
|
||||
|
||||
@@ -98,11 +100,11 @@ ssh kc-lab-2 "curl -sfL https://get.k3s.io | sudo sh -s - agent \
|
||||
Host key verification failed.
|
||||
```
|
||||
|
||||
여기까지는 오류 문구가 찍힌다. 문제는 이 명령을 `TOKEN=$(...)` 로 감쌌을 때다. 명령 치환은 표준 출력만 변수에 담으므로 오류는 stderr 로 흘러가고 `TOKEN` 에는 빈 문자열이 담기며, 셸은 아무 불평도 하지 않는다. 뒤이어 치는 설치 명령은 `--token ''` 을 넘긴 것과 같아진다.
|
||||
오류 메시지는 표준 오류로 출력된다. 그런데 같은 명령을 `TOKEN=$(...)`로 감싸면 표준 출력만 변수에 들어가므로 `TOKEN`에는 빈 문자열이 남는다. 뒤이어 실행한 설치 명령은 결국 `--token ''`을 전달한 것과 같았다.
|
||||
|
||||
## 설치 출력이 성공으로 끝나는 경로
|
||||
## 설치 스크립트 종료와 agent 기동 성공은 다른 상태였다
|
||||
|
||||
빈 문자열을 받은 설치도 끝까지 돈다. agent 가 `--token ''` 을 받아 `level=fatal msg="Error: --token is required"` 로 죽는데, 설치 스크립트는 그 전까지를 다 성공으로 찍고 끝나므로 설치 출력만 보면 성공이다. 성공으로 찍힌 것은 내려받기와 유닛 생성과 `enable` 까지다. 유닛은 `Restart=always` 라 5초마다 조용히 재시도하고, 그래서 실패가 화면이 아니라 `journalctl -u k3s-agent` 안에서만 되풀이된다.
|
||||
빈 토큰을 넘겨도 설치 스크립트는 바이너리 다운로드와 서비스 파일 생성, `enable` 단계까지 진행한다. 이 때문에 스크립트가 종료된 화면만 보면 설치가 끝난 것처럼 보인다. 하지만 실제 agent 프로세스는 `--token is required` 오류로 종료됐고, `Restart=always` 설정 때문에 5초 간격으로 재시작했다. 실제 실패 원인은 `journalctl -u k3s-agent`에서 확인할 수 있었다.
|
||||
|
||||
k3s server 와 agent 를 세우는 단계가 끝났다는 판정은 lab host 에서 노드 목록을 쳐서 두 노드가 `Ready` 로 나오는 것이다.
|
||||
|
||||
@@ -116,19 +118,19 @@ kc-lab-1 Ready control-plane 47m v1.36.4+k3s1 192.168.122.11
|
||||
kc-lab-2 Ready <none> 21m v1.36.4+k3s1 192.168.122.12
|
||||
```
|
||||
|
||||
빈 토큰으로 깔린 agent 는 이 목록에 올라오지 않는다.
|
||||
토큰이 비어 있으면 agent는 정상적으로 기동하지 못하므로 이 목록에 두 번째 노드가 나타나지 않는다.
|
||||
|
||||
## 값을 보여 주지 않고 빈 토큰만 걸러낸다
|
||||
## 토큰 값은 출력하지 않고 비어 있는지만 확인한다
|
||||
|
||||
이 사건에서 필요한 확인은 토큰 내용을 눈으로 대조하는 일이 아니었다. 설치를 시작하기 전에 값이 비어 있는지만 알면 됐다. 당시 기록에는 토큰 길이가 108자로 남아 있지만, 그 숫자는 한 번의 실행에서 나온 값이지 성공 조건이 아니다.
|
||||
|
||||
과거 절차에서는 셸 변수의 길이를 확인했다. 현재 Setup은 이 실패를 피하려고 token file로 바뀌었고, `wc -c`로 파일이 비어 있지 않은지 확인한 뒤 `--token-file`로 넘긴다. 따라서 이 Case에는 원문 근거에 없던 셸 가드 명령을 새로 보태지 않는다.
|
||||
과거 절차에서는 셸 변수의 길이를 확인했다. 현재 설치 절차에서는 토큰을 파일로 받은 뒤 `wc -c`로 파일이 비어 있지 않은지 확인하고 `--token-file`로 넘긴다. 당시 기록에 없는 별도 셸 가드 명령은 추가하지 않았다.
|
||||
|
||||
길이가 `0` 으로 나올 수 있는 길은 하나로 한정되지 않는다. 게스트 안에서 다시 `ssh kc-lab-1`을 불러 실패할 수도 있고, server가 아직 token 파일을 만들지 못했을 수도 있고, 새 셸을 열면서 변수 자체가 사라졌을 수도 있다. 중요한 건 원인을 추측하기 전에 설치 직전의 입력이 비어 있는지부터 확인하는 것이다.
|
||||
|
||||
## 현재 Setup은 처음부터 token file을 쓴다
|
||||
## 현재 설치 절차는 토큰 파일을 사용한다
|
||||
|
||||
셸 변수 방식은 새 창으로 넘어가면 값이 없고, command line에 token이 들어갈 위험도 있다. 그래서 현재 Setup은 이 Case의 우회책을 정식 절차로 올려 **처음부터 파일로 넘긴다.** 아래 파이프 형태는 사건 이후 사용한 historical/reference 방식이고, 현재 Setup은 `scp`·`chmod`·`wc -c`를 나눠 실패 지점을 더 분명하게 만든다.
|
||||
셸 변수는 새 셸로 넘어가면 값이 사라질 수 있고, 토큰을 명령행 인자로 직접 넘기면 프로세스 인자에 값이 노출될 수 있다. 그래서 현재 설치 절차는 토큰을 파일로 전달한다. 아래 파이프 방식은 문제를 확인한 뒤 사용했던 방식이고, 현재 문서에서는 `scp`, `chmod`, `wc -c`를 각각 나눠 어느 단계에서 실패했는지 확인할 수 있게 했다.
|
||||
|
||||
```bash
|
||||
ssh kc-lab-1 'sudo cat /var/lib/rancher/k3s/server/node-token' \
|
||||
@@ -138,11 +140,11 @@ ssh kc-lab-2 "curl -sfL https://get.k3s.io | sudo sh -s - agent \
|
||||
--node-ip 192.168.122.12; rm -f /tmp/token"
|
||||
```
|
||||
|
||||
이 방식은 token 값을 command line 인자로 직접 넣지 않고 셸 변수에도 의존하지 않는다. 현재 canonical Setup은 여기에 파일 존재·길이 확인과 영구 경로 이동을 더해 재부팅 뒤에도 agent가 같은 token file을 읽도록 구성한다.
|
||||
이 방식은 토큰 값을 명령행 인자로 직접 넣지 않고 셸 변수에도 의존하지 않는다. 현재 설치 절차는 여기에 파일 존재 여부와 길이 확인, 영구 경로 이동을 추가해 재부팅 뒤에도 agent가 같은 토큰 파일을 읽도록 구성한다.
|
||||
|
||||
## 아직 원문 증거가 부족한 부분
|
||||
## 확인하지 못한 범위
|
||||
|
||||
원래 빈 토큰 사건의 `level=fatal msg="Error: --token is required"` 와 당시 설치 출력은 여전히 직접 raw가 없다. 다만 2026-09-17 후속 원문은 현재 정상 경로를 보강한다. `15-k3s-precheck.txt` 에는 별도 precheck에서 `Host key verification failed.`가 남아 있고, `21-k3s-token.txt` 는 재구축 시점의 **비어 있지 않은 토큰**을 길이로 확인했으며, `22-k3s-agent-install.txt` 는 그 토큰으로 agent 설치가 성공한 출력을 담는다. 이 셋은 원래 빈 토큰 실패의 재현이 아니라 **후속 정상 경로를 뒷받침하는 자료**다. 과거 사건의 토큰 108자와 후속 실행의 길이가 다르더라도 같은 측정으로 덮어쓰지 않는다.
|
||||
당시 `level=fatal msg="Error: --token is required"` 로그와 설치 출력 원문은 남아 있지 않다. 2026-09-17에 다시 구성하면서 확보한 자료에는 `Host key verification failed.`가 발생한 사전 점검, 비어 있지 않은 토큰 길이 확인, 정상적인 agent 설치 출력이 남아 있다. 이 자료는 현재 정상 절차를 확인한 것이지 과거의 빈 토큰 실패를 다시 재현한 것은 아니다. 당시 토큰 길이 108자 역시 후속 실행의 값으로 덮어쓰지 않는다.
|
||||
|
||||
이 실패를 일부러 다시 만들어 본 기록은 없다. 빈 토큰 사건은 한 번의 과거 관측이고, 현재 정상 절차는 token file 방식으로 바뀌었다. 같은 문제가 다시 발생하면 설치 출력만 보지 말고 `journalctl -u k3s-agent`의 원문과 `kubectl get nodes` 결과를 함께 보존해 실패 지점을 확인한다.
|
||||
|
||||
|
||||
+47
-43
@@ -1,7 +1,7 @@
|
||||
---
|
||||
kind: CASE
|
||||
slug: cloud-init-failures-all-look-like-ssh-refused
|
||||
title: SSH 실패부터 보지 않았다 — cloud-init 시드 경로를 먼저 확인한 이유
|
||||
title: SSH 연결 실패를 확인할 때 cloud-init 시드부터 본 이유
|
||||
topic: build-completion-judgment
|
||||
topicName: 끝났다는 판정
|
||||
project: virtualization
|
||||
@@ -15,49 +15,53 @@ source:
|
||||
- final/document.md#186-단계-00-lab-host-가상화-준비
|
||||
---
|
||||
|
||||
# SSH 실패부터 보지 않았다 — cloud-init 시드 경로를 먼저 확인한 이유
|
||||
# SSH 연결 실패를 확인할 때 cloud-init 시드부터 본 이유
|
||||
|
||||
게스트가 `running`인데 SSH가 안 붙으면 곧바로 SSH 키부터 고치지 않았다. 먼저 cloud-init이 시드를 읽었는지 확인했다. 이 실험대에서 실제로 확인한 것은 `--cloud-init`으로 붙인 시드 경로가 기대대로 보이지 않았던 사례와 cloud-init 22.4.2의 schema 거부다. YAML 파싱 실패, `vol-upload` 누락, libvirt network autostart 문제는 같은 단계에서 점검해야 할 **가능한 실패 경로**로 남기되, 모두 이 환경에서 같은 증상으로 재현했다고 쓰지 않는다.
|
||||
게스트 세 대는 `running` 상태였지만 SSH 공개키 인증이 되지 않았고, 한 게스트의 호스트명은 `localhost`로 남아 있었다. SSH 설정만 수정하기 전에 cloud-init이 시드를 읽었는지부터 확인했다. 이 환경에서 실제로 확인한 문제는 기존 `--cloud-init` 연결에서 기대한 NoCloud 시드가 보이지 않았던 점과 cloud-init 22.4.2의 스키마 검사 결과였다. YAML 파싱 실패, `vol-upload` 누락, libvirt 네트워크 자동 시작 문제는 같은 증상을 만들 수 있는 점검 항목이지만 이 환경에서 각각 재현한 것은 아니다.
|
||||
|
||||
## VM은 떴는데 SSH만 붙지 않았다
|
||||
## 게스트는 실행 중이었지만 SSH 공개키 인증이 되지 않았다
|
||||
|
||||
게스트 세 대가 running 인데 lab host 에서 SSH 가 키로 붙지 않는다.
|
||||
가상 머신 자체는 모두 실행 중이었다. 문제는 운영체제가 기대한 초기 설정을 적용했는지였다.
|
||||
|
||||
virsh list --all : kc-lab-1 · kc-lab-2 · kc-lab-edge 모두 running
|
||||
ssh donghyeon@192.168.122.11 : Permission denied (publickey)
|
||||
게스트의 hostname : localhost
|
||||
cloud-init 이 남긴 오류 : x
|
||||
| 확인 항목 | 당시 상태 |
|
||||
|---|---|
|
||||
| `virsh list --all` | `kc-lab-1`, `kc-lab-2`, `kc-lab-edge` 모두 `running` |
|
||||
| `ssh donghyeon@192.168.122.11` | `Permission denied (publickey)` |
|
||||
| 게스트 호스트명 | `localhost` |
|
||||
| cloud-init 오류 원문 | 별도로 보존하지 않음 |
|
||||
|
||||
cloud-init이 user-data를 적용하지 못하면 기대한 사용자와 SSH key도 들어가지 않을 수 있다. 다만 원인마다 남는 로그와 상태는 다를 수 있으므로 “cloud-init이 오류를 남기지 않는다”로 일반화하지 않는다. 이 사건에서는 SSH 실패와 `localhost` hostname이 먼저 눈에 띄었고, 그래서 시드/data source 경로를 SSH 설정보다 먼저 확인했다.
|
||||
cloud-init이 `user-data`를 적용하지 못하면 사용자 계정과 SSH 공개키도 기대한 상태로 만들어지지 않을 수 있다. 이때 SSH 키만 바꾸면 원인을 놓칠 수 있으므로, 먼저 시드가 게스트에 전달됐는지 확인했다.
|
||||
|
||||
## SSH보다 먼저 cloud-init이 시드를 읽었는지 본다
|
||||
## 먼저 cloud-init이 시드를 읽었는지 확인했다
|
||||
|
||||
SSH 실패가 보이면 아래 경로를 차례로 가른다.
|
||||
SSH 연결 실패와 cloud-init 문제를 구분하기 위해 다음 항목을 순서대로 확인했다.
|
||||
|
||||
시드 연결 방식 : 이 환경에서는 `--cloud-init` 경로로 만든 시드가 guest에서 기대대로 읽히지 않았고, seed ISO를 `bus=virtio` disk로 붙인 구성에서는 `/dev/vdb`의 NoCloud data source로 확인됐다
|
||||
YAML/cloud-config : syntax와 schema를 별도로 확인한다. parser/schema 실패는 guest 로그와 `cloud-init status --long`을 함께 본다
|
||||
`vol-upload` 누락 : libvirt volume 이름만 존재하고 실제 seed 내용이 올라갔는지 용량과 업로드 절차를 확인한다
|
||||
`default` network autostart : host 재부팅 뒤 network 자체가 안 올라온 경우에는 cloud-init과 별개로 guest 접근 경로가 사라질 수 있으므로 `virsh net-info default`를 본다
|
||||
| 확인 항목 | 확인하는 내용 |
|
||||
|---|---|
|
||||
| 시드 연결 방식 | 이 환경에서는 virtio 디스크로 붙인 seed ISO가 `/dev/vdb`의 NoCloud 데이터소스로 인식됐다 |
|
||||
| YAML과 cloud-config | YAML 문법과 cloud-init 스키마 검사는 별도로 확인한다 |
|
||||
| `vol-upload` | libvirt 볼륨만 만든 것이 아니라 실제 seed ISO 내용까지 업로드됐는지 확인한다 |
|
||||
| `default` 네트워크 | 호스트 재부팅 뒤 libvirt 네트워크가 올라왔는지 `virsh net-info default`로 확인한다 |
|
||||
|
||||
판정 : SSH 설정을 고치기 전에 호스트명 한 낱말을 본다. ssh kc-lab-edge 'hostname' 이 kc-lab-edge 를 내면 시드가 읽혔고, 시드가 읽혔으면 같은 파일에 있던 SSH 키도 들어갔다
|
||||
못 들어가면 : virsh screenshot 으로 화면을 떠서 로그인 프롬프트 앞의 호스트명을 읽는다
|
||||
키가 안 들어갔을 때의 탈출구 : cloud-init 의 plain_text_passwd 로 콘솔 로그인
|
||||
SSH가 가능하면 `hostname`과 `cloud-init status`를 먼저 확인한다. 접속 자체가 되지 않으면 `virsh screenshot`으로 콘솔의 호스트명을 확인할 수 있다. 공개키가 적용되지 않았을 때 콘솔 로그인이 필요하도록 `plain_text_passwd`도 당시 cloud-init 설정에 포함했다.
|
||||
|
||||
반대 방향도 하나 있다. 게스트의 cloud-init 22.4.2 스키마 검사기는 sudo 를 리스트로 쓴 것을 거부한다. 그런데 그 표기로도 부팅은 되고, kc-lab-1 과 kc-lab-2 에서 그 상태로 NOPASSWD sudo 가 돌고 있다. 검사가 통과해도 안 도는 쪽이 넷이고 검사에 걸려도 도는 쪽이 하나라, 어느 방향이든 검사 결과를 게스트의 상태로 읽으면 틀린다.
|
||||
다만 스키마 검사 결과만으로 게스트의 최종 상태를 판단하지는 않는다. cloud-init 22.4.2는 `sudo`를 리스트로 쓴 표현을 거부했지만, 기존 `kc-lab-1`과 `kc-lab-2`에서는 같은 표현으로 `NOPASSWD` sudo가 실제 동작하고 있었다. 스키마 검사는 사전 점검이고, 최종 상태는 부팅한 게스트에서 다시 확인해야 했다.
|
||||
|
||||
## 당시 cloud-init 실험 환경
|
||||
|
||||
호스트 : test-server, Arch Linux
|
||||
RAM : 11,648MiB
|
||||
QEMU : 11.1.1
|
||||
libvirt : 12.7.0
|
||||
base 이미지 : Debian 12 genericcloud amd64
|
||||
게스트 OS : Debian GNU/Linux 12 (bookworm)
|
||||
게스트 : kc-lab-edge 192.168.122.10 · kc-lab-1 192.168.122.11 · kc-lab-2 192.168.122.12
|
||||
시드 : seed-<이름>.iso, CIDATA 라벨, bus=virtio 로 붙임
|
||||
게스트의 cloud-init : 22.4.2
|
||||
cloud-init 이 깐 패키지 : curl · nftables
|
||||
running 에서 done 까지 : 약 50초
|
||||
| 항목 | 값 |
|
||||
|---|---|
|
||||
| 호스트 | test-server, Arch Linux |
|
||||
| RAM | 11,648MiB |
|
||||
| QEMU | 11.1.1 |
|
||||
| libvirt | 12.7.0 |
|
||||
| base 이미지 | Debian 12 genericcloud amd64 |
|
||||
| 게스트 OS | Debian GNU/Linux 12 (bookworm) |
|
||||
| 게스트 | kc-lab-edge 192.168.122.10 · kc-lab-1 192.168.122.11 · kc-lab-2 192.168.122.12 |
|
||||
| 시드 | `seed-<이름>.iso`, CIDATA 라벨, `bus=virtio` |
|
||||
| cloud-init | 22.4.2 |
|
||||
| cloud-init으로 설치한 패키지 | curl · nftables |
|
||||
| `running`에서 `done`까지 | 약 50초 |
|
||||
|
||||
## 같은 증상을 확인하는 순서
|
||||
|
||||
@@ -96,10 +100,10 @@ virsh vol-upload --pool default seed-kc-lab-1.iso seed-kc-lab-1.iso
|
||||
|---|---|
|
||||
| `--cloud-init`으로 붙인 시드가 guest에서 기대대로 읽히지 않음 | 이 환경에서 실제 관측. 수동 virtio seed 구성으로 바꾼 뒤 NoCloud `seed=/dev/vdb` 확인 |
|
||||
| YAML/cloud-config 파싱 또는 schema 문제 | schema 거부는 실제 관측. 임의의 YAML parsing failure를 같은 증상으로 재현한 기록은 없음 |
|
||||
| `vol-upload` 누락 | 절차상 가능한 실패 경로. 실제 누락 부팅 재현 원문은 없음 |
|
||||
| `default` network autostart 비활성 | host reboot 뒤 접근 경로에 영향을 줄 수 있는 사전 조건. 이 실패를 실제 재현한 원문은 없음 |
|
||||
| `vol-upload` 누락 | 절차상 가능한 실패 경로. 실제 누락 부팅을 재현한 기록은 없음 |
|
||||
| `default` network autostart 비활성 | host reboot 뒤 접근 경로에 영향을 줄 수 있는 사전 조건. 이 실패를 실제로 재현한 기록은 없음 |
|
||||
|
||||
시드 연결 방식은 이 실험대에서 실제로 문제를 겪은 부분이다. 당시 `--cloud-init`이 만든 연결에서는 guest가 기대한 NoCloud seed를 읽지 못했고, 최종 구성에서는 seed ISO를 `device=disk,bus=virtio,readonly=on`으로 붙였다. 2026-09-17의 정상 guest `cloud-init status --long`에는 `DataSourceNoCloud [seed=/dev/vdb][dsmode=net]`가 남아 있다. **원인을 ‘Debian genericcloud에는 AHCI 드라이버가 없다’로 일반화하지 않는다.** 현재 증거가 확정하는 것은 이 환경에서 virtio `vdb` seed 경로가 실제로 동작했다는 것까지다.
|
||||
시드 연결 방식은 이 실험대에서 실제로 문제를 겪은 부분이다. 당시 `--cloud-init`이 만든 연결에서는 guest가 기대한 NoCloud seed를 읽지 못했고, 최종 구성에서는 seed ISO를 `device=disk,bus=virtio,readonly=on`으로 붙였다. 2026-09-17의 정상 guest `cloud-init status --long`에는 `DataSourceNoCloud [seed=/dev/vdb][dsmode=net]`가 남아 있다. 현재 남아 있는 증거만으로 `--cloud-init` 경로가 기대대로 동작하지 않은 원인을 특정할 수는 없다. 확인된 것은 virtio `vdb`로 연결한 seed 경로가 이 환경에서 실제로 동작했다는 것까지다.
|
||||
|
||||
```bash
|
||||
virt-install --name kc-lab-1 --memory 5120 --vcpus 2 \
|
||||
@@ -109,9 +113,9 @@ virt-install --name kc-lab-1 --memory 5120 --vcpus 2 \
|
||||
--import --os-variant debian12 --noautoconsole
|
||||
```
|
||||
|
||||
`default` network의 autostart도 guest 내부 문제와 분리해 본다. host 재부팅 뒤 libvirt network가 올라오지 않으면 SSH 접근이 함께 끊길 수 있으므로 `virsh net-info default`의 `Active`와 `Autostart`를 먼저 확인한다. 이 문서는 그 실패를 이 환경에서 실제 재현했다고 주장하지 않고, 재부팅 뒤 접근 경로를 가르는 사전 확인으로 둔다.
|
||||
`default` network의 autostart도 guest 내부 문제와 분리해 확인한다. host 재부팅 뒤 libvirt network가 올라오지 않으면 SSH 접근 경로도 사라질 수 있으므로 `virsh net-info default`의 `Active`와 `Autostart`를 확인한다. network autostart 비활성 자체는 이 환경에서 재현하지 않았으며, 재부팅 뒤 접근 경로를 확인하기 위한 점검 항목으로만 남긴다.
|
||||
|
||||
## 호스트명 한 낱말이 시드와 SSH 를 가른다
|
||||
## 호스트명과 cloud-init 상태로 시드 적용 여부를 확인했다
|
||||
|
||||
게스트에 SSH 가 붙는다면 확인은 한 줄로 끝난다.
|
||||
|
||||
@@ -125,7 +129,7 @@ enp1s0 UP 192.168.122.10/24 metric 100
|
||||
status: done
|
||||
```
|
||||
|
||||
호스트명이 바뀌었다는 것은 시드가 읽혔다는 뜻이고, 시드가 읽혔으면 같은 파일에 있던 SSH 키도 들어갔다. `localhost` 가 나오면 SSH 설정을 고치지 말고 시드부터 의심한다. `cloud-init status` 가 `running` 이면 아직 패키지를 받는 중이고, 이 실험대에서는 `done` 까지 약 50초 걸렸다.
|
||||
호스트명이 `kc-lab-edge`로 바뀌고 `cloud-init status`가 `done`이면 해당 시드가 적용된 상태로 볼 수 있었다. 반대로 `localhost`가 남아 있으면 SSH 설정을 수정하기 전에 시드 연결과 cloud-init 상태부터 다시 확인했다. 이 실험대에서는 `running`에서 `done`까지 약 50초가 걸렸다.
|
||||
|
||||
게스트에 못 들어가면 화면을 직접 뜬다.
|
||||
|
||||
@@ -133,9 +137,9 @@ status: done
|
||||
virsh screenshot kc-lab-1 /tmp/kc1.ppm # 확장자와 무관하게 PNG 로 저장된다
|
||||
```
|
||||
|
||||
로그인 프롬프트 앞의 호스트명 한 낱말만 읽는다. `localhost login:` 이면 cloud-init 이 아예 안 돌았으므로 SSH 쪽은 볼 것이 없다. `kc-lab-1 login:` 이면 cloud-init 은 돌았고 그 안의 사용자·키 단계에서 틀린 것이라 콘솔로 들어가 로그를 본다. 콘솔 로그인에 쓰는 비밀번호가 cloud-init 의 `plain_text_passwd` 이고, 키가 안 들어갔을 때 게스트로 들어가는 길이 이것 하나다.
|
||||
로그인 프롬프트의 호스트명이 `localhost`라면 시드 적용 여부부터 다시 확인한다. `kc-lab-1`처럼 기대한 호스트명이 보인다면 cloud-init은 일부 단계를 수행한 것이므로 콘솔에 로그인해 사용자와 SSH 키 적용 로그를 확인한다. 당시 설정의 `plain_text_passwd`는 공개키 인증이 되지 않을 때 콘솔로 들어가기 위한 수단이었다.
|
||||
|
||||
순서를 이렇게 정한 까닭이 여기에 있다. 화면 한 장과 콘솔에서 보는 로그 두 줄이 「SSH 가 안 되는 이유」를 절반으로 줄인다. 호스트명이 그 절반을 가르므로, 어느 쪽 절반을 볼지가 정해지기 전에는 SSH 설정을 열 이유가 없다.
|
||||
이 순서를 사용하면 SSH 설정 자체의 문제인지, 그보다 앞선 cloud-init 초기화 문제인지 먼저 구분할 수 있다.
|
||||
|
||||
## 검사가 거부해도 부팅은 된다
|
||||
|
||||
@@ -167,21 +171,21 @@ python3 -c 'import yaml,sys; yaml.safe_load(open("kc-lab-1.yaml")); print("YAML
|
||||
|
||||
`0` 과 `2` 와 `YAML OK` 셋이 맞아야 시드를 만든다. 셋이 맞아도 cloud-config 로 유효하지는 않다 — 키 이름을 `users` 대신 `user` 로 친 오타는 이 세 줄을 그냥 통과한다. 그래서 게스트가 한 대라도 떠 있으면 cloud-init 자신의 스키마 검사기를 쓴다.
|
||||
|
||||
```bash label="[lab host] [reference] historical command"
|
||||
```bash label="[lab host] 당시 사용한 명령"
|
||||
ssh donghyeon@192.168.122.11 'umask 077; cat > ~/kc-lab-2.yaml' < kc-lab-2.yaml
|
||||
ssh donghyeon@192.168.122.11 'cloud-init schema -c ~/kc-lab-2.yaml; rm -f ~/kc-lab-2.yaml'
|
||||
```
|
||||
|
||||
이 두 줄은 **당시 문서에 남은 historical command**다. 둘째 줄은 스키마 검사가 실패해도 `; rm` 때문에 파일을 지운다. 따라 하는 절차에서는 검사와 삭제를 분리하고, 검사 성공 여부를 본 뒤 삭제한다.
|
||||
이 두 줄은 당시 문서에 남아 있던 명령이다. 둘째 줄은 스키마 검사가 실패해도 `; rm` 뒤의 삭제가 실행될 수 있으므로, 현재 절차에서는 검사와 삭제를 분리하고 검사 결과를 확인한 뒤 파일을 지운다.
|
||||
|
||||
이 파일에는 콘솔 비밀번호가 평문으로 들어 있어 `/tmp` 가 아니라 자기 홈에 `600` 으로 두고, 검사가 끝나면 바로 지운다.
|
||||
|
||||
## 실제로 재현한 실패와 아직 가정인 실패
|
||||
|
||||
네 경로 가운데 실제 관측으로 직접 닫힌 것은 두 부분이다. 첫째, 기존 `--cloud-init` 연결에서는 기대한 seed 동작을 얻지 못했고 최종 virtio seed에서는 `DataSourceNoCloud [seed=/dev/vdb]`가 확인됐다. 둘째, cloud-init 22.4.2 schema 검사기는 `sudo` 리스트 표기를 실제로 거부했다. 임의의 YAML parsing failure, `vol-upload` 누락, network autostart 비활성은 이 실험대에서 같은 SSH 증상으로 재현한 원문이 없으므로 **진단 후보**로만 남긴다.
|
||||
네 경로 가운데 실제 관측으로 직접 닫힌 것은 두 부분이다. 첫째, 기존 `--cloud-init` 연결에서는 기대한 seed 동작을 얻지 못했고 최종 virtio seed에서는 `DataSourceNoCloud [seed=/dev/vdb]`가 확인됐다. 둘째, cloud-init 22.4.2 schema 검사기는 `sudo` 리스트 표기를 실제로 거부했다. 임의의 YAML parsing failure, `vol-upload` 누락, network autostart 비활성은 이 실험대에서 같은 SSH 증상으로 재현한 기록이 없으므로 진단 후보로만 남긴다.
|
||||
|
||||
후속 원문도 남겼다. `14-cloudinit-schema-check.txt`에는 cloud-init 22.4.2가 `sudo` 리스트 표기를 실제로 거부한 출력이 있다. `15-k3s-precheck.txt`의 `Host key verification failed.`는 2026-09-17 재구축 중 나온 별도 SSH 실패라 원래 사건의 `Permission denied (publickey)`를 재현한 것은 아니다. 원래 `Permission denied (publickey)`, `cloud-init status: done`, 약 50초, `virsh screenshot` 화면은 아직 별도 raw 파일이 없고 당시 본문 기록만 남아 있다.
|
||||
|
||||
이 Case의 과거 실패 조합 전체를 그대로 다시 만드는 재현은 하지 않았다. 다만 2026-09-21에는 worker 두 대를 실제로 철거하고 현재 Setup의 qcow2·seed ISO·cloud-init 경로로 다시 만들어 `cloud-init status: done`과 SSH, 고정 IP, k3s 재합류까지 확인했다. 따라서 **현재 정상 생성 경로는 재검증됐고**, 과거 실패 후보 각각을 일부러 다시 유발한 것은 아니다.
|
||||
과거에 의심했던 실패 조건을 하나씩 다시 만들어 보지는 않았다. 대신 2026-09-21에는 worker 두 대를 실제로 철거한 뒤 현재 문서의 qcow2, seed ISO, cloud-init 절차로 다시 생성했고 `cloud-init status: done`, SSH 접속, 고정 IP, k3s 재합류까지 확인했다. 현재 생성 절차가 동작한다는 것은 확인했지만, 과거의 각 실패 조건을 개별적으로 재현한 것은 아니다.
|
||||
|
||||
<!-- body:end -->
|
||||
|
||||
+41
-44
@@ -1,7 +1,7 @@
|
||||
---
|
||||
kind: CASE
|
||||
slug: renewal-succeeded-while-the-old-certificate-kept-serving
|
||||
title: 갱신은 매번 SUCCESS 였고 옛 인증서가 계속 나갔다 — 2305초와 1~2초
|
||||
title: 인증서 갱신 후 nginx가 기존 인증서를 계속 제공한 문제
|
||||
topic: build-completion-judgment
|
||||
topicName: 끝났다는 판정
|
||||
project: virtualization
|
||||
@@ -13,50 +13,47 @@ source:
|
||||
- final/document.md#194-이-부에서-파생될-open-question
|
||||
---
|
||||
|
||||
# 갱신은 매번 SUCCESS 였고 옛 인증서가 계속 나갔다 — 2305초와 1~2초
|
||||
# 인증서 갱신 후 nginx가 기존 인증서를 계속 제공한 문제
|
||||
|
||||
과거 물리 호스트 배치에서는 갱신이 SUCCESS로 끝나도 nginx가 옛 인증서를 계속 내보냈다. 당시 `certbot-renew.service`에 reload 훅이 없어 갱신에서 서빙까지 2305초 걸렸고, deploy 훅을 두니 1~2초였다. **현재 2026-09-21 edge Debian 12 배치는 `certbot.timer → certbot.service`를 쓴다.** 이 글의 2305초·1~2초는 과거 배치의 측정값으로 남긴다.
|
||||
과거 물리 호스트에서 certbot 갱신은 정상 종료됐지만 nginx가 제공하는 인증서는 바뀌지 않았다. 당시 `certbot-renew.service`에는 nginx reload를 실행하는 훅이 없었고, 인증서 파일이 갱신된 뒤 실제 서비스에 반영되기까지 2305초가 걸렸다. deploy 훅을 추가한 뒤 같은 구간은 1~2초로 줄었다. 현재 Edge VM은 Debian 12의 `certbot.timer → certbot.service`를 사용하므로, 이 수치는 당시 물리 호스트 배치에서 측정한 값으로 구분한다.
|
||||
|
||||
## certbot은 성공했는데 서버 인증서는 그대로였다
|
||||
## 인증서 파일은 갱신됐지만 nginx에는 바로 반영되지 않았다
|
||||
|
||||
인증서 갱신은 매번 성공으로 끝나는데 서버가 내보내는 인증서는 옛것이었다.
|
||||
당시 상태를 나눠 보면 certbot과 nginx가 서로 다른 시점의 인증서를 보고 있었다.
|
||||
|
||||
certbot-renew.timer : 정상
|
||||
certbot-renew.service 의 결과 : SUCCESS
|
||||
유닛의 ExecStartPost 또는 --deploy-hook : x
|
||||
nginx 가 새 인증서를 읽었나 : x
|
||||
갱신에서 서빙까지 : 2305초 (38분 25초)
|
||||
무엇이 reload 했나 : 사람이 직접
|
||||
| 확인 항목 | 당시 결과 |
|
||||
|---|---|
|
||||
| `certbot-renew.timer` | 정상 동작 |
|
||||
| `certbot-renew.service` | `SUCCESS` |
|
||||
| `ExecStartPost` 또는 `--deploy-hook` | 없음 |
|
||||
| nginx reload | 자동으로 실행되지 않음 |
|
||||
| 갱신 후 서비스 반영까지 | 2305초(38분 25초) |
|
||||
| 실제 reload | 사람이 직접 실행 |
|
||||
|
||||
발현하는 날의 증상은 인증서 만료이고, 그날에도 로그에는 SUCCESS 라고 적혀 있다.
|
||||
certbot의 성공 여부만 확인하면 인증서 파일이 갱신됐다는 것까지만 알 수 있었다. nginx가 새 인증서를 읽었는지는 별도로 확인해야 했다.
|
||||
|
||||
## 갱신 성공과 nginx reload는 별도 단계였다
|
||||
|
||||
certbot-renew.service 는 /usr/bin/certbot -q renew 한 줄이고 인증서를 새로 받는 데까지만 책임진다. nginx 는 인증서를 기동 시점에 읽어 메모리에 들고 있고 certbot 은 live/ 심볼릭 링크만 갈아 끼우므로, 경로는 그대로이고 내용만 바뀌어 nginx 는 바뀐 줄 모른다.
|
||||
당시 `certbot-renew.service`는 `/usr/bin/certbot -q renew`만 실행했다. certbot은 `live/` 아래의 심볼릭 링크를 새 인증서 파일로 갱신하지만, nginx는 기동하거나 reload할 때 인증서 파일을 읽는다. 따라서 certbot이 성공해도 nginx를 reload하지 않으면 nginx는 기존 인증서를 계속 제공한다.
|
||||
|
||||
훅도 사람도 없으면 다음 nginx 재시작까지, 사실상 무기한으로 옛 인증서가 나간다.
|
||||
이를 해결하기 위해 `/etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh`에서 `nginx -t && nginx -s reload`를 실행하도록 했다. deploy 훅 파일에는 실행 권한이 필요하며, `post/` 대신 `deploy/`를 사용해 실제 갱신이 발생했을 때만 reload하도록 했다. 훅은 호스트를 다시 구성할 때 누락되지 않도록 저장소에서 관리했다.
|
||||
|
||||
해결 : /etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh 에 nginx -t && nginx -s reload 를 두고 chmod +x 를 준다
|
||||
실행 권한이 없으면 : certbot 이 조용히 건너뛴다
|
||||
post/ 가 아니라 deploy/ 인 까닭 : post/ 는 갱신이 없어도 매번 돌아 하루 두 번 워커를 갈아치운다
|
||||
훅을 저장소에 두는 까닭 : 호스트에만 두었을 때는 호스트를 초기화하면 아무 오류 없이 사라졌다
|
||||
판정 : 로그 문구가 아니라 강제 갱신 전후의 nginx 워커 PID 로 한다
|
||||
적용 여부는 certbot 로그만 보지 않고 강제 갱신 전후의 nginx worker PID로 확인했다. reload 중 새 연결 8856건은 모두 200으로 응답했고 p95는 205.7ms와 204.3ms로 측정됐다.
|
||||
|
||||
훅을 넣어도 안전했다. reload 는 무중단이었고 새 연결 8856건이 전부 200, p95 는 205.7ms 대 204.3ms 로 변화가 없었다.
|
||||
## 과거 측정 배치와 현재 Edge VM 배치
|
||||
|
||||
## 과거 측정 배치와 현재 edge 배치
|
||||
|
||||
엣지 게스트 : kc-lab-edge, 192.168.122.10, Debian 12
|
||||
nginx : nginx/1.22.1
|
||||
certbot 플러그인 : dns-cloudflare
|
||||
발급 대상 : -d hyeonworks.com -d '*.hyeonworks.com'
|
||||
lineage 디렉터리 : /etc/letsencrypt/live/auth.hyeonworks.com/ (2026-09-17 현재 관측)
|
||||
nginx 가 읽는 파일 : fullchain.pem · privkey.pem
|
||||
과거 측정 배치의 타이머 : `certbot-renew.timer → certbot-renew.service`
|
||||
현재 edge Debian 12 : `certbot.timer → certbot.service`
|
||||
인증서 유효기간 : 오늘 + 90일
|
||||
2305초를 잴 때의 배치 : 훅이 물리 호스트에 있었다
|
||||
지금의 배치 : certbot · 인증서 · 갱신 타이머 · deploy 훅이 전부 엣지 게스트에 있다
|
||||
| 항목 | 값 |
|
||||
|---|---|
|
||||
| Edge VM | kc-lab-edge, 192.168.122.10, Debian 12 |
|
||||
| nginx | nginx/1.22.1 |
|
||||
| certbot 플러그인 | dns-cloudflare |
|
||||
| 발급 대상 | `-d hyeonworks.com -d '*.hyeonworks.com'` |
|
||||
| 현재 lineage | `/etc/letsencrypt/live/auth.hyeonworks.com/` (2026-09-17 확인) |
|
||||
| nginx가 읽는 파일 | `fullchain.pem`, `privkey.pem` |
|
||||
| 과거 측정 당시 타이머 | `certbot-renew.timer → certbot-renew.service` |
|
||||
| 현재 Debian 12 타이머 | `certbot.timer → certbot.service` |
|
||||
| 2305초 측정 당시 배치 | deploy 훅이 물리 호스트에 있던 구성 |
|
||||
| 현재 배치 | certbot, 인증서, 타이머, deploy 훅을 Edge VM에 배치 |
|
||||
|
||||
## worker PID로 reload 여부를 확인하는 순서
|
||||
|
||||
@@ -92,9 +89,9 @@ ExecStart=/usr/bin/certbot -q renew --no-random-sleep-on-renew
|
||||
PrivateTmp=true
|
||||
```
|
||||
|
||||
유닛 이름과 `ExecStart` 옵션은 배포판/패키지 판에 따라 달라질 수 있다. 이 Case의 핵심은 이름이 아니라 **renew 성공과 nginx reload는 별도 상태 전이**라는 점이다.
|
||||
유닛 이름과 `ExecStart` 옵션은 배포판과 패키지 버전에 따라 달라질 수 있다. 여기서 확인할 것은 certbot 갱신 성공과 nginx reload가 별도 동작이라는 점이다.
|
||||
|
||||
`ExecStartPost` 도 `--deploy-hook` 도 없다. 이 유닛은 인증서를 새로 받는 데까지만 책임지고, 받은 것을 nginx 가 읽게 만드는 일은 아무도 하지 않는다. 배포판이 이렇게 준다는 것이 요점이라, 「기본값이니 괜찮겠지」가 이 결함이 사는 곳이다.
|
||||
현재 확인한 `certbot.service`에는 `ExecStartPost`나 `--deploy-hook`이 없다. 따라서 이 유닛은 인증서 갱신까지만 수행하고 nginx reload는 실행하지 않는다.
|
||||
|
||||
그래서 이 글의 훅이 모든 배포판에 필요하지는 않다. 위 유닛에 `ExecStartPost` 나 `--deploy-hook` 이 이미 적혀 있는 배포판이라면 훅을 새로 넣을 것이 아니라 거기 적힌 명령이 nginx 를 reload 하는지만 본다.
|
||||
|
||||
@@ -102,11 +99,11 @@ PrivateTmp=true
|
||||
|
||||
nginx 는 `ssl_certificate` 에 적힌 파일을 기동과 reload 시점에 읽어 메모리에 들고 있고, certbot 은 `live/` 아래의 심볼릭 링크를 새 파일로 갈아 끼운다. 설정에 적힌 경로는 한 글자도 바뀌지 않고 그 경로가 가리키는 파일만 바뀌므로, nginx 쪽에서는 다시 읽을 계기가 생기지 않는다. 갱신이 끝난 뒤에 nginx 로 reload 를 걸어 주는 것이 없으면 옛 인증서가 계속 나간다.
|
||||
|
||||
## 88일 동안 이 결함이 보이지 않는다
|
||||
## 자동 갱신 상태만 보면 문제를 늦게 발견할 수 있다
|
||||
|
||||
타이머는 정상이고 갱신은 매번 `SUCCESS` 로 끝난다. 만료 30일 전까지는 갱신 자체를 하지 않으므로 88일 동안 발현할 기회가 없다. 발현하는 날의 증상은 인증서 만료이고, 그날에도 로그에는 `SUCCESS` 라고 적혀 있다.
|
||||
타이머가 정상이고 certbot 실행 결과가 `SUCCESS`여도 nginx reload 여부는 별개다. 인증서 갱신이 실제로 발생하지 않는 기간에는 이 차이가 드러나지 않을 수 있으므로, 타이머 상태만으로 서비스 중인 인증서까지 정상이라고 판단하지 않는다.
|
||||
|
||||
훅을 저장소에 두는 까닭도 여기에 있다. 호스트에만 두었을 때는 호스트를 초기화하면 아무 오류 없이 사라졌고, 사라진 것도 갱신이 실제로 일어나는 날까지는 드러나지 않는다.
|
||||
deploy 훅을 저장소에서 관리한 것도 같은 이유다. 호스트에만 파일을 두면 재구성 과정에서 빠질 수 있고, 다음 갱신 전까지 누락을 발견하지 못할 수 있다.
|
||||
|
||||
## 훅 두 줄과 실행 권한
|
||||
|
||||
@@ -120,7 +117,7 @@ nginx -t && nginx -s reload
|
||||
sudo chmod +x /etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh
|
||||
```
|
||||
|
||||
실행 권한이 없으면 certbot 이 조용히 건너뛴다. `post/` 가 아니라 `deploy/` 에 넣는 것은 `post/` 가 갱신이 없어도 매번 돌아 하루 두 번 워커를 갈아치우기 때문이다.
|
||||
deploy 훅 파일에 실행 권한이 없으면 certbot이 해당 스크립트를 실행하지 않는다. `post/` 대신 `deploy/`를 사용한 이유는 실제 인증서 갱신이 있을 때만 nginx를 reload하기 위해서다.
|
||||
|
||||
이 실험대에서 잰 차이는 이렇다.
|
||||
|
||||
@@ -129,15 +126,15 @@ sudo chmod +x /etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh
|
||||
| 갱신 → 서빙 | 2305초 (38분 25초) | 1~2초 |
|
||||
| 무엇이 reload 했나 | 사람이 직접 | certbot deploy 훅 |
|
||||
|
||||
훅도 사람도 없었다면 다음 nginx 재시작까지, 사실상 무기한이다.
|
||||
deploy 훅도 수동 reload도 없다면 nginx는 다음 reload 또는 재시작 전까지 기존 인증서를 계속 사용한다.
|
||||
|
||||
## 판정은 로그 문구가 아니라 워커 PID 로 한다
|
||||
## nginx reload 여부는 worker PID로 확인했다
|
||||
|
||||
```bash
|
||||
sudo certbot renew --dry-run
|
||||
```
|
||||
|
||||
dry-run 은 훅이 호출되는지까지만 말해 준다. 호출된 훅이 nginx 를 정말 갈아 끼웠는지는 따로 본다.
|
||||
dry-run으로는 deploy 훅이 호출되는지 확인할 수 있다. 실제 nginx reload 여부는 별도로 확인했다.
|
||||
|
||||
순서가 dry-run 먼저인 것은 뒤엣것이 상태를 바꾸기 때문이다. `--force-renewal` 은 인증서를 실제로 새로 받아 발급 한도(주당 중복 5장)를 깎으므로, 진짜 판정이 필요할 때 한 번만 쓴다.
|
||||
|
||||
@@ -151,7 +148,7 @@ sudo certbot renew --force-renewal
|
||||
ps -eo pid,lstart,args | grep 'nginx: worker' | grep -v grep
|
||||
```
|
||||
|
||||
reload 는 마스터를 그대로 두고 워커만 갈아 끼우므로, 전후로 워커 PID 가 바뀌면 새 설정이 적용됐다. `lstart` 를 같이 뽑는 것은 PID 가 우연히 재사용됐을 때를 가르기 위해서다.
|
||||
nginx reload에서는 master 프로세스가 유지되고 worker 프로세스가 교체되므로, 전후의 worker PID와 시작 시각을 비교해 reload 여부를 확인했다. `lstart`를 함께 기록한 것은 PID 재사용 가능성을 구분하기 위해서다.
|
||||
|
||||
certbot 이 `Hook 'deploy-hook' ran with error output` 이라고 찍는데 실패가 아니다. nginx 의 `types_hash` 경고가 stderr 로 나갔을 뿐이고 내용은 `test is successful` 과 `signal process started` 다. 로그에서 `error` 를 grep 하는 감시를 걸면 성공한 훅을 실패로 오독한다.
|
||||
|
||||
@@ -174,7 +171,7 @@ timedatectl show -p NTP -p NTPSynchronized
|
||||
|
||||
2305초는 훅이 물리 호스트에만 있던 시절의 값이다. 지금은 certbot 과 인증서와 갱신 타이머와 deploy 훅이 전부 엣지 게스트에 있고, 그 배치에서 다시 재면 같은 수가 나오는지는 재지 않았다. 그래서 이 글의 2305초는 훅이 없으면 이만큼 벌어진다는 한 번의 측정이고 지금 배치의 값이 아니다. 1~2초 쪽도 같은 시기에 잰 값이다.
|
||||
|
||||
당시 측정의 raw 출력 파일은 별도로 보존하지 않았다. 2305초, 8856건, p95 두 값, 845361바이트, 106초와 worker PID 전후 비교는 당시 본문 기록에만 남아 있다. 따라서 이 수치는 현재 raw 출력으로 다시 대조할 수 있는 값이 아니라 **당시 기록 범위의 historical measurement**로 읽는다.
|
||||
당시 측정의 원본 출력 파일은 별도로 보존하지 않았다. 2305초, 8856건, 두 p95 값, 845361바이트, 106초의 시계 차이와 worker PID 비교는 당시 본문 기록에만 남아 있다. 따라서 이 수치는 현재 원본 출력과 다시 대조할 수 없는 당시 측정값으로 구분한다.
|
||||
|
||||
88일이라는 잠복 기간은 만료 30일 전에야 갱신을 시작한다는 동작에서 끌어낸 것이지, 한 주기를 실제로 돌려 본 값이 아니다. 훅을 뺀 채 만료일까지 가 본 기록은 없고 그런 기록이 있을 까닭도 없다.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user