[k8] kubeadm을 이용한 Kubernetes 클러스터 구축하기

kubeadm은 Kubernetes 공식 프로젝트에서 제공하는 유틸리티로, 쿠버네티스 클러스터를 부트스트랩(초기화 맟 설정)할 수 있습니다. kubeadm을 사용해 Kubernetes 클러스터를 설정하는 단계를 하나씩 살펴보겠습니다.

 

1. 가상 머신 준비

하나의 Master와 2개의 Worker-node로 이루어진 쿠버네티스 클러스터를 셋업합니다.

(1) hosts 파일 수정

vim /etc/hosts 

172.16.4.67     k8-master 
172.16.4.68     worker1 
172.16.4.69     worker2

 
(2) swap 구성 

sudo swapoff –a 
sudo vim /etc/fstab 에서  swap~ 라인 주석 처리 
mount -a

(3) IPv4 패킷 포워딩 활성화 

# sysctl params required by setup, params persist across reboots 
cat <<EOF | sudo tee /etc/sysctl.d/k8s.conf 
net.ipv4.ip_forward = 1 
EOF 
 
# Apply sysctl params without reboot 
sudo sysctl --system

# 확인  
sysctl net.ipv4.ip_forward

 

2. container runtime 설치 

여기서는 컨테이너 런타임으로 containerd를 사용합니다. 모든 노드에 containerD를 설치하세요.

OS-ubuntu에 containerd 설치

# Docker의  apt 리포지토리 설정 
# Add Docker's official GPG key: 
sudo apt-get update 
sudo apt-get install ca-certificates curl 
sudo install -m 0755 -d /etc/apt/keyrings 
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc 
sudo chmod a+r /etc/apt/keyrings/docker.asc 

# Add the repository to Apt sources: 
echo \ 
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian \ 
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \ 
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null 
sudo apt-get update 

#containerd 패키지 설치 
sudo apt-get install -y containerd.io  
sudo systemctl status containerd.service

 

3. kubeadm 설치

 kubeadm은 Kubernetes 클러스터를 부트스트랩(초기화 및 구성)하기 위해, 필요한 구성 요소들을 각 노드에 올바른 순서로 설치하고 설정해 줍니다. 모든 노드에 kubeadm을 설치하세요.

#Kubernetes apt 저장소를 설정 
sudo apt-get update 
sudo apt-get install -y apt-transport-https ca-certificates curl gnupg 

# If the folder `/etc/apt/keyrings` does not exist, it should be created before the curl command, read the note below. 
# sudo mkdir -p -m 755 /etc/apt/keyrings 
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.34/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg 
sudo chmod 644 /etc/apt/keyrings/kubernetes-apt-keyring.gpg # allow unprivileged APT programs to read this keyring 
 
# This overwrites any existing configuration in /etc/apt/sources.list.d/kubernetes.list 
echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.34/deb/ /' | sudo tee /etc/apt/sources.list.d/kubernetes.list 
sudo chmod 644 /etc/apt/sources.list.d/kubernetes.list   # helps tools such as command-not-found to work correctly 


sudo apt-get update 
sudo apt-get install -y kubelet kubeadm kubectl 
sudo apt-mark hold kubelet kubeadm kubectl 
(선택) sudo systemctl enable --now kubelet

 

4. cgroup 드라이버 설정 

cgroup은 리눅스 커널의 기능(primitive)으로, 프로세스(또는 컨테이너)가 사용할 수 있는 시스템 자원(CPU, 메모리, 디스크 I/O 등)을 제한하거나 관리할 수 있게 해줍니다. 예를 들어, 특정 컨테이너의 메모리 사용량을 512MB로 제한하고 싶다면, 실제로 그 제한을 적용해주는 역할을 하는 것이 바로 cgroup입니다. Docker나 Kubernetes 역시 이 기능을 기반으로 동작합니다.

 

컨테이너 런타임과 kubelet에는 각각 "cgroup driver"라는 설정 항목이 있으며, 이는 리눅스 시스템에서 cgroup을 어떻게 관리할지를 결정하는 중요한 요소입니다.

 

kubelet과 컨테이너 런타임(containerd 등)을 설정할 때 사용할 수 있는 cgroup driver는 다음 두 가지입니다

• cgroupfs
• systemd

두 가지 중 어떤 것을 사용해도 되지만, 반드시 kubelet과 컨테이너 런타임 모두 동일한 cgroup driver를 사용하도록 설정해야 합니다. 특히 시스템의 init system이 systemd인 경우, cgroupfs 드라이버는 권장되지 않습니다. 그 이유는 systemd가 시스템에서 하나의 cgroup 관리자만 존재하기를 기대하기 때문입니다.

 

먼저 기반 시스템에서 사용 중인 init system을 확인하려면 다음 명령어를 실행하세요. 그리고 init system이  systemd 이면, cgroup driver로 systemd driver를 사용하세요.

