On-Premise 환경에서 안정적이고 확장 가능한 쿠버네티스(Kubernetes) 클러스터를 구축하는 것은 많은 기업의 중요한 과제입니다. 클라우드 서비스의 편리함도 좋지만, 데이터 주권이나 특정 규제 준수를 위해 자체 데이터 센터에 K8S 클러스터를 운영해야 하는 경우가 많습니다. 이럴 때 가장 강력한 자동화 도구 중 하나가 바로 Kubespray입니다. 이 글에서는 10년 경력의 전문가 시선으로 Kubespray를 활용하여 여러분의 물리적 또는 가상 환경에 On-Premise K8S 클러스터를 성공적으로 구축하는 전 과정을 상세히 안내해 드립니다.
이 가이드를 통해 Kubespray의 기본 원리부터 환경 준비, 인벤토리 설정, 그리고 최종적인 클러스터 배포 및 검증까지 실질적인 노하우를 얻으실 수 있습니다. 여러분은 복잡한 수동 설치 과정 없이 Ansible 기반의 Kubespray를 통해 빠르고 일관성 있게 프로덕션 레디 K8S 클러스터를 구축하는 방법을 숙달하게 될 것입니다.
Kubespray란 무엇이며 On-Premise 구축에 적합한 이유
Kubespray는 쿠버네티스 클러스터 배포 및 구성을 자동화하는 오픈 소스 프로젝트입니다. 핵심적으로 Ansible 플레이북을 기반으로 동작하며, 다양한 인프라 환경에서 일관성 있는 설치를 보장합니다. 클라우드 환경뿐만 아니라 On-Premise K8S 클러스터 구축에 매우 강력한 도구로 인정받고 있습니다. 이는 필요한 모든 구성 요소를 YAML 기반의 인벤토리 및 변수 파일을 통해 정의할 수 있기 때문입니다.
클라우드 환경은 클릭 몇 번으로 클러스터를 생성할 수 있지만, On-Premise 환경에서는 OS 설치부터 네트워크 구성, 컴포넌트 설치까지 모든 단계를 수동으로 처리해야 하는 경우가 많습니다. 이 지루하고 오류 발생 가능성이 높은 작업을 Kubespray가 대신해 줍니다. Kubespray를 사용하면 K8S 클러스터의 버전 관리, CNI 플러그인 선택, etcd 구성 방식 등 세밀한 부분을 표준화된 방식으로 적용할 수 있습니다.
특히 Kubespray의 장점은 유연성입니다. 여러분이 원하는 대로 마스터 노드 수, 워커 노드 수, 그리고 쿠버네티스 버전을 자유롭게 선택할 수 있습니다. 또한, Ansible을 사용하기 때문에 이미 사내에서 Ansible 자동화 환경이 구축되어 있다면 도입 장벽이 매우 낮습니다. On-Premise K8S 클러스터를 구축할 때 신뢰성을 높이는 핵심 요소가 바로 이 자동화된 배포 프로세스입니다. Kubespray는 이러한 요구사항을 충족시키는 최적의 솔루션입니다.
On-Premise K8S 클러스터 구축을 위한 선행 작업 및 환경 준비
성공적인 Kubespray 기반 K8S 클러스터 구축은 철저한 사전 준비에서 시작됩니다. On-Premise 환경의 특성상 하드웨어 또는 VM 환경 설정이 가장 중요합니다. 최소한의 요구사항을 충족하는 환경을 구성해야 배포 중 예기치 않은 오류를 방지할 수 있습니다.
먼저, 클러스터 구성원들의 OS는 안정적인 리눅스 배포판을 선택하는 것이 좋습니다. 최근 추세에 따라 Ubuntu 22.04 LTS 버전이 널리 사용되고 있으며, 참고 자료에서도 이 버전을 기반으로 하고 있습니다. 마스터 노드와 워커 노드의 최소 사양을 정하고 네트워크 구성을 완료해야 합니다. 모든 노드는 고정 IP 주소를 할당받아야 하며, 호스트 간의 통신이 원활해야 합니다.
다음은 모든 노드에서 반드시 수행해야 할 공통 필수 준비 단계입니다. 이는 Kubespray가 원활하게 Ansible 플레이북을 실행하기 위한 기반 작업입니다. 특히 Kubernetes는 스왑(Swap) 사용을 권장하지 않으므로, 반드시 비활성화해야 합니다. swapoff -a 명령은 이 과정에서 핵심적인 역할을 수행합니다.
모든 노드에서 공통으로 처리해야 할 환경 설정
모든 서버(컨트롤 플레인 및 워커 노드)는 동일한 기본 환경을 가져야 합니다. 여기에는 호스트 이름 확인과 권한 설정이 포함됩니다. 호스트 이름을 통한 네트워킹은 Kubespray 인벤토리 구성의 핵심이므로, 모든 노드의 /etc/hosts 파일에 상호 IP와 호스트 이름을 등록해야 합니다.
또한, Ansible 자동화를 위해 배포를 실행하는 호스트에서 타겟 노드들로 SSH 접속 시 비밀번호를 묻지 않도록 설정해야 합니다. 이를 위해 SSH 키 쌍을 생성하고 모든 노드에 ssh-copy-id를 사용하여 키를 배포하는 과정이 필수적입니다. 또한, 배포 사용자가 sudo 권한을 비밀번호 없이 사용할 수 있도록 설정하는 것도 자동화를 위해 매우 중요합니다.
- /etc/hosts 파일 동기화: 모든 노드 간 호스트 이름 해석을 위해 IP와 호스트 이름을 등록합니다.
- SSH 키 기반 인증 설정: 비밀번호 없이 무인(Unattended) 배포를 가능하게 합니다.
- Swap 비활성화: Kubernetes 안정성을 위해 반드시 swapoff -a를 실행하고 /etc/fstab에서 해당 항목을 제거합니다.
- 기본 패키지 설치: git, python3, sshpass 등 Kubespray 실행에 필요한 의존성을 설치합니다.
Kubespray 설치 및 Ansible 환경 구성
환경 준비가 완료되었다면, 이제 Kubespray 자체를 설치하고 Ansible 실행 환경을 구성할 차례입니다. 이 작업은 보통 별도의 배포 관리 호스트에서 수행하는 것이 권장되지만, 마스터 노드 중 하나에서 직접 수행할 수도 있습니다. 이 단계에서는 최신 버전의 Kubespray를 Git을 통해 복제하고, 의존성을 격리하기 위해 Python 가상 환경을 사용하는 것이 모범 사례입니다.
Kubespray 저장소를 클론한 후, 해당 디렉토리로 이동하여 requirements.txt 파일을 참조하여 필요한 파이썬 라이브러리를 설치합니다. 특히 Ansible 버전과의 호환성을 유지하는 것이 중요하며, 가상 환경을 사용하면 시스템 전체에 영향을 주지 않고 필요한 의존성만 명확하게 관리할 수 있습니다. On-Premise K8S 클러스터 구축 시 의존성 충돌은 흔한 문제입니다. 이를 방지하기 위해 venv 사용은 필수적입니다.
TIP: Kubespray는 Ansible을 사용하므로, Kubespray 실행 전 반드시 ‘source venv/bin/activate’ 명령어로 가상 환경을 활성화해야 합니다. 활성화하지 않으면 필요한 라이브러리들을 찾지 못해 배포가 실패할 수 있습니다.
설치 과정은 비교적 간단합니다. Git 클론 후 요구사항 설치만 하면 됩니다. 이처럼 Kubespray는 복잡한 K8S 클러스터 구축 과정을 표준화된 스크립트 기반으로 단순화시켜 줍니다. On-Premise 환경에서 일관성을 유지하는 데 큰 도움이 됩니다.
Kubespray 인벤토리 파일 작성의 이해와 실제 적용
Kubespray의 심장부는 바로 인벤토리(Inventory) 파일입니다. 이 파일은 Ansible에게 어떤 서버들이 클러스터에 참여할 것인지, 각 서버의 역할(컨트롤 플레인, 워커 노드, etcd 멤버)은 무엇인지를 알려줍니다. Kubespray는 기본적으로 제공하는 샘플 인벤토리를 복사하여 사용자 환경에 맞게 수정하는 방식을 사용합니다.
inventory/sample 디렉토리에 있는 파일을 inventory/mycluster와 같은 새로운 디렉토리로 복사한 후, 주요 설정 파일인 hosts.yaml을 편집해야 합니다. 이 파일에서 각 노드의 IP 주소와 역할을 명확하게 정의해야 합니다. 예를 들어, 세 대의 서버로 On-Premise K8S 클러스터를 구성한다면, 한 대는 컨트롤 플레인 및 etcd 역할을 수행하고 나머지 두 대는 워커 노드 역할을 맡게 됩니다. hosts.yaml 파일에서 ansible_host 변수를 통해 실제 접속 가능한 IP 주소를 정확하게 명시하는 것이 중요합니다.
인벤토리 설정 외에도 cluster.yml 파일에서 클러스터의 전반적인 구성을 조정할 수 있습니다. 여기에는 쿠버네티스 배포 버전, CNI(Container Network Interface) 선택(예: Calico, Flannel), 그리고 API 서버 포트 등이 포함됩니다. Kubespray의 강력한 점은 이러한 세부 설정을 모두 이 인벤토리와 변수 파일들을 통해 제어할 수 있다는 것입니다. 여러분이 원하는 K8S 클러스터의 특성에 맞게 이 파일들을 수정하는 것이 Kubespray 활용의 핵심입니다.
다음은 기본적인 hosts.yaml 구조의 예시입니다. 실제 환경에 맞게 IP와 호스트 이름을 변경해야 합니다.
| 그룹 | 호스트 이름 | Ansible Host IP |
|---|---|---|
| all | k8s-master | 192.168.0.201 |
| etcd | k8s-master | 192.168.0.201 |
| kube_control_plane | k8s-master | 192.168.0.201 |
| kube_node | k8s-worker1, k8s-worker2 | 192.168.0.202, 192.168.0.203 |
Kubespray 실행 및 On-Premise K8S 클러스터 배포
인벤토리 구성을 마쳤다면, 이제 Kubespray의 핵심인 Ansible 플레이북을 실행하여 실제 On-Premise K8S 클러스터 구축을 시작합니다. 이 단계는 몇 가지 주요 플레이북 중 하나를 선택하여 실행하게 되는데, 가장 일반적인 방법은 cluster.yml 플레이북을 사용하는 것입니다. 이 플레이북은 설정된 모든 노드에 대해 쿠버네티스 설치 및 클러스터 구성을 처음부터 끝까지 자동화합니다.
실행 명령어는 다음과 같습니다. 배포를 실행하는 호스트에서 가상 환경이 활성화된 상태여야 하며, -i 옵션을 통해 구성한 인벤토리 경로를 지정해야 합니다. Kubespray는 ansible_user 설정에 따라 원격 호스트에 접속하게 되므로, SSH 비밀번호 없이 접속이 가능한지 마지막으로 확인해야 합니다.
배포 과정은 노드 수와 설정에 따라 상당한 시간이 소요될 수 있습니다. 이 과정에서 Ansible은 OS 패치, 컨테이너 런타임 설치(Docker 또는 Containerd), kubeadm 실행, 그리고 CNI 설치 등을 순차적으로 수행합니다. 만약 배포 중 문제가 발생하면, Ansible의 롤백 기능은 없으므로, 이전 상태로 되돌리거나 수동으로 정리 후 재시작해야 합니다. 따라서 Kubespray를 이용한 K8S 클러스터 구축 시에는 idempotent(멱등성)을 유지하기 위해 신중한 사전 준비가 필요합니다.
실행 명령어 예시: ansible-playbook -i inventory/mycluster/hosts.yaml cluster.yml -b
-b 옵션은 become을 의미하며, root 권한으로 작업을 수행하도록 지시합니다. Kubespray는 이 명령어를 통해 완벽하게 자동화된 On-Premise K8S 클러스터를 생성해 냅니다. 이 자동화 덕분에 우리는 수동 설치 시 발생할 수 있는 휴먼 에러를 최소화할 수 있습니다.
클러스터 검증 및 Kubespray 설정 파일 심층 분석
배포 플레이북 실행이 성공적으로 완료되었다면, 이제 On-Premise K8S 클러스터가 정상적으로 작동하는지 검증해야 합니다. 검증은 주로 마스터 노드에 접속하여 kubectl 명령어를 사용하는 것으로 시작됩니다. Kubespray는 기본적으로 kubeconfig 파일을 적절한 위치에 생성해주므로, 별도 설정 없이 kubectl get nodes 명령어를 실행할 수 있습니다.
모든 노드가 Ready 상태로 표시되면, 여러분이 구축한 K8S 클러스터는 성공적으로 운영될 준비가 된 것입니다. Kubespray가 설정한 CNI가 정상 작동하는지, 핵심 파드들이 문제없이 실행되고 있는지 확인하는 것이 다음 단계입니다. kube-system 네임스페이스의 파드들을 확인해보는 것이 좋습니다.
Kubespray의 진정한 힘은 inventory/mycluster/group_vars 디렉토리 내의 수많은 변수 파일에 있습니다. 이 파일들을 통해 클러스터의 세부 사항을 튜닝할 수 있습니다. 예를 들어, 기본적으로 Calico 대신 Flannel을 사용하고 싶다면, cni.yml 또는 관련 변수 파일을 수정해야 합니다. On-Premise K8S 클러스터의 보안 강화나 특정 네트워크 정책 적용 시 이 변수 파일들이 핵심적인 역할을 수행합니다.
다음은 주요 구성 변수 파일 및 역할에 대한 간략한 비교입니다.
| 파일명/그룹 | 주요 제어 항목 |
|---|---|
| hosts.yaml | 노드 목록 및 역할 할당 |
| group_vars/k8s_cluster/k8s-cluster.yml | 쿠버네티스 버전, CNI, Kubelet 설정 등 핵심 파라미터 |
| group_vars/k8s_cluster/k8s_control_plane.yml | etcd 구성, API 서버 인증 설정 |
이러한 세부 조정을 통해 여러분은 On-Premise K8S 클러스터를 기업의 고유한 요구사항에 완벽하게 맞출 수 있습니다. Kubespray는 단순한 설치 도구가 아니라, 클러스터 수명 주기 관리의 시작점이 되는 강력한 템플릿 프레임워크입니다. 이 모든 과정이 Ansible을 통해 자동화된다는 점을 다시 한번 강조 드립니다. Kubespray를 잘 활용하면 향후 버전 업그레이드나 클러스터 복구 작업도 훨씬 수월해집니다.
Kubespray를 활용한 클러스터 유지보수 및 확장 전략
Kubespray를 이용해 On-Premise K8S 클러스터를 구축하는 것은 끝이 아니라 시작입니다. 클러스터는 지속적인 유지보수와 확장이 필요하며, Kubespray는 이 과정에서도 빛을 발합니다. 이미 잘 정의된 인벤토리와 변수 파일이 있기 때문에, 새로운 워커 노드를 추가하거나 기존 노드를 교체하는 작업이 매우 간편해집니다.
새로운 워커 노드를 추가하려면, 해당 서버의 OS 준비 작업을 동일하게 수행한 후, hosts.yaml 파일에 새 노드의 정보를 kube_node 그룹에 추가하기만 하면 됩니다. 그 후, cluster.yml을 다시 실행하면 Kubespray는 변경된 인벤토리만을 감지하여 필요한 부분, 즉 새 노드에만 쿠버네티스 컴포넌트를 설치하게 됩니다. 이것이 자동화된 인프라 관리의 가장 큰 이점입니다.
유지보수 측면에서 가장 중요한 것은 버전 업그레이드입니다. 쿠버네티스 마이너 버전이 릴리스될 때마다 Kubespray는 해당 버전을 지원하도록 업데이트됩니다. 컨트롤 플레인 업그레이드는 기본적으로 순차적으로 수행되어 서비스 중단을 최소화합니다. 먼저 마스터 노드 그룹을 대상으로 upgrade-cluster.yml과 같은 특화된 플레이북을 실행하고, 이후 워커 노드 그룹을 대상으로 동일한 작업을 수행하면 됩니다. On-Premise K8S 클러스터 운영의 안정성은 이러한 체계적인 업데이트 프로세스에 달려있습니다.
또한, Kubespray는 클러스터 제거를 위한 플레이북도 제공합니다. 이는 클러스터를 완전히 초기화하거나 리빌드해야 할 때 매우 유용합니다. reset.yml 플레이북을 실행하면 모든 노드에서 쿠버네티스 관련 설정과 파일들이 깨끗하게 제거되어, 깨끗한 상태로 K8S 클러스터 재구축이 가능합니다. Kubespray는 전체 K8S 라이프사이클을 고려하여 설계된 도구임을 알 수 있습니다.
자주 묻는 질문
Kubespray를 사용하려면 반드시 Ansible을 사용해야 하나요
네, Kubespray는 본질적으로 Ansible 플레이북의 집합체입니다. 따라서 Kubespray를 실행하려면 시스템에 Ansible이 설치되어 있어야 하며, 모든 설정은 Ansible 인벤토리 및 변수 파일을 통해 이루어집니다. On-Premise K8S 클러스터 구축 자동화의 핵심 기반 기술입니다.
Kubespray는 Docker 외의 다른 컨테이너 런타임을 지원하나요
예, Kubespray는 Docker 외에도 Containerd와 CRI-O 등 다양한 컨테이너 런타임을 지원합니다. 이 선택은 inventory/mycluster/group_vars/k8s_cluster/k8s-cluster.yml 파일 내의 특정 변수를 수정하여 지정할 수 있으며, On-Premise 환경의 제약 사항이나 선호도에 따라 유연하게 선택 가능합니다.
배포 중 SSH 연결 실패 오류가 발생하면 어떻게 해야 하나요
SSH 연결 실패는 대부분 사용자 계정 권한 문제 또는 키 배포 오류에서 발생합니다. 먼저, 배포를 실행하는 사용자가 모든 타겟 노드에서 NOPASSWD 설정이 제대로 되어 있는지 확인해야 합니다. 또한, 모든 노드의 호스트 이름이 /etc/hosts에 올바르게 등록되어 있는지, 그리고 SSH 접속이 비밀번호 입력 없이 바로 되는지 수동으로 점검해 보는 것이 필수적입니다.
Kubespray로 설치된 K8S 클러스터의 버전을 나중에 변경할 수 있나요
네, 가능합니다. Kubespray는 버전 업그레이드를 지원하는 체계적인 프로세스를 갖추고 있습니다. group_vars/k8s_cluster/k8s-cluster.yml 파일에서 원하는 쿠버네티스 버전을 변경한 후, 업그레이드 전용 플레이북을 실행하여 순차적인 마이그레이션을 진행할 수 있습니다. 이는 On-Premise K8S 클러스터의 장기적인 운영 안정성에 기여합니다.
Kubespray 설치 전 필요한 최소한의 하드웨어 사양은 어떻게 되나요
최소 사양은 Kubernetes 공식 권장 사항과 유사하지만, 안정적인 On-Premise K8S 클러스터 운영을 위해서는 컨트롤 플레인 노드당 최소 2 vCPU와 4GB RAM을 권장합니다. 워커 노드는 배포할 워크로드의 크기에 따라 달라지지만, 최소 2 vCPU와 4GB RAM 정도가 필요하며, etcd를 별도 노드에 구성할 경우 etcd 노드에는 빠른 디스크 I/O 성능을 보장해야 합니다.
마무리하며
지금까지 Kubespray를 활용하여 On-Premise K8S 클러스터를 성공적으로 구축하는 전 과정을 상세하게 살펴보았습니다. Kubespray는 Ansible 기반의 강력한 자동화 도구로서, 복잡한 인프라 설정 단계를 표준화하고 오류 가능성을 획기적으로 줄여줍니다. 여러분은 환경 준비부터 인벤토리 구성, 실제 배포 및 검증, 그리고 향후 유지보수 전략까지 익히셨습니다.
On-Premise K8S 클러스터 구축에 있어 Kubespray는 가장 신뢰할 수 있는 선택지 중 하나이며, 이 가이드가 여러분의 프로젝트에 실질적인 도움이 되기를 바랍니다. Kubespray를 마스터하여 안정적인 사내 K8S 클러스터 운영의 기반을 다지시기를 응원합니다.