KonanLLM multi-node 시작

1. 문서 목적

이 문서는 KonanLLM 을 여러 대 서버(멀티 노드) 에 설치하는 절차를 처음부터 끝까지 설명합니다. 사전 준비 확인부터 파일 배치, 입력 파일 편집, 설치 실행, 설치 후 확인까지 이 문서 안에서 순서대로 따라가면 됩니다.

이 문서는 여러 대 환경(멀티 노드)에 설치하는 경우만 다룹니다. 서버 한 대에 설치하려면 single-node 시작 을 보세요.

멀티 노드 설치에서는 install 을 실행하는 서버가 Docker Swarm 의 manager node 가 되고, 나머지 서버는 worker node 로 참여합니다.

입력 파일 키 의미·매핑 관계 같은 참조 문서는 install 입력 세부 설명 을 보세요.

2. 사전 준비 확인

대상 환경: Ubuntu 기반 서버 여러 대 — manager 로 쓸 서버 1대와 worker 서버들. GPU 워크로드(konan-ocr 등)를 사용할 노드에는 GPU 가 장착되어 있어야 합니다.

설치에 참여할 모든 서버에 다음이 갖춰져 있어야 합니다. 항목별 확인 명령과 정상 기준을 함께 적었으니 서버마다 하나씩 확인하세요.

2.1 공통 (모든 노드)

Docker — 각 서버에 설치되어 있어야 합니다. 아래 명령이 오류 없이 실행되면 정상입니다.

docker version
systemctl status docker    # Active: active (running) 이면 정상

인터넷이 차단된 환경이라면 Docker 설치 패키지와 필요한 이미지를 사전에 별도로 준비해야 합니다.

Harbor 레지스트리 로그인 (온라인 패키지 설치 시) — 온라인 버전 설치 패키지는 컨테이너 이미지를 Harbor image registry 에서 받아옵니다. 설치를 진행하기 전에 설치에 참여하는 모든 노드(manager + worker)에서 docker CLI 로그인이 되어 있어야 이미지를 받을 수 있습니다.

docker login docker.konantech.com    # 모든 노드에서 각각 실행

로그인 계정과 비밀번호는 설치 패키지를 전달한 담당자에게 요청하세요. 로그인이 되어 있지 않으면 설치 중 이미지 pull 단계에서 실패합니다.

2.2 GPU 호스트

kylin-docai-ocr, kylin-docai-vllm, dcgm-exporter 등 GPU 워크로드가 올라가는 노드에는 아래가 모두 필요합니다.

NVIDIA 드라이버 — CUDA 13.0 이상을 지원하는 버전. nvidia-smi 실행 시 GPU 목록과 함께 우측 상단 CUDA Version 이 13.0 이상으로 표시되면 정상입니다.

nvidia-smi

NVIDIA Container Toolkit — Toolkit 을 통해 NVIDIA Container Runtime(통칭 nvidia-docker) 이 Docker 에서 GPU 컨테이너를 실행할 수 있어야 합니다.

nvidia-ctk --version    # 버전이 출력되면 설치되어 있는 것입니다

Docker default runtime — default runtime 이 nvidia 로 설정되어 있어야 합니다.

docker info | grep "Default Runtime"
# Default Runtime: nvidia    ← 이렇게 나오면 정상

확인 결과가 위와 다르면 (Docker 미설치, Toolkit 미설치, default runtime 이 nvidia 가 아님) 아래 2.3 대처 방법 절차대로 조치한 뒤 다시 확인하세요.

2.3 `Default Runtime: nvidia` 가 보이지 않을 때 대처 방법

확인 결과가 정상이 아니면 원인에 따라 아래 순서로 조치한 뒤 다시 확인합니다.

① Docker 자체가 설치되어 있지 않은 경우

curl -fsSL https://get.docker.com | sudo sh

인터넷이 차단된 환경이라면 사전에 준비한 Docker 설치 패키지로 설치합니다.

