k8s-cluster-bootstrap
Summary
온프레미스 Kubernetes 클러스터를 설치할 때마다 반복하던 수작업과 설정 누락을 줄이기 위해, 명령 한 번으로 설치를 끝내는 오픈소스 도구를 만들었습니다. 사전 설정부터 런타임 설치, 클러스터 초기화, 네트워크 구성, 워커 조인까지 한 흐름으로 처리해 노드가 늘어나도 같은 절차로 클러스터를 구성할 수 있습니다.
- Role
- DeveloperMaintainer
- Outcome
- K8s 1.24–1.36169개 버전 지원28개 릴리스
반복 설치에서 설정이 누락되거나 달라졌습니다
온프레미스 클러스터를 설치할 때마다 각 노드의 메모리 스왑, 커널과 네트워크를 설정하고, 컨테이너 런타임과 Kubernetes 구성요소를 하나하나 설치해야 했습니다. 마스터 노드 초기화와 CNI 배포를 마친 뒤에는 워커 노드마다 조인 토큰을 전달했습니다. 이 과정을 수작업으로 반복하다 보니 노드가 늘어날수록 설정을 빠뜨리거나 노드마다 다르게 설정하여 잘못 구성되는 일이 잦았습니다.
설정 누락과 노드별 차이를 줄이려면, 설치 절차는 같은 순서로 실행하되 환경에 따라 달라지는 값은 따로 지정할 수 있어야 했습니다. 그래서 모든 노드에 필요한 사전 설정과 런타임 설치는 공통 절차로 묶고, 마스터 초기화와 워커 조인은 노드 역할에 따라 나누었습니다. Kubernetes 버전과 런타임, 네트워크 대역은 실행 옵션으로 지정하게 하여 스크립트를 직접 수정하지 않고도 각 환경에 적용할 수 있도록 했습니다. 이렇게 노드마다 명령 한 번으로 필요한 설정과 설치를 수행하는 부트스트랩을 만들고, 오픈소스로 공개한 뒤 지원 환경을 넓히며 지금까지 28차례 릴리스했습니다.
한 번의 명령이 하는 일
스크립트에 노드 역할과 설치 옵션을 지정하여 sudo로 실행하면, 사전 설정부터 마스터 초기화 또는 워커 조인까지 자동으로 진행됩니다. 아래 영상은 Ubuntu 22.04에서 containerd와 Kubernetes 1.31.0을 선택하여 마스터 노드를 설치한 실제 실행 화면입니다.
노드마다 필요한 설정이 빠지는 문제를 줄이기 위해, 패키지 설치뿐 아니라 운영체제 설정까지 같은 흐름에서 처리하도록 했습니다. 스왑과 UFW를 비활성화하고, 선택한 런타임과 Kubernetes 구성요소를 설치합니다. 컨테이너 실행과 네트워크 통신에 필요한 커널 모듈과 sysctl 설정도 함께 적용하며, 재부팅 후에도 유지되도록 설정 파일에 저장했습니다.
마스터 노드 설정이 끝난 뒤에도 워커마다 조인 토큰을 전달해야 했기 때문에, 노드 연결 과정까지 자동화했습니다. 마스터에서는 kubeadm으로 클러스터를 초기화하고 kubeconfig와 조인 명령을 생성합니다. Calico는 지정한 Pod 네트워크 대역에 맞춰 배포하고, VXLAN을 기본값으로 두되 환경에 따라 IPIP를 선택할 수 있도록 했습니다. 워커에서는 SSH로 마스터의 조인 명령을 받아 실행하게 하여, 노드를 추가할 때마다 토큰을 복사하고 조인 명령을 입력하던 작업을 줄였습니다.
설치 조건을 검사하고 오류에 대응했습니다
지원 버전을 넓히는 과정에서, Kubernetes 버전만 보고 deb 패키지의 리비전을 정하던 방식으로는 설치가 실패하는 경우가 있었습니다. 같은 Kubernetes 버전이라도 저장소에 등록된 패키지 리비전이 다를 수 있었기 때문입니다. 그래서 apt-cache madison으로 저장소에 있는 실제 패키지 버전을 조회하고, kubelet과 kubeadm, kubectl을 같은 버전으로 설치하도록 바꿨습니다. 설치 후에는 apt-mark hold로 고정하여 패키지 업데이트 과정에서 Kubernetes 버전이 의도치 않게 바뀌지 않도록 했습니다.
Docker를 사용하는 경우에는 Kubernetes와 연결할 cri-dockerd를 소스에서 빌드합니다. 이때 필요한 Go 버전을 코드에 고정해 두면 cri-dockerd가 업데이트될 때마다 스크립트도 수정해야 하므로, go.mod에서 요구하는 버전을 읽어 해당 Go 툴체인을 설치한 뒤 빌드하도록 했습니다.
설치가 시작된 뒤에 입력 오류를 발견하지 않도록, 노드 역할에 필요한 옵션과 런타임, 지원 버전을 먼저 확인합니다. 지원 버전 목록은 스크립트 옆의 VERSIONLIST를 우선 읽고, 파일이 없으면 GitHub에서 가져옵니다. 목록을 확인할 수 없거나 요청한 버전의 패키지를 찾지 못하면 오류 내용을 보여주고 설치를 중단하여, 조건을 확인하지 않은 채 다음 단계로 넘어가지 않도록 했습니다.
지원 환경과 공개
Ubuntu 18.04부터 26.04까지, Kubernetes 1.24.15부터 1.36.4까지 총 169개 버전을 지원합니다. Apache-2.0으로 공개한 뒤 설치 과정에서 발견한 문제와 환경별 차이를 보완하며 지금까지 28차례 릴리스했습니다. 온프레미스 클러스터를 구축할 때 반복하던 사전 설정과 런타임 설치, 워커 조인을 노드별 명령 한 번으로 처리할 수 있도록 했습니다.