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 |
|
|
import-head 9465582b5d1630eb4ae7c4e078021486919bf6b6 · uncommitted-working-tree snapshot |
|
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를 들고 있어 plainkubectl 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자는 시점값이라 판올림이나 재설치 뒤에도 같은 길이라고 가정하지 않는다.