그동안은 쿠버네티스 환경을 구성할 때 강사님께서 주시는 vagrantfile을 그저 받아서 vagrant up을 하여
설치환경을 구성하였는데, 이제는 단순한 실습 환경을 넘어서,
인프라 관리자의 관점에서 쿠버네티스를 어떻게 설치해야 하는지를
공식 문서를 기준으로 하나씩 확인하며 정리할 필요가 있다고 느꼈다.

이 포스팅은
쿠버네티스 공식 문서를 따라가며
설치 전 사전 조건부터 컨테이너 런타임, 네트워크 플러그인까지
“왜 이 설정이 필요한지”를 중심으로 정리한 기록이다.

쿠버네티스 공식 홈페이지 - kubeadm

이렇게 쿠버네티스 공식 홈페이지에 들어가게되면

기초적으로 확인할 , 필수포트와 스왑 구성을 해야한다고 나와있다.

1. 필수 포트 확인

필수 포트 확인에 대한 내용은 아래 공식 문서를 참고하였다.
쿠버네티스 공식 홈페이지 - 포트와 프로토콜

쿠버네티스 설치 전에는 필수 포트가 네트워크 상에서 차단되어 있지 않은지를 확인해야 한다.
이는 해당 포트에 서비스가 이미 실행 중이어야 한다는 의미가 아니라,
설치 이후 쿠버네티스 컴포넌트들이 사용할 수 있도록 포트가 열려 있어야 한다는 의미이다.

대표적으로 쿠버네티스 API 서버는 기본적으로 6443/TCP 포트를 사용한다.

다음은 API 서버 포트를 확인할 때 사용할 수 있는 명령어 예시이다.

nc 127.0.0.1 6443 -zv -w 2

이 명령은 다음을 의미한다.

• 127.0.0.1 : 로컬 노드
• 6443 : 쿠버네티스 API 서버 포트
• -z : 실제 데이터 전송 없이 포트 상태만 확인
• -v : 상세 출력
• -w 2 : 타임아웃 2초

실제 실행 결과와 그 의미

로컬 환경에서 위 명령을 실행했을 때 다음과 같은 출력이 나타났다.

이 결과는 포트가 차단되어 있다는 의미가 아니다.

Connection refused 는
해당 IP와 포트에 현재 리스닝 중인 프로세스가 존재하지 않는다는 의미이다.

즉, 다음과 같은 상황을 의미한다.

• 방화벽에 의해 포트가 막힌 상태 → 아님
• 해당 노드에 API 서버 프로세스가 실행 중 → 아님

본 실습 환경에서는 이 명령을 쿠버네티스 컨트롤 플레인 노드가 아닌 로컬 PC에서 실행했기 때문에,
127.0.0.1:6443 에 kube-apiserver 프로세스가 존재하지 않아 위와 같은 결과가 출력되었다.

공식 문서의 예제를 어떻게 이해해야 하는가

중요한 점은,
공식 문서에 제시된 nc 명령이 쿠버네티스 설치 전에 반드시 실행해야 하는 절차는 아니라는 점이다.
(그래서 현재 시점에서는 중요한게 아니다.)

해당 예제는 다음을 설명하기 위한 것이다.

쿠버네티스 API 서버는 기본적으로 6443 포트를 사용한다

설치 이후, 또는 운영 중 장애 상황에서

API 서버 포트가 정상적으로 열려 있는지 이런 방식으로 확인할 수 있다

즉, 설치 전 단계에서는 이 명령의 성공 여부를 확인하는 것이 목적이 아니라,
해당 포트가 방화벽·네트워크 정책 상 차단되지 않도록 사전에 설계되어 있어야 한다는 점을 인지하는 것이 목적이다.

2. 스왑 구성

스왑(Swap) 구성에 대해서는 쿠버네티스 공식 문서에서 다음과 같이 명시하고 있다.

쿠버네티스에서 kubelet은 기본적으로 스왑 메모리가 활성화되어 있으면 실행에 실패하도록 설계되어 있다.
이는 쿠버네티스가 노드의 메모리 상태를 정확하게 인지하고,
파드의 리소스 사용량을 안정적으로 제어하기 위함이다.

