kubeadm 설치하기

이 페이지에서는 kubeadm 툴박스 설치 방법을 보여준다. 이 설치 프로세스를 수행한 후 kubeadm으로 클러스터를 만드는 방법에 대한 자세한 내용은 kubeadm으로 클러스터 생성하기 페이지를 참고한다.

This installation guide is for Kubernetes v1.34. If you want to use a different Kubernetes version, please refer to the following pages instead:

시작하기 전에

  • 호환되는 리눅스 호스트. 쿠버네티스 프로젝트는 데비안 및 레드햇 기반 리눅스 배포판과 패키지 매니저가 없는 배포판에 대한 일반적인 지침을 제공한다.
  • 머신당 2GB 이상의 RAM (이보다 적으면 앱을 위한 공간이 거의 남지 않는다).
  • 컨트롤 플레인 머신에는 2개 이상의 CPU.
  • 클러스터의 모든 머신 간 완전한 네트워크 연결 (공용 또는 사설 네트워크 무관).
  • 모든 노드에 대해 고유한 호스트네임, MAC 주소, 그리고 product_uuid. 자세한 내용은 여기를 참고한다.
  • 머신에 특정 포트들이 열려있어야 한다. 자세한 내용은 여기를 참고한다.

OS 버전 확인

  • kubeadm 프로젝트는 LTS 커널을 지원한다. LTS 커널 목록을 참고한다.
  • uname -r 명령을 사용하여 커널 버전을 확인할 수 있다

자세한 정보는 리눅스 커널 요구사항을 참고한다.

  • kubeadm 프로젝트는 최신 커널 버전을 지원한다. 최신 커널 목록은 윈도우 서버 릴리스 정보를 참고한다.
  • systeminfo 명령을 사용하여 커널 버전(OS 버전이라고도 함)을 확인할 수 있다

자세한 정보는 윈도우 OS 버전 호환성을 참고한다.

kubeadm으로 생성된 쿠버네티스 클러스터는 커널 기능을 사용하는 소프트웨어에 의존한다. 이 소프트웨어에는 컨테이너 런타임, kubelet, 그리고 컨테이너 네트워크 인터페이스 플러그인이 포함되지만 이에 국한되지 않는다.

지원되지 않는 커널 버전으로 인한 예기치 않은 오류를 방지하기 위해, kubeadm은 SystemVerification 사전 검사를 실행한다. 이 검사는 커널 버전이 지원되지 않으면 실패한다.

kubeadm이 커널 버전을 지원하지 않더라도, 커널이 필요한 기능을 제공한다는 것을 알고 있다면 검사를 건너뛰도록 선택할 수 있다.

모든 노드에서 MAC 주소와 product_uuid가 고유한지 확인

  • ip link 또는 ifconfig -a 명령을 사용하여 네트워크 인터페이스의 MAC 주소를 확인할 수 있다
  • sudo cat /sys/class/dmi/id/product_uuid 명령을 사용하여 product_uuid를 확인할 수 있다

하드웨어 장치는 고유한 주소를 가질 가능성이 매우 높지만, 일부 가상 머신은 동일한 값을 가질 수 있다. 쿠버네티스는 이러한 값을 사용하여 클러스터의 노드를 고유하게 식별한다. 이러한 값이 각 노드에서 고유하지 않으면 설치 과정이 실패할 수 있다.

네트워크 어댑터 확인

네트워크 어댑터가 두 개 이상이고, 쿠버네티스 컴포넌트가 디폴트 라우트(default route)에서 도달할 수 없는 경우, 쿠버네티스 클러스터 주소가 적절한 어댑터를 통해 이동하도록 IP 경로를 추가하는 것이 좋다.

필수 포트 확인

쿠버네티스 컴포넌트가 서로 통신하려면 이러한 필수 포트가 열려 있어야 한다. netcat과 같은 도구를 사용하여 포트가 열려 있는지 확인할 수 있다. 예를 들어

nc 127.0.0.1 6443 -zv -w 2

