Files

32 KiB

id, kind, slug, title, topic, topicName, project, status, studio, pinnedVersions, source, sourceRevision, evidence
id kind slug title topic topicName project status studio pinnedVersions source sourceRevision evidence
5e629c2f-e653-4dd9-b1c9-1fe6b2bb181d SETUP install-k3s-server-and-agent k3s server 와 agent 를 게스트 두 대에 깔고 lab host 에서 kubectl 로 본다 lab-environment-build 실험대 환경 구성 virtualization 게시 전 https://hyeonworks.com/studio/documents/5e629c2f-e653-4dd9-b1c9-1fe6b2bb181d/edit
name version
k3s v1.36.4+k3s1
name version
Debian GNU/Linux 12 (bookworm)
final/document.md#188-단계-02-k3s-server-와-agent
final/document.md#185-가이드-묶음이-스스로-정한-규약
final/document.md#184-이-부의-출처와-범위
import-head 9465582b5d1630eb4ae7c4e078021486919bf6b6 · uncommitted-working-tree snapshot
../../../final/evidence/raw/lab-state-before-rebuild/22-k3s-agent-install.txt
../../../final/evidence/raw/lab-state-before-rebuild/23-k3s-cluster-verify.txt

k3s server 와 agent 를 게스트 두 대에 깔고 lab host 에서 kubectl 로 본다

kc-lab-1 에 k3s server 를 kc-lab-2 에 agent 를 깔고 lab host 에서 kubectl get nodes 로 두 노드를 보는 절차다. 설치 명령은 각각 한 줄이고, kubeconfig 를 가져오는 것과 토큰을 옮기는 것이 그 앞뒤를 채운다.

lab host와 두 worker에서 치는 명령을 구분한다

기본은 [lab host] 다. 게스트에 로그인해서 치지 않는다.

까닭이 셋이다. 게스트에는 lab host 의 개인키도 ~/.ssh/config 도 없어서 게스트 안에서 ssh kc-lab-1 을 치면 Host key verification failed. 로 끝난다. 그 실패를 셸 변수 대입으로 감싸면 오류는 화면으로 새고 변수에는 빈 문자열이 담기는데, 셸은 아무 불평도 하지 않는다. 그 결과 토큰 변수가 비어 있었고, 설치 스크립트는 종료됐지만 실제 agent 프로세스는 --token is required 오류로 시작하지 못했다.

셸을 하나만 쓰면 이 문제가 통째로 없어진다. 예외가 둘이다.

번호 무엇 어디서
1 server 설치와 그 확인 [lab host] — 확인 한 번만 게스트 쪽 kubectl 로 돈다
2 · 3 kubeconfig 와 토큰 [lab host]
4 agent 설치 토큰 파일을 옮긴 뒤 [kc-lab-2] 안에서
5 워크스테이션에서 쓰기 [워크스테이션]

편집기를 여는 곳은 둘이다. 2번에서 kubeconfig 의 server: 줄 하나를 고치고, 4번에서 agent 유닛의 토큰 경로 한 줄을 고친다.

kc-lab-1은 server, kc-lab-2는 agent로 붙인다

가이드 02 의 「이 단계가 끝나면」은 두 줄이다.

lab host 에서 kubectl get nodes 를 치면 두 노드가 Ready 로 나온다. sudo 도 ssh 도 붙이지 않는다.

무엇 kc-lab-1 kc-lab-2
역할 server (control-plane) agent
유닛 k3s.service k3s-agent.service
--node-ip 192.168.122.11 192.168.122.12
판 번호 v1.36.4+k3s1 v1.36.4+k3s1
kubeconfig /etc/rancher/k3s/k3s.yaml 없다
ROLES 열 control-plane <none> — 라벨이 없다는 뜻이다

k3s 가 따로 설치하지 않아도 딸려 오는 것이 다섯이다. 뒤 단계에서 「왜 80 포트가 이미 잡혀 있지」와 「왜 PVC 가 이 노드에만 묶이지」의 답이 전부 이 목록에 있다.

