Files

10 KiB

kind, slug, title, topic, topicName, project, status, sourceRevision, evidence, source
kind slug title topic topicName project status sourceRevision evidence source
CASE an-empty-token-installed-the-agent-anyway k3s agent 설치 후 두 번째 노드가 등록되지 않은 원인 build-completion-judgment 끝났다는 판정 virtualization 게시 전 import-head 9465582b5d1630eb4ae7c4e078021486919bf6b6 · uncommitted-working-tree snapshot
../../../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
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 를 찾는다.

토큰이 지나는 길과 명령을 치는 셸

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의 셸 변수에 담아 설치 명령으로 넘겼다. 문제가 생긴 지점도 이 변수 전달 과정이었다. 현재 설치 절차는 토큰 파일을 사용하므로 아래 명령은 당시 문제를 설명하기 위한 예시다.

TOKEN=$(ssh kc-lab-1 'sudo cat /var/lib/rancher/k3s/server/node-token')
echo "${#TOKEN} 자"        # 값이 아니라 길이만 확인한다

비밀은 길이나 존재 여부만 확인하고 값을 찍지 않는다. 가이드가 먼저 정한 표기 규약이고, 값을 찍으면 터미널 스크롤백과 화면 공유에 그대로 남기 때문이다.

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 도 없다.

[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 로 나오는 것이다.

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를 각각 나눠 어느 단계에서 실패했는지 확인할 수 있게 했다.

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 결과를 함께 보존해 실패 지점을 확인한다.

가드 한 줄이 실제로 빈 토큰을 잡아 본 기록도 없다.