[Kubernetes] 설치 및 클러스터 구축 중 trouble shooting

ubuntu 환경에서 kubeadm, containerd, flannel을 사용하는 경우를 기준으로 작성하였습니다. 
 
 

0. 포트 점유 문제

init을 하려고 보니 `Port 10250 is in use`, `Port 6443 is in use`, `[ERROR Port-Availability]: Port 2379 is in use` 등등... 포트가 이미 점유되었다며 팽당한 경우의 해결입니다. 
만약 전에 하다가 말아먹고 reset한 기억이 있다면 찌꺼기를 치워주시고 다시 init부터 시작하시면 됩니다. 

sudo kubeadm reset
sudo systemctl stop kubelet
sudo systemctl stop containerd
sudo rm -rf /etc/cni/net.d
sudo rm -rf /var/lib/cni/
sudo rm -rf /var/lib/kubelet/*
sudo rm -rf /etc/kubernetes

 
엥 처음인디요? ㅠㅠ... 인 경우에는 기존에 microk8s나 minikube 등이 깔려있을 가능성이 높습니다. 다음 명령어로 조회해보시고... 

sudo ss -tulnp | grep -E '6443|2379|10250|10257'

여기 etcd, kube-controlle, kube-apiserver, kubelet 이외의 뭔가가 조회되면 금마를 싹 치우면 해결입니다. 

sudo snap remove [위에서조회된그놈!!]
sudo systemctl stop kubelet
sudo systemctl disable kubelet
sudo kubeadm reset -f

 
 

1. swap이 활성화됨

이 명령을 치셨을 때 뭔가가 출력된다면 swap 이슈입니다. 

swapon --show

kubelet은 swap 메모리를 극혐해서 만나자마자 픽 죽어버리는데, 만나버린 것입니다...  kubelet이 죽는 가장 대표적인 원인입니다.
즉시 swap을 off하고, 리부트되어도 다시 켜지지 않도록 설정 파일에서 주석처리 한 후 kubelet을 restart 해서 소생시켜주면 해결입니다. 

sudo swapoff -a
sudo sed -i '/\bswap\b/ s/^/#/' /etc/fstab
sudo systemctl restart kubelet.service

 
 

2. 필요한 모듈(overlay, br_netfilter)이 로드되지 않음 

이 명령에 결과가 둘 중 하나라도 결과가 출력되지 않는다면 해당 모듈이 올라오지 않은 상황입니다. 

lsmod | grep overlay
lsmod | grep br_netfilter

직접 모듈을 올려준 뒤 재부팅되어도 올라와있도록 설정 파일을 작성해주면 해결입니다. 

sudo modprobe overlay
sudo modprobe br_netfilter

cat <<EOF | sudo tee /etc/modules-load.d/k8s.conf
overlay
br_netfilter
EOF

 
 

3. br_netfilter 관련 설정이 활성화되지 않음

이 명령 결과에 0이 보이면 이 문제입니다. 

sysctl net.bridge.bridge-nf-call-iptables
sysctl net.bridge.bridge-nf-call-ip6tables
sysctl net.ipv4.ip_forward

싹다 활성화시킨 후 커널 설정을 restart해서 적용해주면 해결입니다. 

cat <<EOF | sudo tee /etc/sysctl.d/k8s.conf
net.bridge.bridge-nf-call-iptables  = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward                 = 1
EOF

sudo sysctl --system

 
 

4. containerd 이슈 

이 명령 결과에 active(running)이 떠있지 않거나 존재하지 않는다고 하면 containerd(컨테이너 런타임) 이슈입니다. (만약 docker나 cri-o를 쓰신다면 pass...ㅎㅎ)

sudo systemctl status containerd

직접 설치 또는 활성화를 해주면 해결입니다. 

# 설치하기 
sudo apt update
sudo apt install containerd -y

# 활성화하기
sudo systemctl enable containerd
sudo systemctl start containerd

 
 

5. containerd 설정파일 이슈

이 명령 결과에 .toml 파일이 조회되지 않으면 설정 파일이 만들어지지 못한겁니다. 

ls /etc/containerd/

만들어주면 해결입니다. 

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

sudo systemctl enable containerd
sudo systemctl restart containerd

만약 이미 있는 경우, 이 명령을 해서 Cgroup 설정이 Systemd로 되어있는지 확인해봅시다. 

cat /etc/containerd/config.toml | grep SystemdCgroup

false로 되어있다면 true로 변경해주면 해결입니다. 

sudo sed -i 's/SystemdCgroup = false/SystemdCgroup = true/g' /etc/containerd/config.toml

sudo systemctl enable containerd
sudo systemctl restart containerd

 
 

6. kube친구들이 설치되지 않음

아래 명령어를 했을 때 버전이 출력되지 않는게 있다면 잡았다 요놈입니다. 

kubeadm version
kubectl version
kubelet --version

설치해주면 해결입니다. 

echo "deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.30/deb/ /" | sudo tee /etc/apt/sources.list.d/kubernetes.list
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.30/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg

sudo apt update
sudo apt install -y kubeadm kubectl kubelet
sudo apt-mark hold kubeadm kubectl kubelet

 
 

7. flannel 이슈 

node들을 조회했을 때 영원히 Not Ready인 경우 -> 아래 명령으로 확인했을 때 STATUS가 Running이 아니라면 flannel 이슈입니다.

kubectl get pods -n kube-flannel -o wide

 
STATUS가 Running이 아닌 친구의 NODE 항목을 보시면 어느 노드인지가 나오는데, 그 노드에서 조치를 취해주셔야 합니다. 
지피티의 설명에 따르면 각 STATUS의 의미는 다음과 같습니다...

✅ 1. Pending

• 의미: Pod가 스케줄되었지만 아직 노드에 배치되지 못함.
• 주요 원인
  • kube-flannel Pod를 올릴 리소스가 부족함 (CPU, 메모리)
  • 필요한 이미지 다운로드가 지연됨
  • CNI 설정이 안 되어 있음
• 해결 방법
  • kubectl describe pod <pod이름> -n kube-flannel로 자세히 보기
  • 노드 상태가 NotReady면 CNI나 kubelet 확인
  • 리소스 부족 시 불필요한 pod 정리
  • containerd, kubelet 상태 확인

---

✅ 2. CrashLoopBackOff

• 의미: 컨테이너가 실행되었다가 비정상 종료되며 반복 재시도 중
• 주요 원인
  • 설정 오류 (예: 잘못된 CNI config)
  • 네트워크 관련 시스템 모듈 누락 (br_netfilter, overlay)
  • containerd에 문제가 있거나 runtime-endpoint 설정 오류
• 해결 방법
  • kubectl logs <pod이름> -n kube-flannel로 로그 확인
  • containerd 설정(/etc/containerd/config.toml) 및 서비스 상태 점검
  • /etc/crictl.yaml 안의 runtime-endpoint가 올바른지 (unix:///run/containerd/containerd.sock)

---

✅ 3. ImagePullBackOff / ErrImagePull

• 의미: 필요한 이미지를 가져오지 못함
• 주요 원인
  • 네트워크 오류
  • 이미지가 Docker Hub나 registry에서 삭제됨
  • proxy 설정 문제
• 해결 방법
  • kubectl describe pod ...로 이미지 URL 확인
  • 인터넷 연결 확인
  • 프록시/방화벽 설정 확인
  • 수동으로 이미지 풀(crictl pull <image>) 시도

---

✅ 4. Init:CrashLoopBackOff 또는 Init:Error

• 의미: initContainer에서 실패함
• 주요 원인
  • 초기 셋업 명령 오류
  • 필요한 파일/디렉토리/설정이 없음
• 해결 방법
  • kubectl describe pod ...에서 이벤트 로그 확인
  • 관련 설정 확인
  • mount volume 경로 등 재검토

---

✅ 5. Completed

• 의미: Pod가 정상적으로 종료됨 (일시적 Job에서만 정상)
• 주의사항: flannel은 지속적으로 동작하는 DaemonSet이므로 Completed가 나오면 비정상

---

✅ 6. Unknown

• 의미: kubelet이나 API 서버와의 통신 오류
• 해결 방법
  • 노드의 kubelet 상태 확인
  • kubelet, containerd, network 상태 확인
  • journalctl -u kubelet, journalctl -u containerd 등 확인

 
많은 경우 br_netfilter 모듈이 올라오지 않았거나 필요한 설정이 활성화되지 않은 문제인데, 2번 3번 항목을 시도해보시는걸 추천드립니다. 
만약 다음 명령 결과에도 Running 외의 STATUS가 있다면 flannel 자체가 설치되지 않은 경우입니다. 이건 마스터 문제입니다. 

kubectl get pods -n kube-system -l k8s-app=kube-dns

이 디렉토리를 확인해보셔야 합니다. 만약 디렉토리가 없거나 속에 든게 없으면 CNI가 설치되지 않은 경우이고, 마스터 문제입니다. 

ls /opt/cni/bin

직접 CNI를 다시 설치해주면 해결입니다. 

CNI_VERSION=$(curl -s https://api.github.com/repos/containernetworking/plugins/releases/latest | grep '"tag_name":' | sed -E 's/.*"([^"]+)".*/\1/')
sudo mkdir -p /opt/cni/bin
curl -L https://github.com/containernetworking/plugins/releases/download/${CNI_VERSION}/cni-plugins-linux-amd64-${CNI_VERSION}.tgz | sudo tar -C /opt/cni/bin -xz

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

