[우리 FIS 아카데미 5기] DevOps - 쿠버네티스 클러스터 구축

💻 쿠버네티스 클러스터 구축 전체 과정 정리

환경 요약

• 하이퍼바이저: VirtualBox NAT 네트워크

• OS: Ubuntu Server 24.04

• CRI: containerd

• CNI: Calico

• 설치: kubeadm / kubelet / kubectl

1) 전체 아키텍처

구성

• myserver01 — master node(control-plane)

• myserver02 — worker node

• myserver03 — worker node

포트 포워딩

• myserver01 = 10.0.2.15

• myserver02 = 10.0.2.20

• myserver03 = 10.0.2.25

NAT 네트워크 설정

• 설정 → 네트워크 → NAT 네트워크로 변경

• 복제 VM은 MAC 주소 중복 주의 → Refresh 여러 번! (고유 MAC 필수)

• 세 노드(myserver01/02/03) 동일하게 적용
  

---

2) 고정 IP & 호스트명 설정

초기 복제 직후 01/02/03 모두 10.0.2.15 → 아래처럼 조정:

myserver01 → 10.0.2.15 (유지)

myserver02 → 10.0.2.20

myserver03 → 10.0.2.25

/etc/netplan/01-netcfg.yaml 파일 확인 후 수정

• 현재는 myserver01, myserver02, myserver03 같은 파일 내용

고정 IP 변경 후 적용

[myserver02]

• myserver03도 동일하게 설정

1. 고정 ip 변경

➡️ 확인!

# 적용
sudo netplan apply
# 확인
ip a

⚠️ 문제 발생! 도커 존재 → 도커 다 삭제

• 이전에 도커를 설치해둔 vm을 복제했기 때문..
• 기존 Docker 흔적 제거(복제본이면 특히!)
• Docker 없으면 생략

sudo apt-get purge -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo rm -f $(which docker)
sudo rm -rf /var/lib/docker
sudo rm -rf /var/lib/containerd
sudo rm -rf /etc/docker

#도커 확인
docker --version

2. 호스트명 변경

# 호스트 이름 설정
sudo hostnamectl set-hostname myserver02

# 확인
hostname

# 재부팅
sudo reboot

👀참고) /etc/hosts에 노드 이름 등록
: /etc/hosts는 IP ↔ 도메인/호스트명 매핑 테이블

• 직접 ip 입력하는 것 대신 호스트명으로 접속 가능
  ex) ssh ubuntu@10.0.2.20 -> ssh ubuntu@myserver02
  

---

3) 서버간 통신을 위한 ssh key 설정

1. ssh key 설정

# 키 생성
ssh-keygen -t rsa -b 4096

# 확인
ls -l .ssh

2. 원격 서버에 ssh 공개 키 추가

• 공개 키를 원격 서버의 ~/.ssh/authorized_keys 파일에 추가
• myserver01 ↔ myserver02 ↔ myserver03 서로서로 통신 가능
• 비밀번호 입력 없이 접근 가능

# 각 노드에서 상호 교차 등록

# 01
ssh-copy-id ubuntu@myserver02
ssh-copy-id ubuntu@myserver03

# 02
ssh-copy-id ubuntu@myserver01
ssh-copy-id ubuntu@myserver03

# 03
ssh-copy-id ubuntu@myserver01
ssh-copy-id ubuntu@myserver02

➡️ ssh ubuntu@myserver0# 로 비밀번호 없이 바로 접근 가능

---

4) Kubernetes 네트워크 설정을 위한 모듈 로드 설정 파일 생성

모든 노드(myserver01~03)에서 root로 적용:

# root 계정으로 진행
sudo -i

커널 모듈 설정 (모듈 로드)

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

# 설정 적용
modprobe overlay
modprobe br_netfilter

• /etc/modules-load.d/: 이 디렉터리에 있는 파일들은 시스템이 부팅될 때 자동으로 읽혀서, 여기에 적힌 커널 모듈들을 로드
• overlay: 레이어드 파일 시스템을 구현하는 모듈
  • 컨테이너 이미지가 여러 층(layer)으로 구성될 수 있게 함
• br_netfilter: 브릿지 네트워크를 통해 오가는 패킷에 iptables 규칙이 적용될 수 있도록 해주는 모듈
  • 쿠버네티스의 네트워크 정책과 서비스 라우팅에 필수적인 기능

sysctl 네트워크 파라미터 설정

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


# 변경사항 완전  적용
sysctl --system

net.ipv4.ip_forward = 1: IP forwarding을 활성화

• 리눅스 커널이 라우터처럼 동작하여, 서로 다른 네트워크 인터페이스 간에 패킷을 전달할 수 있음
• Pod 간의 통신에 필수적인 기능

---

5) containerd & Kubernetes 설치

containerd 설치/설정

# 컨테이너 설치 
sudo apt update && sudo apt install -y containerd

# 확인
containerd --version
systemctl status containerd

sudo mkdir -p /etc/containerd

sudo containerd config default | sudo tee /etc/containerd/config.toml > /dev/null

