KyungRyeol Yoon KyungRyeol Yoon
Kubernetes · Cluster ·

[Kubernetes] kubeadm으로 쿠버네티스 클러스터 설치하기 (Ubuntu/Debian)

· 3분 읽기

🏗️ 1. 클러스터 구성 환경 #

본 가이드는 Ubuntu 20.04 LTS 이상 환경을 기준으로 작성되었습니다.

  • Master Node (1대): 클러스터 관리 및 제어 (최소 2 vCPU, 2GB RAM)
  • Worker Node (N대): 실제 컨테이너(Pod)가 실행되는 노드
  • OS: Ubuntu 20.04 / 22.04 LTS

⚙️ 2. 사전 준비 작업 (모든 노드 공통) #

쿠버네티스가 안정적으로 돌아가기 위해 시스템의 기초를 다지는 단계입니다. 모든 노드에서 실행해 주세요.

2.1 Swap 메모리 비활성화 🛑 #

쿠버네티스는 성능과 안정성을 위해 스왑 메모리를 사용하지 않습니다.

1# 즉시 비활성화
2sudo swapoff -a
3
4# 재부팅 시에도 적용되도록 설정 (fstab에서 swap 라인 주석 처리)
5sudo sed -i '/swap/s/^/#/' /etc/fstab
6
7# 확인 (Swap 항목이 0B여야 함)
8free -h

2.2 네트워크 브리지 및 커널 모듈 설정 🌐 #

노드 간 통신과 iptables가 브리지 트래픽을 올바르게 처리하도록 설정합니다.

 1cat <<EOF | sudo tee /etc/modules-load.d/k8s.conf
 2br_netfilter
 3EOF
 4
 5cat <<EOF | sudo tee /etc/sysctl.d/k8s.conf
 6net.bridge.bridge-nf-call-ip6tables = 1
 7net.bridge.bridge-nf-call-iptables = 1
 8net.ipv4.ip_forward = 1
 9EOF
10
11# 설정 적용
12sudo sysctl --system

📦 3. 컨테이너 런타임(Docker) 설치 #

요즘은 Containerd를 많이 쓰지만, 기본 학습을 위해 가장 친숙한 Docker를 설치하는 과정입니다.

 1# 패키지 업데이트 및 필수 도구 설치
 2sudo apt-get update
 3sudo apt-get install -y apt-transport-https ca-certificates curl gnupg lsb-release
 4
 5# Docker 설치
 6sudo apt-get install -y docker.io
 7
 8# Docker 서비스 활성화 및 시작
 9sudo systemctl enable --now docker
10
11# Docker cgroup driver를 systemd로 변경 (K8s 권장사항)
12cat <<EOF | sudo tee /etc/docker/daemon.json
13{
14  "exec-opts": ["native.cgroupdriver=systemd"],
15  "log-driver": "json-file",
16  "log-opts": {
17    "max-size": "100m"
18  },
19  "storage-driver": "overlay2"
20}
21EOF
22
23sudo systemctl restart docker

🛠️ 4. Kubernetes 컴포넌트 설치 #

클러스터 운영의 핵심 도구인 kubeadm, kubelet, kubectl을 설치합니다.

 1# 구글 클라우드 퍼블릭 키 다운로드
 2sudo curl -fsSLo /usr/share/keyrings/kubernetes-archive-keyring.gpg [https://packages.cloud.google.com/apt/doc/apt-key.gpg](https://packages.cloud.google.com/apt/doc/apt-key.gpg)
 3
 4# 쿠버네티스 리포지토리 추가
 5echo "deb [signed-by=/usr/share/keyrings/kubernetes-archive-keyring.gpg] [https://apt.kubernetes.io/](https://apt.kubernetes.io/) kubernetes-xenial main" | sudo tee /etc/apt/sources.list.d/kubernetes.list
 6
 7# 패키지 설치
 8sudo apt-get update
 9sudo apt-get install -y kubelet kubeadm kubectl
10
11# 버전 업데이트로 인한 혼란 방지를 위해 버전 고정
12sudo apt-mark hold kubelet kubeadm kubectl

🚩 5. 마스터 노드 초기화 (Master Node Only) #

이제 실제로 클러스터를 시작합니다. 마스터 노드에서만 실행하세요.

1# pod-network-cidr은 이후 설치할 CNI(예: Flannel)에 맞춰 설정합니다.
2sudo kubeadm init --pod-network-cidr=10.244.0.0/16

💡 초기화 완료 후 설정 (일반 사용자용) #

초기화가 끝나면 화면에 나오는 명령어를 복사해서 실행해 주세요.

1mkdir -p $HOME/.kube
2sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
3sudo chown $(id -u):$(id -g) $HOME/.kube/config

주의! 마지막에 출력되는 kubeadm join ... 명령어를 별도로 메모장 등에 꼭 저장해 두세요. 워커 노드를 연결할 때 필요합니다.

🤝 6. 네트워크 플러그인(CNI) 설치 #

파드(Pod)끼리 통신할 수 있도록 Flannel 네트워크를 설치합니다.

1kubectl apply -f [https://raw.githubusercontent.com/flannel-io/flannel/master/Documentation/kube-flannel.yml](https://raw.githubusercontent.com/flannel-io/flannel/master/Documentation/kube-flannel.yml)

✅ 7. 워커 노드 연결 및 상태 확인 #

이제 워커 노드로 가서 아까 저장해둔 join 명령어를 입력합니다.

1sudo kubeadm join <MASTER_IP>:6443 --token <TOKEN> \
2    --discovery-token-ca-cert-hash sha256:<HASH>

마지막으로 마스터 노드에서 상태를 확인합니다.

1kubectl get nodes
Advertisement
관련 글