cat <<EOF | sudo tee /etc/sysctl.d/k8s.conf
net.bridge.bridge-nf-call-iptables  = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward                 = 1
EOF

sudo sysctl --system

kubectl apply -f https://raw.githubusercontent.com/coreos/flannel/master/Documentation/kube-flannel.yml

 
 

 

 
 
 

+ 원큐에 설치하기 위한 흑마법

마스터노드 version 

#!/bin/bash

set -euo pipefail

echo "1. 시스템 업데이트 및 업그레이드 중..."
sudo apt update && sudo apt upgrade -y
echo "1단계 완료: 시스템 업데이트 및 업그레이드"

echo "2. 스왑 비활성화 및 fstab에서 스왑 주석 처리..."
sudo swapoff -a
sudo sed -i '/\bswap\b/ s/^/#/' /etc/fstab
echo "2단계 완료: 스왑 비활성화 완료"

echo "3. 커널 모듈 로드 및 설정 적용 중..."
sudo modprobe overlay
sudo modprobe br_netfilter
cat <<EOF | sudo tee /etc/modules-load.d/k8s.conf >/dev/null
overlay
br_netfilter
EOF
cat <<EOF | sudo tee /etc/sysctl.d/k8s.conf >/dev/null
net.bridge.bridge-nf-call-iptables  = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward                 = 1
EOF
sudo sysctl --system
echo "3단계 완료: 커널 모듈 및 sysctl 설정 적용"

