閉域網は一覧の勝負 — Kubespray が取得するものを外で確定する

한국어 원문으로 표시합니다.

한 줄 요약

kubespray 의 폐쇄망 설치는 "받을 것의 목록을 만들고 → 사내에 같은 경로로 차려 두고 → 인벤토리 변수로 주소만 바꾸는" 일이며, 이 모듈은 그 가운데 목록과 변수까지를 다룹니다.

왜 이게 필요했나

kubespray 는 설치 도중 인터넷에서 꽤 많은 것을 받습니다. 이 코스의 실측 설치에서도 github.com 릴리스(containerd·runc·etcd·CNI 플러그인·calicoctl), dl.k8s.io(kubeadm·kubelet·kubectl), registry.k8s.io·quay.io·docker.io 의 이미지, 우분투 apt 저장소의 패키지를 받았습니다. 금융·공공·제조 현장의 서버는 이 가운데 어느 것에도 닿지 않습니다. 그래서 kubespray 문서의 폐쇄망 절은 미리 가져가야 할 것을 다섯으로 나눕니다 — 정적 파일(바이너리·압축), OS 패키지, 컨테이너 이미지, 그리고 선택으로 파이썬 패키지와 Helm 차트. 그리고 사내에 차려야 할 것도 그에 맞춰 적습니다 — 파일용 HTTP 미러, 사내 deb·rpm 저장소, 사내 컨테이너 레지스트리, 선택으로 PyPI 와 Helm 저장소.

어떻게 동작하나

목록은 도구가 만듭니다. contrib/offline/generate_list.sh 는 download.yml 에서 *_download_url 과 이미지의 repo·tag 를 뽑아 틀(template)을 만들고, 작은 플레이북(generate_list.yml)으로 그 틀에 변수를 채워 temp/files.list 와 temp/images.list 를 냅니다. 이 VM 에서 실측하면 3.6초에 파일 24줄·이미지 48줄이 나옵니다. 켜지 않은 CNI(cilium·flannel 등)와 애드온의 것까지 모두 들어 있어서 실제 설치에 쓰이는 것보다 넉넉합니다 — 반입 심사를 한 번에 끝내려면 넉넉한 쪽이 낫습니다. 이미지의 출처는 quay.io 18·registry.k8s.io 18·docker.io 10·ghcr.io 2 였습니다.

함정: 목록 플레이북은 localhost 에서 돕니다. README 는 인벤토리나 group_vars 에 판 변수를 적고 -i 로 넘기라고 합니다. 그런데 generate_list.yml 의 대상은 hosts: localhost 이고, localhost 는 인벤토리의 어느 그룹에도 속하지 않아 all 의 group_vars 만 받습니다. 이 코스처럼 kube_version 을 group_vars/k8s_cluster 에 적어 두면(kubespray 샘플이 두는 자리입니다) 목록 플레이북은 그 값을 보지 못하고 기본값으로 목록을 만듭니다. 실측에서 인벤토리는 1.35.8 인데 목록은 1.36.4 로 나왔고, 오류도 경고도 없었습니다. -e kube_version=1.35.8 을 주거나 판을 group_vars/all 에 두어야 맞습니다.

주소는 변수로 바꿉니다. 샘플의 group_vars/all/offline.yml 과 문서가 보여 주는 변수는 두 갈래입니다.

이미지   kube_image_repo · gcr_image_repo · docker_image_repo · quay_image_repo · github_image_repo  → "{{ registry_host }}"
파일     github_url · dl_k8s_io_url · storage_googleapis_url · get_helm_url                         → "{{ files_repo }}/<원래 도메인>"
노드     containerd_registries_mirrors(containerd 2) · containerd_registry_auth(1.7)                 → 사내 레지스트리를 믿게
OS 패키지 ubuntu_repo · debian_repo · yum_repo                                                         → 사내 저장소

이미지는 레지스트리 주소만 바뀌고 경로(coredns/coredns:v…)는 그대로입니다. 파일도 문서의 팁대로 원래 도메인을 첫 디렉터리로 두면(files_repo/dl.k8s.io/release/…) 원본 URL 에서 미러 URL 로 기계적으로 옮길 수 있습니다. 이 변수들을 all 에 두는 이유는 etcd 만 맡은 노드도 받아야 하고, 위의 목록 플레이북도 읽어야 하기 때문입니다. 실측에서 all 에 둔 오프라인 변수로 목록 72줄이 한 줄도 빠짐없이 사내 주소로 바뀌었습니다.

제어 노드도 반입 대상입니다. kubespray v2.32.0 은 ansible==12.3.0 과 몇몇 파이썬 패키지를 정확한 판으로 요구합니다. 폐쇄망의 제어 노드에서 pip install -r requirements.txt 를 하려면 휠을 미리 내려받아 가야 하고, 내려받은 환경과 설치할 환경의 파이썬 판·아키텍처가 같아야 합니다. pip install --dry-run --no-index --find-links 로 인터넷 없이 풀리는지 밖에서 먼저 확인할 수 있습니다.

현장에서 만나는 모습

폐쇄망 반입은 대개 "목록 제출 → 심사 → 반입 → 설치" 순서이고, 목록이 틀리면 전체 일정이 한 바퀴 밀립니다. 가장 흔한 실수 셋은 이렇습니다. 판이 다른 목록(위의 함정), 이미지 주소 하나를 빠뜨린 오프라인 변수(그 한 이미지만 원래 도메인으로 받으려다 멈춘다), 그리고 제어 노드의 Ansible 을 잊는 것입니다. 이 모듈의 실습은 이 셋을 밖에서 미리 확인하는 순서로 짜여 있습니다.

실제로 사내 레지스트리를 띄우고 목록의 이미지를 옮겨 담고(manage-offline-container-images.sh), 파일 미러를 nginx 로 내보내고(manage-offline-files.sh), 인터넷이 끊긴 노드에서 설치를 끝까지 돌리는 일은 폐쇄망을 따로 다루는 코스에서 이어집니다. 여기서 만든 목록·대응표·파이썬 꾸러미가 그 코스의 입력입니다.

다음 실습에서 할 것

generate_list.sh 로 기본 목록을 만들고 출처별로 셉니다. 인벤토리를 넘겼을 때와 판을 -e 로 넘겼을 때 목록의 판이 어떻게 다른지 확인합니다. offline.yml 에 사내 미러 주소를 채워 목록이 전부 사내를 가리키는지 보고, 원본과 미러의 대응표를 만듭니다. 노드가 사내 레지스트리를 쓰게 하는 containerd 설정을 더하고, 마지막으로 Ansible 까지 담은 파이썬 꾸러미가 인터넷 없이 풀리는지 확인합니다.