Kubernetes 구축 완벽 가이드

Kubernetes 구축 완벽 가이드

Kubernetes(쿠버네티스, 줄여서 K8s)는 컨테이너화된 애플리케이션의 배포, 확장 및 관리를 자동화하는 오픈소스 플랫폼입니다. 이 가이드에서는 Kubernetes 클러스터를 처음부터 구축하는 방법을 단계별로 알아보겠습니다.

목차

1. Kubernetes란?
2. 사전 요구사항
3. 구축 방법 선택하기
4. Minikube로 로컬 환경 구축하기
5. Kubeadm으로 프로덕션 클러스터 구축하기
6. 클러스터 검증하기
7. 첫 애플리케이션 배포하기

1. Kubernetes란?

Kubernetes는 Google이 개발하고 현재는 Cloud Native Computing Foundation(CNCF)에서 관리하는 컨테이너 오케스트레이션 플랫폼입니다. 주요 기능은 다음과 같습니다:

• 자동화된 배포 및 롤백
• 서비스 디스커버리와 로드 밸런싱
• 스토리지 오케스트레이션
• 자동 복구(Self-healing)
• 시크릿 및 구성 관리

2. 사전 요구사항

Kubernetes를 구축하기 전에 다음 사항을 준비해야 합니다:

하드웨어 요구사항

• 마스터 노드: 최소 2GB RAM, 2 CPU 코어
• 워커 노드: 최소 1GB RAM, 1 CPU 코어 (노드당)
• 디스크 공간: 20GB 이상

소프트웨어 요구사항

• Linux 운영체제 (Ubuntu 20.04/22.04, CentOS 7/8, RHEL 등)
• 컨테이너 런타임 (Docker, containerd, CRI-O 중 하나)
• 네트워크 연결 및 고유 호스트명, MAC 주소, product_uuid

3. 구축 방법 선택하기

Kubernetes를 구축하는 방법은 여러 가지가 있습니다:

로컬 개발 환경

• Minikube: 단일 노드 클러스터, 학습 및 테스트용
• kind (Kubernetes in Docker): Docker 컨테이너 내에서 실행
• Docker Desktop: Windows/Mac에서 간편하게 사용

프로덕션 환경

• kubeadm: 수동 클러스터 구축 도구
• kops: AWS에 특화된 클러스터 관리 도구
• kubespray: Ansible 기반 배포 도구
• 관리형 서비스: EKS(AWS), GKE(Google Cloud), AKS(Azure)

이 가이드에서는 Minikube와 kubeadm을 중심으로 설명하겠습니다.

4. Minikube로 로컬 환경 구축하기

Minikube는 로컬 개발 및 학습에 최적화된 도구입니다.

4.1 Minikube 설치

# Linux에서 Minikube 다운로드 및 설치
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
sudo install minikube-linux-amd64 /usr/local/bin/minikube

# macOS에서 설치 (Homebrew 사용)
brew install minikube

# Windows에서 설치 (Chocolatey 사용)
choco install minikube

4.2 kubectl 설치

kubectl은 Kubernetes 클러스터와 상호작용하기 위한 커맨드라인 도구입니다.

# Linux
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl

# macOS
brew install kubectl

# Windows
choco install kubernetes-cli

4.3 Minikube 클러스터 시작

# 클러스터 시작
minikube start

# 특정 드라이버 지정 (Docker, VirtualBox, Hyper-V 등)
minikube start --driver=docker

# 리소스 설정
minikube start --cpus=4 --memory=8192

4.4 클러스터 상태 확인

# 클러스터 상태 확인
minikube status

# kubectl로 노드 확인
kubectl get nodes

# 대시보드 열기
minikube dashboard

5. Kubeadm으로 프로덕션 클러스터 구축하기

kubeadm은 프로덕션 수준의 클러스터를 구축할 수 있는 도구입니다.

5.1 모든 노드에서 사전 설정

다음 단계를 마스터 노드와 워커 노드 모두에서 실행해야 합니다.

스왑 비활성화

sudo swapoff -a
sudo sed -i '/ swap / s/^\(.*\)$/#\1/g' /etc/fstab

컨테이너 런타임 설치 (containerd)

# 필수 모듈 로드
cat <<EOF | sudo tee /etc/modules-load.d/containerd.conf
overlay
br_netfilter
EOF

sudo modprobe overlay
sudo modprobe br_netfilter

# 네트워크 설정
cat <<EOF | sudo tee /etc/sysctl.d/99-kubernetes-cri.conf
net.bridge.bridge-nf-call-iptables = 1
net.ipv4.ip_forward = 1
net.bridge.bridge-nf-call-ip6tables = 1
EOF

sudo sysctl --system

# containerd 설치
sudo apt-get update
sudo apt-get install -y containerd
sudo mkdir -p /etc/containerd
containerd config default | sudo tee /etc/containerd/config.toml
sudo systemctl restart containerd
sudo systemctl enable containerd

Kubernetes 구성 요소 설치

# 패키지 저장소 추가
sudo apt-get update
sudo apt-get install -y apt-transport-https ca-certificates curl

curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.28/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg

echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.28/deb/ /' | sudo tee /etc/apt/sources.list.d/kubernetes.list

# kubeadm, kubelet, kubectl 설치
sudo apt-get update
sudo apt-get install -y kubelet kubeadm kubectl
sudo apt-mark hold kubelet kubeadm kubectl

5.2 마스터 노드 초기화

마스터 노드에서만 실행합니다.

# 클러스터 초기화
sudo kubeadm init --pod-network-cidr=10.244.0.0/16

# 초기화 완료 후 출력되는 join 명령어를 저장해두세요!
# 예: kubeadm join 192.168.1.100:6443 --token abcdef.0123456789abcdef --discovery-token-ca-cert-hash sha256:...

# kubectl 설정
mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config

5.3 네트워크 플러그인 설치

Pod 간 통신을 위해 CNI(Container Network Interface) 플러그인이 필요합니다.

# Flannel 설치
kubectl apply -f https://github.com/flannel-io/flannel/releases/latest/download/kube-flannel.yml

# 또는 Calico 설치
kubectl apply -f https://docs.projectcalico.org/manifests/calico.yaml

# 또는 Weave Net 설치
kubectl apply -f https://github.com/weaveworks/weave/releases/download/v2.8.1/weave-daemonset-k8s.yaml

5.4 워커 노드 추가

각 워커 노드에서 마스터 노드 초기화 시 출력된 join 명령어를 실행합니다.

# 워커 노드에서 실행
sudo kubeadm join 192.168.1.100:6443 --token abcdef.0123456789abcdef \
    --discovery-token-ca-cert-hash sha256:1234567890abcdef...

토큰이 만료된 경우 마스터 노드에서 새 토큰을 생성할 수 있습니다:

# 마스터 노드에서 실행
kubeadm token create --print-join-command

6. 클러스터 검증하기

클러스터가 제대로 구축되었는지 확인합니다.

# 노드 상태 확인
kubectl get nodes

# 모든 Pod 확인
kubectl get pods --all-namespaces

# 클러스터 정보 확인
kubectl cluster-info

# 컴포넌트 상태 확인
kubectl get componentstatuses

모든 노드가 "Ready" 상태이고, 시스템 Pod들이 "Running" 상태이면 성공입니다!

7. 첫 애플리케이션 배포하기

Nginx 웹 서버를 배포해보겠습니다.

7.1 Deployment 생성

# Nginx 배포
kubectl create deployment nginx --image=nginx

# 배포 확인
kubectl get deployments
kubectl get pods

7.2 Service 생성

# NodePort 서비스로 노출
kubectl expose deployment nginx --port=80 --type=NodePort

# 서비스 확인
kubectl get services

# 서비스 접속 (Minikube의 경우)
minikube service nginx

7.3 Deployment 확장

# 레플리카 수 증가
kubectl scale deployment nginx --replicas=3

# 확인
kubectl get pods

7.4 애플리케이션 정리

# 리소스 삭제
kubectl delete service nginx
kubectl delete deployment nginx

추가 권장사항

모니터링 및 로깅

프로덕션 환경에서는 모니터링과 로깅이 필수입니다:

# Metrics Server 설치 (리소스 모니터링용)
kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml

# Prometheus & Grafana (상세 모니터링)
# Helm을 사용하여 설치 권장

# ELK/EFK Stack (로깅)
# Elasticsearch, Fluentd/Logstash, Kibana

Ingress Controller

외부 트래픽을 관리하기 위해 Ingress Controller를 설치합니다:

# NGINX Ingress Controller
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.8.1/deploy/static/provider/cloud/deploy.yaml

보안 강화

• RBAC(역할 기반 액세스 제어) 설정
• Network Policy 구성
• Pod Security Standards 적용
• 정기적인 보안 업데이트

문제 해결 팁

Pod가 Pending 상태인 경우

kubectl describe pod <pod-name>

일반적인 원인: 리소스 부족, 노드 selector 미스매치, PersistentVolume 이슈

노드가 NotReady 상태인 경우

kubectl describe node <node-name>
systemctl status kubelet
journalctl -xeu kubelet

일반적인 원인: kubelet 서비스 중단, 네트워크 플러그인 문제

네트워크 통신 문제

# DNS 확인
kubectl run -it --rm debug --image=busybox --restart=Never -- nslookup kubernetes.default

# Pod 간 통신 확인
kubectl run -it --rm debug --image=busybox --restart=Never -- ping <pod-ip>

마치며

Kubernetes 클러스터 구축은 처음에는 복잡해 보일 수 있지만, 한 단계씩 따라가면 충분히 가능합니다. 로컬 환경에서 Minikube로 시작해 개념을 익히고, 점진적으로 kubeadm을 사용한 멀티 노드 클러스터로 확장하는 것을 추천합니다.

더 자세한 내용은 공식 Kubernetes 문서를 참고하시기 바랍니다. Happy Kubernetes-ing! 🚀

참고 자료

• Kubernetes 공식 문서
• Minikube 문서
• kubeadm 문서
• Kubernetes The Hard Way