② NVIDIA Container Toolkit 이 설치되어 있지 않은 경우

apt 저장소를 등록한 뒤 nvidia-container-toolkit 을 설치합니다.

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | \
  sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
  sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

③ Docker 의 default runtime 이 nvidia 로 설정되어 있지 않은 경우

sudo nvidia-ctk runtime configure --runtime=docker --set-as-default
sudo systemctl restart docker

또는 /etc/docker/daemon.json 에 아래 항목을 직접 추가한 뒤 Docker 를 재시작해도 됩니다.

{
  "default-runtime": "nvidia"
}

④ 설정 반영 후 재확인

docker info | grep "Default Runtime"

Default Runtime: nvidia 가 출력되면 정상입니다.

2.4 SSH 접근

wrapper 가 manager 에서 worker 로 docker swarm join 을 보낼 때 단일 admin 계정으로 SSH 가 가능해야 합니다. 모든 worker 노드에 동일한 계정이 존재해야 하며, manager 서버에서 아래처럼 접속되는지 미리 확인하세요.

ssh <admin계정>@<worker_IP> hostname

sshpass 같은 호스트 OS 패키지는 별도로 설치할 필요 없습니다 — installer 이미지 안에 포함되어 있고 wrapper 가 컨테이너 안에서 실행합니다.

2.5 공유 스토리지 (HOST_WORKSPACE_PATH)

multi-node 에서는 HOST_WORKSPACE_PATH 가 모든 노드에서 같은 경로로 접근 가능한 공유 스토리지(NFS 등) 여야 합니다. 한 노드에만 있는 로컬 디렉터리를 가리키면 다른 노드의 컨테이너가 파일을 찾지 못합니다.

각 노드에서 아래 명령으로 같은 경로가 마운트되어 있는지 확인하세요.

df -h <공유_스토리지_경로>    # 모든 노드에서 동일 경로·동일 파일시스템이면 정상

3. 설치 파일 풀기

3.1 설치 패키지 압축 해제

번들은 manager 로 쓸 서버 한 대에만 풉니다 (worker 서버에는 번들을 풀지 않아도 됩니다).

tar -xvf konanllm-<version>-install-<timestamp>.tar
cd konanllm-install

예를 들어 파일명이 konanllm-3.2.1-rc-install-20260722041822.tar 라면:

tar -xvf konanllm-3.2.1-rc-install-20260722041822.tar
cd konanllm-install

압축 해제 후 생성되는 디렉터리 구성은 다음과 같습니다.

konanllm-install/
├── docker-compose.yml   # installer 컨테이너 구성 파일
├── docs/                # 설치·운영 문서
├── external_files/      # 모델 파일 배치 위치 (설치 전 직접 채워야 함)
├── images/              # 컨테이너 이미지 파일 위치 (docai 이미지 등)
├── inputs/              # 설치 입력 파일 (konanllm-input.prop, konanllm-input.multi.prop)
├── instctl.sh           # 설치·운영 명령 진입점 (install / status / destroy / uninstall)
├── stacks/              # 솔루션 스택 파일 위치
└── workspace/           # 작업 디렉터리 (HOST_WORKSPACE_PATH 기본 위치)

3.2 모델 파일 다운로드·배치

external_files/ 는 설치 패키지에 빈 구조로 제공되며, 설치 전에 모델 파일을 직접 받아서 배치해야 합니다. installer 가 자동으로 채워 주지 않습니다.

① 다운로드 — 모델 다운로드 페이지 에서 Konan-LLM-ENT-XX.tar.gz, embedding-10.tar, reranking-10.tar 를 받습니다. konan-ocr 를 사용하는 경우 kylin-docai-model.tar.gz 도 받습니다. 파일별 용도는 아래 표를 참고하세요.

