154 lines
10 KiB
Markdown
154 lines
10 KiB
Markdown
---
|
|
kind: CASE
|
|
slug: an-empty-token-installed-the-agent-anyway
|
|
title: k3s agent 설치 후 두 번째 노드가 등록되지 않은 원인
|
|
topic: build-completion-judgment
|
|
topicName: 끝났다는 판정
|
|
project: virtualization
|
|
status: 게시 전
|
|
sourceRevision: import-head 9465582b5d1630eb4ae7c4e078021486919bf6b6 · uncommitted-working-tree snapshot
|
|
evidence:
|
|
- ../../../final/evidence/raw/lab-state-before-rebuild/15-k3s-precheck.txt
|
|
- ../../../final/evidence/raw/lab-state-before-rebuild/21-k3s-token.txt
|
|
- ../../../final/evidence/raw/lab-state-before-rebuild/22-k3s-agent-install.txt
|
|
source:
|
|
- final/document.md#185-가이드-묶음이-스스로-정한-규약
|
|
- final/document.md#188-단계-02-k3s-server-와-agent
|
|
- final/document.md#184-이-부의-출처와-범위
|
|
---
|
|
|
|
# k3s agent 설치 후 두 번째 노드가 등록되지 않은 원인
|
|
|
|
`kc-lab-2`에 k3s agent를 설치했을 때 설치 스크립트는 오류 없이 끝났지만, `kubectl get nodes`에는 `kc-lab-1`만 보였다. `k3s-agent` 로그를 확인하니 `--token is required`가 반복되고 있었고, agent에 전달한 토큰 변수가 비어 있던 것이 원인이었다. 현재 Setup에서는 토큰을 파일로 전달해 같은 문제가 생기지 않도록 절차를 바꿨다.
|
|
|
|
## 설치 스크립트는 끝났지만 노드가 등록되지 않았다
|
|
|
|
agent 설치 스크립트는 오류 없이 종료됐다. 하지만 두 노드가 `Ready` 상태로 보여야 하는 `kubectl get nodes`에는 `kc-lab-1`만 나왔다.
|
|
|
|
| 확인 항목 | 결과 |
|
|
|---|---|
|
|
| agent 설치 스크립트 | 오류 없이 종료 |
|
|
| `kubectl get nodes` | `kc-lab-1`만 표시 |
|
|
| `k3s-agent` 서비스 | 5초 간격으로 재시작 |
|
|
| `journalctl -u k3s-agent` | `level=fatal msg="Error: --token is required"` |
|
|
|
|
설치 스크립트가 끝났다는 사실만으로는 agent가 정상적으로 클러스터에 등록됐다고 판단할 수 없었다.
|
|
|
|
## 토큰 변수에 빈 문자열이 들어간 원인
|
|
|
|
토큰을 읽는 `ssh` 명령을 lab host가 아니라 게스트 안에서 실행했고, 해당 명령은 `Host key verification failed.`로 실패했다. 이 명령을 `TOKEN=$(...)` 형태로 실행하면 표준 출력만 변수에 들어가기 때문에 `TOKEN`에는 빈 문자열이 남는다.
|
|
|
|
그 상태로 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에서는 토큰을 파일로 받아 `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:<비밀번호> |
|
|
|
|
## 같은 실패를 다시 만들려면
|
|
|
|
1. lab host 에서 게스트 세 대를 세우고 kc-lab-1 에 k3s server 를 깐다.
|
|
2. lab host 에서 ssh kc-lab-1 로 게스트에 로그인한다.
|
|
3. 게스트 프롬프트에서 TOKEN=$(ssh kc-lab-1 'sudo cat /var/lib/rancher/k3s/server/node-token') 을 친다.
|
|
4. echo "${#TOKEN} 자" 가 0 을 낸다.
|
|
5. 같은 셸에서 agent 설치 명령에 --token "$TOKEN" 을 넘긴다. 설치 출력은 오류 없이 끝난다.
|
|
6. lab host 로 돌아와 kubectl get nodes 를 친다. 노드가 하나뿐이다.
|
|
7. ssh kc-lab-2 'journalctl -u k3s-agent' 에서 --token is required 를 찾는다.
|
|
|
|
|
|
<!-- body:start -->
|
|
|
|
## 토큰이 지나는 길과 명령을 치는 셸
|
|
|
|
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의 셸 변수에 담아 설치 명령으로 넘겼다. 문제가 생긴 지점도 이 변수 전달 과정이었다. 현재 설치 절차는 토큰 파일을 사용하므로 아래 명령은 당시 문제를 설명하기 위한 예시다.
|
|
|
|
```bash
|
|
TOKEN=$(ssh kc-lab-1 'sudo cat /var/lib/rancher/k3s/server/node-token')
|
|
echo "${#TOKEN} 자" # 값이 아니라 길이만 확인한다
|
|
```
|
|
|
|
비밀은 길이나 존재 여부만 확인하고 값을 찍지 않는다. 가이드가 먼저 정한 표기 규약이고, 값을 찍으면 터미널 스크롤백과 화면 공유에 그대로 남기 때문이다.
|
|
|
|
```bash
|
|
ssh kc-lab-2 "curl -sfL https://get.k3s.io | sudo sh -s - agent \
|
|
--server https://192.168.122.11:6443 \
|
|
--token '$TOKEN' \
|
|
--node-ip 192.168.122.12"
|
|
```
|
|
|
|
## 게스트에서 실행한 ssh 명령은 토큰을 가져오지 못했다
|
|
|
|
토큰을 꺼내려고 게스트에 먼저 들어가면 같은 명령이 다르게 끝난다. 게스트에는 lab host 의 개인키도 `~/.ssh/config` 도 없다.
|
|
|
|
```bash
|
|
[kc-lab-1] $ ssh kc-lab-1 'sudo cat /var/lib/rancher/k3s/server/node-token'
|
|
Host key verification failed.
|
|
```
|
|
|
|
오류 메시지는 표준 오류로 출력된다. 그런데 같은 명령을 `TOKEN=$(...)`로 감싸면 표준 출력만 변수에 들어가므로 `TOKEN`에는 빈 문자열이 남는다. 뒤이어 실행한 설치 명령은 결국 `--token ''`을 전달한 것과 같았다.
|
|
|
|
## 설치 스크립트 종료와 agent 기동 성공은 다른 상태였다
|
|
|
|
빈 토큰을 넘겨도 설치 스크립트는 바이너리 다운로드와 서비스 파일 생성, `enable` 단계까지 진행한다. 이 때문에 스크립트가 종료된 화면만 보면 설치가 끝난 것처럼 보인다. 하지만 실제 agent 프로세스는 `--token is required` 오류로 종료됐고, `Restart=always` 설정 때문에 5초 간격으로 재시작했다. 실제 실패 원인은 `journalctl -u k3s-agent`에서 확인할 수 있었다.
|
|
|
|
k3s server 와 agent 를 세우는 단계가 끝났다는 판정은 lab host 에서 노드 목록을 쳐서 두 노드가 `Ready` 로 나오는 것이다.
|
|
|
|
```bash
|
|
kubectl get nodes -o wide
|
|
```
|
|
|
|
```
|
|
NAME STATUS ROLES AGE VERSION INTERNAL-IP
|
|
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는 정상적으로 기동하지 못하므로 이 목록에 두 번째 노드가 나타나지 않는다.
|
|
|
|
## 토큰 값은 출력하지 않고 비어 있는지만 확인한다
|
|
|
|
이 사건에서 필요한 확인은 토큰 내용을 눈으로 대조하는 일이 아니었다. 설치를 시작하기 전에 값이 비어 있는지만 알면 됐다. 당시 기록에는 토큰 길이가 108자로 남아 있지만, 그 숫자는 한 번의 실행에서 나온 값이지 성공 조건이 아니다.
|
|
|
|
과거 절차에서는 셸 변수의 길이를 확인했다. 현재 설치 절차에서는 토큰을 파일로 받은 뒤 `wc -c`로 파일이 비어 있지 않은지 확인하고 `--token-file`로 넘긴다. 당시 기록에 없는 별도 셸 가드 명령은 추가하지 않았다.
|
|
|
|
길이가 `0` 으로 나올 수 있는 길은 하나로 한정되지 않는다. 게스트 안에서 다시 `ssh kc-lab-1`을 불러 실패할 수도 있고, server가 아직 token 파일을 만들지 못했을 수도 있고, 새 셸을 열면서 변수 자체가 사라졌을 수도 있다. 중요한 건 원인을 추측하기 전에 설치 직전의 입력이 비어 있는지부터 확인하는 것이다.
|
|
|
|
## 현재 설치 절차는 토큰 파일을 사용한다
|
|
|
|
셸 변수는 새 셸로 넘어가면 값이 사라질 수 있고, 토큰을 명령행 인자로 직접 넘기면 프로세스 인자에 값이 노출될 수 있다. 그래서 현재 설치 절차는 토큰을 파일로 전달한다. 아래 파이프 방식은 문제를 확인한 뒤 사용했던 방식이고, 현재 문서에서는 `scp`, `chmod`, `wc -c`를 각각 나눠 어느 단계에서 실패했는지 확인할 수 있게 했다.
|
|
|
|
```bash
|
|
ssh kc-lab-1 'sudo cat /var/lib/rancher/k3s/server/node-token' \
|
|
| ssh kc-lab-2 'sudo tee /tmp/token >/dev/null'
|
|
ssh kc-lab-2 "curl -sfL https://get.k3s.io | sudo sh -s - agent \
|
|
--server https://192.168.122.11:6443 --token-file /tmp/token \
|
|
--node-ip 192.168.122.12; rm -f /tmp/token"
|
|
```
|
|
|
|
이 방식은 토큰 값을 명령행 인자로 직접 넣지 않고 셸 변수에도 의존하지 않는다. 현재 설치 절차는 여기에 파일 존재 여부와 길이 확인, 영구 경로 이동을 추가해 재부팅 뒤에도 agent가 같은 토큰 파일을 읽도록 구성한다.
|
|
|
|
## 확인하지 못한 범위
|
|
|
|
당시 `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` 결과를 함께 보존해 실패 지점을 확인한다.
|
|
|
|
가드 한 줄이 실제로 빈 토큰을 잡아 본 기록도 없다.
|
|
|
|
<!-- body:end -->
|