k8s-cluster-bootstrap

반복 설치에서 설정이 누락되거나 달라졌습니다

온프레미스 클러스터를 설치할 때마다 스왑·커널·네트워크 설정, 컨테이너 런타임과 Kubernetes 구성요소 설치를 반복했습니다. 마스터 초기화와 CNI 배포를 마친 뒤에는 워커마다 조인 토큰을 전달해야 했습니다. 노드가 늘수록 빠뜨리거나 서로 다르게 설정하기 쉬운 작업이었습니다.

온프레미스 클러스터를 여러 번 세팅하며 이 비효율이 반복된다는 걸 절감했고, 그래서 "명령 한 번"으로 끝내는 부트스트랩을 만들었습니다. 오픈소스로 공개해 지금까지 28개 릴리스를 유지했습니다.

한 번의 명령이 하는 일

스크립트를 sudo로 실행하고 옵션만 주면, 사전 설정부터 클러스터 완성까지 한 흐름으로 처리됩니다. 아래는 마스터 노드를 한 명령으로 부트스트랩하는 실제 실행 영상입니다.

• 사전 설정: 스왑 비활성화, 방화벽 정리, overlay·br_netfilter 커널 모듈 로드, iptables 브리징 sysctl 영구 설정
• 런타임·구성요소: cri-dockerd(또는 containerd) 설치와 systemd 등록, kubelet·kubeadm·kubectl 설치
• 마스터: kubeadm init(지정한 K8s 버전·호스트 IP·Pod CIDR·CRI 소켓), .kube/config 생성, 조인 토큰 발급
• CNI: Calico 자동 배포. API가 안정화될 때까지 기다린 뒤 Pod CIDR과 인캡슐레이션(클라우드 안전한 VXLAN 기본, bare-metal엔 IPIP)을 적용
• 워커: sshpass·rsync로 마스터에서 조인 토큰을 받아 kubeadm join 자동 실행

설치 조건을 검사하고 오류에 대응했습니다

설치 전에 네트워크와 패키지 조건을 검사하고, 환경별 차이는 옵션으로 지정하도록 했습니다. 마스터·워커(-m/-w), 마스터 IP(-i), Calico CIDR(-c), 런타임(-ct), 인캡슐레이션(-e), Kubernetes 버전(-v), metrics-server(-ms), 일반 사용자 kubeconfig(-r) 등 13개 플래그를 제공합니다.

• cri-dockerd를 바이너리에 의존하지 않고 소스에서 컴파일하고, go.mod에서 필요한 Go 버전을 감지해 툴체인까지 자동 설치
• apt-cache madison으로 정확한 deb 리비전을 해석하고(패치 리비전이 제각각이라), apt-mark hold로 버전을 고정해 의도치 않은 업그레이드를 차단. Kubernetes 1.24.15부터 1.36.4까지 170개 버전을 지원
• GPG 키는 기본 엔드포인트 실패 시 대체 소스로 페일오버, 마스터 IP가 Pod CIDR과 겹치지 않고 사설 대역인지 검증, apt 락 정리 등 실패 상황을 처리
• 지원 버전 목록을 GitHub 또는 로컬 VERSIONLIST에서 읽어 오프라인에서도 동작하고, info/success/warning/danger 색상 출력으로 진행 상황을 바로 파악

지원 환경과 공개

Ubuntu 18.04부터 26.04까지 지원하고 Apache-2.0으로 공개했으며, v0.1.1부터 v1.3.0까지 28개 릴리스를 유지하고 있습니다. 약 723줄의 방어적 bash(에러 상태 검사·리턴 코드 가드)로 작성돼, 온프레미스 클러스터를 반복적으로 세우는 실제 작업에서 그대로 쓰입니다.