이름 무엇
Traefik 인그레스 컨트롤러. :80 을 듣는다
servicelb (klipper-lb) LoadBalancer 타입을 호스트 포트로 매핑
local-path 기본 StorageClass. 노드 로컬 디스크
flannel 파드 네트워크 (VXLAN)
kube-router NetworkPolicy 집행

재설치 전에 토큰과 기존 k3s 상태를 확인한다

전제는 한 줄이다 — 앞 단계가 끝나 lab host 에서 두 게스트에 SSH 가 붙는다.

k3s 전체 제거 절차는 아직 이 실험대에서 실행해 검증하지 않았다. 설치 스크립트가 k3s-uninstall.sh와 k3s-agent-uninstall.sh를 설치하지만, 이 두 스크립트를 사용해 server와 agent를 제거한 뒤 다시 구성하는 경로는 확인하지 않았다.

어디서 무엇을 적었나
노드 IP 가 다른 대역으로 잡혔을 때 그때 고치는 것보다 지금 재설치가 싸다
CA 가 바뀌었을 때 2번의 kubeconfig 복사를 다시 한다

CA(Certificate Authority)는 인증서에 서명해 주는 쪽을 말한다. k3s 를 다시 깔면 그것이 바뀌므로 lab host 의 kubeconfig 도 같이 못 쓰게 된다. 걷어내는 명령은 여기에 적지 않는다.

두 VM의 SSH·주소·시간부터 확인한다

가이드 02 에도 바꾸기 전 상태를 보는 단계가 없다. 앞 단계가 남긴 확인을 그대로 다시 치는 것이 이 단계의 전제다.

두 게스트가 돌고 있는지, 그리고 SSH 가 대화 없이 통과하는지.

virsh list --all
ssh donghyeon@192.168.122.11 'hostname; cat /etc/os-release | head -1'

두 게스트가 running 인가, 그리고 SSH 가 비밀번호를 묻지 않고 호스트명을 찍는가.

ssh kc-lab-2 가 비밀번호를 물으면 3번의 토큰 전달과 4번의 설치가 전부 대화식으로 멈춘다. 여기서 걸러야 설치 도중에 멈추지 않는다.

server를 설치하고 agent를 join시킨다

1. server 를 깐다

목적 — kc-lab-1 을 control-plane 으로 세우고, 그 노드가 자기 주소를 192.168.122.11 로 알게 한다.

ssh kc-lab-1 "curl -sfL https://get.k3s.io | sudo env INSTALL_K3S_VERSION=v1.36.4+k3s1 sh -s - server --node-ip 192.168.122.11"
ssh kc-lab-1 'sudo systemctl is-active k3s; sudo kubectl get nodes'

정상이면 유닛이 active 이고 get nodes 에 kc-lab-1 한 줄이 Ready 로 있다. 설치 직후 30초 남짓은 NotReady 이거나 아예 목록이 비어 있는 쪽이 정상이다 — 파드 네트워크가 아직 안 올라온 시간이라 한 번 더 친다.

--node-ip 를 준다. 게스트에 인터페이스가 여럿이면 k3s 가 엉뚱한 것을 고를 수 있고, 그러면 두 노드가 서로를 다른 주소로 알게 된다. 이때 Traefik 과 servicelb, local-path, flannel, kube-router 도 함께 선다. 이 가이드에서 kubectl 을 게스트 쪽에서 돌리는 일은 ② 한 번으로 끝난다. lab host 에는 아직 kubeconfig 가 없기 때문이고, 그것을 두는 일이 바로 2번이다.

실패하면 설치 출력만으로 판정하지 않는다. 유닛이 active 인데 get nodes 가 접속 오류를 내면 API 서버가 아직 기동 중이다. 유닛이 activating 에서 안 넘어가거나 failed 면 설치 자체가 실패한 것이니 로그를 본다.

ssh kc-lab-1 'sudo journalctl -u k3s -n 50 --no-pager'

2. kubeconfig 를 lab host 로 가져온다

목적 — lab host 에서 sudo 도 ssh 도 붙이지 않고 kubectl 을 치게 만든다. agent 노드에는 kubeconfig 가 없으므로 클러스터를 어디서 볼지 먼저 정해 둔다.