파일	용도	필수 여부
`Konan-LLM-ENT-XX.tar.gz`	LLM 모델	필수
`embedding-10.tar`	embedding 모델	필수
`reranking-10.tar`	reranking 모델	필수
`kylin-docai-model.tar.gz`	DocAI 모델 / 이미지	DocAI 에서 사이냅 OCR 이 아닌 `konan-ocr` 를 사용하는 경우에만 필요

kylin-docai-model.tar.gz 는 DocAI 에서 사이냅 OCR 대신 konan-ocr 를 사용하는 경우에만 받으면 됩니다. 사이냅 OCR 을 사용한다면 받지 않아도 됩니다.

② 압축 해제

# XX 는 전달받은 모델 버전 번호에 맞게 바꿔 실행하세요 (예: Konan-LLM-ENT-13.tar.gz)
tar -xzvf Konan-LLM-ENT-XX.tar.gz
tar -xvf embedding-10.tar
tar -xvf reranking-10.tar
tar -xzvf kylin-docai-model.tar.gz    # konan-ocr 사용 시에만

kylin-docai-model.tar.gz 를 해제하면 아래 항목들이 생성됩니다.

모델 디렉터리: kylin-docai-ocr/, kylin-docai-vllm/
이미지 파일: release.konantech.com__5000__kylin-docai-ocr__1.0.0.tar, release.konantech.com__5000__vllm-openai__v0.19.1.tar

③ 배치 — 압축 해제 결과물을 아래 규칙대로 옮깁니다.

이미지 파일 → images/ : kylin-docai-model.tar.gz 해제 시 생성된 두 이미지 파일을 images/ 디렉터리에 넣습니다.

mv release.konantech.com__5000__kylin-docai-ocr__1.0.0.tar images/
mv release.konantech.com__5000__vllm-openai__v0.19.1.tar images/

모델 디렉터리 → external_files/ : kylin-docai-ocr, kylin-docai-vllm 디렉터리를 포함한 모델 디렉터리들을 아래 구조에 맞게 external_files/ 아래로 옮깁니다.

배치가 끝나면 최종적으로 아래 구조가 되어야 합니다.

external_files/
├── kylin-gaia/
│   └── model_repo/
│       ├── Konan-LLM-ENT-XX/
│       ├── embedding-10/
│       └── reranking-10/
├── kylin-docai-ocr/
│   └── PP-DocLayoutV2/
└── kylin-docai-vllm/
    ├── PaddleOCR-VL-Konan/
    └── PaddleOCR-VL-1.5/

images/
├── release.konantech.com__5000__kylin-docai-ocr__1.0.0.tar
└── release.konantech.com__5000__vllm-openai__v0.19.1.tar

4. 입력 파일 편집

멀티 노드 설치는 실행 전에 입력 파일을 환경에 맞게 편집해야 합니다.

vi inputs/konanllm-input.multi.prop

각 키의 의미와 입력 형식은 아래와 같습니다.

