쿠버네티스(k8s) 온프레미스 환경으로 설치하기

현재 새로운 프로젝트에 앞서 docker compose를 이용해서 멀티 서버 환경을 구성했습니다. 서버에 장애를 확인하기 위해 모니터링까지 구축해놨지만 장애에 유기적으로 대응하는 부분은 부족하다고 느껴져 k8s에 대해 뒤적뒤적 거리게 되었습니다.
 
k8s를 구축하는데 있어서 클라우드를 활용할 수 있겠지만 우리의 경우 보안으로 인해 클라우드 환경은 이용할 수 없다는 제약이 존재 합니다.
그럼 결국 On-premise 환경으로 구축을 해야한다는 것을 의미합니다.
 
이번 k8s은 1.33.1 버전을 이용하여 구축하게 되었습니다. (2025-06-04 기준 최신버전)
 
우선은 서버1대 (Ubuntu 24.04 LTS)에 단일 노드 구성으로 진행하고 추후에 노드를 늘려가는식으로 진행하려 합니다.
 

1. 시스템 준비

sudo swapoff -a
sudo sed -i '/ swap / s/^/#/' /etc/fstab          # 영구 비활성화
sudo modprobe overlay br_netfilter
cat <<EOF | sudo tee /etc/sysctl.d/k8s.conf
net.bridge.bridge-nf-call-iptables  = 1
net.ipv4.ip_forward                 = 1
net.bridge.bridge-nf-call-ip6tables = 1
EOF
sudo sysctl --system

기본적으로 k8s는 swap 메모리를 비활성화 해야합니다. (swap 메모리를 간단히 얘기하면 RAM 용량이 부족할때 디스크용량을 추가로 이용하겠다는 개념입니다.)

2. Containerd Install

sudo apt-get update && sudo apt-get install -y containerd
sudo mkdir -p /etc/containerd
sudo containerd config default | sudo tee /etc/containerd/config.toml
sudo sed -i 's/SystemdCgroup = false/SystemdCgroup = true/' /etc/containerd/config.toml
sudo systemctl restart containerd && sudo systemctl enable containerd

최신 k8s은 docker container를 사용하지않고 Containerd를 자체적으로 사용합니다. (docker container로 내부적으론 containerd를 호출 하는 방식으로 알고 있습니다.)
 
그리고 config.toml파일에 SystemdCgroup = true로 변경해주어야 합니다.

3. kubelet, kubeadm, kubectl Install

# ① 키 보관 디렉터리 생성
sudo install -m 0755 -d /etc/apt/keyrings

# ② 커뮤니티 저장소용 GPG 키 내려받아 dearmor
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.33/deb/Release.key |
  sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-archive-keyring.gpg
sudo chmod go+r /etc/apt/keyrings/kubernetes-archive-keyring.gpg

# ③ APT 저장소 정의
echo "deb [signed-by=/etc/apt/keyrings/kubernetes-archive-keyring.gpg] \
https://pkgs.k8s.io/core:/stable:/v1.33/deb/ /" | \
  sudo tee /etc/apt/sources.list.d/kubernetes.list
  
sudo apt-get update

# (가장 간단) 최신 패치 수준 설치
sudo apt-get install -y kubelet kubeadm kubectl

# (지정 버전이 필요할 때) 먼저 버전을 확인하고 설치
apt-cache madison kubelet | head        # 1.33.1-1.1 같은 형식 확인
sudo apt-get install -y kubelet=1.33.1-1.1 kubeadm=1.33.1-1.1 kubectl=1.33.1-1.1

 

4. Version Hold

sudo apt-mark hold kubelet kubeadm kubectl

혹시 모를 버전 변경을 방지하고자 버전 유지를 진행합니다.

5. Cluster Init

sudo kubeadm init \
    --pod-network-cidr=10.244.0.0/16 \
    --kubernetes-version=1.33.1
    
# 완료 메시지에 kubeadm join 명령(토큰, hash 포함)이 출력되므로 기록.

여기서 발생하는 토큰은 나중에 새로운 노드를 클러스터로 join할때 사용하게 됩니다. hash값은 내가 연결하려는 API서버가 올바른 CA 인증서를 가진 클러스터인지를 검증하기 위한 공개키 지문입니다. 이 또한 클러스터로 join할때 사용됩니다.

6. kubectl 환경 구성

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

7. CNI적용 (e.g., Calico)

kubectl apply -f https://raw.githubusercontent.com/projectcalico/calico/v3.28.0/manifests/calico.yaml

CNI(Container Network Interface)에 줄임말이다. CNI는 새 파드 생성 시 가상 NIC-IP 라우팅 할당을 담당하며 파드 삭제 시 정리도 맡아준다. 

8. 단일노드 스케줄링 허용

kubectl taint nodes --all node-role.kubernetes.io/control-plane-

kubeadm은 기본적으로 제어플레인 노드에 node-role.kubernetes.io/control-plane:NoSchedule taint를 자동 추가합니다.
이는 "시스템 파드만 올라오고 일반 워크로드 파드는 배치 금지"라는 정책입니다. 현재는 단일노드로 일반 파드까지 띄워보기 위해서는 해당 정책을 꺼준다고 생각하면 됩니다.