왜 쿠버네티스는 스왑을 허용하지 않을까

리눅스에서 스왑은
물리 메모리가 부족할 때 디스크 공간을 메모리처럼 사용하는 기능이다.

하지만 쿠버네티스 환경에서는 이 방식이 문제가 된다.

• 스왑은 디스크 I/O를 사용하기 때문에 성능 예측이 어렵다
• kubelet은 파드의 메모리 사용량을 기준으로 스케줄링과 eviction을 수행한다
• 스왑이 활성화되어 있으면 실제 메모리 사용량을 정확히 판단하기 어렵다

이로 인해 쿠버네티스는 “메모리가 부족하면 느리게 버티는 것”보다
“명확하게 OOM을 발생시키는 것”을 더 안전한 동작으로 판단한다.

그래서 기본 정책은 다음과 같다.

스왑이 켜져 있으면 kubelet은 실행되지 않는다.

스왑 비활성화 방법

쿠버네티스를 설치하기 위해서는 노드에서 스왑을 비활성화해야 한다.

우선 현재 활성화된 스왑을 즉시 비활성화한다.

swapoff -a

이 명령은 현재 실행 중인 시스템에서만 스왑을 끄는 임시 설정이다.

재부팅 후에도 스왑이 다시 활성화되지 않도록 하기 위해
/etc/fstab 파일에서 스왑 설정을 주석 처리한다.

sed -i '/ swap / s/^/#/' /etc/fstab

이렇게 설정하면 시스템 재부팅 이후에도 스왑이 비활성화된 상태를 유지한다.

현재 스왑 활성화 여부 확인

swapon --show

아무 출력도 없으면 → 스왑 비활성화 상태이다

출력이 있으면 → 스왑 활성화 상태이다

나는 현재 이렇게 스왑이 비활성화된 상태라고 출력이 된다.

여기서 더 자세하기 보기 위해서 다음 명령어를 쳐봤다.

free -h

여기서 Swap: 0B 0B 0B 로 나오면 완전히 비활성화 상태이다.

3. 컨테이너 런타임 설치

마지막으로 쿠버네티스를 설치하기 위해서는 컨테이너 런타임을 설치해야 한다.
쿠버네티스는 자체적으로 컨테이너를 실행하지 않기 때문에, 외부 컨테이너 런타임이 반드시 필요하다.
본 실습에서는 쿠버네티스 공식 문서에서 권장하는 containerd를 컨테이너 런타임으로 사용한다.

일단 위 글에서 살펴보라고 나온 컨테이너 런타임에 들어가서 보면
다음과 같이 나온다.

컨테이너 런타임을 설치하기 전에 리눅스 커널 파라미터를 사전에 설정해야 한다는 내용이 나온다.

위 문서에서는 다음과 같은 sysctl 설정을 적용하도록 안내하고 있다.

이 설정들은 단순히 containerd만을 위한 설정이 아니라,
쿠버네티스 파드 네트워크가 정상적으로 동작하기 위해 필수적인 커널 설정이다.

3-1. sysctl 설정

sysctl 설정이 필요한 이유.

쿠버네티스에서 파드는 가상 네트워크를 통해 서로 통신한다.
이 과정에서 리눅스 커널은 다음과 같은 역할을 수행해야 한다.

• 브리지 네트워크를 통해 들어오는 패킷을 iptables에서 처리할 수 있어야 한다
• 파드 간 트래픽이 노드를 거쳐 포워딩될 수 있어야 한다
• 컨테이너 네트워크 인터페이스(CNI)가 커널 네트워크 스택과 정상적으로 연동되어야 한다

하지만 리눅스 기본 설정에서는
브리지 네트워크를 통과하는 패킷이 iptables 규칙을 거치지 않거나,
IP 포워딩이 비활성화되어 있는 경우가 많다.

이 상태로 쿠버네티스를 설치하면 다음과 같은 문제가 발생할 수 있다.