항목	의미	입력 형식 / 예시
`cluster_node_ips`	Swarm 에 참여할 전체 노드 IP 목록 (manager + worker) (필수) Swarm join 후 IP↔hostname 매칭으로 배치 라벨 적용 install 을 실행하는 서버(manager)의 IP 필수 포함	쉼표 구분 CSV 예: `192.168.0.32,192.168.0.7`
`gpu_node_ips`	GPU 가 있는 노드 IP 목록 (필수) `dcgm-exporter` GPU 모니터링 대상	쉼표 구분 CSV 예: `192.168.0.32`
`kylin-search.node_ips`	`kylin-search` 를 올릴 노드 IP 목록 (필수)	쉼표 구분 CSV 예: `192.168.0.7`
`license.search_type`	`kylin-search` 라이선스 타입 (필수)	발급받은 라이선스 타입 예: `SI32gn` (single-node 시작 3.2 작성법 참고)
`license.server`	라이선스를 검증하는 KLS(Konan License Server) 주소 비우면 manager host published port(`$HOST_IP:7580`) 사용 (single-node 시작 3.2 작성법 참고)	외부 라이선스 서버 사용 시 `host:port` 형식 예: `192.168.0.32:7581`
`docai.use_konan_ocr`	코난의 OCR 기능 사용 여부 `true` 면 `docai-ocr`/`docai-vllm` 함께 기동 타사 OCR 사용 시 `false` (미기동, 아래 docai node_ip 입력은 비워 둠)	`true` 또는 `false`
`kylin-docai-ocr.node_ip`	`docai-ocr` 를 올릴 노드 IP (`docai.use_konan_ocr=true` 일 때 필수)	예: `192.168.0.32`
`kylin-docai-ocr.gpu_index`	`docai-ocr` 가 사용할 GPU 번호 (기본 0번 GPU)	GPU index 숫자 예: `0`
`kylin-docai-vllm.node_ip`	`docai-vllm` 을 올릴 노드 IP	예: `192.168.0.32`
`kylin-docai-vllm.gpu_index`	`docai-vllm` 이 사용할 GPU 번호 (기본 0번 GPU)	GPU index 숫자 예: `0`
`metis.init_group_gpus`	`kylin-gaia` 가 LLM / embedding / reranking 모델 로드에 사용할 노드별 GPU 매핑 각 노드의 GPU 배치를 지정 빈 값이면 미설정	`"<node_ip>:gpu_index,gpu_index"` 를 space 로 구분 예: `192.168.0.32:0,1,2 192.168.0.7:0,1,2`
`retag.repo`	이미지 retag 대상 repository (사이트 내부 레지스트리 사용 시) 빈 값이면 retag/push 미수행	registry 주소 또는 빈 값
`retag.push`	`true` 면 retag 후 push, `false` 면 로컬 retag 만 수행	`true` 또는 `false`

작성 예시 — manager 192.168.0.32 + worker 192.168.0.7 2노드 구성, GPU 는 manager 에만 있는 경우:

cluster_node_ips=192.168.0.32,192.168.0.7
gpu_node_ips=192.168.0.32
kylin-search.node_ips=192.168.0.7
license.search_type=SI32gn
license.server=
docai.use_konan_ocr=true
kylin-docai-ocr.node_ip=192.168.0.32
kylin-docai-ocr.gpu_index=0
kylin-docai-vllm.node_ip=192.168.0.32
kylin-docai-vllm.gpu_index=0
metis.init_group_gpus=192.168.0.32:1,2
retag.repo=
retag.push=false

위 예시에서 metis.init_group_gpus 는 DocAI(gpu_index=0)가 쓰지 않는 GPU 1,2 를 지정했습니다. kylin-gaia 가 모델을 로드할 GPU 는 DocAI 계층이 사용하지 않는 GPU 를 권장합니다.

각 키가 솔루션 스택 파일의 어디로 반영되는지는 install 입력 세부 설명 에 정리되어 있습니다.

retag.repo / retag.push 를 사용해 Harbor 같은 사이트 내부 레지스트리로 이미지를 retag/push 할 경우, host 에서 먼저 docker login <registry> 를 1회 수행해야 할 수 있습니다. 설치 과정은 host Docker daemon 의 인증 상태를 사용합니다.

5. install 실행

manager 로 쓸 서버에서 한 줄로 실행합니다.

./instctl.sh install

install 을 실행하면 아래 순서로 진행됩니다. 각 단계에서 무엇을 물어보는지 설명과 함께 정리했습니다.

① 작업 디렉터리(HOST_WORKSPACE_PATH) 입력 — 처음 실행 시에만

HOST_WORKSPACE_PATH 가 .env 에 설정되지 않았습니다.
  default: /home/ubuntu/installer/konanllm-install/workspace
  - 싱글 노드 설치는 default 를 그대로 사용해도 됩니다.
  - 멀티 노드 설치는 모든 노드가 접근 가능한 공유 스토리지(NFS 등) 경로를 입력하세요.
  사용할 경로 (Enter=default):

