[K3s 클러스터 구축] 1. PXE로 Debian 12 노드 프로비저닝 및 트러블슈팅

개요

• 목적: K3s 노드(Debian 12 Bookworm) 초기 OS 세팅
• 방식: netboot.xyz 활용 PXE 네트워크 부팅 (수동 설치 최소화)

구성 환경 및 인프라

구분	상세 내용	비고
Master Node	Proxmox VM (ex: VM 120)	Control Plane
Worker 노드	Intel N100 베어메탈 미니 PC	Worker 1, 2
PXE 서버	netboot.xyz 컨테이너	Proxmox 내 Docker VM
DHCP 서버	OPNsense	네트워크 부팅 옵션 제공
부팅 방식	UEFI 기반 PXE 네트워크 부팅

---

1. netboot.xyz 구축 (PXE 부팅 서버)

Proxmox 내 Docker VM에서 netboot.xyz 컨테이너를 구동하여 PXE 환경 구축.

# docker-compose.yml
services:
  netbootxyz:
    image: ghcr.io/netbootxyz/netbootxyz:latest
    container_name: netbootxyz
    environment:
      - PUID=1000
      - PGID=1000
    volumes:
      - ./config:/config
      - ./assets:/assets
    ports:
      - 3000:3000   # 웹 관리 UI
      - 69:69/udp   # TFTP
      - 8080:80     # HTTP (메뉴/자산 서빙)
    restart: unless-stopped

부팅 후 웹 UI(http://[Docker_IP]:3000)에 접속하여 메뉴/자산 관리 가능.

---

2. OPNsense DHCP 네트워크 부팅 설정

• 목적: 노드의 PXE 서버 탐색을 위한 DHCP 옵션 할당
• 경로: 서비스 → ISC DHCPv4 → [LAN] → ‘네트워크 부팅’ 섹션

설정 항목	입력 값
네트워크 부팅 사용	체크
다음 서버 IP 설정	192.168.1.239 (netboot.xyz 컨테이너 호스트 IP)
기본 BIOS 파일 이름 설정	netboot.xyz.kpxe
x86 UEFI(32비트) 파일 이름 설정	netboot.xyz.efi
x64 UEFI/EBC(64비트) 파일 이름 설정	netboot.xyz.efi

---

3. 노드별 Debian 12 설치 (K3s 최적화)

• 대상 기기 전원 On 후 PXE 부팅 진행

부팅 순서

1. BIOS/UEFI 진입 → Network/PXE 부팅 활성화 및 1순위 설정
2. PXE 부팅 후 netboot.xyz 메뉴 접속
3. Linux Network Installs → Debian → Debian 12 (Bookworm) 선택
4. OS 설치 시작

OS 파티션 및 소프트웨어 설정 (K3s 경량화)

설정 항목	권장 값	비고
파티션	수동(Manual)	root(/) 40GB, 데이터(/var/lib/rancher/k3s) 100GB 분리 (용량증가 대비)
소프트웨어	SSH server, standard system utilities	데스크탑 체크 해제
계정	일반 계정(sudo) 생성	root 로그인 비활성화
고정 IP	OPNsense DHCP Reservation	역할별 호스트네임 부여

초기 설정정

OS 부팅 완료 후 터미널에 접속. K3s 구동을 위해 다음 명령어들로 환경 튜닝 진행:

# 기본 패키지 업데이트
apt update && apt upgrade -y
 
# K3s 구동 및 스토리지 연동(Longhorn/NFS 등)에 필요한 필수 패키지 설치
apt install -y curl sudo open-iscsi nfs-common
 
# swap 비활성화 (Kubernetes 권장 사항)
swapoff -a
sed -i '/ swap / s/^/#/' /etc/fstab

---

4. [중요] Proxmox VM UEFI PXE 부팅 트러블슈팅 (8.4+)

• Master 노드(OVMF/UEFI) VM에서 PXE 부팅 시 주로 발생하는 문제와 해결책 요약.

문제 1: 부트 메뉴 PXE 옵션 누락

구분	상세 내용
증상	Boot Order net0 최상위 설정 시에도 UEFI 부트 메뉴에 네트워크 카드 미인식
원인	Proxmox 8.4 보안 패치 반영 (VirtIO RNG 부재 시 네트워크 스택 비활성화)
해결	VM 하드웨어에 VirtIO RNG 추가

# Proxmox 쉘에서 명령어로 추가
qm set <VMID> --rng0 source=/dev/urandom

(또는 웹 UI → VM 선택 → Hardware → Add → VirtIO RNG 추가)

• 결과: 재부팅 후 UEFI PXEv4 옵션 정상 노출.

문제 2: Access Denied (PXE 파일 로드 실패)

구분	상세 내용
증상	부팅 파일(netboot.xyz.efi) 로드 직후 Access Denied 에러 발생 및 종료
원인	EFI 디스크 내 마이크로소프트 보안 키(Pre-Enrolled Keys)에 의한 Secure Boot 동작. 서명되지 않은 외부 파일 실행 차단
해결	기존 EFI 디스크 제거 및 pre-enrolled-keys=0 옵션의 새 디스크 재생성 (Secure Boot 해제)

qm stop <VMID>
qm set <VMID> --delete efidisk0
qm set <VMID> --efidisk0 local-lvm:0,efitype=4m,pre-enrolled-keys=0
qm start <VMID>

Tip: VM 생성 시 OS 탭 Advanced 영역에서 “Pre-Enroll Keys” 체크 해제 권장.

---

참고: K3s Master (VM) 최종 하드웨어 설정

• 위 트러블슈팅 반영 후의 최종 VM 설정 요약:

옵션	설정 값	목적 및 비고
bios	ovmf	UEFI 부팅 모드
boot	order=net0;scsi0;ide2	초기 OS 설치를 위해 네트워크 부팅 최우선 지정
efidisk0	pre-enrolled-keys=0	Secure Boot 차단
rng0	(추가됨)	난수 생성기(네트워크 스택 활성화용)
net0	e1000	초기 PXE 호환성 확보용 (※ 설치 완료 후 virtio로 변경 권장)

Tip: 설치 종료 후 반드시 네트워크를 virtio 모델로 복구하고, Boot Order 1순위를 scsi0으로 조정.