kubeadm 설치하기

kubeadm 설치하기

이 페이지에서는 kubeadm 도구 상자를 설치하는 방법을 보여줘요. 이 설치 과정을 수행한 뒤 kubeadm으로 클러스터를 만드는 방법은 kubeadm으로 클러스터 만들기 페이지를 참고하세요.

출처: 문서

본문

시작하기 전에

• 호환되는 Linux 호스트. 쿠버네티스 프로젝트는 Debian과 Red Hat 기반 및 패키지 관리자가 없는 Linux 배포판에 대한 일반 지침을 제공해요.
• 머신당 2 GB 이상의 RAM (그 이하이면 앱을 위한 여유 공간이 거의 없어요).
• 컨트롤 플레인 머신용 CPU 2개 이상.
• 클러스터의 모든 머신 사이의 완전한 네트워크 연결 (공용 또는 사설 네트워크 모두 괜찮아요).
• 모든 노드에 고유한 hostname, MAC 주소, product_uuid. 자세한 내용은 여기를 참고하세요.
• 머신에서 특정 포트가 열려 있어야 해요. 자세한 내용은 여기를 참고하세요.

kubeadm 설치는 동적 링크를 사용하는 바이너리로 이뤄지며, 대상 시스템이 glibc를 제공한다고 가정해요. 이는 많은 Linux 배포판(Debian, Ubuntu, Fedora, CentOS 등 포함)에서 합리적인 가정이지만, Alpine Linux처럼 glibc를 기본으로 포함하지 않는 커스텀·경량 배포판에서는 항상 그런 것은 아닙니다. 배포판이 glibc를 포함하거나 예상되는 심볼을 제공하는 호환성 레이어를 가질 것으로 기대됩니다.

OS 버전 확인

• kubeadm 프로젝트는 LTS 커널을 지원해요. LTS 커널 목록을 참고하세요.
• 커널 버전은 uname -r 명령으로 알 수 있어요.

자세한 내용은 Linux 커널 요구 사항을 참고하세요.

• kubeadm 프로젝트는 최신 커널 버전을 지원해요. 최신 커널 목록은 Windows Server 릴리스 정보를 참고하세요.
• 커널 버전(OS 버전이라고도 함)은 systeminfo 명령으로 알 수 있어요.

자세한 내용은 Windows OS 버전 호환성을 참고하세요.

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

지원되지 않는 커널 버전으로 인한 예상치 못한 오류를 피하도록 kubeadm은 SystemVerification 사전 점검을 실행해요. 커널 버전이 지원되지 않으면 이 점검이 실패합니다.

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

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

• 네트워크 인터페이스의 MAC 주소는 ip link 또는 ifconfig -a 명령으로 알 수 있어요.
• product_uuid는 sudo cat /sys/class/dmi/id/product_uuid 명령으로 확인할 수 있어요.

하드웨어 장치는 보통 고유한 주소를 가지지만, 일부 가상 머신은 동일한 값을 가질 수 있어요. 쿠버네티스는 이 값들을 사용해 클러스터의 노드를 고유하게 식별합니다. 이 값들이 각 노드에 고유하지 않으면 설치 과정이 실패할 수 있습니다.

네트워크 어댑터 확인

네트워크 어댑터가 여러 개 있고 쿠버네티스 구성 요소가 기본 경로에서 연결할 수 없다면, 쿠버네티스 클러스터 주소가 적절한 어댑터를 통해 가도록 IP 경로를 추가하는 것을 권장해요.

필요한 포트 확인하기

쿠버네티스 구성 요소가 서로 통신하려면 이 필수 포트가 열려 있어야 해요. netcat 같은 도구로 포트가 열려 있는지 확인할 수 있어요. 예를 들어:

nc 127.0.0.1 6443 -zv -w 2

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

Swap 구성

kubelet의 기본 동작은 노드에서 swap 메모리가 감지되면 시작에 실패하는 것이에요. 즉 swap을 비활성화하거나 kubelet이 허용해야 합니다.

• swap을 허용하려면 kubelet 구성에 failSwapOn: false를 추가하거나 명령줄 인자로 넣는다. 참고: failSwapOn: false를 제공해도 워크로드는 기본적으로 swap 접근 권한이 없어요. 이는 kubelet 구성 파일에서 swapBehavior를 설정해 바꿀 수 있다. swap을 사용하려면 기본 NoSwap 설정이 아닌 다른 swapBehavior를 설정해라. 자세한 내용은 Swap 메모리 관리를 참고.
• swap을 비활성화하려면 sudo swapoff -a로 임시로 끌 수 있다. 재부팅 후에도 지속되게 하려면 시스템에서 어떻게 구성했는지에 따라 /etc/fstab, systemd.swap 같은 구성 파일에서 swap을 비활성화해라.