# sed 를 활용한 파일 편집 systemd cgroup 설정
sudo sed -i 's/SystemdCgroup = false/SystemdCgroup = true/g' /etc/containerd/config.toml

# false -> true 변경 확인
sudo cat /etc/containerd/config.toml | grep SystemdCgroup

kubeadm / kubelet / kubectl 설치

sudo apt-get update
sudo apt-get install -y apt-transport-https ca-certificates 

# 공식 저장소 키 & 레포
sudo mkdir -p /etc/apt/keyrings

curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.30/deb/Release.key | \
  sudo 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/ /" | \
  sudo tee /etc/apt/sources.list.d/kubernetes.list
  

# 저장소 활성화 옵션 추가
sudo tee /etc/apt/apt.conf.d/99allow-insecure-repositories <<EOF
APT::Get::AllowUnauthenticated "true";
Acquire::AllowInsecureRepositories "true";
Acquire::AllowDowngradeToInsecureRepositories "true";
EOF

# 업데이트 (인증 오류 무시) 
sudo apt-get update --allow-unauthenticated

# 패키지 설치 (사용 가능한 버전 찾기)
sudo apt-get install -y --allow-unauthenticated kubelet kubeadm kubectl


# 설치된 버전들 확인 
kubectl version --client --output=yaml
kubeadm version
kubelet --version

---

6) 마스터 초기화(myserver01)

# CNI 설치 및 클러스터 초기화   
# calico CNI 사용시 192.168.0.0/16 IP로 등록 / 쿠버네티스 Pod 네트워크 대역을 지정하는 설정
# Calico 공식 매니페스트(calico.yaml) 에 기본적으로 192.168.0.0/16 대역이 설정되어 있음

# containerd 로 설정하여 이미지를 받을수 있게 설정(20250922 기준 필요)
sudo kubeadm config images pull --cri-socket unix:///run/containerd/containerd.sock

kubectl apply -f https://docs.projectcalico.org/manifests/calico.yaml

sudo kubeadm init --apiserver-advertise-address=10.0.2.15 --pod-network-cidr=192.168.0.0/16 --cri-socket /run/containerd/containerd.sock

초기화 후 kubeconfig 설정:

# 클러스터 관리 설정
# config : Kubernetes 클러스터 접속 정보를 담고 있는 설정 파일
# 사용자가 k8s 활용 가능하도록 설정을 저장할 디렉토리 생성
# 설정 디렉터리의 소유자와 그룹을 변경해 현재 사용자가 사용할 수 있도록 변경
$ mkdir -p $HOME/.kube
$ sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
$ sudo chown $(id -u):$(id -g) $HOME/.kube/config 

# 확인
$ ls.kube/
config

• key 출력되면 워커 노드에게 배정
• key 값 분실시에는 새로 키 생성 또는 키 검색으로 해결해야 함

💥 트러블 슈팅 : 설치하다 중지 pending / not ready

방법 1) 직접 다운 받고 설치

$ curl https://docs.projectcalico.org/manifests/calico.yaml
$ kubectl apply -f calico.yaml

방법 2) 설정 파일 reset

sudo kubeadm reset -f
sudo systemctl stop kubelet
sudo systemctl stop containerd
sudo rm -rf /etc/kubernetes /var/lib/etcd
sudo systemctl start containerd
sudo kubeadm init --apiserver-advertise-address=10.0.2.15 --pod-network-cidr=192.168.0.0/16 --cri-socket /run/containerd/containerd.sock

방법 3) 이미지 레지스트리 교체 (도커 허브 풀 에러)

• docker.io/calico → quay.io/calico 치환

# 1) 매니페스트 내려받기
curl -fsSLO https://raw.githubusercontent.com/projectcalico/calico/v3.26.0/manifests/calico.yaml
# 2) docker.io/calico → quay.io/calico 로 치환
sed -i 's#docker.io/calico#quay.io/calico#g' calico.yaml
# 3) 적용
kubectl apply -f calico.yaml

---

7) 워커 노드 조인(myserver02, myserver03)

마스터에서 출력된 join 명령으로 조인

sudo kubeadm join 10.0.2.15:6443 \
  --token <토큰> \
  --discovery-token-ca-cert-hash sha256:<해시>

---

8) 상태 확인

kubectl get nodes -o wide

모든 노드가 Ready면 성공! 🎉

---

부록: 체크리스트

• VM NAT 네트워크 & 포트포워딩 구성
• MAC 주소 중복 없음(복제 후 Refresh)
• 고정 IP: 01=10.0.2.15, 02=10.0.2.20, 03=10.0.2.25
• 호스트명 정확히 설정(myserver01/02/03)
• /etc/hosts에 노드명/IP 등록
• SSH 키 상호 교환(무비번)
• overlay, br_netfilter 모듈 & sysctl 적용
• containerd 설치 및 SystemdCgroup=true
• kubeadm/kubelet/kubectl 설치
• kubeadm init → kubeconfig 세팅
• Calico 적용(필요 시 레지스트리 교체)
• 워커 kubeadm join 완료 → kubectl get nodes Ready