• 파드 간 통신 실패
• 서비스(Service) 트래픽이 정상적으로 전달되지 않음
• CNI 플러그인 초기화 실패

이를 방지하기 위해, 공식 문서에서는 아래와 같은 커널 파라미터 설정을 사전 조건으로 요구한다.

적용하는 sysctl 파라미터의 의미

net.bridge.bridge-nf-call-iptables = 1
net.bridge.bridge-nf-call-ip6tables = 1

위 설정은
브리지 네트워크를 통해 전달되는 패킷이
iptables 및 ip6tables 규칙을 거치도록 설정하는 옵션이다.

즉, 쿠버네티스 네트워크 정책과 서비스 규칙이
브리지 인터페이스에서도 정상적으로 적용되도록 하기 위한 설정이다.

net.ipv4.ip_forward = 1

이 설정은 IP 포워딩을 활성화하는 옵션이다.
노드가 파드 트래픽을 다른 파드나 노드로 전달하기 위해 반드시 필요하다.

sysctl 파라미터 적용

공식 문서에서 제시한 명령어를 그대로 사용하여
해당 커널 파라미터를 적용한다.

이 설정은 컨테이너 런타임(containerd) 설치 이전에 적용되어야 하며,
이후 CNI 플러그인과 쿠버네티스 네트워크가 정상적으로 동작하기 위한 기반이 된다.

3-2. cgroup 드라이버

컨테이너 런타임을 설치할 때 반드시 함께 고려해야 하는 요소가 cgroup(control group) 드라이버이다.

리눅스에서 cgroup은
프로세스에 할당된 CPU, 메모리, I/O와 같은 자원을 제한하고 관리하기 위한 기능이다.
쿠버네티스에서는 이 cgroup을 기반으로 파드와 컨테이너의 리소스를 제어한다.

kubelet과 컨테이너 런타임에서 cgroup이 중요한 이유

쿠버네티스에서 실제 컨테이너를 관리하는 주체는 다음 두 컴포넌트이다.

• kubelet
• 컨테이너 런타임(containerd)

이 두 컴포넌트는 모두 cgroup을 통해 다음과 같은 작업을 수행한다.

• 파드의 CPU / 메모리 요청(request)과 제한(limit) 적용
• 노드의 리소스 사용량 추적
• 메모리 부족 상황에서 파드 eviction 판단

이 때문에 kubelet과 컨테이너 런타임은 반드시 동일한 cgroup 드라이버를 사용해야 한다.
두 컴포넌트가 서로 다른 방식으로 cgroup을 관리할 경우,
노드의 리소스 상태를 서로 다르게 인식하게 되어 시스템이 불안정해질 수 있다.

사용 가능한 cgroup 드라이버 종류

쿠버네티스에서 사용할 수 있는 cgroup 드라이버는 크게 두 가지이다.

• cgroupfs
• systemd

cgrupfs 드라이버

cgroupfs 드라이버는
kubelet이 직접 cgroup 파일 시스템을 제어하는 방식이다.

과거에는 기본값으로 많이 사용되었지만,
init 시스템이 systemd인 환경에서는 권장되지 않는다.

그 이유는 systemd 자체가 이미 cgroup 관리자 역할을 수행하고 있기 때문이다.
이 상태에서 cgroupfs를 사용하면,
하나의 시스템에 두 개의 cgroup 관리자(systemd + cgroupfs) 가 공존하게 되어
리소스 관리 충돌이 발생할 수 있다.

systemd cgroup 드라이버

systemd cgroup 드라이버는
systemd를 통해 cgroup을 관리하는 방식이다.

systemd 기반 리눅스 배포판에서는
모든 서비스와 프로세스가 systemd 단위(unit)로 관리되며,
각 단위마다 cgroup이 자동으로 할당된다.

따라서 systemd를 init 시스템으로 사용하는 환경에서는
kubelet과 컨테이너 런타임 모두 systemd cgroup 드라이버를 사용하는 것이 권장된다.