ps -p 1

 

(1) kubectl

다행히, Kubernetes v1.22 버전부터, kubeadm을 사용해 클러스터를 생성할 때 사용자가 KubeletConfiguration에서 cgroupDriver 필드를 직접 설정하지 않으면, kubeadm은 기본값으로 systemd를 사용하도록 설정합니다. 

 

(2) conatinerd

sudo containerd config default \
  | sed 's/SystemdCgroup = false/SystemdCgroup = true/' \
  | sudo tee /etc/containerd/config.toml > /dev/null

# 확인
cat /etc/containerd/config.toml | grep -i SystemdCgroup -B 50

# 서비스 재시작
sudo systemctl restart containerd

 

SystemdCgroup = true 로 올바르게 설정되었다면 containerd 서비스를 재시작하세요.

 

5. Control -plane 노드 초기화  

Control-plane 노드를 초기화합니다. 이 때  필요한 모든 구성 요소가 마스터 서버에 설치되고 설정됩니다. 

# Master node only 
sudo kubeadm init --apiserver-advertise-address 172.16.4.67 --pod-network-cidr "10.244.0.0/16" --upload-certs

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

# 확인  
kubectl get nodes -o wide

 

• --pod-network-cidr
  사용할 Pod 서브넷(pod subnet) 을 반드시 명시해야 합니다. --pod-network-cidr 옵션은 파드들이 실제로 IP 주소를 할당받게 될 서브넷 범위를 지정하는 설정입니다. 예를 들어, 10.200.0.0/16 으로 설정하면, 클러스터 내의 모든 파드가 10.200.0.0/16 서브넷 범위 내에서 IP 주소를 할당받게 됩니다.
• --apiserver-advertise-address
  to tell the cluster what IP address is going to be for your kubeAPI server. So this will set this to be the IP address of our master node.
• --upload-certs
  upload all of the certificates to a secret, so that all of the other nodes will nave access to the certificates.

 

클러스터를 사용하려면 일반 사용자로서 다음 명령어를 실행합니다.

  mkdir -p $HOME/.kube
  sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
  sudo chown $(id -u):$(id -g) $HOME/.kube/config
  
  # 테스트
  kubectl get nodes -w

 

control-plane 노드가 NotReady입니다. 이유는 아직 네트워크 플러그인을 설치하지 않아서 입니다. 

[NOTE] 마스터가 초기화된 후, 워커 노드를 마스터에 조인하기 전에 Pod Network를 설정이 올바른지 확인하세요.

6. CNI 플러그인 설치

클러스터 내 모든 파드(Pod) 간의 통신을 가능하게 하기 위해 CNI 플러그인을 설치합니다. 

 

(1) 클러스터의 모든 노드에서 다음 명령어를 실행하세요. 

sudo modprobe br_netfilter

br_netfilter 모듈은 iptables가 브리지된 트래픽을 볼 수 있도록 해주며, 이는 Kubernetes 네트워킹(특히 Flannel 및 kube-proxy 사용 시)에 필수적입니다. 이 모듈이 없으면 패킷 포워딩이나 방화벽 규칙이 제대로 작동하지 않습니다.

 

 

(2) sysctl 설정이 올바르게 구성되어 있는지 확인하세요.

echo 'net.bridge.bridge-nf-call-iptables = 1' | sudo tee -a /etc/sysctl.d/99-kubernetes-cri.conf
echo 'net.bridge.bridge-nf-call-ip6tables = 1' | sudo tee -a /etc/sysctl.d/99-kubernetes-cri.conf

sudo sysctl --system

 

(3) 부팅 시 해당 모듈이 자동으로 로드되도록 설정하세요.

echo br_netfilter | sudo tee -a /etc/modules-load.d/k8s.conf

 

(4) CNI 플러그인을 설치하세요. 2가지 예시를 보여드리니, 2개중 하나만 설치합니다. 

 

• flannel

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

• calico

# cni network 설치
kubectl apply -f https://raw.githubusercontent.com/projectcalico/calico/v3.27.2/manifests/calico.yaml

 

이 때 control-plane에만 설치하면 돼요.이 작업은 네트워크 플러그인 에이전트의 인스턴스를 모든 노드에 하나씩 배포하게 됩니다. 이를 통해 각 노드에서 네트워크를 실제로 처리할 수 있게 됩니다.

 

 

만약 위처럼 오류가 있다면 수정 후에 Flannel 파드를 다음처럼 재시작하세요. 

kubectl delete pod -n kube-flannel -l app=flannel

 

다음처럼 Kubernetes가 자동으로 다시 생성합니다.

6. 워커노드 조인

마지막으로 워커 노드를 마스터 노드에 조인(join)하세요. 이 과정을 완료하면 Kubernetes 환경에서 애플리케이션을 실행할 준비가 완료됩니다