mkdir -p ~/.kube
ssh kc-lab-1 'sudo cat /etc/rancher/k3s/k3s.yaml' > ~/.kube/config
chmod 600 ~/.kube/config

이 파일은 클러스터 admin 자격증명이라 600 으로 둔다. sudo 는 cat 에만 걸리고 > 에는 걸리지 않는다 — 리다이렉션은 셸이 명령보다 먼저 현재 사용자 권한으로 처리한다. 그래서 출력 파일은 홈 아래에 둔다.

nano ~/.kube/config

server: 줄 하나만 고치고 나머지는 그대로 둔다.

server: https://192.168.122.11:6443
grep server: ~/.kube/config
kubectl get nodes

실제 확인한 결과

    server: https://192.168.122.11:6443
NAME       STATUS   ROLES           AGE   VERSION
kc-lab-1   Ready    control-plane   47m   v1.36.4+k3s1

아직 노드가 한 줄뿐인 쪽이 정상이다. agent 는 4번에서 붙인다.

세 줄이 다 필요하고 빠뜨렸을 때 깨지는 곳이 다르다.

줄 빠뜨리면
mkdir -p ~/.kube > 는 파일을 열 뿐 경로를 만들지 않는다. cat 이 시작되기도 전에 No such file or directory 로 끝난다
주소 고치기 k3s 가 쓴 https://127.0.0.1:6443 은 게스트 안에서만 맞는 주소라 lab host 에서는 자기 자신의 6443 을 두드린다
chmod 600 이 파일은 클러스터 admin 자격증명이다. 비밀번호 파일과 같은 급으로 다룬다

주소를 고쳐도 인증서 검증이 통과하는 것은 API 서버 인증서 SAN 에 두 주소가 다 들어 있기 때문이다. 5번의 SSH 터널이 127.0.0.1 로 붙을 수 있는 것도 같은 까닭이다.

ssh kc-lab-1 'sudo openssl x509 -in /var/lib/rancher/k3s/server/tls/serving-kube-apiserver.crt -noout -ext subjectAltName'

이 실험대는 ②와 ④를 치환 한 줄로 이어 붙였다.

ssh kc-lab-1 'sudo cat /etc/rancher/k3s/k3s.yaml' \
  | sed 's|127.0.0.1|192.168.122.11|' > ~/.kube/config

치환은 바꾼 줄도 나머지 줄도 보여 주지 않는다. kubeconfig 는 클러스터를 볼 때마다 다시 열게 되는 파일이라 한 번은 전체를 보는 편이 낫고, 나눈 형태는 이 실험대에서 치지 않았다.

실패하면 lab host 에서 connection refused 가 나면 ⑤ 의 grep 부터 친다. 127.0.0.1 이 그대로 보이면 ④ 에서 저장이 안 됐다. x509 오류는 파일 안의 CA 와 서버가 지금 쓰는 CA 가 어긋난 것이라, k3s 를 다시 깔았다면 이 복사도 다시 한다.

3. 토큰을 파일로 꺼내 길이만 본다

목적 — agent 가 클러스터에 들어갈 때 쓸 node-token 을 lab host 에 내려놓고, 값이 아니라 길이로 비어 있지 않은지 확인한다.

ssh kc-lab-1 'sudo cat /var/lib/rancher/k3s/server/node-token' > node-token
wc -c node-token

정상이면 세 자리 수와 파일 이름 한 줄. 이 실험대가 변수에 담아 잰 토큰은 108자였다. K10<해시>::server:<비밀번호> 형식이라 k3s 판올림에 따라 자릿수가 달라진다. 값 자체는 출력하지 않고 파일 크기가 0이 아닌지만 확인한다.

값을 화면에 찍지 않는 것은 터미널 스크롤백과 셸 히스토리에 그대로 남기 때문이다. 그리고 이 확인이 4번으로 빈 파일을 넘기는 실수를 여기서 끊는다. 현재 절차는 토큰을 셸 변수에 담지 않고 파일로 저장하므로, 예전처럼 셸이 바뀌어 변수가 사라지는 문제는 없다. 원격 ssh가 실패했다면 리다이렉션으로 빈 파일이 생길 수 있으므로 길이와 파일 존재를 함께 확인한다.

