Skip to content

KonanLLM 운영 포인트

1. 문서 목적

이 문서는 KonanLLM 설치 후 자주 사용하는 운영 명령과 상태 점검 포인트를 정리합니다. 전체 상태 확인, 컴포넌트별 재기동, external_files 반영, 서비스 제거와 같은 작업을 이 문서에서 다룹니다.

2. 우선 확인할 컴포넌트

문제가 생기면 아래 순서로 보는 것이 좋습니다. 데이터 plane 이 막혔으면 응용이 안 뜨고, 에이전트 plane 이 막혔으면 agent 호출이 실패하기 때문에 의존성 순으로 봅니다.

  • 데이터 plane: postgresql, redis, lakefs
  • 에이전트 plane: agent-server, opensandbox-server, sandbox-workspace
  • 응용 (Kylin solution): kylin-gaia, kylin-service, kylin-gateway, kylin-search
  • GPU 응용: kylin-docai-ocr, kylin-docai-vllm

3. 자주 쓰는 상태 확인 명령

./instctl.sh status
./instctl.sh status kylin-search
./instctl.sh status kylin-gaia
./instctl.sh status kylin-docai-ocr
./instctl.sh status kylin-docai-vllm

kylin-search는 host 고정 배치와 license 설정이 중요합니다.

확인 포인트:

  • 의도한 deploy_hosts 노드에 실제로 배치되었는지
  • status kylin-search에서 상태가 정상인지
  • setup 이후 license 관련 파일이 준비되었는지

5. gaia 관련 점검

kylin-gaia 는 모델 리포지터리 준비가 중요합니다.

확인 포인트:

  • external_files로 준비된 model_repo가 있는지
  • status kylin-gaia가 정상인지
  • 동적 할당용 GPU 후보군 설정이 의도한 값으로 반영되었는지
  • install 시 입력한 GPU 목록이 스택에 맞게 반영됐는지 확인
  • 초기 구동 후 Studio 대시보드 화면에 표시되는 GPU 정보 정상출력으로 확인 가능

6. OCR / vLLM 관련 점검

GPU 사용 컴포넌트는 host/GPU 설정과 외부 파일 준비가 중요합니다.

확인 포인트:

  • OCR의 host, gpu_uuid
  • vLLM backend별 host, gpu_uuid
  • 모델 웨이트가 external_files를 통해 준비되었는지
  • 해당 노드에서 실제 service가 올라왔는지

7. agent-server / sandbox plane 점검

에이전트 plane 은 agent-server (api / worker 2 service) + opensandbox-server + sandbox-workspace 3 컴포넌트로 구성됩니다. 한 곳이 막히면 graph 실행이나 사용자 코드 실행이 실패합니다.

확인 포인트:

  • agent-server 의 api / worker 가 각각 1 replica 로 떠 있는지
  • ./instctl.sh status agent-server 출력의 service 별 replicas 컬럼
  • agent-server 가 postgresql 과 redis 에 도달 가능한지
  • DATABASE_URL / REDIS_URL 이 가리키는 host 가 같은 swarm overlay 에서 DNS 로 풀리는지
  • opensandbox-server 가 docker socket 마운트와 sandbox network 에 정상 접속하는지
  • sandbox 컨테이너가 새로 spawn 될 때 kylin-network 에 join 하는지 확인
  • runtime.execd_image 가 노드에 pull 되어 있는지 (opensandbox-execd:<태그>)
  • sandbox-workspace 의 /workspaces / /staging bind mount 가 호스트 경로와 일치하는지
  • 멀티 노드면 NFS 같은 공유 저장소여야 함
  • agent-server 첫 sandbox 호출은 image pull 때문에 30~70 초 소요 가능 — OPENSANDBOX_TIMEOUT (기본 300) 안인지 확인

8. observability 관련 점검

필요하면 아래도 함께 확인합니다.

  • prometheus
  • grafana
  • otel-collector
  • dcgm-exporter

특히 dcgm-exporter는 gpu_hosts 설정과 GPU 노드 배치를 함께 확인해야 합니다.

9. 설치 후 재반영 시나리오

설정 한두 개를 바꿀 때 전체 install 을 다시 돌릴 필요는 없습니다. 시나리오별로 필요한 단계만 호출합니다.