사용하는 파드 네트워크 플러그인도 특정 포트가 열려 있어야 할 수 있다. 각 파드 네트워크 플러그인마다 다르므로, 해당 플러그인이 필요로 하는 포트에 대해서는 플러그인 문서를 참고한다.

스왑 구성

노드에서 스왑 메모리가 감지되면 kubelet의 기본 동작은 시작에 실패하는 것이다. 이는 스왑이 비활성화되거나 kubelet에 의해 용인되어야 함을 의미한다.

  • 스왑을 용인하려면, kubelet 구성에 failSwapOn: false를 추가하거나 커맨드라인 인수로 설정한다. 참고: failSwapOn: false가 제공되더라도 워크로드는 기본적으로 스왑에 접근할 수 없다. 이는 kubelet 구성 파일에서 다시 swapBehavior를 설정하여 변경할 수 있다. 스왑을 사용하려면, 기본 NoSwap 설정이 아닌 다른 swapBehavior를 설정한다. 자세한 내용은 스왑 메모리 관리를 참고한다.
  • 스왑을 비활성화하려면, sudo swapoff -a를 사용하여 일시적으로 스와핑을 비활성화할 수 있다. 재부팅 후에도 이 변경사항을 유지하려면, 시스템 구성 방법에 따라 /etc/fstab, systemd.swap과 같은 구성 파일에서 스왑이 비활성화되어 있는지 확인한다.

컨테이너 런타임 설치

파드에서 컨테이너를 실행하기 위해, 쿠버네티스는 컨테이너 런타임을 사용한다.

기본적으로, 쿠버네티스는 컨테이너 런타임 인터페이스(CRI)를 사용하여 사용자가 선택한 컨테이너 런타임과 인터페이스한다.

런타임을 지정하지 않으면, kubeadm은 잘 알려진 엔드포인트를 스캐닝하여 설치된 컨테이너 런타임을 자동으로 감지하려고 한다.

컨테이너 런타임이 여러 개 감지되거나 하나도 감지되지 않은 경우, kubeadm은 에러를 반환하고 사용자가 어떤 것을 사용할지를 명시하도록 요청할 것이다.

자세한 정보는 컨테이너 런타임 을 참고한다.

아래 표는 지원 운영 체제에 대한 알려진 엔드포인트를 담고 있다.

리눅스 컨테이너 런타임
런타임유닉스 도메인 소켓 경로
containerdunix:///var/run/containerd/containerd.sock
CRI-Ounix:///var/run/crio/crio.sock
도커 엔진 (cri-dockerd 사용)unix:///var/run/cri-dockerd.sock

윈도우 컨테이너 런타임
런타임윈도우 네임드 파이프(named pipe) 경로
containerdnpipe:////./pipe/containerd-containerd
도커 엔진 (cri-dockerd 사용)npipe:////./pipe/cri-dockerd

kubeadm, kubelet 및 kubectl 설치

모든 머신에 다음 패키지들을 설치한다.

  • kubeadm: 클러스터를 부트스트랩하는 명령이다.

  • kubelet: 클러스터의 모든 머신에서 실행되는 파드와 컨테이너 시작과 같은 작업을 수행하는 컴포넌트이다.

  • kubectl: 클러스터와 통신하기 위한 커맨드 라인 유틸리티이다.

kubeadm은 kubelet 또는 kubectl 을 설치하거나 관리하지 않으므로, kubeadm이 설치하려는 쿠버네티스 컨트롤 플레인의 버전과 일치하는지 확인해야 한다. 그렇지 않으면, 예상치 못한 버그 동작으로 이어질 수 있는 버전 차이(skew)가 발생할 위험이 있다. 그러나, kubelet과 컨트롤 플레인 사이에 하나의 마이너 버전 차이가 지원되지만, kubelet 버전은 API 서버 버전 보다 높을 수 없다. 예를 들어, 1.7.0 버전의 kubelet은 1.8.0 API 서버와 완전히 호환되어야 하지만, 그 반대의 경우는 아니다.