실패하면 wc -c 가 0 을 내면 원인이 셋 가운데 하나다.

0 인 까닭 확인
게스트 안에서 쳤다 — 가장 흔하다 프롬프트가 kc-lab-1 이면 exit 로 lab host 로 나온다
server 가 아직 안 떠서 파일이 없다 아래 한 줄로 파일 유무부터 본다
현재 디렉터리가 달라 node-token 파일을 못 찾는다 pwd 와 ls -l node-token 으로 파일 위치부터 확인한다
ssh kc-lab-1 'sudo ls -l /var/lib/rancher/k3s/server/node-token'

4. 토큰을 agent 노드로 옮기고 거기서 설치한다

목적 — kc-lab-2 를 agent 로 붙이고, 토큰이 명령줄과 히스토리에 남지 않게 파일로 넘긴다.

scp node-token kc-lab-2:~/node-token
rm node-token
ssh kc-lab-2
chmod 600 ~/node-token
curl -sfL https://get.k3s.io | sudo env INSTALL_K3S_VERSION=v1.36.4+k3s1 sh -s - agent \
  --server https://192.168.122.11:6443 \
  --token-file ~/node-token \
  --node-ip 192.168.122.12
sudo install -m 600 -o root -g root ~/node-token /etc/rancher/node-token
sudo ls -l /etc/rancher/node-token
sudo nano /etc/systemd/system/k3s-agent.service

⑧ ExecStart= 아래에서 '--token-file' 다음 줄의 경로를 /etc/rancher/node-token 으로 고친다. 고치고 나면 그 두 줄이 이렇게 보인다.

	'--token-file' \
	'/etc/rancher/node-token' \
sudo systemctl daemon-reload
sudo systemctl restart k3s-agent
rm ~/node-token

:::warning

⑥부터 ⑨ 까지를 건너뛰고 rm ~/node-token 만 치면 이 노드는 다시 못 뜬다. 설치 스크립트가 --token-file 에 준 경로를 유닛의 ExecStart 에 그대로 굽기 때문에, 파일이 사라지면 agent 가 영원히 그 파일을 기다린다. 2026-09-17 에 A-4 를 돌려 노드 전원을 뽑았다 다시 켜면서 그대로 겪었다 — VM 은 떴는데 노드가 NotReady 에서 안 돌아왔다.

:::

k3s[522]: level=info msg="Waiting for file \"/home/donghyeon/node-token\" to be created"
k3s-agent.service: Scheduled restart job, restart counter is at 1.

2026-09-17에는 토큰을 /etc/rancher/node-token 으로 옮기고 유닛을 그쪽으로 돌린 뒤 홈의 사본을 지웠다. agent 를 완전히 세웠다 다시 켠 뒤에도 active 였고 노드도 Ready 로 돌아왔다.

-rw------- 1 root root 109 /etc/rancher/node-token
	'--token-file' \
	'/etc/rancher/node-token' \
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는 치환할 패턴이 없어도 종료 코드 0으로 끝날 수 있고, 이 패턴에는 $HOME 이 들어 있어 설치할 때와 다른 계정으로 치면 아무 줄도 안 바뀐 채 ⑨ 가 이어서 돈다. 그러면 지금 떠 있는 노드는 멀쩡해 보이고 다음 재부팅에서야 Waiting for file 로 멎는다. 유닛을 열면 고칠 줄이 눈에 보이고, 고쳤는지도 저장하기 전에 눈으로 본다. 이 편집기 형태는 이 실험대에서 치지 않았다.

설치 스크립트는 sudo 아래 root 로 도니 홈의 600 파일도 읽는다. --token 대신 --token-file 을 쓰면 토큰이 명령줄에 안 들어가므로 프로세스 목록과 셸 히스토리에 남지 않고, 토큰을 꺼낸 셸과 같은 셸에서 쳐야 한다는 제약도 없어진다.

이 실험대는 두 줄로 했다. 아래는 당시 실행한 명령을 남긴 블록이고, 따라 하는 절차는 위 ①~⑪처럼 검증과 삭제를 분리한다.

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"

