[k8s] offline-kubespray 사용 방법

보통 쿠버네티스 클러스터를 구축할때 인터넷이 가능한 상황에서 구축을 많이하게 되는데, 때때로 고객사 망에 의해 인터넷이 안되는 환경에서 쿠버네티스 클러스터를 구축할때가 존재한다. 아래에서는 인터넷이 안되는 환경을 offline이라고 표현한다.

다행히 이런 인터넷이 안되는 환경에서 클러스터를 구축하는걸 도와주는 github repository가 존재한다.

https://github.com/kubespray-offline/kubespray-offline

GitHub - kubespray-offline/kubespray-offline: kubespray offline support scripts

kubespray offline support scripts. Contribute to kubespray-offline/kubespray-offline development by creating an account on GitHub.

github.com

해당 repository는 kubespray의 버전을 따라가는것으로 보여진다.

https://github.com/kubernetes-sigs/kubespray/tree/master

GitHub - kubernetes-sigs/kubespray: Deploy a Production Ready Kubernetes Cluster

Deploy a Production Ready Kubernetes Cluster. Contribute to kubernetes-sigs/kubespray development by creating an account on GitHub.

github.com

offline에서의 클러스터 구축 과정을 간단하게 요약하면

online환경(인터넷이 가능한)에서 kubespray를 돌릴수있는 파일들을 전부 준비(다운로드)
파일들을 USB에 담고
offline환경에서 kubespray를 실행한다.

offline kubespray 설치를 위한 서버 구성

테스트를 위한 VMWare 로 서버 구축을 진행
- 서버
  - 파일 서버 & container registry로 사용할 서버 1대 (RAM 4GB, 6 core, 90GB)
  - 쿠버네티스 구축을 위한 서버 1대 (RAM 4GB, 6 core, 60GB)
  - openssh-server 패키지를 설치해줘야한다