kubectl 설치에 대한 정보는 kubectl 설치 및 설정을 참고한다.

버전 차이에 대한 자세한 내용은 다음을 참고한다.

다음 지침은 쿠버네티스 v1.34에 대한 것이다.

  1. apt 패키지 인덱스를 업데이트하고 쿠버네티스 apt 리포지터리를 사용하는 데 필요한 패키지를 설치한다.

    sudo apt-get update
# apt-transport-https는 더미 패키지일 수 있다. 그렇다면 해당 패키지를 건너뛸 수 있다
sudo apt-get install -y apt-transport-https ca-certificates curl gpg

  2. 쿠버네티스 패키지 리포지터리용 공개 샤이닝 키를 다운로드한다. 모든 리포지터리에 동일한 서명 키가 사용되므로 URL의 버전은 무시할 수 있다.

    # `/etc/apt/keyrings` 디렉터리가 존재하지 않으면, curl 명령 전에 생성해야 한다. 아래 참고사항을 읽어본다.
# sudo mkdir -p -m 755 /etc/apt/keyrings
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.34/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg

  1. 적절한 쿠버네티스 apt 리포지터리를 추가한다. 이 리포지터리에는 쿠버네티스 1.34에 대한 패키지만 있다는 점에 유의한다. 다른 쿠버네티스 마이너 버전의 경우, 원하는 마이너 버전과 일치하도록 URL의 쿠버네티스 마이너 버전을 변경해야 한다 (설치할 계획인 쿠버네티스 버전에 대한 문서를 읽고 있는지도 확인해야 한다).

    # 이 명령어는 /etc/apt/sources.list.d/kubernetes.list 에 있는 기존 구성을 덮어쓴다.
echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.34/deb/ /' | sudo tee /etc/apt/sources.list.d/kubernetes.list

  2. apt 패키지 색인을 업데이트하고, kubelet, kubeadm, kubectl을 설치하고 해당 버전을 고정한다.

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

  3. (선택사항) kubeadm을 실행하기 전에 kubelet 서비스를 활성화한다.

    sudo systemctl enable --now kubelet

  1. SELinux를 permissive 모드로 설정한다.

    다음 지침은 쿠버네티스 1.34에 대한 것이다.

    # SELinux를 permissive 모드로 설정한다 (효과적으로 비활성화)
sudo setenforce 0
sudo sed -i 's/^SELINUX=enforcing$/SELINUX=permissive/' /etc/selinux/config

  1. 쿠버네티스 yum 리포지터리를 추가한다. 리포지터리 정의의 exclude 파라미터는 쿠버네티스를 업그레이드하기 위해 따라야 하는 특별한 절차가 있으므로 yum update 실행 시 쿠버네티스와 관련된 패키지가 업그레이드되지 않도록 한다. 이 리포지터리에는 쿠버네티스 1.34에 대한 패키지만 있다는 점에 유의한다. 다른 쿠버네티스 마이너 버전의 경우, 원하는 마이너 버전과 일치하도록 URL의 쿠버네티스 마이너 버전을 변경해야 한다 (설치할 계획인 쿠버네티스 버전에 대한 문서를 읽고 있는지도 확인해야 한다).

    # 이것은 /etc/yum.repos.d/kubernetes.repo에 있는 기존 구성을 덮어쓴다
cat <<EOF | sudo tee /etc/yum.repos.d/kubernetes.repo
[kubernetes]
name=Kubernetes
baseurl=https://pkgs.k8s.io/core:/stable:/v1.34/rpm/
enabled=1
gpgcheck=1
gpgkey=https://pkgs.k8s.io/core:/stable:/v1.34/rpm/repodata/repomd.xml.key
exclude=kubelet kubeadm kubectl cri-tools kubernetes-cni
EOF

  2. kubelet, kubeadm 및 kubectl을 설치한다.

    sudo yum install -y kubelet kubeadm kubectl --disableexcludes=kubernetes

  3. (선택사항) kubeadm을 실행하기 전에 kubelet 서비스를 활성화한다.

    sudo systemctl enable --now kubelet

