Kubernetes 홈 서버 구축기 - (1)

이상윤·2026년 3월 23일

Kubernetes

목록 보기
1/6

기존 학교 서버 대여 기간이 끝나서, K8s 홈 서버 구축기를 다룰 예정이다.

학습용 간단한 MSA 서비스를 배포할 예정이고, 집 PC의 스펙이 여유롭지 않아서 Master 노드 1개와 Worker 노드 2개로 구성할 예정이다.

노드들의 스펙은 다음과 같이 정하였다.

Master Node

  • Cpu 2 Core, RAM 3GB

Worker Node

  • Cpu 1 Core, RAM 2GB

그리고 Ubuntu Live Server 22.04 LTS버전을 사용했으며, VM의 네트워크 설정에서 NAT대신 어댑터에 브리지 설정으로 대체하였다. 이는 각 VM이 공유기로부터 직접 IP를 할당받아 서로 다른 PC처럼 동작하도록 하기 위해서이며, 껐다 킬시 ip가 바뀌기 때문에 나중에 고정해 주어야 한다.

기본 설정은 Master나 Worker이나 똑같기 때문에 VM 1개를 apt upgrede까지 끝내면, 이제 본격적인 구축을 시작할 수 있다.

설치 과정은 다음 공식 Document를 따른다.

그럼 이제 필수 패키지들을 설치하자.

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

먼저 apt-transport-https는 우분투의 패키지 관리자인 apt가 일반적인 HTTP가 아닌, 암호화된 보안 통신망인 HTTPS 주소를 통해 패키지를 내려받을 수 있도록 도와주는 도구이다. 최근 우분투 버전에는 이 기능이 이미 포함되어 있는 경우가 많지만, 어떤 환경에서도 문제없이 작동하도록 관례적으로 가장 먼저 설치해 준다.

이렇게 보안 통신망을 준비했더라도, 접속하려는 사이트가 정말 믿을 만한 곳인지 확인하는 과정이 필요한데, 이때 ca-certificates가 그 역할을 한다. 이 패키지에는 전 세계적으로 신뢰받는 기관들이 발급한 디지털 인증서 목록이 들어있어, 컴퓨터가 HTTPS 사이트에 접속할 때 해당 사이트가 안전한지 실시간으로 판단할 수 있게 해준다.

마지막으로 파일이 도중에 변조되지는 않았는지, 정말 구글이나 쿠버네티스 팀에서 보낸 것이 맞는지를 확인해야 하는데, 이때 gpg가 그 역할을 수행하며, gpg는 내려받은 패키지에 찍힌 암호화 서명을 검증하여, 해당 파일이 제작자의 원본과 1%도 다르지 않다는 것을 최종적으로 보증해 준다.

이제 구글 클라우드 공개 샤이닝 키를 다운로드하자.

sudo mkdir -p -m 755 /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

그 다음으로는, 기본 apt 패키지에 kube 시리즈가 존재하지 않으므로 수동으로 추가해주자.

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 apt-get update
sudo apt-get install -y kubelet kubeadm kubectl
sudo apt-mark hold kubelet kubeadm kubectl

이때 각 도구들에 대해 간단히 알아보자.
1. kubeadm

쿠버네티스 클러스터를 구성하는 표준 설치 및 관리 도구이다.

주요 기능은 다음과 같다.

  • 인증서 및 토큰 관리
    각 컴포넌트 간 통신을 위한 TLS 인증서를 생성하고 노드 합류를 위한 보안 토큰을 발행한다.
  • 정적 포드 생성
    kube-apiserver, kube-controller-manager, kube-scheduler를 구동하기 위한 YAML 매니페스트를 생성한다.
  • 클러스터 생명주기 관리
    버전 업그레이드, 노드 초기화 등의 작업을 수행한다.

일회성 명령어로 실행되며, 설정이 완료된 후에는 상주하며 동작하지 않는다.

  1. kubelet

클러스터의 모든 노드에서 실행되는 핵심 에이전트이다.