컨테이너 런타임 설치하기

Pod에서 컨테이너를 실행하기 위해 쿠버네티스는 컨테이너 런타임을 사용해요.

기본적으로 쿠버네티스는 선택한 컨테이너 런타임과 인터페이스하기 위해 CRI(Container Runtime Interface)를 사용합니다.

런타임을 지정하지 않으면 kubeadm은 알려진 엔드포인트 목록을 스캔해 설치된 컨테이너 런타임을 자동으로 감지하려 해요.

컨테이너 런타임이 여러 개 또는 없음이 감지되면 kubeadm은 오류를 던지고 어느 것을 사용할지 지정하라고 요청합니다.

자세한 내용은 컨테이너 런타임을 참고하세요.

Docker Engine은 컨테이너 런타임이 쿠버네티스와 동작하는 데 필요한 CRI를 구현하지 않아요. 그 때문에 cri-dockerd라는 추가 서비스를 설치해야 합니다. cri-dockerd는 버전 1.24에서 kubelet에서 제거된 레거시 내장 Docker Engine 지원을 기반으로 한 프로젝트입니다.

아래 표에는 지원되는 운영 체제의 알려진 엔드포인트가 포함되어 있어요:

런타임	Unix 도메인 소켓 경로
containerd	unix:///var/run/containerd/containerd.sock
CRI-O	unix:///var/run/crio/crio.sock
Docker Engine (using cri-dockerd)	unix:///var/run/cri-dockerd.sock

런타임	Windows named pipe 경로
containerd	npipe:////./pipe/containerd-containerd
Docker Engine (using cri-dockerd)	npipe:////./pipe/cri-dockerd

kubeadm, kubelet, kubectl 설치하기

이 패키지들을 모든 머신에 설치해요:

• kubeadm: 클러스터를 부트스트랩하는 명령.
• kubelet: 클러스터의 모든 머신에서 실행되며 파드와 컨테이너를 시작하는 일을 하는 구성 요소.
• kubectl: 클러스터와 통신하는 명령줄 유틸리티.

kubeadm은 kubelet이나 kubectl을 설치하거나 관리하지 않으므로, kubeadm이 설치하려는 쿠버네티스 컨트롤 플레인 버전과 일치하는지 직접 확인해야 해요. 그렇지 않으면 예상치 못하고 버그성 있는 동작을 일으키는 버전 스큐가 발생할 위험이 있습니다. 그러나 kubelet과 컨트롤 플레인 사이에 하나 minor 버전 스큐는 지원되지만, kubelet 버전은 API 서버 버전을 절대 초과해서는 안 돼요. 예를 들어 1.7.0을 실행하는 kubelet은 1.8.0 API 서버와 완전히 호환되어야 하지만, 그 반대는 아닙니다.

kubectl 설치에 대한 정보는 kubectl 설치 및 설정을 참고하세요.

이 지침은 모든 쿠버네티스 패키지를 시스템 업그레이드에서 제외해요. kubeadm과 쿠버네티스는 업그레이드에 특별한 주의가 필요하기 때문입니다.

버전 스큐에 대한 자세한 내용은:

• 쿠버네티스 버전 및 버전 스큐 정책
• kubeadm 특정 버전 스큐 정책

각 쿠버네티스 minor 버전에는 전용 패키지 리포지토리가 있어요. v1.37이 아닌 minor 버전을 설치하려면 원하는 minor 버전의 설치 가이드를 참고하세요.

이 지침은 쿠버네티스 v1.37용이에요.

1. apt 패키지 인덱스를 업데이트하고 Kubernetes apt 리포지토리를 사용하는 데 필요한 패키지를 설치한다:

   sudo apt-get update
   # apt-transport-https may be a dummy package; if so, you can skip that package
   sudo apt-get install -y apt-transport-https ca-certificates curl gpg
   

2. Kubernetes 패키지 리포지토리의 공개 서명 키를 다운로드한다. 모든 리포지토리에 같은 서명 키가 사용되므로 URL의 버전은 무시할 수 있다:

   # If the directory `/etc/apt/keyrings` does not exist, it should be created before the curl command, read the note below.
   # sudo mkdir -p -m 755 /etc/apt/keyrings
   curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.37/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
   