echo "4. containerd 설치 및 설정 중..."
sudo apt install -y containerd
sudo mkdir -p /etc/containerd
sudo containerd config default | sudo tee /etc/containerd/config.toml >/dev/null
sudo sed -i 's/SystemdCgroup = false/SystemdCgroup = true/g' /etc/containerd/config.toml
sudo systemctl enable containerd
sudo systemctl restart containerd
echo "4단계 완료: containerd 설치 및 실행 완료"

echo "5. 쿠버네티스 apt 저장소 설정 및 설치 중..."
sudo mkdir -p /etc/apt/keyrings
echo "deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.30/deb/ /" | sudo tee /etc/apt/sources.list.d/kubernetes.list >/dev/null
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.30/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
sudo apt update
sudo apt install -y kubeadm kubectl kubelet
sudo apt-mark hold kubeadm kubectl kubelet
echo "5단계 완료: kubeadm, kubectl, kubelet 설치 완료"

echo "6. kubeadm 초기화 시작..."
sudo kubeadm init --pod-network-cidr=10.244.0.0/16 --cri-socket=unix:///run/containerd/containerd.sock
echo "6단계 완료: kubeadm 초기화 완료"

echo "7. kubeconfig 설정..."
mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config
echo "7단계 완료: kubeconfig 설정 완료"