설치 작업 파일을 저장할 디렉터리를 묻는 것입니다. 멀티 노드 설치에서는 default 를 그대로 쓰면 안 되고, 모든 노드가 같은 경로로 접근 가능한 공유 스토리지(NFS 등) 경로를 입력해야 합니다 (2.5 공유 스토리지 참고). 입력한 값은 .env 에 저장되어 다음 실행부터는 묻지 않습니다.

② install 대상 stack 확인

install 대상 stack: konanllm-swarm 사용하시겠습니까? [Y/n]: Y

배포에 사용할 stack(konanllm-swarm)을 쓸지 확인하는 것입니다. Y 를 입력합니다.

이때 아래와 같은 sync-user 경고가 나올 수 있습니다. stack 설정에 사용자 정보가 없거나 현재 호스트와 다르면 자동으로 현재 호스트 사용자 정보를 반영하는 정상 동작이므로 조치할 필요 없습니다.

[WARN] sync-user: stack 사용자 설정과 현재 호스트 정보가 다릅니다.
  - stack yaml: uid=<unset> gid=<unset> user=<unset>
  - host user : uid=1000 gid=1000 user=ubuntu
[INFO] sync-user: stacks/Pulumi.konanllm-swarm.yaml 에 현재 호스트 사용자 정보를 반영했습니다.

③ installer 이미지 pull + installer 컨테이너 기동

[+] up 30/30
 ✔ Image docker.konantech.com/konanllm/installer:v1.0.3-rc.1 Pulled
 ✔ Container installer                                       Started

installer 이미지를 받아 installer 컨테이너를 띄우는 단계입니다. 네트워크 상태에 따라 수 분 정도 걸릴 수 있습니다. 이미지 pull 이 실패하면 Harbor 레지스트리 로그인 여부를 확인하세요 (2.1 공통 참고).

④ install 모드 선택

install 모드를 선택하세요 [single/multi] (default: single): multi

멀티 노드 설치이므로 반드시 multi 를 입력합니다. 기본값이 single 이기 때문에 그대로 Enter 를 누르면 single-node 모드로 진행되니 주의하세요. 잘못 진행했다면 10. 자주 발생하는 문제 의 대처를 보세요.

multi 를 입력하면 이어서 6. Swarm 자동 구성 단계 가 진행됩니다.

6. Swarm 자동 구성 단계

wrapper 가 다음 순서로 swarm cluster 를 자동 구성합니다.

멀티 노드 설치에서는 install 을 실행하는 서버가 Docker Swarm 의 manager node 가 됩니다. 즉, ./instctl.sh install 을 실행한 서버에서 docker swarm init 이 수행되고, 나머지 서버는 worker 로 join 됩니다.

[INFO] multi-node manager IP 자동 감지: <manager IP>
[INFO] multi-node install: docker swarm init --advertise-addr <manager IP>

cluster_node_ips 에서 현재 호스트의 IP 를 찾아 manager 로 init (이미 active 면 skip)
나머지 IP 가 worker 후보

이미 join 된 worker 가 있으면 다음과 같이 사전 필터 단계에서 skip 됩니다.

[INFO] 10.10.16.152: 이미 swarm 에 있음 (skip)
[INFO] swarm cluster 가 이미 완전 구성되어 있습니다 — SSH 단계 skip

아직 join 안 된 worker 가 남아 있으면 SSH 자격 증명을 한 번만 묻습니다 (모든 노드 공통).

multi-node SSH user (모든 노드 공통, 예: root): mckim
multi-node SSH password:

이후 wrapper 가 각 worker 에 docker swarm join 을 보냅니다.

[INFO] 10.10.16.152: docker swarm join 실행...
[OK] 10.10.16.152 joined
[INFO] multi-node swarm cluster 구성 완료 (joined=2, skipped=0)