공식 문서에서도
systemd 환경에서는 systemd cgroup 드라이버 사용을 권장하고 있으며,
특히 cgroup v2 환경에서는 systemd 사용이 사실상 표준에 가깝다.

본 실습 환경에서의 선택

앞서 살펴본 cgroup 드라이버 개념을 바탕으로,
본 실습 환경에서는 다음과 같은 구성을 선택하였다.

본 실습은 systemd 기반의 Rocky Linux 환경에서 진행되었으며,
컨테이너 런타임으로는 containerd를 사용하였다.

이에 따라 kubelet과 컨테이너 런타임 간의 cgroup 관리 방식을 일치시키기 위해
systemd cgroup 드라이버를 사용하도록 설정하였다.

실제로 containerd 설정 파일을 생성한 뒤,
기본값으로 설정되어 있는 cgroupfs 방식이 아닌
systemd 방식으로 cgroup 드라이버를 변경하였다.

3-3 컨테이너 런타임 설치

공식 문서에는 다음과 같은 컨테이너 런타임들이 소개되어 있다.

• containerd
• CRI-O
• Docker 엔진 (cri-dockerd 사용)
• 미란티스 컨테이너 런타임(MCR)

이 중에서 본 실습에서는
containerd를 컨테이너 런타임으로 선택하였다.

containerd를 선택한 이유

containerd는 CNCF에서 관리되는 오픈소스 컨테이너 런타임으로,
쿠버네티스가 공식적으로 지원하는 CRI 호환 런타임이다.

containerd를 사용할 경우 다음과 같은 특징이 있다.

• 별도의 어댑터 없이 kubelet과 직접 CRI 연동 가능
• Docker 엔진에 비해 구조가 단순함
• 쿠버네티스 공식 문서에서 권장하는 기본 런타임
• 현재 운영 환경에서 가장 널리 사용되는 런타임 중 하나

반면, Docker 엔진은
쿠버네티스 1.24 버전부터 kubelet 내장 지원이 제거되었기 때문에
추가 어댑터인 cri-dockerd를 설치해야만 사용이 가능하다.

본 실습에서는
불필요한 중간 계층을 줄이고, 공식 권장 구조에 맞추기 위해
Docker 엔진 및 cri-dockerd는 사용하지 않았다.

containerd 설치 및 CRI 엔드포인트

containerd를 설치하면,
다음 경로에 CRI 소켓이 생성된다.

/var/run/containerd/containerd.sock

kubeadm은 이 소켓을 통해
containerd가 CRI 런타임으로 동작하고 있음을 자동으로 인식한다.

따라서 본 실습에서는
kubeadm 실행 시 별도로 컨테이너 런타임 엔드포인트를 지정하지 않아도
containerd를 정상적으로 감지하여 클러스터 초기화를 진행할 수 있다.

containerd 설정 파일과 cgroup 드라이버

공식 문서에서는
containerd 설치 이후 유효한 설정 파일(config.toml)을 생성하고,
systemd cgroup 드라이버를 사용하도록 설정할 것을 권장한다.

이에 따라 본 실습에서는
기본 설정 파일을 생성한 뒤
cgroup 드라이버를 systemd 방식으로 변경하였다.

이 설정을 통해

• kubelet
• containerd

두 컴포넌트가 동일한 cgroup 관리 방식을 사용하도록 구성하였다.

설정 변경 이후에는
containerd 서비스를 재시작하여 변경 사항을 적용하였다.

3-4 네트워크 플러그인

공식 홈페이지에서는 이렇게, 컨테이너 런타임 뿐만 아니라 클러스터에 동작하는 네트워크 플러그인도 필요하다고 나와있어 네트워크 플러그인도 설치해준다.

쿠버네티스 공식 홈페이지 - 네트워크 플러그인

위 링크를 들어가면 다음과 같이 나온다.

네트워크 플러그인이 필요한 이유

쿠버네티스에서 파드는 노드 안에서 생성되고 삭제되며,
클러스터 상태에 따라 언제든지 다른 노드로 이동할 수 있다.

