본문으로 건너뛰기
버전: Next

워커 노드 추가

NuFi 마스터 노드에 워커 노드를 추가하여 클러스터를 확장할 수 있습니다. 폐쇄망 환경을 기준으로 설명합니다.

사전 준비​

항목요구사항
OSUbuntu 22.04+ (마스터와 동일 아키텍처)
CPU4코어 이상
RAM16GB 이상
디스크100GB 이상
GPU (선택)NVIDIA 드라이버 사전 설치

네트워크 요구사항​

방향포트프로토콜용도
워커 → 마스터6443TCPK3s API
워커 → 마스터8472UDPFlannel VXLAN

워커 번들​

워커 조인에 필요한 파일은 NuFi 공급자가 제공하는 worker-bundle 디렉토리에 포함되어 있습니다.

worker-bundle/
├── join-worker.sh                    # 조인 스크립트
├── k3s                               # k3s 바이너리
├── k3s.tar.zst                       # airgap 컨테이너 이미지
├── nvidia-container-toolkit/         # NVIDIA CTK (선택)
└── docs/
    └── worker-join-guide.md

토큰 확인​

마스터 노드에서 조인 토큰을 확인합니다.

요청

sudo cat /var/lib/rancher/k3s/server/node-token

응답

K10abcdef1234567890abcdef1234567890abcdef1234567890::server:abcdef1234567890
경고

node-token은 워커 노드 조인 권한을 부여하는 값입니다. 외부로 노출되지 않도록 주의하세요.

조인 실행​

워커 노드에서 번들 디렉토리로 이동한 뒤 스크립트를 실행합니다.

cd worker-bundle
sudo ./join-worker.sh <마스터IP> <토큰>
인자설명예시
마스터IP마스터 노드의 IP 주소192.168.10.1
토큰위에서 확인한 node-token 값 전체K10abc...::server:abc...

실행 예시:

sudo ./join-worker.sh 192.168.10.1 \
  K10abcdef1234567890abcdef1234567890abcdef1234567890::server:abcdef1234567890

실행 단계​

스크립트는 아래 단계를 자동 수행합니다.

[1/6] 필수 파일 확인
[2/6] 시스템 설정           (swap off, sysctl, NVIDIA CTK)
[3/6] k3s 바이너리 설치
[4/6] airgap 이미지 배치
[5/6] k3s-agent 서비스 등록
[6/6] 조인 완료 대기
팁

NVIDIA GPU가 감지되면 containerd nvidia runtime이 자동으로 설정됩니다.

조인 확인​

마스터 노드에서 노드 목록을 확인합니다.

요청

kubectl get nodes

응답

NAME        STATUS   ROLES                  AGE     VERSION
master-01   Ready    control-plane,master   3d      v1.34.3+k3s1
worker-01   Ready    <none>                 30s     v1.34.3+k3s1

새 워커 노드가 Ready 상태로 표시되면 조인 완료입니다.

정보

airgap 이미지 import 및 CNI 초기화에 30~90초 정도 걸릴 수 있습니다. Ready가 아닌 경우 2분 정도 대기 후 다시 확인하세요.

문제 해결​

로그 확인​

# 서비스 상태
sudo systemctl status k3s-agent

# 실시간 로그
sudo journalctl -u k3s-agent -f

# 최근 100줄
sudo journalctl -u k3s-agent -n 100

자주 나오는 에러​

증상원인해결
401 또는 Failed to get node-ca-hash토큰 오타 또는 공백 포함토큰을 다시 복사하여 앞뒤 공백 없이 전달
dial tcp :6443: connect: timeout방화벽이 6443 차단워커 → 마스터 TCP 6443 허용
flannel ... no route 반복방화벽이 UDP 8472 차단워커 → 마스터 UDP 8472 허용
certificate not yet valid워커 노드 시간이 맞지 않음sudo date -s "YYYY-MM-DD HH:MM:SS"로 시간 동기화
kubectl get nodes에 안 보임airgap 이미지 누락 또는 아키텍처 불일치journalctl -u k3s-agent로 이미지 import 확인

조인 취소 및 재시도​

조인을 처음부터 다시 하려면 워커에서 아래를 실행합니다.

sudo systemctl stop k3s-agent
sudo systemctl disable k3s-agent
sudo rm -f /etc/systemd/system/k3s-agent.service
sudo rm -f /etc/systemd/system/k3s-agent.service.env
sudo rm -rf /var/lib/rancher/k3s /etc/rancher/k3s
sudo systemctl daemon-reload

마스터에서 해당 노드가 목록에 남아있다면 제거합니다.

kubectl delete node <워커노드이름>

이후 조인 실행부터 다시 진행합니다.