--non-interactive 로 실행할 때는 INSTCTL_SWARM_SSH_USER, INSTCTL_SWARM_SSH_PASS env 로 자격 증명을 전달합니다.

7. install 본 흐름과 입력값 확인

swarm 구성이 끝나면 일반 install 흐름이 그대로 이어집니다.

prepare (init · 입력 반영 · [missing-image preload] · [retag/push] · setup)
→ host-action
→ deploy (up)

각 단계의 정상 출력·점검 포인트는 install 동작 세부 설명 을 보세요.

멀티 노드 설치에서는 single-node 처럼 항목별로 값을 입력받는 대신, inputs/konanllm-input.multi.prop 에 입력된 값을 읽어 입력값 요약으로 보여 주고 마지막에 한 번만 확인을 받습니다. 필수 값이 빠져 있으면 prepare 단계에서 중단됩니다.

[INFO] konanllm multi-node 입력값 요약

[INFO] 항목: cluster_node_ips
[INFO] 설명: multi-node input — 노드 식별은 IP(CSV) 로 통일. Swarm 에 참여할 전체 노드 IP 목록 (manager + worker).
[INFO] 현재값 (필수): 192.168.0.32,192.168.0.7

[INFO] 항목: gpu_node_ips
[INFO] 설명: GPU 가 있는 노드 IP 목록. dcgm-exporter GPU 모니터링 대상.
[INFO] 현재값 (필수): 192.168.0.32

... (kylin-search.node_ips, license.search_type, license.server,
     docai.use_konan_ocr, kylin-docai-ocr.node_ip / gpu_index,
     kylin-docai-vllm.node_ip / gpu_index, metis.init_group_gpus,
     retag.repo, retag.push 순서로 동일하게 출력) ...

[INFO] 항목 설명 요약
  - cluster_node_ips: ...
  - license.search_type: kylin-search license type (필수).
  ...
이 입력값으로 multi-node install 을 진행하시겠습니까? [Y/n]:

요약에 표시된 각 항목의 값이 konanllm-input.multi.prop 에 입력한 값과 일치하는지 확인한 뒤:

모든 값이 맞으면 Y (Enter) 를 눌러 설치를 진행합니다.
잘못된 값이 있으면 n 을 눌러 중단하고, inputs/konanllm-input.multi.prop 을 수정한 뒤 ./instctl.sh install 을 다시 실행합니다.

8. 설치 후 확인

설치가 끝나면 아래 명령으로 상태를 확인합니다.

./instctl.sh status

docker service ls 로도 각 서비스의 상태를 확인할 수 있습니다.

docker service ls

각 서비스의 REPLICAS 가 1/1 로 표시되면 정상 기동된 상태입니다.

REPLICAS 0/1 — 이미지 로드(image load)가 진행 중인 상태입니다. 비정상이 아니며, 1/1 로 정상화되기까지 다소 시간이 걸릴 수 있습니다. 처음 설치에서는 각 노드가 이미지를 받는 시간 때문에 preparing / 0/1 상태가 조금 길어질 수 있습니다.
REPLICAS 1/1 — 서비스가 정상 기동된 상태입니다.

0/1 상태가 장시간(수십 분 이상) 지속되면 해당 서비스의 로그를 확인해 원인을 파악합니다.

docker service logs <서비스명>
docker service logs -f <서비스명>   # 실시간 로그 확인

같이 보면 좋은 점검 포인트:

의도한 노드에 컴포넌트가 배치됐는지 — docker service ps <service> 의 NODE 컬럼 확인
GPU 컴포넌트(kylin-docai-ocr, kylin-docai-vllm, dcgm-exporter)가 GPU 노드에서 실행되는지
공유 스토리지(HOST_WORKSPACE_PATH) 가 모든 노드에서 동일 경로로 보이는지
kylin-search 가 1/1 인지 — 라이선스 값(license.search_type)이 잘못되면 기동에 실패합니다.
kylin-gaia 가 1/1 인지 — external_files/kylin-gaia/model_repo/ 아래 모델 배치가 잘못되면 기동에 실패합니다.