두 줄 안에 원격 셸 둘과 sudo 둘, 파이프 하나, 설치 스크립트 하나, 마지막 삭제 하나가 겹쳐 있다. 실패했을 때 어느 쪽이 실패했는지 갈리지 않아 위에서는 ① 부터 ⑪ 까지로 나눴다. 토큰이 /tmp/token 대신 자기 홈에 놓이고 sudo tee 대신 scp 와 chmod 600 이 그 파일을 만드는 것도 그래서 달라진다. 이 나눈 형태는 이 실험대에서 치지 않았다.

실패하면 agent 설치는 성공했는데 노드가 안 보이면 로그에 --token is required 가 있는지 본다. 토큰이 빈 값이었으면 설치 스크립트는 내려받기와 유닛 생성과 활성화까지 다 성공으로 찍고 끝나고, 유닛은 Restart=always 설정 때문에 약 5초 간격으로 다시 시작한다.

ssh kc-lab-2 'sudo journalctl -u k3s-agent -n 30 --no-pager'

5. 워크스테이션에서도 쓰려면 터널을 뚫는다

목적 — 개발 머신에서 같은 클러스터를 보게 한다. 이 단계를 건너뛰어도 클러스터는 선다.

ssh -N -L 6443:192.168.122.11:6443 test-server
ssh kc-lab-1 'sudo cat /etc/rancher/k3s/k3s.yaml' > kc-lab.yaml
chmod 600 kc-lab.yaml
mkdir -p ~/.kube
scp test-server:kc-lab.yaml ~/.kube/kc-lab.yaml
ssh test-server 'rm kc-lab.yaml'
chmod 600 ~/.kube/kc-lab.yaml
export KUBECONFIG=~/.kube/kc-lab.yaml
grep server: ~/.kube/kc-lab.yaml
kubectl get nodes

정상이면 server: 가 https://127.0.0.1:6443 이고, get nodes 가 4번과 같은 두 줄을 낸다. 터널 창을 닫으면 바로 멎는다.

여기서는 주소를 고치지 않는다. k3s 원본이 이미 https://127.0.0.1:6443 이고 터널 덕에 워크스테이션에서는 그 주소가 맞다. 2번에서 고쳤던 것은 lab host 에서 볼 때 127.0.0.1 이 lab host 자신을 가리키기 때문이었다. 같은 파일이라도 어느 기계에서 읽느냐에 따라 맞는 주소가 다르다.

이 실험대는 ②와 ③을 ssh 두 겹으로 겹쳐 한 줄에 넣었다.

ssh test-server "ssh kc-lab-1 'sudo cat /etc/rancher/k3s/k3s.yaml'" > ~/.kube/kc-lab.yaml

따옴표가 두 겹이라 어느 기계에서 어느 명령이 도는지가 한 줄에 묻힌다. 기계마다 한 명령이 되게 나눈 형태는 이 실험대에서 치지 않았다.

실패하면 타임아웃이면 ① 의 터널 창이 닫힌 것이고, connection refused이면 터널 자체는 열려 있지만 반대편 API 서버가 요청을 받지 못하는 상태다. 터널이 닫히면 kubectl 이 통째로 멎어 터널 상태와 클러스터 상태가 섞인다. 노드를 중단하고 다시 시작하는 실험은 lab host에서 실행한다.

kubeconfig와 systemd unit의 위치

kubeconfig 사본이 사는 곳은 둘이고, 같은 파일인데 주소가 다르다.

