컨테이너 런타임 설치

containerd(기본), Docker, CRI-O 등 클러스터 노드에 컨테이너 런타임을 자동 배포하고 설정합니다.

컨테이너 런타임 선택 (택 1)

ubuntu.yaml의 kube_cri 값에 따라 아래 3개 중 하나만 골라 설치됩니다(roles/qks-kubernetes/cri/meta/main.yaml에서 분기, 셋을 동시에 설치할 수 없음). 버전을 명시적으로 고정하고 싶으면 어느 런타임을 고르든 공통으로 kube_cri_version을 지정하면 되고, 생략하면 compatible-matrix.yaml에서 kube_version에 맞는 값이 자동으로 결정됩니다.

ubuntu.yaml에서 하나를 고른 뒤, 아래 A/B/C 중 그 옵션에 해당하는 섹션만 읽고 진행하면 됩니다. 세 섹션을 순서대로 다 하는 게 아닙니다.

플레이북 실행 (A/B/C 공통)

./install.sh ubuntu k8s.yaml

A. containerd (기본)

설정값

ubuntu.yaml:

kube_cri: "containerd"      # 생략 가능(기본값)
# kube_cri_version: "2.3.0"   # 생략 시 compatible-matrix.yaml의 containerd_matrix[kube_version]에서 자동 결정

설치 흐름

버전에 따라 설치 방식이 갈립니다(roles/qks-kubernetes/cri/containerd/tasks/debian.yaml):

containerd < 2.3  → APT 설치 (Docker 공식 저장소, containerd.io 패키지)
containerd >= 2.3 → 바이너리 설치 (GitHub 릴리즈 tarball을 /usr/local에 직접 배치)
                     - containerd 바이너리 + runc 바이너리를 각각 다운로드
                     - containerd.service systemd 유닛 신규 생성(containerd.service.j2)
                     - /usr/bin/ctr 심볼릭 링크 생성

설정 파일 템플릿은 containerd 마이너 버전별로 나뉘어 있습니다: roles/qks-kubernetes/cri/containerd/templates/containerd-config-{1.3,1.4,1.5,1.6,1.7,2.2,2.3}.x.toml.j2. 새 마이너 버전을 지원하려면 이 템플릿을 하나 추가해야 합니다.

설치 확인

crictl info
containerd --version
systemctl status containerd

B. Docker

설정값

ubuntu.yaml:

kube_cri: "docker"

설치 흐름

1. Docker 공식 APT 저장소 등록, 버전 고정(docker_version)
2. docker-ce/docker-ce-cli 설치, apt-mark hold
3. /etc/docker, /etc/systemd/system/docker.service.d 디렉토리 생성
4. Docker systemd 서비스/드롭인(cgroup 드라이버, 인시큐어 레지스트리, data-root) 적용
5. cri-dockerd 설치 (roles/qks-kubernetes/cri/docker/tasks/debian.yaml)
   - Kubernetes 1.24부터 dockershim이 제거되어, Docker를 CRI로 쓰려면 별도 셔틀 데몬이 필요
   - GitHub 공식 릴리즈(cri-dockerd, 버전: qks_cri_dockerd_version)에서 바이너리 다운로드
   - cri-docker.service / cri-docker.socket systemd 유닛 설치 및 활성화

설정값 (cri-dockerd)

roles/qks-kubernetes/cri/docker/defaults/main.yaml:

qks_cri_dockerd_version: 0.4.4

Ubuntu 24.04(noble)용 공식 .deb 패키지가 아직 없어(bionic/focal/jammy만 배포됨), GitHub 릴리즈의 범용 tarball(cri-dockerd-{version}.amd64.tgz)을 받아 바이너리를 직접 배치하고 공식 저장소의 systemd 유닛 파일(packaging/systemd/cri-docker.{service,socket})을 그대로 사용합니다. 유닛 파일 자체를 바꾸려면 roles/qks-kubernetes/cri/docker/templates/cri-docker.{service,socket}.j2를 수정합니다.

설치 확인

kubectl get nodes -o wide   # CONTAINER-RUNTIME 컬럼이 docker://<version>인지 확인
systemctl is-active cri-docker.service cri-docker.socket
docker --version

C. CRI-O

설정값

ubuntu.yaml:

kube_cri: "cri-o"

설치 흐름

1. openSUSE OBS 저장소 등록: isv:/cri-o:/stable:/v{K8s 마이너 버전}/deb/
   (2026-09-29부로 이전 devel:kubic:libcontainers 프로젝트는 폐쇄됨)
2. cri-o 패키지 설치(별도 cri-o-runc/podman 불필요 — runc 내장), apt-mark hold
3. registry.conf 생성(docker.io를 미지정 레지스트리 검색 대상으로 등록)
4. CRI-O 재시작 + Ready 대기

설치 확인

kubectl get nodes -o wide   # CONTAINER-RUNTIME 컬럼이 cri-o://<K8s버전>인지 확인
crictl info
systemctl status crio

다음 단계