9.1 라이선스 타입 / 서버 정보 변경

kylin-search.license_server / kylin-search.license_type 변경 시.

스택 파일 수정 (또는 input.prop 수정 후 install 재실행)
→ setup                 # kql.lic 파일 재생성
→ restart kylin-search  # bind mount 파일 변경은 up 으로 컨테이너 재기동 안 됨
→ status kylin-search

라이선스 값은 setup 단계에서 kql.lic 파일로 변환되어 bind mount 로 컨테이너에 노출됩니다. 파일 내용만 바뀌므로 stack spec 변경이 아니라서 up 만으로는 컨테이너가 재기동되지 않습니다. restart 로 명시 재기동해야 합니다.

9.2 GPU 노드 이동 / GPU UUID 변경

kylin-docai-ocr.host / kylin-docai-ocr.gpu_uuid / kylin-docai-vllm.backends[].host·gpu_uuid 변경 시.

스택 파일 수정 (또는 input.prop 수정 후 install 재실행)
→ setup                 # placement label 갱신을 위해 반드시
→ preview
→ up <component>
→ status <component>

이때 이전 노드의 service task 가 자동으로 정리되는지 확인합니다. docker service ps 출력에서 이전 노드의 task 가 남아 있다면 잠시 후 다시 확인하거나 restart 를 검토합니다.

9.3 external_files 추가 / 변경

번들 루트 external_files/<컴포넌트>/ 에 있는 파일을 추가·교체했을 때.

external_files/<컴포넌트>/<경로> 배치
→ setup --overwrite-external-files       # workspace 로 다시 복사
→ restart <컴포넌트>                       # bind mount 내용 변경은 up 으로는 컨테이너 재기동이 안 됨
→ status <컴포넌트>

external_files 변경은 stack spec 변경이 아니라 컨테이너 bind mount 내용 변경입니다. 따라서:

  • setup 단계에서 새 파일을 workspace 로 다시 복사해야 하고 (--overwrite-external-files 명시),
  • up 만으로는 Pulumi 가 spec 변경을 감지하지 못해 컨테이너가 재기동되지 않으므로 restart 로 명시 재기동해야 합니다.

9.4 컴포넌트 설정 파일 덮어쓰기

workspace/components/<컴포넌트>/ 의 yaml / json / conf 등 설정 파일을 다시 채워야 할 때 (원본을 갱신했거나 임시로 수정한 값을 되돌릴 때).

스택 파일·원본 설정 갱신
→ setup --overwrite-config           # yaml/json/conf 등 설정 파일 다시 덮어씀
→ restart <컴포넌트>                   # 컨테이너가 새 설정을 잡으려면 명시 재기동
→ status <컴포넌트>

설정 파일은 보통 bind mount 로 컨테이너에 노출되므로, 파일 내용만 바뀌어도 컨테이너가 자동으로 다시 읽지 않습니다 — restart 가 필요합니다.

컴포넌트 application 이 자체 사용자로 설정 파일의 소유주를 바꿔놓은 경우에도 setup --overwrite-config 가 권한 부족으로 막히지 않도록 자동 처리됩니다 (기존 owner / mode 유지하며 내용만 덮어씀).

9.5 이미지 태그 변경

스택 파일에서 image 태그 수정
→ preview               # 변경된 컴포넌트만 잡히는지
→ up <component>
→ status <component>    # docker service ps 의 IMAGE 컬럼 확인

이미지 pull 지연으로 preparing 상태가 오래 보일 수 있습니다.

9.6 컴포넌트 일시 비활성화 / 재활성화

특정 사이트나 환경에서 일부 컴포넌트를 잠시 제외하거나 다시 활성화할 때 사용합니다.

스택 파일의 disable_services 목록에 컴포넌트 이름을 추가 / 제거합니다.

  • 비활성화 (목록에 추가): 해당 컴포넌트는 preview / up 의 변경 대상에 더 이상 잡히지 않습니다. 이미 배포된 컴포넌트는 자동으로 내려가지 않으므로 ./instctl.sh destroy <component> 로 명시적으로 내려야 합니다.
  • 재활성화 (목록에서 제거): ./instctl.sh up <component> 또는 전체 up 으로 다시 올립니다.

disable_services 키의 자세한 의미는 세부 설정 을 보세요.