어디에 무엇
lab host ~/.kube/config — 600. server: 를 https://192.168.122.11:6443 으로 고친 사본
워크스테이션 ~/.kube/kc-lab.yaml — 원본 그대로(https://127.0.0.1:6443) + SSH 터널

유닛 이름도 노드마다 다르다.

노드 유닛
server k3s.service
agent k3s-agent.service

뒤의 실험에서 노드를 멈출 때 칠 이름이 이것이다. systemctl stop k3s 를 agent 노드에서 치면 아무 일도 일어나지 않고, 「주입했는데 증상이 없다」로 읽히게 된다. server 노드를 잃으면 kubectl 자체가 불통이 되고, agent 를 잃으면 kubectl 은 되지만 그 위의 워크로드가 사라진다.

두 노드가 Ready이고 지정한 IP를 쓰는지 확인한다

확인 ① 두 노드가 우리가 준 주소로 서 있는가

agent 가 클러스터에 들어왔는지, 그리고 제 주소로 들어왔는지.

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

-o wide 를 주는 까닭이 마지막 열이다. INTERNAL-IP 두 개가 1번과 4번에서 --node-ip 로 준 값과 같은가. 그다음이 STATUS 두 줄 Ready, 그다음이 ROLES 열이다. <none> 은 오류가 아니라 역할 라벨이 없다는 뜻이고, agent 는 원래 그렇다.

두 줄이 Ready 이고 IP 가 맞으면 이 단계는 끝났다. IP 가 다른 대역으로 잡혀 있으면 지금은 아무 증상이 없다가 다음 단계의 nginx upstream 과 노드 상실 실험에서 어긋난다. 그때 고치는 것보다 지금 재설치가 싸다. kc-lab-2 가 아예 안 보이면 join 이 실패한 것이니 agent 로그를 본다.

확인 ② 우리가 준 주소가 유닛에 그렇게 적혔는가

설치 스크립트에 준 옵션이 유닛 파일에 굳었는지.

ssh kc-lab-1 'systemctl cat k3s | grep -A3 ExecStart='
ssh kc-lab-2 'systemctl cat k3s-agent | grep -A4 ExecStart='

실측

ExecStart=/usr/local/bin/k3s server '--node-ip' '192.168.122.11'
ExecStart=/usr/local/bin/k3s agent  '--node-ip' '192.168.122.12'

ExecStart= 줄의 부분명령(server 인가 agent 인가)과 그 뒤의 인자.

확인 ① 은 k3s 가 보고한 주소이고 이 두 줄은 우리가 준 주소다. 둘이 다르면 옵션이 안 먹었다. 유닛 이름을 틀리면 No files found 가 나오는데, 그것 자체가 「이 노드는 agent 다」라는 답이 된다.

확인 ③ k3s 가 딸려 오게 한 것이 다 떴는가

우리가 안 깔았는데 이미 돌고 있는 것과 기본 저장소가 무엇인지.

kubectl get pods -A
kubectl get storageclass

실측

NAMESPACE     NAME                                      READY   STATUS      RESTARTS      AGE
kube-system   coredns-54996dc9b4-x5bsz                  1/1     Running     0             49m
kube-system   helm-install-traefik-cnv8z                0/1     Completed   2 (48m ago)   48m
kube-system   helm-install-traefik-crd-c6vft            0/1     Completed   0             48m
kube-system   local-path-provisioner-77b9867795-5k8d2   1/1     Running     0             49m
kube-system   metrics-server-6dc596dfb8-nzwt2           1/1     Running     0             49m
kube-system   svclb-traefik-a18ee1fc-2s9rl              2/2     Running     0             48m
kube-system   svclb-traefik-a18ee1fc-xmrrt              2/2     Running     0             22m
kube-system   traefik-59b7647586-rsrbc                  1/1     Running     0             48m

NAME                   PROVISIONER             RECLAIMPOLICY   VOLUMEBINDINGMODE      ALLOWVOLUMEEXPANSION   AGE
local-path (default)   rancher.io/local-path   Delete          WaitForFirstConsumer   false                  49m

kube-system 줄들의 STATUS 다. Running 과 Completed 가 섞여 있는 쪽이 정상이고, 일회성 잡은 Completed 로 남는다. svclb-traefik- 로 시작하는 줄이 둘인 것도 봐 둔다. StorageClass 에서는 이름 뒤의 (default) 표시가 어디 붙어 있는가.

svclb-traefik- 두 줄은 DaemonSet 이 노드마다 하나씩 뜬 것이라, 4번의 join 이 실제로 먹었다는 또 하나의 증거가 된다. local-path 에 (default) 가 붙어 있으면 다음 단계의 PVC 는 StorageClass 를 안 적어도 그것으로 만들어진다. Pending 이나 CrashLoopBackOff 가 섞여 있으면 그 파드부터 describe 로 본다.

확인 ④ agent 노드에서 kubectl 이 거절되는 것은 정상이다

agent 노드에서 kubectl 을 쳤을 때 나오는 거절이 어느 층의 신호인지.

Get "http://localhost:8080/api?timeout=32s": dial tcp [::1]:8080: connect: connection refused

주소 한 칸이다. localhost:8080 인가 다른 주소인가.

명령 자체는 있다. 설치 스크립트가 /usr/local/bin/kubectl -> k3s 심볼릭 링크를 만든다. 없는 것은 붙을 곳을 알려 주는 kubeconfig 이고, 넷 다 못 찾으면 kubectl 은 오류를 내지 않고 하드코딩된 기본값으로 넘어간다.

어디를 찾나 kc-lab-1 kc-lab-2
$KUBECONFIG 비어 있음 비어 있음
~/.kube/config 없음 없음
/etc/rancher/k3s/k3s.yaml 있음 없음

http://localhost:8080 은 쿠버네티스 1.20 이전 API 서버가 평문으로 열던 레거시 포트다. 이 설명은 이 실험대에서 따로 재현한 값이 아니라 쿠버네티스의 과거 동작을 기준으로 한다. 이 주소는 어디에도 적혀 있지 않으므로, 그것이 보이면 네트워크 문제가 아니라 설정을 하나도 못 찾았다는 뜻이다. 방화벽이나 k3s 를 의심하기 전에 kubeconfig 부터 본다.

:::warning

k3s.yaml 을 복사해 넣으면 agent 노드에서도 다 보이지만 복사하지 않는다. 워커 한 대가 털리면 클러스터 전체가 털리는 구성이 된다.

:::

agent 가 원래 가진 신원은 급이 다르다.

subject=O = system:nodes, CN = system:node:kc-lab-2

Node authorizer 와 NodeRestriction admission 은 이 신원이 자기 노드에 배정된 객체만 다루도록 제한한다. 이 부분은 쿠버네티스의 권한 모델에 따른 설명이다. 그 자격증명은 kubelet 전용 경로(/var/lib/rancher/k3s/agent/)에 있어 kubectl 이 읽지도 않는다. 그래서 실패가 권한 없음이 아니라 설정 없음으로 나타난다.

k3s 두 노드 확인표

무엇 명령 통과
두 노드 kubectl get nodes -o wide 둘 다 Ready · INTERNAL-IP 가 .11 과 .12
어디서 치나 위 명령에 sudo 도 ssh 도 안 붙는다 lab host 에서 그대로 돈다
server 유닛 ssh kc-lab-1 'systemctl cat k3s | grep -A3 ExecStart=' server '--node-ip' '192.168.122.11'
agent 유닛 ssh kc-lab-2 'systemctl cat k3s-agent | grep -A4 ExecStart=' agent '--node-ip' '192.168.122.12'
딸려 온 것 kubectl get pods -A svclb-traefik- 로 시작하는 줄이 둘
기본 저장소 kubectl get storageclass local-path (default)

agent가 join하지 못하거나 재부팅 뒤 안 돌아올 때

증상 원인 확인
wc -c node-token 이 0 server에서 토큰을 읽는 원격 명령이 실패해 빈 파일이 생겼다 ls -l node-token 과 ssh kc-lab-1 'sudo ls -l /var/lib/rancher/k3s/server/node-token'
agent 설치는 성공했는데 노드가 안 보임 토큰이 빈 값으로 넘어갔다 journalctl -u k3s-agent 에 --token is required
agent 가 NotReady 토큰이나 주소 오타 ssh kc-lab-2 'sudo journalctl -u k3s-agent -n 30 --no-pager'
노드 IP 가 예상과 다름 --node-ip 없이 설치 kubectl get nodes -o wide
lab host 에서 kubectl 이 No such file mkdir -p ~/.kube 를 빠뜨렸다 2번 ①
lab host 에서 connection refused kubeconfig 의 127.0.0.1 을 안 바꿨다 grep server: ~/.kube/config
kc-lab-2 에서 localhost:8080 agent 에는 kubeconfig 가 없다. 정상이다 확인 ④
워크스테이션에서 타임아웃 터널이 없다 5번 ①
x509 오류 k3s 재설치로 CA 가 바뀌었다 2번의 복사를 다시 한다
파드가 한 노드에만 몰림 스케줄러 판단 topologySpreadConstraints 로 강제

이 k3s 구성에서 실제로 확인한 범위

  • 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번의 나눈 형태는 이 실험대에서 치지 않았다. 이 실험대가 친 것은 원격 셸 둘을 파이프로 이은 두 줄이고, 나눈 형태로 같은 클러스터가 서는지는 다시 재지 않았다.
  • 2026-09-22 재검증에서 worker를 다시 만든 뒤 lab host의 기존 ~/.kube/config는 옛 CA를 들고 있어 plain kubectl get nodes가 x509: certificate signed by unknown authority로 실패했다. 2번 절차대로 현재 kc-lab-1:/etc/rancher/k3s/k3s.yaml을 다시 받아 server:를 https://192.168.122.11:6443으로 고친 뒤, 환경변수 없이 kubectl get nodes -o wide에서 두 노드 Ready를 확인했다. 기존 config는 ~/.kube/config.before-virtualization-revalidation-*로 보존했다. 증거는 final/evidence/raw/2026-09-21-test-server-revalidation/125-host-default-kubeconfig-refresh.txt다.
  • 5번의 ②③도 이 실험대에서 치지 않았다. 이 실험대가 친 것은 원격 셸을 두 겹으로 겹친 한 줄이다.
  • 인증서 SAN 조회와 두 journalctl 을 2026-09-17 에 쳤다. SAN 에 두 주소가 다 들어 있다 — 127.0.0.1 과 192.168.122.11 이라, kubeconfig 의 주소를 어느 쪽으로 고쳐도 검증이 통과한다.
X509v3 Subject Alternative Name:
    DNS:kubernetes, DNS:kubernetes.default, DNS:kubernetes.default.svc,
    DNS:kubernetes.default.svc.cluster.local, DNS:localhost, DNS:kc-lab-1,
    IP Address:127.0.0.1, IP Address:0:0:0:0:0:0:0:1,
    IP Address:192.168.122.11, IP Address:10.43.0.1, IP Address:192.168.122.11

192.168.122.11 이 두 번 나오는데 중복이고 동작에는 영향이 없다. 10.43.0.1 은 클러스터 안에서 API 서버를 부르는 Service 주소다.

  • 2026-09-17에는 journalctl -u k3s-agent 가 정상 상태에서도 E 로 시작하는 줄을 많이 냈다. 이것을 모르면 「막혔을 때 여기를 보라」는 안내대로 로그를 열었다가 멀쩡한 노드를 고장으로 읽을 수 있다. 같은 순간 kubectl get nodes 는 둘 다 Ready 였다.
E0917 07:42:16.919786 conn.go:353] "Error on socket receive" err="read tcp 127.0.0.1:10250->127.0.0.1:55428: use of closed network connection"

kubectl exec 나 logs 로 연결했다가 끊을 때마다 한 줄씩 남는다. 봐야 할 것은 E 인지가 아니라 문구다 — 토큰이나 주소가 틀렸으면 failed to get CA certs 나 401 Unauthorized 가 나온다.

  • k3s-uninstall.sh와 k3s-agent-uninstall.sh를 사용한 전체 제거·재설치 경로는 아직 확인하지 않았다.
  • 2026-09-21 worker 재구축에서는 k3s server와 agent 설치 경로를 다시 실행해 두 노드가 Ready로 돌아오는 것까지 확인했다. 다만 이 검증은 기존 lab host 위에서 worker VM을 다시 만든 구간 재구축이고, 빈 물리 host에서 단계 00부터 전체 가이드를 다시 실행한 것은 아니다. 과거 토큰 108자는 시점값이라 판올림이나 재설치 뒤에도 같은 길이라고 가정하지 않는다.