echo "8. Flannel 네트워크 플러그인 적용 중..."
kubectl apply -f https://raw.githubusercontent.com/coreos/flannel/master/Documentation/kube-flannel.yml
echo "8단계 완료: Flannel 네트워크 플러그인 적용 완료"

echo "9. UFW 방화벽 설정 중..."
sudo ufw status verbose
for port in 6443 2379 2380 10250 10251 10252 8285 8472; do
  sudo ufw allow $port
  sudo ufw allow $port/udp
done
sudo ufw status verbose
echo "9단계 완료: 방화벽 포트 설정 완료"

echo "10. 노드 상태 확인..."
kubectl get nodes

echo "10단계 완료: 노드 상태 확인 완료"

# kubeadm join 커맨드 저장
JOIN_COMMAND=$(sudo kubeadm token create --print-join-command)

echo
echo "===== 워커 노드에서 사용할 join 명령어 ====="
echo "$JOIN_COMMAND"
echo "========================================="

워커노드 version 

#!/bin/bash

set -euo pipefail

echo "1. 시스템 업데이트 및 업그레이드 중..."
sudo apt update && sudo apt upgrade -y
echo "1단계 완료: 시스템 업데이트 및 업그레이드"

echo "2. 스왑 비활성화 및 fstab에서 스왑 주석 처리..."
sudo swapoff -a
sudo sed -i '/\bswap\b/ s/^/#/' /etc/fstab
echo "2단계 완료: 스왑 비활성화 완료"

echo "3. 커널 모듈 로드 및 설정 적용 중..."
sudo modprobe overlay
sudo modprobe br_netfilter
cat <<EOF | sudo tee /etc/modules-load.d/k8s.conf >/dev/null
overlay
br_netfilter
EOF
cat <<EOF | sudo tee /etc/sysctl.d/k8s.conf >/dev/null
net.bridge.bridge-nf-call-iptables  = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward                 = 1
EOF
sudo sysctl --system
echo "3단계 완료: 커널 모듈 및 sysctl 설정 적용"

echo "4. containerd 설치 및 설정 중..."
sudo apt install -y containerd
sudo mkdir -p /etc/containerd
sudo containerd config default | sudo tee /etc/containerd/config.toml >/dev/null
sudo sed -i 's/SystemdCgroup = false/SystemdCgroup = true/g' /etc/containerd/config.toml
sudo systemctl enable containerd
sudo systemctl restart containerd
echo "4단계 완료: containerd 설치 및 실행 완료"

echo "5. 쿠버네티스 apt 저장소 설정 및 kubeadm, kubelet 설치 중..."
sudo mkdir -p /etc/apt/keyrings
echo "deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.30/deb/ /" | sudo tee /etc/apt/sources.list.d/kubernetes.list >/dev/null
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.30/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
sudo apt update
sudo apt install -y kubeadm kubelet
sudo apt-mark hold kubeadm kubelet
echo "5단계 완료: kubeadm, kubelet 설치 완료"

echo "6. UFW 방화벽 설정 중..."
sudo ufw status verbose
for port in 6443 26443 8285 8472; do
  sudo ufw allow $port
  sudo ufw allow $port/udp
done
sudo ufw status verbose
echo "6단계 완료: 방화벽 포트 설정 완료"

echo
echo "===== 워커 노드에서 마스터 노드에서 받은 kubeadm join 명령어를 입력하세요 ====="
echo "예시: sudo [join 명령어] --cri-socket=unix:///run/containerd/containerd.sock"
echo "※ 마스터 노드에서 'kubeadm token create --print-join-command' 명령어로 join 커맨드를 생성할 수 있습니다."
echo "==============================================================================="

파이팅이어요