이때 다음과 같은 작업이 필요하다.

• 파드 생성 시 IP 할당
• 파드 삭제 시 IP 회수
• 파드 간 통신 경로 구성
• 노드 간 파드 트래픽 라우팅
• 서비스(Service) 트래픽 처리

이 모든 네트워크 관련 작업을 담당하는 것이 네트워크 플러그인이다.

따라서 네트워크 플러그인이 설치되지 않은 상태에서는 다음과 같은 현상이 발생한다.

• 파드는 생성되지만 NotReady 상태에 머무른다
• 파드 간 통신이 불가능하다
• CoreDNS가 정상적으로 동작하지 않는다
• 서비스(Service)를 통한 접근이 불가능하다

즉, 네트워크 플러그인이 없으면
쿠버네티스 클러스터는 사실상 정상 동작할 수 없다.

CNI(Container Network Interface)

쿠버네티스는 네트워크 플러그인과 연동하기 위해
CNI(Container Network Interface) 라는 표준 인터페이스를 사용한다.

CNI는 다음을 정의한다.

• 컨테이너 네트워크를 설정하는 방식
• 네트워크 플러그인이 kubelet과 통신하는 방법
• 파드 생성/삭제 시 네트워크를 설정·정리하는 규칙

쿠버네티스는 CNI 규격을 만족하는 플러그인이라면
어떤 구현체라도 사용할 수 있도록 설계되어 있다.

네트워크 플러그인의 종류

공식 문서에는 다양한 네트워크 플러그인이 소개되어 있다.

예를 들면 다음과 같다.

• Calico
• Flannel
• Weave Net
• Cilium

각 플러그인은
네트워크 구현 방식, 성능 특성, 보안 기능(NetworkPolicy 지원 여부) 등이 서로 다르다.

따라서 실제 운영 환경에서는
클러스터 규모, 보안 요구사항, 네트워크 정책 적용 여부 등을 고려하여
적절한 네트워크 플러그인을 선택해야 한다.

본 실습에서의 네트워크 플러그인 선택

본 실습 환경에서는
네트워크 플러그인으로 Calico를 사용한다.

Calico는

• 쿠버네티스 NetworkPolicy를 기본적으로 지원하며
• 노드 간 파드 통신을 안정적으로 처리하고
• 공식 문서와 실습 자료에서 널리 사용되는 플러그인이다

다음 단계에서는
kubeadm을 통해 클러스터를 초기화한 이후,
Calico 네트워크 플러그인을 설치하여
파드 네트워크를 실제로 구성한다.

이제는 이해할 수 있는 쿠버네티스 설치 명령어(Full)

echo '======== [4] Rocky Linux 기본 설정 ========'
echo '======== [4-1] 패키지 업데이트 ========'
# 강의와 동일한 실습 환경을 유지하기 위해 Linux Update는 하지 마세요!
# yum -y update # (x)

echo '======== [4-2] 타임존 설정 ========'
timedatectl set-timezone Asia/Seoul
timedatectl set-ntp true
chronyc makestep

echo '======== [4-3] [WARNING FileExisting-tc]: tc not found in system path 로그 관련 업데이트 ========'
yum install -y yum-utils iproute-tc
echo '======== [4-3] [WARNING OpenSSL version mismatch 로그 관련 업데이트 ========'
yum update openssl openssh-server -y

echo '======= [4-4] hosts 설정 =========='
cat << EOF >> /etc/hosts
192.168.56.30 k8s-master
EOF

echo '======== [5] kubeadm 설치 전 사전작업 ========'
echo '======== [5] 방화벽 해제 ========'
systemctl stop firewalld && systemctl disable firewalld

echo '======== [5] Swap 비활성화 ========'
swapoff -a && sed -i '/ swap / s/^/#/' /etc/fstab

echo '======== [6] 컨테이너 런타임 설치 ========'
echo '======== [6-1] 컨테이너 런타임 설치 전 사전작업 ========'
echo '======== [6-1] iptable 세팅 ========'
cat <<EOF |tee /etc/modules-load.d/k8s.conf
overlay
br_netfilter
EOF