10. 재반영 시 자주 쓰는 명령

./instctl.sh up kylin-search
./instctl.sh up kylin-gaia
./instctl.sh up kylin-docai-ocr
./instctl.sh up kylin-docai-vllm

설정 변경 후에는 필요에 따라 setup을 먼저 다시 실행하세요.

11. 삭제 / 재설치 절차

KonanLLM 을 삭제하거나 다시 설치할 때는 먼저 목적 을 구분해서 판단하는 것이 좋습니다.

  • 서비스/스택만 다시 올리면 되는 경우: destroy 후 install 또는 up
  • 환경을 완전히 비우고 처음부터 다시 설치하는 경우: uninstall
  • node join 상태, overlay network, service-to-service 통신까지 꼬인 경우: swarm cluster 정리까지 검토

11.1 전체 삭제 후 다시 설치 (destroy)

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

확인 포인트:

  • 삭제 전에 필요한 설정 파일과 운영 데이터 백업이 끝났는지
  • external_files/, 공유 스토리지, bind mount 데이터는 별도로 관리해야 하는지
  • 동일 스택에 재설치할 것인지, 새 stack 으로 재구성할 것인지

single-node 에서는 보통 위 절차 후 ./instctl.sh install 재실행으로 충분합니다. destroy 는 이미지·workspace 데이터를 그대로 남기므로 재설치 시 image pull/setup 부담이 줄어드는 장점이 있습니다.

11.2 환경 완전 제거 후 다시 설치 (uninstall)

./instctl.sh uninstall

uninstall 은 destroy 에 더해 다음까지 한 번에 정리합니다.

  • 솔루션 이미지: 로컬 + worker 노드 (SSH)
  • named volume node-add-data (각 swarm 노드)
  • installer 컨테이너 stop/remove + installer 이미지 rmi
  • HOST_WORKSPACE_PATH 내부의 .pulumi / components / locks / dist / outputs / build / .cache / images / .current-stack
  • kylin-gaia 가 로드한 LLM 등은 graceful kill 단계에서 자동으로 언로드 (skip 하려면 --no-graceful)

확인 포인트:

  • 진행 직전 dry-list 가 보여 주는 삭제 대상이 의도와 맞는지
  • multi-node 환경이면 SSH 자격증명 입력에 답할 준비가 됐는지 (worker 노드 작업 시점에 컨테이너가 prompt, 한 번 입력 후 같은 run 내 재사용. 또는 INSTCTL_SWARM_SSH_USER / INSTCTL_SWARM_SSH_PASS env 로 사전 설정)
  • external_files/ 와 공유 스토리지의 운영 데이터 백업이 끝났는지
  • bundle 디렉토리(instctl.sh 위치) 는 보존되므로, 완전히 지우려면 상위에서 해당 bundle 디렉토리를 직접 제거할 의향이 있는지

옵션으로 일부 단계만 보존할 수 있습니다.

  • --keep-images / --no-cluster-images: 이미지는 보존 또는 로컬만 정리
  • --keep-workspace: workspace 내부 정리 skip
  • --keep-installer: installer 컨테이너·이미지 보존

상세 동작은 실제 실행 전 dry-list 와 prompt 를 기준으로 확인하세요. 설치 단계별 흐름은 install 동작 세부 설명을 함께 참고하면 됩니다.

11.3 특정 컴포넌트만 삭제 후 다시 올리기

./instctl.sh destroy <component>
./instctl.sh status <component>
./instctl.sh up <component>

컴포넌트 설정이나 외부 파일만 다시 반영하면 되는 경우에는 전체 삭제보다 이 흐름이 안전합니다.

11.4 multi-node 에서 swarm cluster 정리까지 필요한 경우

아래와 같은 경우에는 application 삭제만으로 복구되지 않을 수 있습니다.

  • worker 가 정상적으로 join 되지 않음
  • overlay network 기반 service 간 통신이 계속 실패함
  • 방화벽 / NIC / routing / VLAN 변경 후부터 swarm 통신 이상이 생김

이 경우에는:

  1. ./instctl.sh destroy 로 애플리케이션 리소스를 먼저 정리하고
  2. worker node 부터 swarm leave
  3. manager node 를 마지막에 정리하고
  4. swarm cluster 를 다시 구성한 뒤
  5. ./instctl.sh install 을 재실행합니다.