9. KonanLLM 삭제 / cluster 정리

삭제 이전에 kylin-gaia 가 로드한 LLM, embedding, reranking 모델들을 모두 언로드 하거나 직접 삭제하지 않으면 솔루션 삭제가 실패합니다. uninstall 을 쓰는 경우에는 자동 graceful kill 단계가 포함되어 있어 별도로 언로드하지 않아도 됩니다.

용도에 따라 두 가지 흐름이 있습니다.

(A) 서비스만 내리고 데이터는 보존 — 재설치 또는 재배포 예정인 경우:

./instctl.sh destroy
./instctl.sh status

destroy 는 service (swarm) / stack 리소스만 삭제합니다. HOST_WORKSPACE_PATH 의 workspace 디렉터리, 설정 파일, bind mount 데이터, 공유 스토리지 데이터는 그대로 남아 있어 기본적으로 데이터는 보전됩니다.

(B) 환경을 완전히 제거 — 이미지·workspace·installer 컨테이너까지 모두 정리:

./instctl.sh uninstall

uninstall 은 destroy + 잔여 정리 + named volume 제거 + 로컬·worker 노드 이미지 제거(SSH) + installer 컨테이너 down/rmi + HOST_WORKSPACE_PATH 내부 정리까지 한 번에 수행합니다. 진행 직전 dry-list 를 보여 주고 정확히 UNINSTALL 입력을 받아야 진행합니다. multi-node 환경에서는 worker 노드 작업(volume·이미지 제거) 시점에 SSH user/password 를 prompt 하며 한 번 입력하면 그 run 내에서는 캐시 재사용합니다 (또는 INSTCTL_SWARM_SSH_USER / INSTCTL_SWARM_SSH_PASS env 로 사전 설정).

bundle 디렉토리(instctl.sh 위치) 자체는 보존되며, 완전히 지우려면 상위 디렉토리에서 해당 bundle 디렉토리를 직접 제거하세요.

swarm cluster 초기화가 필요한 경우에는 운영 포인트 의 삭제 / 재설치 절차를 먼저 확인하세요.

10. 자주 발생하는 문제

installer/컴포넌트 이미지 pull 실패 (denied, unauthorized 등) → Harbor 레지스트리 로그인이 안 된 노드가 있는 경우입니다. 모든 노드에서 docker login docker.konantech.com 을 수행한 뒤 다시 시도하세요 (2.1 공통 참고).
install 모드에서 multi 대신 기본값(single)으로 잘못 진행한 경우 → ./instctl.sh destroy 로 정리한 뒤 ./instctl.sh install 을 다시 실행하고 multi 를 입력합니다.
cluster_node_ips 에 현재 호스트의 IP 가 없음 → install 즉시 실패. 해당 IP 가 hostname -I 출력에 있어야 합니다.
worker 의 SSH 자격 증명 불일치 → install 단계에서 join 실패. 모든 노드에 동일 계정이 존재해야 합니다.
HOST_WORKSPACE_PATH 가 한 노드만 가지고 있는 로컬 경로 → 다른 노드의 컴포넌트가 파일을 못 찾음. NFS 같은 공유 스토리지로 다시 설정 후 installer-recreate.
노드 이동·GPU UUID 변경 같은 사후 변경은 운영 포인트 의 재반영 시나리오를 보세요.

11. 다음 문서

single-node 시작: 서버 한 대 설치 절차
install 입력 세부 설명: 입력 파일·매핑 참조 (single/multi 공용)
install 동작 세부 설명: install 단계별 정상 출력 + 재반영 시나리오
운영 포인트: 운영 명령 모음