modprobe overlay
modprobe br_netfilter

cat <<EOF |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

echo '======== [6-2] 컨테이너 런타임 (containerd 설치) ========'
echo '======== [6-2-1] containerd 패키지 설치 (option2) ========'
echo '======== [6-2-1-1] docker engine 설치 ========'
echo '======== [6-2-1-1] repo 설정 ========'
yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

echo '======== [6-2-1-1] containerd 설치 ========'
yum install -y containerd.io-1.6.21-3.1.el9.aarch64
systemctl daemon-reload
systemctl enable --now containerd

echo '======== [6-3] 컨테이너 런타임 : cri 활성화 ========'
containerd config default > /etc/containerd/config.toml
sed -i 's/ SystemdCgroup = false/ SystemdCgroup = true/' /etc/containerd/config.toml
systemctl restart containerd

echo '======== [7] kubeadm 설치 ========'
echo '======== [7] repo 설정 ========'
cat <<EOF | sudo tee /etc/yum.repos.d/kubernetes.repo
[kubernetes]
name=Kubernetes
baseurl=https://pkgs.k8s.io/core:/stable:/v1.27/rpm/
enabled=1
gpgcheck=1
gpgkey=https://pkgs.k8s.io/core:/stable:/v1.27/rpm/repodata/repomd.xml.key
exclude=kubelet kubeadm kubectl cri-tools kubernetes-cni
EOF

echo '======== [7] SELinux 설정 ========'
setenforce 0
sed -i 's/^SELINUX=enforcing$/SELINUX=permissive/' /etc/selinux/config

echo '======== [7] kubelet, kubeadm, kubectl 패키지 설치 ========'
yum install -y kubelet-1.27.2-150500.1.1.aarch64 kubeadm-1.27.2-150500.1.1.aarch64 kubectl-1.27.2-150500.1.1.aarch64 --disableexcludes=kubernetes
systemctl enable --now kubelet

echo '======== [8] kubeadm으로 클러스터 생성  ========'
echo '======== [8-1] 클러스터 초기화 (Pod Network 세팅) ========'
kubeadm init --pod-network-cidr=20.96.0.0/12 --apiserver-advertise-address 192.168.56.30

echo '======== [8-2] kubectl 사용 설정 ========'
mkdir -p $HOME/.kube
cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
chown $(id -u):$(id -g) $HOME/.kube/config

echo '======== [8-3] Pod Network 설치 (calico) ========'
kubectl create -f https://raw.githubusercontent.com/k8s-1pro/install/main/ground/k8s-1.27/calico-3.26.4/calico.yaml
kubectl create -f https://raw.githubusercontent.com/k8s-1pro/install/main/ground/k8s-1.27/calico-3.26.4/calico-custom.yaml

echo '======== [8-4] Master에 Pod를 생성 할수 있도록 설정 ========'
kubectl taint nodes k8s-master node-role.kubernetes.io/control-plane-

echo '======== [9] 쿠버네티스 편의기능 설치 ========'
echo '======== [9-1] kubectl 자동완성 기능 ========'
yum -y install bash-completion
echo "source <(kubectl completion bash)" >> ~/.bashrc
echo 'alias k=kubectl' >>~/.bashrc
echo 'complete -o default -F __start_kubectl k' >>~/.bashrc
source ~/.bashrc

echo '======== [9-2] Dashboard 설치 ========'
kubectl create -f https://raw.githubusercontent.com/k8s-1pro/install/main/ground/k8s-1.27/dashboard-2.7.0/dashboard.yaml

echo '======== [9-3] Metrics Server 설치 ========'
kubectl create -f https://raw.githubusercontent.com/k8s-1pro/install/main/ground/k8s-1.27/metrics-server-0.6.3/metrics-server.yaml

위 포스팅은 인프런 강의 : 쿠버네티스 어나더 클래스-Sprint 1, 2
및 쿠버네티스 무게감 있게 설치하기를 참고하여 작성한 포스팅입니다.