실행 순서는 위 다섯 단계를 그대로 따르면 됩니다. cluster 재구성 전에는 worker 부터 leave 하고 manager 를 마지막에 정리하는 순서를 유지하세요.

11.5 먼저 확인하면 좋은 문서

12. 자주 만나는 문제

증상 → 의심·확인 흐름. KonanLLM 환경에서 반복적으로 보고되는 케이스 위주입니다. multi-node 문제는 서비스 상태, 노드 접근성, shared storage 경로를 함께 확인하세요.

  • status kylin-search 의 docker service ps 출력에서 NODE 컬럼 확인
  • 의심 1: 스택의 deploy_hosts 또는 단수 deploy_host 가 실제 노드 호스트네임과 일치하는지 (대소문자 포함)
  • 의심 2: swarm 노드에 kylin-search==true label 이 붙었는지 — setup 단계가 label 을 자동으로 적용. label 누락이면 setup 재실행
  • 의심 3: 노드가 swarm 에 join 되지 않았거나 drain 상태 — docker node ls

12.2 라이선스 서버에 도달 안 됨

증상: kylin-search service logs 에 license 관련 connection 실패.

  • kylin-search.license_server 의 IP:Port 가 서비스 노드에서 도달 가능한지 (nc -zv <ip> <port>)
  • 사이트 방화벽이 해당 포트를 열어두었는지
  • 값 자체에 오타 (포트 콜론 누락 등) 가 없는지

12.3 GPU UUID 못 찾음 / 컨테이너 GPU 미접근

  • host (단수 키) 에 지정한 노드에서 nvidia-smi -L 실행해 gpu_uuid 가 일치하는지 확인
  • nvidia-container-toolkit 설치 누락 시 컨테이너 시작 자체가 실패 — docker info 의 Default Runtime 확인
  • vLLM 다중 backend 의 경우 backend 별 host/gpu_uuid 가 동일 노드의 다른 GPU 를 가리키는지 확인

12.4 external_files 의 새 파일이 컨테이너에 안 보임

  • setup 단계를 건너뛰었거나 --overwrite-external-files 를 안 줘서 옛 파일이 그대로일 가능성. 변경 후엔 ./instctl.sh setup --overwrite-external-files 재실행
  • setup 출력에서 변경한 파일의 "external file 복사 완료" 라인이 보이는지
  • setup 후에도 컨테이너가 옛 파일을 잡고 있을 수 있음 — ./instctl.sh restart <컴포넌트> 로 명시 재기동 (bind mount 내용 변경은 up 만으로는 재기동 안 됨)
  • 멀티 노드 swarm 에서 workspace 가 NFS 공유가 아니면 한 노드에만 복사된 상태 — HOST_WORKSPACE_PATH 가 공유 저장소인지 확인

12.5 agent-server 첫 호출이 timeout

증상: agent-server worker 가 sandbox 호출에서 timeout 발생, OPENSANDBOX_TIMEOUT exceeded 류 로그.

  • opensandbox-server 가 사용하는 execd_image 가 노드에 pull 되어 있는지 확인 (docker pull <image> 미리)
  • 첫 spawn 시 image pull 만 30~70 초 소요. OPENSANDBOX_TIMEOUT (기본 300) 안인지 확인
  • 사이트가 registry 접근이 막혀 있다면 미리 image 를 load 해두기

12.6 sandbox 가 spawn 됐지만 kylin-network 에 join 안 됨

  • opensandbox-server 의 config.toml 의 [docker] network_mode 가 kylin-network 인지 (또는 swarm_global_config.common_network_name 과 일치하는지)
  • swarm 의 overlay network 가 모든 노드에 propagate 되었는지 — docker network ls 의 SCOPE=swarm 확인

12.7 image pull 지연으로 preparing 상태가 너무 김

  • 처음 배포 시 노드별 image pull 시간 때문에 정상. 5~10 분 대기 후 다시 status 확인
  • 지속되면 docker service ps <service> 의 ERROR 컬럼 확인 — pull 권한 부재면 사이트 registry 인증 점검
  • 해소되지 않으면 노드에서 수동으로 docker pull <image> 시도해 권한·네트워크 분리

13. 다음 문서