Container Orchestration/Kubernetes

Kubernetes 클러스터 구축하기(kubespray 2025v.)

Somaz 2025. 7. 31. 07:00
728x90
반응형

Overview

이번 포스팅에서는 Kubespray를 이용해 Kubernetes 클러스터를 자동으로 설치하고 구성하는 방법을 알아보고, 나아가 Worker Node를 추가하여 확장하는 실습까지 진행해보았다.
 
Kubespray는 Ansible 기반의 프로비저닝 도구로, YAML 기반 인벤토리 파일만 정의하면 다양한 환경(GCP, AWS, 온프렘 등)에서 HA 구성을 포함한 쿠버네티스 클러스터를 유연하게 설치할 수 있는 강력한 툴이다.
 
 
이번 실습에서는 다음의 내용을 중심으로 진행하였다.

  • GCP 기반 Control/Worker Node VM 구성 (Terraform)
  • Kubespray 설치 및 Ansible 가상환경 구성
  • 클러스터 인벤토리 정의 및 Helm, MetalLB, Ingress 설정 포함
  • Ansible 플레이북을 통한 클러스터 설치 (cluster.yml)
  • 워커 노드 1대 추가 후 scale.yml 을 통한 확장 구성

 
 
추가적으로 kubectl, bashrc, 자동완성, 컨텍스트 설정 등 쿠버네티스 운영에 필요한 기본 설정도 함께 정리하였다.

출처 : https://medium.com/@sankalp_saxena/provisioning-ha-k8s-cluster-using-ansible-and-kubespray-using-ec2-instances-45a7b7365d97

 
 
 
 
 

 

Kubespray 설치

 
2025.07.30 기준이다.
 
 
 
 

 
 
 
 
 

시스템 구성

  • OS : Ubuntu 24.02 LTS(Focal)
  • Onpremise Server

 

Master Node(Control Plane) IP CPU Memory
k8s-control-01 10.10.10.17 4 24GB

 

Worker Node  IP CPU Memory
k8s-compute-01 10.10.10.18 12 48GB
k8s-compute-02 10.10.10.19 12 48GB

 
 
 
 
 
 

 
 
 
 
 
 

VM 생성

  • Cockpit 을 사용해서 생성했다.

 
 
 
 

SSH 키 생성 및 복사

ssh-keygen

# sudo vi /etc/hosts
10.10.10.17 k8s-control-01
10.10.10.18 k8s-compute-01
10.10.10.19 k8s-compute-02

ssh-copy-id k8s-control-01
ssh-copy-id k8s-compute-01
ssh-copy-id k8s-compute-02

# 확인
ssh k8s-control-01
ssh k8s-compute-01
ssh k8s-compute-02

 
 
 

패키지 설치

sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt-get -y update
sudo apt install -y python3.10 python3-pip git python3.10-venv
python3.10 --version

cp -rfp inventory/sample inventory/somaz-cluster

# 가상환경 생성 및 활성화
python3.10 -m venv venv
source venv/bin/activate

cd ~/kubespray
pip install -U -r requirements.txt

 
 
 
 

Kubespray 배포

  • 먼저 k8s-compute-01 까지만 설치해준 뒤 `scale.yml` 을 사용해서 k8s-compute-02를 추가 해볼 것이다.

 
 

인벤토리 수정

 
 
`inventory/somaz-cluster/inventory.ini`

[kube_control_plane]
k8s-control-01 ansible_host=10.10.10.17 ip=10.10.10.17 etcd_member_name=etcd1

[etcd:children]
kube_control_plane

[kube_node]
# node4 ansible_host=95.54.0.15  # ip=10.3.0.4
# node5 ansible_host=95.54.0.16  # ip=10.3.0.5
# node6 ansible_host=95.54.0.17  # ip=10.3.0.6
k8s-compute-01

 
 
 
`inventory/somaz-cluster/group_vars/k8s_cluster/k8s-cluster.yml`