CNI 플러그인 설치(대부분의 파드 네트워크에 필요)

CNI_PLUGINS_VERSION="v1.3.0"
ARCH="amd64"
DEST="/opt/cni/bin"
sudo mkdir -p "$DEST"
curl -L "https://github.com/containernetworking/plugins/releases/download/${CNI_PLUGINS_VERSION}/cni-plugins-linux-${ARCH}-${CNI_PLUGINS_VERSION}.tgz" | sudo tar -C "$DEST" -xz

명령어 파일을 다운로드할 디렉터리 정의

DOWNLOAD_DIR="/usr/local/bin"
sudo mkdir -p "$DOWNLOAD_DIR"

선택적으로 crictl을 설치한다 (컨테이너 런타임 인터페이스(CRI)와의 상호작용에 필요, kubeadm에는 선택사항).

CRICTL_VERSION="v1.31.0"
ARCH="amd64"
curl -L "https://github.com/kubernetes-sigs/cri-tools/releases/download/${CRICTL_VERSION}/crictl-${CRICTL_VERSION}-linux-${ARCH}.tar.gz" | sudo tar -C $DOWNLOAD_DIR -xz

kubeadm, kubelet을 설치하고 kubelet systemd 서비스를 추가한다.

RELEASE="$(curl -sSL https://dl.k8s.io/release/stable.txt)"
ARCH="amd64"
cd $DOWNLOAD_DIR
sudo curl -L --remote-name-all https://dl.k8s.io/release/${RELEASE}/bin/linux/${ARCH}/{kubeadm,kubelet}
sudo chmod +x {kubeadm,kubelet}

RELEASE_VERSION="v0.16.2"
curl -sSL "https://raw.githubusercontent.com/kubernetes/release/${RELEASE_VERSION}/cmd/krel/templates/latest/kubelet/kubelet.service" | sed "s:/usr/bin:${DOWNLOAD_DIR}:g" | sudo tee /usr/lib/systemd/system/kubelet.service
sudo mkdir -p /usr/lib/systemd/system/kubelet.service.d
curl -sSL "https://raw.githubusercontent.com/kubernetes/release/${RELEASE_VERSION}/cmd/krel/templates/latest/kubeadm/10-kubeadm.conf" | sed "s:/usr/bin:${DOWNLOAD_DIR}:g" | sudo tee /usr/lib/systemd/system/kubelet.service.d/10-kubeadm.conf

도구 설치 페이지의 지침에 따라 kubectl을 설치한다.

선택적으로, kubeadm을 실행하기 전에 kubelet 서비스를 활성화한다.

sudo systemctl enable --now kubelet

kubelet은 이제 kubeadm이 수행할 작업을 알려 줄 때까지 크래시루프(crashloop) 상태로 기다려야 하므로 몇 초마다 다시 시작된다.

cgroup 드라이버 구성

컨테이너 런타임과 kubelet은 "cgroup 드라이버"라는 속성을 갖고 있으며, cgroup 드라이버는 리눅스 머신의 cgroup 관리 측면에 있어서 중요하다.

문제 해결

kubeadm에 문제가 있는 경우, 문제 해결 문서를 참고한다.

다음 내용

이 페이지는 쿠버네티스가 필요로 하는 기능을 제공하는 써드파티 프로젝트 또는 제품에 대해 언급하고 있습니다. 쿠버네티스 프로젝트 저자들은 이러한 써드파티 프로젝트 또는 제품에 대해 책임지지 않습니다. CNCF 웹사이트 가이드라인에서 더 자세한 내용을 확인합니다.

다른 써드파티 링크를 추가하는 변경을 제안하기 전에, 컨텐츠 가이드를 확인해야 합니다.

최종 수정 October 15, 2025 at 10:23 AM PST: [ko] Update install-kubeadm.md translation (d23c5f29f5)