kubeadm 쿠버네티스 설치

kubeadm으로 클러스터를 올리기 전, 마스터·워커 노드에 공통으로 해줘야 하는 준비 작업을 정리합니다.

⚠️ 저장소 변경 안내: 예전에는 apt.kubernetes.io / packages.cloud.google.com(kubernetes-xenial) 저장소를 썼는데, 이 레거시 저장소는 2023년 9월 동결된 뒤 2024년 3월 구글 호스팅 저장소가 완전히 폐지되어 더 이상 설치할 수 없습니다. 지금은 커뮤니티 소유 저장소인 pkgs.k8s.io 를 써야 합니다. 아래 예시는 이 최신 방식으로 작성했습니다.

1. 노드 공통 사전 설정

먼저 호스트명을 겹치지 않게 지정합니다. 노드 간 통신에 쓰이므로 중복되면 안 됩니다.

hostnamectl set-hostname master1   # 예: master1, worker1 ...
# 로그아웃 또는 재부팅으로 적용

swap을 끄고, 커널 모듈과 sysctl 값을 설정합니다.

# swap 비활성화 (/etc/fstab의 swap 라인도 주석 처리)
swapoff -a

# 커널 모듈
tee /etc/modules-load.d/k8s.conf <<EOF
overlay
br_netfilter
EOF
modprobe overlay
modprobe br_netfilter

# 네트워크 sysctl
tee /etc/sysctl.d/kubernetes.conf <<EOF
net.bridge.bridge-nf-call-ip6tables = 1
net.bridge.bridge-nf-call-iptables = 1
net.ipv4.ip_forward = 1
EOF
sysctl --system

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

쿠버네티스는 CRI(Container Runtime Interface)를 통해 컨테이너 런타임과 통신합니다. containerd를 설치할게요.

apt-get update
apt-get install -y ca-certificates curl gnupg

install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  | gpg --dearmor -o /etc/apt/keyrings/docker.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
https://download.docker.com/linux/ubuntu \
$(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
  | tee /etc/apt/sources.list.d/docker.list > /dev/null

apt-get update
apt-get install -y containerd.io

containerd 설정에서 SystemdCgroup을 반드시 켜야 kubelet과 cgroup 드라이버가 맞아 안정적으로 동작합니다.

mkdir -p /etc/containerd
containerd config default | tee /etc/containerd/config.toml
sed -i 's/SystemdCgroup = false/SystemdCgroup = true/g' /etc/containerd/config.toml

systemctl restart containerd
systemctl enable containerd

3. kubelet · kubeadm · kubectl 설치 (pkgs.k8s.io)

설치할 마이너 버전을 정해 저장소를 등록합니다. 예시는 v1.30 이며, 원하는 버전으로 바꾸면 됩니다.

apt-get update
apt-get install -y apt-transport-https ca-certificates curl gpg

# 커뮤니티 저장소 키 등록
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.30/deb/Release.key \
  | 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.30/deb/ /" \
  | tee /etc/apt/sources.list.d/kubernetes.list

apt-get update
apt-get install -y kubelet kubeadm kubectl
apt-mark hold kubelet kubeadm kubectl   # 자동 업그레이드 방지

apt-mark hold 는 패키지가 임의로 업그레이드되어 클러스터가 흔들리는 걸 막아줍니다. 버전을 올릴 때만 hold를 풀고 진행하세요.

마지막으로 자동완성을 걸어두면 편합니다.

echo "source <(kubectl completion bash)" >> ~/.bashrc

여기까지가 마스터·워커 공통 준비입니다. 다음 글에서 실제로 클러스터를 초기화하고 노드를 조인합니다.