주요 기능은 다음과 같다.

  • 컨테이너 실행 및 상태 감시
    API 서버로부터 전달받은 Pod의 명세를 확인하고, 컨테이너 런타임에 요청하여 컨테이너를 실행한다.

  • 상태 보고
    해당 노드의 자원 상태와 컨테이너의 헬스 체크 결과를 마스터 노드에 보고한다.

  • 정적 포드 감시
    특정 디렉터리를 모니터링하여 파일이 존재하면 API 서버 없이도 컨테이너를 직접 구동합니다.

이는 OS의 Systemd 서비스로 등록되어 백그라운드에서 항상 실행되며, 컨테이너 형태로 돌아가지 않는 유일한 핵심 컴포넌트이다.

  1. kubectl
    사용자가 쿠버네티스 API 서버와 통신하기 위해 사용하는 CLI이며, 가장 많이 사용하게 될 도구이다.

주요 기능은 다음과 같다.

  • API 호출
    사용자의 명령을 REST API 요청으로 변환하여 마스터 노드의 kube-apiserver에 전달한다.

  • 리소스 조작
    Pod, Service, Deployment 등 쿠버네티스 객체의 생성, 조회, 수정, 삭제(CRUD)를 수행한다.

  • 인증 및 컨텍스트 관리
    kubeconfig 파일을 참조하여 접속할 클러스터 정보와 사용자 권한을 확인한다.

그럼 우리가 내리는 명령이 어떻게 클러스터에 적용되는지 한번 알아보자.
1. 가장 먼저, 사용자가 kubectl apply -f pod.yaml 명령을 내린다.
2. kubectl은 사용자의 인증 정보를 확인하고, YAML 명세서를 마스터 노드의 kube-apiserver에 REST API 요청으로 전달한다.
3. kube-apiserver는 요청을 받아 etcd에 상태를 저장하고, Scheduler가 어느 노드에 배포할 지 결정하면 해당 노드의 kubelet에 작업 지시를 내린다.
4. 그럼 kubelet은 전달받은 pod의 명세를 확인하고, Container Runtime Interface(CRI)에 맞춰 Container Runtime에 컨테이너를 생성하라고 요청한다.
5. Container Runtime은 이미지가 있는지 확인하고, 하위 레벨 런타임을 호출하여 실제 컨테이너를 만들고 구동한다.

여기서 일반적으로 컨테이너 런타임은 containerd를 많이 사용하고, 하위 레벨 런타임은 runc를 많이 사용한다.

그럼 이제 마지막으로, 컨테이너 런타임으로 사용할 containerd를 설치해주자. containerd를 설치하면 의존성에 의해 runc가 같이 설치된다.

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

쿠버네티스 환경에서 containerd를 사용하려면, 컨테이너 런타임과 kubelet의 Cgroup 드라이버를 OS의 프로세스 관리 시스템(systemd)과 일치시켜야 한다. 이 이유는 나중에 정리하겠다.

다음 명령어를 수행해주자.

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

진짜 진짜 마지막으로, 쿠버네티스는 노드 간 패킷 라우팅과 포드 네트워크 통신에 리눅스 커널의 IP Forwarding 기능을 사용하기 때문에 이를 켜 주어야 한다.

sudo modprobe overlay
sudo modprobe br_netfilter

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

그러면 이제 kube관련 패키지 설치는 끝났고, 이제 VM 복사 후 노드 관련 설정을 해주자.

VM을 복사 할때는 다 어댑터에 브리지 형식으로 하고, IP주소가 다 다르게 해야한다. 그러고 접속을 하면 사용자 이름을 바꿔주어야 한다.

VM 종료 후 네트워크 설정 페이지에서 MAC Address를 새로고침 해주자.

그리고 접속 후 호스트이름을 변경해주어야 하는데, 다음 명령어로 hostname과 hosts파일의 내용을 변경해주자.

echo "Worker01" | sudo tee /etc/hostname
sudo tee /etc/hosts <<EOF
127.0.0.1 localhost
127.0.1.1 Worker01
EOF
sudo hostnamectl set-hostname Worker01

설정 후 재접속하면 다음과 같이 변경된 것을 볼 수 있다.

여기까지 VM 세팅과 패키지 설치를 마쳤고, 다음 포스팅에서는 노드 설정과 CNI설치 과정을 알아보겠다.

profile
이상윤
.
다음 포스트

Kubernetes 홈 서버 구축기 - (2)

0개의 댓글