- 네트워크
  - 두개의 서버 모두 "호스트 전용 어댑터"( 인터넷 안됨 + 내부망 네트워크) 설정
    - 파일서버 주소: 192.168.56.104
    - 쿠버네티스 노드: 192.168.56.103
  - (참고로 "어댑터에 브리지"는 인터넷이 가능하면서 내부망 네트워크 구성이다.

offline kubespray 설치를 위한 파일 준비 (v2.23.1버전 기준)

해당 과정은 인터넷이 가능한 상태에서 진행해야합니다.

아래 명령어를 실행해서 offline-kubespray repository를 clone한다.

git clone https://github.com/kubespray-offline/kubespray-offline.git -b v2.23.1-0
cd kubespray-offline

이후 config.sh 파일안의 값을 수정해야하는데. 파일을 준비할때 컨테이너 이미지들을 pull을 해야해서 실행하려는 노드의 container runtime을 지정해줘야한다. 아래는 containerd의 예시이다.

#!/bin/bash

# Kubespray version to download. Use "master" for latest master branch.
KUBESPRAY_VERSION=${KUBESPRAY_VERSION:-2.23.1}
#KUBESPRAY_VERSION=${KUBESPRAY_VERSION:-master}

# container runtime for preparation node
# docker=${docker:-docker}
docker=${docker:-/usr/local/bin/nerdctl}

# Run ansible in container?
ansible_in_container=${ansible_in_container:-false}

수정을 다한 다음에 kubespray-offline 폴더아래에 ./download-all.sh 파일을 실행하여 offline상태의 kubespray를 돌리기 위한 파일들을 다운로드 받는다. 실행이 다된다면 동일한 경로에 outputs 폴더가 생성되는데 해당 폴더 아래에 필요한 파일들이 저장된다. outputs폴더 구조는 다음과 같다. (depth=1)

outputs
├── debs
│   └── local
│       └── pkgs
├── files
│   ├── kubernetes
│   │   ├── calico
│   │   │   └── v3.25.2
│   │   ├── cni
│   │   ├── cri-tools
│   │   ├── etcd
│   │   └── v1.27.10
│   └── runc
│       └── v1.1.12
├── images
├── patches
│   └── 2.18.0
├── playbook
│   └── roles
│       └── offline-repo
│           ├── defaults
│           ├── files
│           └── tasks
└── pypi
    ├── ansible
    ├── ansible-core
    ├── cffi
    ├── cryptography
    ├── cython
    ├── distro
    ├── files
    ├── flit-core
    ├── jinja2
    ├── jmespath
    ├── markupsafe
    ├── netaddr
    ├── packaging
    ├── pbr
    ├── pip
    ├── pycparser
    ├── pyyaml
    ├── resolvelib
    ├── ruamel-yaml
    ├── ruamel-yaml-clib
    ├── selinux
    ├── setuptools
    └── wheel

setuptools 75.3.0 파일 정보 추가

v2.23.1버전의 문제인지 모르겠지만 setuptools의 75.3.0버전이 존재하지 않아 kubespray실행시 에러가 발생한다. 따라서 아래와같이 setuptools 75.3.0 파일 및 정보를 추가한다.

# setuptools whl파일 다운로드
cd ./outputs/pypi/files
wget https://files.pythonhosted.org/packages/90/12/282ee9bce8b58130cb762fbc9beabd531549952cac11fc56add11dcb7ea0/setuptools-75.3.0-py3-none-any.whl

cd ../setuptools
ln -s ../files/setuptools-75.3.0-py3-none-any.whl setuptools-75.3.0-py3-none-any.whl

# index.html수정해서 75.3.0에 대한 버전 추가
nano index.html

'
<!DOCTYPE html>
<html>
  <head>
    <title>Links for setuptools</title>
  </head>
  <body>
    <h1>Links for setuptools</h1>
    <a href="setuptools-40.9.0-py2.py3-none-any.whl#sha256=a96b1bef41915307025ae357fde45c1ccbd2bb0d37b3a8bc239dddd55bd01ca3">setuptools-40.9.0-py2.py3-none-any.whl</a><br/>
    <a href="setuptools-75.3.0-py3-none-any.whl#sha256=f2504966861356aa38616760c0f66568e535562374995367b4e69c7143cf6bcd">setuptools-75.3.0-py3-none-any.whl</a><br/>
    <a href="setuptools-75.8.0-py3-none-any.whl#sha256=e3982f444617239225d675215d51f6ba05f845d4eec313da4418fdbb56fb27e3">setuptools-75.8.0-py3-none-any.whl</a><br/>
  </body>
</html>
'

outputs 폴더 압축 및 USB이동

아래 명령어를 이용하여 outputs폴더를 압축한다.

tar -zcvf outputs.tar.gz outputs

offline kubespray 실행

USB를 통해서 가져온 outputs 압축파일을 압축해제한다.

tar xzvf outputs.tar.gz
cd outputs

local fileserver & local container registry 생성

offline kubespray의 동작방식은 특정 서버에 파일서버와 컨테이너 registry를 띄워놓고 쿠버네티스 노드와 통신하여 필요한 파일들을 가져오는 방식이다. 따라서 이러한 역할을 하는 요소를 outputs/setup-all.sh 를 실행하여 준비한다.

offline-kubespray실행

outputs/extract_kubespray.sh 파일을 실행하면 위 config.sh파일에서 설정한 kubespray-{version} 폴더가 생성됨.

v2.23.1버전의 문제인지 kube_control_nodes groups 인식이 안되는 문제가 존재하여 roles/kubernetes/preinstall/tasks/0040-verify-settings.yml 파일을 아래와같이 수정해야한다.

# AS-IS
- name: Stop if either kube_control_plane or kube_node group is empty
  assert:
    that: "groups.get('{{ item }}')"
  with_items:
    - kube_control_plane
    - kube_node
  run_once: true
  when: not ignore_assert_errors
# ...(생략)


# TO-BE
- name: Stop if either kube_control_plane or kube_node group is empty
  fail:
    msg: "kube_control_plane or kube_node group is empty!"
  when:
    - groups.get('kube_control_plane', {}) | length == 0
    - groups.get('kube_node', {}) | length == 0
# ...(생략)

kubespray를 돌리기 위한 python 환경 세팅 (ubuntu 20.04)

cd outputs
python3.9 -m venv ~/.venv/default
source ~/.venv/default/bin/activate
./extract-kubespray.sh
cd kubespray-{version}
pip install -U pip
pip install -r requirements.txt

outputs 안에 있는 playbook 폴더를 kubespray폴더 아래로 복사

cd outputs
cp -r playbook kubespray-{version}/
cd kubespray-{version}

이후 아래와같이 사용할 inventory/../group_vars/all 폴더 아래에 offline.yml 파일을 수정. 192.168.56.104는 파일서버&container registry가 떠있는 서버 주소를 뜻함(예시용). 만약 containerd registry mirror설정이 필요하면 아래와같이 설정 진행.

설정하는 이유는 offline환경에서의 쿠버네티스 노드가 docker.io로 이미지 pull요청을 하면 안되니 docker.io로 요청을 하는것을 우리가 구축한 container registry로 트래픽이 가게끔 해주는것이다.

http_server: "http://192.168.56.104" # 192.168.56.104는 private registry를 올린 서버 주소
registry_host: "192.168.56.104:35000"

# Insecure registries for containerd
containerd_registries_mirrors:
  - prefix: "{{ registry_host }}"
    mirrors:
      - host: "http://{{ registry_host }}"
        capabilities: ["pull", "resolve"]
        skip_verify: true
  - prefix: docker.io
    mirrors:
      - host: "http://{{ registry_host }}"
        capabilities: ["pull", "resolve"]
        skip_verify: true
  - prefix: ghcr.io
    mirrors:
      - host: "http://{{ registry_host }}"
        capabilities: ["pull", "resolve"]
        skip_verify: true
  - prefix: gcr.io
    mirrors:
      - host: "http://{{ registry_host }}"
        capabilities: ["pull", "resolve"]
        skip_verify: true
  - prefix: quay.io
    mirrors:
      - host: "http://{{ registry_host }}"
        capabilities: ["pull", "resolve"]
        skip_verify: true
  - prefix: k8s.gcr.io
    mirrors:
      - host: "http://{{ registry_host }}" 
        capabilities: ["pull", "resolve"]
        skip_verify: true
  - prefix: registry.k8s.io
    mirrors:
      - host: "http://{{ registry_host }}" 
        capabilities: ["pull", "resolve"]
        skip_verify: true

files_repo: "{{ http_server }}/files"
yum_repo: "{{ http_server }}/rpms"
ubuntu_repo: "{{ http_server }}/debs"

# Registry overrides
kube_image_repo: "{{ registry_host }}"
gcr_image_repo: "{{ registry_host }}"
docker_image_repo: "{{ registry_host }}"
quay_image_repo: "{{ registry_host }}"

# Download URLs: See roles/download/defaults/main.yml of kubespray.
kubeadm_download_url: "{{ files_repo }}/kubernetes/{{ kube_version }}/kubeadm"
kubectl_download_url: "{{ files_repo }}/kubernetes/{{ kube_version }}/kubectl"
kubelet_download_url: "{{ files_repo }}/kubernetes/{{ kube_version }}/kubelet"
# etcd is optional if you **DON'T** use etcd_deployment=host
etcd_download_url: "{{ files_repo }}/kubernetes/etcd/etcd-{{ etcd_version }}-linux-amd64.tar.gz"
cni_download_url: "{{ files_repo }}/kubernetes/cni/cni-plugins-linux-{{ image_arch }}-{{ cni_version }}.tgz"
crictl_download_url: "{{ files_repo }}/kubernetes/cri-tools/crictl-{{ crictl_version }}-{{ ansible_system | lower }}-{{ image_arch }}.tar.gz"
# If using Calico
calicoctl_download_url: "{{ files_repo }}/kubernetes/calico/{{ calico_ctl_version }}/calicoctl-linux-{{ image_arch }}"
# If using Calico with kdd
calico_crds_download_url: "{{ files_repo }}/kubernetes/calico/{{ calico_version }}.tar.gz"

runc_download_url: "{{ files_repo }}/runc/{{ runc_version }}/runc.{{ image_arch }}"
nerdctl_download_url: "{{ files_repo }}/nerdctl-{{ nerdctl_version }}-{{ ansible_system | lower }}-{{ image_arch }}.tar.gz"
containerd_download_url: "{{ files_repo }}/containerd-{{ containerd_version }}-linux-{{ image_arch }}.tar.gz"

아래 명령어로 offline repo configuration(e.g. deb 파일 다운로드 주소등) 을 진행

ansible-playbook -i inventory/../hosts.yml playbook/offline-repo.yml --ask-become-pass

마지막으로 아래 명령어로 쿠버네티스 클러스터 구축을 진행

ansible-playbook -i inventory/sample/hosts.yml --become --become-user=root --ask-become-pass cluster.yml

저작자표시 비영리 변경금지

'Develop > DevOps' 카테고리의 다른 글

[helm] local-path-provisioner helm chart 작업 (0)	2025.03.25
[istio] terraform istio 설치 및 Gateway & VirtualService 사용 정리 (0)	2025.02.26
[DevOps] 인증서 관련해서 내용 정리 (1)	2024.12.19
[nginx-ingress] virtualserver, virtualserverroute (0)	2024.12.04
[github] github action Auto Assign 사용 (0)	2024.11.24

내 블로그 - 관리자 홈 전환	`Q` `Q`
새 글 쓰기	`W` `W`

글 수정 (권한 있는 경우)	`E` `E`
댓글 영역으로 이동	`C` `C`

이 페이지의 URL 복사	`S` `S`
맨 위로 이동	`T` `T`
티스토리 홈 이동	`H` `H`
단축키 안내	`Shift` + `/` `⇧` + `/`

개발 공부방

[k8s] offline-kubespray 사용 방법

offline kubespray 설치를 위한 서버 구성

offline kubespray 설치를 위한 파일 준비 (v2.23.1버전 기준)

setuptools 75.3.0 파일 정보 추가

outputs 폴더 압축 및 USB이동

offline kubespray 실행

local fileserver & local container registry 생성

offline-kubespray실행

'Develop > DevOps' 카테고리의 다른 글

티스토리툴바

단축키

내 블로그

블로그 게시글

모든 영역

« 2025/04 »
일	월	화	수	목	금	토
		1	2	3	4	5
6	7	8	9	10	11	12
13	14	15	16	17	18	19
20	21	22	23	24	25	26
27	28	29	30

[k8s] offline-kubespray 사용 방법

offline kubespray 설치를 위한 서버 구성

offline kubespray 설치를 위한 파일 준비 (v2.23.1버전 기준)

setuptools 75.3.0 파일 정보 추가

outputs 폴더 압축 및 USB이동

offline kubespray 실행

local fileserver & local container registry 생성

offline-kubespray실행

'Develop > DevOps' 카테고리의 다른 글

'Develop/DevOps' 관련글

티스토리툴바

단축키

내 블로그

블로그 게시글

모든 영역