...
# Choose network plugin (cilium, calico, kube-ovn, weave or flannel. Use cni for generic cni plugin)
# Can also be set to 'cloud', which lets the cloud provider setup appropriate routing
kube_network_plugin: cilium
...
#cluster_name: cluster.local
cluster_name: somaz-cluster.local

 
 
 
`inventory/somaz-cluster/group_vars/k8s_cluster/addons.yml`

# Helm deployment
helm_enabled: true
...
# Metrics Server deployment
metrics_server_enabled: true
...
# The plugin manager for kubectl
krew_enabled: true
krew_root_dir: "/usr/local/krew"
...

 
 
 

Ansible 통신 가능 확인

# 주의할점 ~/kubespray 해당경로에서 진행
ansible all -i inventory/somaz-cluster/inventory.ini -m ping

 
 

플레이북 실행

# 주의할점 ~/kubespray 해당경로에서 진행
ansible-playbook -i inventory/somaz-cluster/inventory.ini cluster.yml --become

# 백그라운드 실행
nohup ansible-playbook -i inventory/somaz-cluster/inventory.ini cluster.yml --become &

# scale
nohup ansible-playbook -i inventory/somaz-cluster/inventory.ini scale.yml --become &
nohup ansible-playbook -i inventory/somaz-cluster/inventory.ini scale.yml --limit add_node --become &

# remove
ansible-playbook -i inventory/somaz-cluster/inventory.ini remove-node.yml -b --extra-vars='node=node3' --extra-vars reset_nodes=true

 

자격증명 가져오기

mkdir ~/.kube
sudo cp /etc/kubernetes/admin.conf ~/.kube/config
sudo chown $USER:$USER ~/.kube/config

 

kubelet 설치 및 자동완성

echo '# kubectl completion and alias' >> ~/.bashrc
echo 'source <(kubectl completion bash)' >> ~/.bashrc
echo 'alias k=kubectl' >> ~/.bashrc
echo 'complete -F __start_kubectl k' >> ~/.bashrc

# bashrc 적용
source ~/.bashrc

 

설치 확인

k get nodes
NAME             STATUS   ROLES           AGE    VERSION
k8s-compute-01   Ready    <none>          2d4h   v1.33.3
k8s-control-01   Ready    control-plane   2d4h   v1.33.3

 
 
 

에러 확인

현재 cilium 권한 에러가 발생한다.

  • https://github.com/cilium/cilium/issues/23838

 
 
 

chown -R root:root /opt/cni/bin

k version
Client Version: v1.33.3
Kustomize Version: v5.6.0
Server Version: v1.33.3

containerd --version
containerd github.com/containerd/containerd/v2 v2.1.3 c787fb98911740dd3ff2d0e45ce88cdf01410486

k get ds cilium -n kube-system -o=jsonpath='{.spec.template.spec.containers[0].image}'
quay.io/cilium/cilium:v1.17.3@sha256:1782794aeac951af139315c10eff34050aa7579c12827ee9ec376bb719b82873

 
 
 
또는 아래와 같이 수정한다.
 
`inventory/somaz-cluster/group_vars/k8s_cluster/k8s-cluster.yml`

# default
kube_owner: kube

# 변경
kube_owner: root

 
 
 
 
 
 

 
 
 
 
 
 

Kubespray Worker Node 조인

 
 

Kubespray 배포

  • 이제 `scale.yml` 을 사용해서 k8s-compute-02를 추가 해본다.

 
 
 

인벤토리 수정

 
 
`inventory/somaz-cluster/inventory.ini`

# This inventory describe a HA typology with stacked etcd (== same nodes as control plane)
# and 3 worker nodes
# See https://docs.ansible.com/ansible/latest/inventory_guide/intro_inventory.html
# for tips on building your # inventory

