Profile picture

[Ansible] 앤서블 기반 Kubespray로 쿠버네티스 정말 간단하게 설치하기!

JaehyoJJAng2025년 05월 21일

개요

이전에 저는 앤서블로 쿠버네티스를 설치하는 방법에 대해서 기록하였습니다.


이번 게시글에서는 Kubespray라는 앤서블 기반의 프로젝트를 활용하여 정말! 간편하게 쿠버네티스를 설치하는 방법에 대해서 기록해보려고 합니다.


Kubespray란 무엇일까요? 🤔


Kubespray는 앤서블 플레이북을 기반으로 운영 환경 수준의 쿠버네티스 클러스터를 쉽고 안정적으로 배포하고 관리할 수 있게 해주는 오픈소스 프로젝트입니다.


복잡한 설치 과정을 미리 작성된 자동화 스크립트(플레이북)를 실행하는 것만으로 대체할 수 있죠.


Kubespray의 핵심 장점!

  • ⚙️ 자동화와 일관성: 수동 작업에서 발생하는 실수를 원천 차단하고, 언제나 동일한 구성의 클러스터를 만들 수 있습니다.
  • 🎨 유연한 맞춤 설정: Calico, Cilium, Flannel 등 다양한 CNI(네트워크 플러그인)와 클라우드 환경, 다양한 리눅스 배포판(Ubuntu, CentOS 등)을 지원하며, 원하는 구성 요소를 변수 설정만으로 쉽게 변경할 수 있습니다.
  • 🚀 운영 환경 수준의 구성: 단순히 쿠버네티스만 설치하는 것이 아니라, 운영에 필요한 다양한 구성(HA 구성, 인증서 관리 등)을 포함하여 안정적인 클러스터 구축이 가능합니다.
  • 🔄 클러스터 생명주기 관리: 신규 노드를 추가하거나(Scale-Out), 클러스터 버전을 업그레이드하는 복잡한 작업도 Kubespray를 통해 자동화할 수 있습니다.

Kubespray 동작 원리 및 예시

Kubespray의 핵심은 인벤토리(Inventory) 파일 에 원하는 클러스터의 구성을 정의하는 것입니다.


어떤 서버가 마스터 노드가 될지, 어떤 서버가 워커 노드가 될지 등을 ini 형식의 파일에 간단히 명시하기만 하면 됩니다.


앤서블은 이 인벤토리 파일을 읽어서. 각 서버의 역할에 맞는 플레이북을 자동으로 실행하여 쿠버네티스 클러스터를 구성합니다.


인벤토리 파일 예시 (inventory.ini)

예를 들어, 1개의 마스터 노드와 1개의 워커 노드를 가진 클러스터를 구성한다고 가정해 보겠습니다.

# ## 인벤토리 설정 ##
[all]
master   ansible_host=192.168.219.140   ip=192.168.10.11   ansible_user=master
node     ansible_host=192.168.219.141   ip=192.168.10.21   ansible_user=node

# ## 역할(Role) 정의 ##
# 쿠버네티스 컨트롤 플레인 및 etcd 역할을 할 노드 그룹
[kube_control_plane]
master

[etcd]
master

# 쿠버네티스 워커 노드 역할을 할 노드 그룹
[kube_node]
node

# 위 그룹들을 모두 포함하는 k8s 클러스터 그룹
[k8s_cluster:children]
kube_control_plane
kube_node

이렇게 서버 IP와 역할을 정의해두기만 하면, kubespray가 나머지 복잡한 설치 과정은 모두 알아서 처리해줍니다!


Kubespray로 쿠버네티스 클러스터 구축하기 🚀

image

이제 직접 kubespray를 사용하여 쿠버네티스 클러스터를 구축해보겠습니다.


0. 사전 준비물

  • 1. 앤서블 컨트롤 노드: 앤서블 명령을 실행할 PC 또는 서버
  • 2. 타겟 노드: 쿠버네티스 마스터/워커 노드가 될 서버들
  • 3. SSH 키 기반 통신: 컨트롤 노드에서 모든 타겟 노드로 비밀번호 없이 SSH 접속이 가능해야 함. (ssh-copy-id 사용)
  • 4. 파이썬: 컨트롤 노드에 Python 3와 pip가 설치되어 있어야 함. (최신 배포판에는 Python3가 탑재되어 있음.)

위 구성이 완료되었다면, 아래 앤서블 ad-hoc을 실행하여 정상적으로 앤서블 서버와 관리 노드간 통신이 되는지 테스트해봅시다.

ansible -i inventory.ini kube_node -m ping

node | SUCCESS => {
    "ansible_facts": {
        "discovered_interpreter_python": "/usr/bin/python3"
    },
    "changed": false,
    "ping": "pong"
}

1. Kubespray 다운로드 및 의존성 설치

먼저 컨트롤 노드에서 Kubespray 프로젝트를 클론하고, 필요한 파이썬 라이브러리를 설치합니다.

# Kubespray 소스 코드 다운로드
git clone https://github.com/kubernetes-sigs/kubespray.git

# 프로젝트 디렉토리로 이동
cd kubespray

# 가상 환경을 만들겠습니다.
python3 -m venv venv
source venv/bin/activate

# 필요한 파이썬 라이브러리 설치
pip install --upgrade pip
pip install ansible-core==2.17.3
pip install -r requirements.txt

2. 인벤토리 구성

Kubespray에서 기본적으로 제공되는 샘플 인벤토리를 복사하여 저만의 클러스터 구성을 만들어주겠습니다.

# 샘플 인벤토리를 'mycluster' 라는 이름으로 복사
cp -rfp inventory/sample inventory/mycluster

이제 inventory/mycluster/inventory.ini 파일을 열고, 위에서 설명한 예시처럼 자신의 서버 IP와 역할을 맞게 수정합니다.


3. [선택] 클러스터 설정 커스터마이징

kubespray는 매우 상세한 설정 변경을 지원합니다.

예를 들어, 네트워크 플러그인을 기본값인 Calico에서 Cilium으로 바꾸고 싶다면 아래 파일에서 변수 하나만 수정하면 됩니다.

  • 파일 위치: inventory/mycluster/group_vars/k8s_cluster/k8s-cluster.yml
  • 변경 내용: kube_network_plugin: calico -> kube_network_plugin: cilium

이 외에도 쿠버네티스 버전, 대시보드 설치 여부 등 거의 모든 설정을 group_vars 디렉토리 안의 *.yml 파일들에서 변경할 수 있습니다.


4. 플레이북 실행

모든 준비가 끝났습니다. 이제 아래 명령어로 앤서블 플레이북을 실행하면 설치가 자동으로 시작됩니다.

ansible-playbook -i inventory/mycluster/inventory.ini --become --become-user=root --ask-become-pass cluster.yml

5. 클러스터 설치 확인

설치가 완료되면 마스터 노드에 접속하여 클러스터가 정상적으로 생성되었는지 확인합니다.

# 모든 노드가 'Ready' 상태인지 확인
kubectl get nodes -o wide

# 시스템 파드들이 모두 'Running' 상태인지 확인
kubectl get pods -A
    Tag -
Loading script...