Debian 12와 Ubuntu 22.04보다 오래된 릴리스에서는 /etc/apt/keyrings 디렉토리가 기본적으로 존재하지 않으며, curl 명령 전에 만들어야 해요.

3. 적절한 Kubernetes apt 리포지토리를 추가한다. 이 리포지토리는 쿠버네티스 v1.37용 패키지만 있다는 점을 유의하세요. 다른 쿠버네티스 minor 버전은 URL의 minor 버전을 원하는 버전으로 바꿔야 합니다(설치하려는 쿠버네티스 버전의 문서를 읽고 있는지도 확인해야 해요).

   # This overwrites any existing configuration in /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.37/deb/ /' | sudo tee /etc/apt/sources.list.d/kubernetes.list
   

4. apt 패키지 인덱스를 업데이트하고 kubelet, kubeadm, kubectl을 설치하고 버전을 고정한다:

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

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

   sudo systemctl enable --now kubelet
   

6. SELinux를 permissive 모드로 설정한다:

   이 지침은 쿠버네티스 v1.37용이에요.

   # Set SELinux in permissive mode (effectively disabling it)
   sudo setenforce 0
   sudo sed -i 's/^SELINUX=enforcing$/SELINUX=permissive/' /etc/selinux/config
   

• setenforce 0과 sed ...로 SELinux를 permissive 모드로 설정하면 사실상 비활성화된다. 컨테이너가 호스트 파일시스템에 접근하게 하려면 이 작업이 필요하다. 예를 들어 일부 클러스터 네트워크 플러그인이 그것을 요구한다. kubelet에서 SELinux 지원이 개선될 때까지 해야 해요.
• SELinux를 구성하는 방법을 안다면 활성 상태로 두어도 되지만, kubeadm이 지원하지 않는 설정이 필요할 수 있다.

2. Kubernetes yum 리포지토리를 추가한다. 리포지토리 정의의 exclude 파라미터는 쿠버네티스 업그레이드에 따라야 할 특별한 절차가 있으므로, 일반 dnf update를 실행할 때 쿠버네티스 관련 패키지가 업그레이드되지 않게 보장한다. 이 리포지토리는 쿠버네티스 v1.37용 패키지만 있다는 점을 유의하세요. 다른 쿠버네티스 minor 버전은 URL의 minor 버전을 원하는 버전으로 바꿔야 합니다(설치하려는 쿠버네티스 버전의 문서를 읽고 있는지도 확인해야 해요).

   # This overwrites any existing configuration in /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.37/rpm/
   enabled=1
   gpgcheck=1
   gpgkey=https://pkgs.k8s.io/core:/stable:/v1.37/rpm/repodata/repomd.xml.key
   exclude=kubelet kubeadm kubectl cri-tools kubernetes-cni
   EOF
   

3. kubelet, kubeadm, kubectl을 설치한다:

   DNF4 (Fedora < 41, RHEL/CentOS < 10) 시스템의 경우

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

   DNF5의 Fedora 시스템:

   sudo dnf install -y kubelet kubeadm kubectl --setopt=disable_excludes=kubernetes
   

   RHEL/CentOS 10 이상에서 의존성으로 iptables를 가져오지 않으려면:

   sudo dnf install -y kubelet kubeadm kubectl --setopt=disable_excludes=kubernetes --setopt=install_weak_deps=False
   

4. (선택 사항) 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 변수는 쓰기 가능한 디렉토리로 설정해야 해요. Flatcar Container Linux를 실행 중이라면 DOWNLOAD_DIR="/opt/bin"으로 설정하세요.

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

선택적으로 crictl을 설치한다 (Container Runtime Interface(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

glibc를 기본으로 포함하지 않는 Linux 배포판에 대해서는 시작하기 전에 섹션의 참고를 보세요.

Install Tools 페이지의 지침을 따라 kubectl을 설치한다.

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

sudo systemctl enable --now kubelet

Flatcar Container Linux 배포판은 /usr 디렉토리를 읽기 전용 파일시스템으로 마운트해요. 클러스터를 부트스트랩하기 전에 쓰기 가능한 디렉토리를 구성하는 추가 단계를 수행해야 합니다. 쓰기 가능한 디렉토리를 설정하는 방법은 Kubeadm 문제 해결 가이드를 참고하세요.

kubelet은 kubeadm이 무엇을 하라고 알려주길 기다리며 크래시루프에서 몇 초마다 재시작하고 있어요.

문제 해결

kubeadm에서 어려움을 겪고 있다면 문제 해결 문서를 참고하세요.

더 알아보기 (Learn more)

• kubeadm으로 클러스터 만들기