# Configure 'ip' variable to bind kubernetes services on a different ip than the default iface
# We should set etcd_member_name for etcd cluster. The node that are not etcd members do not need to set the value,
# or can set the empty string value.
[kube_control_plane]
k8s-control-01 ansible_host=10.10.10.17 ip=10.10.10.17 etcd_member_name=etcd1

[etcd:children]
kube_control_plane

[kube_node]
# node4 ansible_host=95.54.0.15  # ip=10.3.0.4
# node5 ansible_host=95.54.0.16  # ip=10.3.0.5
# node6 ansible_host=95.54.0.17  # ip=10.3.0.6
k8s-compute-01
k8s-compute-02

[add_node]
k8s-compute-02

 
 
 

플레이북 실행

# scale.yaml 실행
nohup ansible-playbook -i inventory/concrit-cluster/inventory.ini scale.yml --limit add_node --become &

 
 
 

설치 확인

k get nodes
NAME             STATUS   ROLES           AGE    VERSION
k8s-compute-01   Ready    <none>          2d5h   v1.33.3
k8s-compute-02   Ready    <none>          2d4h   v1.33.3
k8s-control-01   Ready    control-plane   2d5h   v1.33.3

 

 

 

만약 에러 발생시 아래의 명령어를 실행 후 다시 `scale.yml` 실행한다. 

ansible-playbook -i inventory/concrit-cluster/inventory.ini playbooks/facts.yml --become

 

 


 
 

 
 
 
 

마무리: “운영 친화적인 Kubernetes 설치 자동화, Kubespray”

Kubespray는 단순 설치 자동화를 넘어 운영 환경 수준의 쿠버네티스 클러스터 구성을 가능하게 해준다.
 
특히 다음과 같은 경우에 유용하다.

  • Terraform + Ansible 연동을 통한 IaC 기반 인프라 관리
  • HA 클러스터, MetalLB/Ingress 구성 자동화
  • 온프레미스나 사설 클라우드에서 빠른 배포 필요 시
  • CI 환경에서 테스트 클러스터 생성 및 제거 반복

 
 
이번 실습을 통해 Kubernetes 설치 과정을 수동으로 반복하는 대신, 선언형 인벤토리 파일과 Ansible 플레이북으로 클러스터를 통제하는 방법을 체득할 수 있었다.
 
 
향후에는 다음과 같은 고급 기능 실습도 추천한다.

  • Control Plane 다중 구성 (HA 구성)
  • 외부 etcd 클러스터 연동
  • GitOps 도구 (ArgoCD, Flux)와의 통합
  • Prometheus/Grafana, Loki 등의 모니터링 연동
  • Worker Node 자동 스케일링 구성

 
 
Ansible 기반 자동화 → 클러스터 구축 → GitOps 기반 앱 배포라는 흐름을 갖추면 운영 자동화 수준을 한 단계 끌어올릴 수 있다.
 
 
 
 
 
 
 
 
 
 

Reference

https://github.com/kubernetes-sigs/kubespray

https://github.com/kubernetes-sigs/kubespray/blob/master/docs/operations/nodes.md#2-run-scaleyml

728x90
반응형
저작자표시 비영리 변경금지 (새창열림)

'Container Orchestration > Kubernetes' 카테고리의 다른 글

Kubernetes Local Storage Solutions: OpenEBS vs Longhorn vs Rook Ceph 완전 비교 가이드  (0) 2025.12.17
Containerd v3에서 Insecure Registry 설정 방식 변경  (0) 2025.11.26
Helmfile 완전 정복: 실무에서 Helm을 선언적으로 관리하는 방법  (0) 2025.06.16
Helm values.schema.json 완벽 정리  (0) 2025.05.29
배포하다 서비스 터진 적 있다면? 꼭 알아야 할 Kubernetes 전략 가이드  (2) 2025.05.28

'Container Orchestration/Kubernetes'의 다른글

  • 현재글Kubernetes 클러스터 구축하기(kubespray 2025v.)

관련글

댓글

티스토리툴바