install 입력 세부 설명

1. 문서 목적

이 문서는 ./instctl.sh install 이 읽는 입력 파일 의 각 키 의미와, 그 값이 솔루션 스택 파일의 어디로 흘러가는지를 정리합니다. 싱글 노드 / 멀티 노드 설치 둘 다 다룹니다.

절차 중심 가이드:

싱글 노드 설치는 single-node 시작
멀티 노드 설치는 multi-node 시작

2. 두 가지 입력 파일

inputs/konanllm-input.prop          # 싱글 노드 설치용 (single-node)
inputs/konanllm-input.multi.prop    # 멀티 노드 설치용 (multi-node)

install 은 두 파일의 존재 여부로 설치 방식을 정합니다.

inputs/ 상태	install 동작
`konanllm-input.prop` 만 있음	single-node 로 진행
`konanllm-input.multi.prop` 만 있음	multi-node 로 진행
두 파일 모두 있음	화면에서 모드 선택 (또는 `--single-node` / `--multi-node` 명시)
두 파일 모두 없음	install 중단

3. 입력 → 솔루션 스택 파일 관계

사용자가 직접 손대는 것은 입력 파일 입니다. install 은 이 값을 매핑 yaml 기준으로 자동으로 솔루션 스택 파일에 반영하고 배포까지 이어 갑니다.

inputs/konanllm-input.prop       ─┐
                                   │  install 단계의 매핑 yaml 기준으로 반영
inputs/konanllm-input.multi.prop ─┤
                                   ▼
                            stacks/Pulumi.my-site.yaml   ← 최종적으로 이 파일이 수정되어 배포에 반영됨
                                   │
                                   ▼
                            컴포넌트 컨테이너들

stack 파일을 직접 수동 편집할 일이 생기면 세부 설정 의 컴포넌트별 키 참조를 참고하세요.

4. 싱글 노드 설치 입력 파일

# kylin-search license type (필수).
license.search_type=

# license 서버 주소. 비우면 host published port 사용 ($HOST_IP:7580).
# 외부 license 서버 사용 시 "host:port" 명시.
license.server=

# konan-ocr 제품 사용 여부. true 면 docai-ocr/docai-vllm 함께 기동(GPU 필요),
# false 면 미기동
docai.use_konan_ocr=false

# docai-ocr GPU 할당 설정 (docai.use_konan_ocr=true 일 때만 사용, 기본 0번 GPU)
kylin-docai-ocr.gpu_index=0

# docai-vllm GPU 할당 설정 (기본 0번 GPU)
kylin-docai-vllm.gpu_index=0

# kylin-gaia METIS_INIT_GROUP_GPUS — GPU index CSV. 예) 0,1,2
# 빈 값이면 stack 에 반영하지 않고 skip 한다.
metis.init_group_gpus=

# retag 대상 repository. 빈값이면 retag/push 동작 안 함
retag.repo=
# true 면 retag 후 push, false 면 로컬 retag 만 수행
retag.push=false

싱글 노드 설치는 보통 받은 파일을 그대로 두고 install 실행 중 대화식으로 값을 채웁니다. 자세한 절차는 single-node 시작 를 보세요.

5. 멀티 노드 설치 입력 파일

# multi-node input — 노드 식별은 IP(CSV) 로 통일. Swarm join 후 IP↔hostname 매칭으로 배치·라벨 적용.
# Swarm 에 참여할 전체 노드 IP 목록 (manager + worker). 쉼표로 구분.
cluster_node_ips=
# GPU 가 있는 노드 IP 목록. dcgm-exporter GPU 모니터링 대상.
gpu_node_ips=

# kylin-search 를 올릴 노드 IP 목록. 쉼표로 구분.
kylin-search.node_ips=

# kylin-search license type (필수).
license.search_type=
# license 서버 주소. 비우면 manager host published port 사용 ($HOST_IP:7580).
# 외부 license 서버 사용 시 "host:port" 명시.
license.server=

# konan-ocr 제품 사용 여부. true 면 docai-ocr/docai-vllm 함께 기동(GPU 필요),
# false 면 미기동
docai.use_konan_ocr=false

# docai-ocr 를 올릴 노드 IP
kylin-docai-ocr.node_ip=
# docai-ocr GPU 할당 설정 (기본 0번 GPU)
kylin-docai-ocr.gpu_index=0
# docai-vllm 을 올릴 노드 IP
kylin-docai-vllm.node_ip=
# docai-vllm GPU 할당 설정 (기본 0번 GPU)
kylin-docai-vllm.gpu_index=0

# kylin-gaia METIS_INIT_GROUP_GPUS — "<node_ip>:gpu_index,gpu_index" 토큰을 space 로 구분.
# 예) 10.10.16.151:0,1,2 10.10.16.152:0,1,2
# IP 는 swarm hostname 으로 자동 변환. 빈 값이면 설정하지 않는다.
metis.init_group_gpus=

# retag 대상 repository. 빈값이면 retag/push 동작 안 함
retag.repo=
# true 면 retag 후 push, false 면 로컬 retag 만 수행
retag.push=false

멀티 노드 설치는 위 값을 환경에 맞게 사전에 편집해야 합니다. 자세한 절차는 multi-node 시작 를 보세요.

6. 각 키가 솔루션 스택의 어디로 가는가

./instctl.sh install 이 매핑 yaml 기준으로 반영하는 위치를 정리합니다 (싱글/멀티 노드 공통, 모드별 차이만 표시).

입력 키	솔루션 스택 반영 위치	비고
`license.search_type`	`kylin-search.runtime.license_type`	필수
`license.server`	`kylin-search.runtime.license_server`	비우면 default `$HOST_IP:7580`
`kylin-search.node_ips`	`kylin-search.runtime.deploy_hosts`	multi 는 입력값, single 은 wrapper 가 감지한 단일 노드 호스트로 자동 채움
`docai.use_konan_ocr`	`disable_services` (토글)	`true` 면 `kylin-docai-ocr` / `kylin-docai-vllm` 을 제외 목록에서 빼서 기동, `false`/빈값이면 제외 목록에 넣어 미기동. 기본값 `false` — konan-ocr 를 쓰려면 반드시 `true` 로 두어야 하며, `false` 면 아래 OCR/vLLM 관련 입력은 묻지 않고 무시됩니다
`kylin-docai-ocr.node_ip`	`kylin-docai-ocr.runtime.host`	multi 는 입력값, single 은 단일 노드 호스트 자동
`kylin-docai-ocr.gpu_uuid` / `gpu_index`	`kylin-docai-ocr.runtime.gpu_uuid`	UUID 우선, 없으면 index
`kylin-docai-vllm.node_ip`	`kylin-docai-vllm.runtime.backends[].host`	multi 는 입력값, single 은 단일 노드 호스트 자동
`kylin-docai-vllm.gpu_uuid` / `gpu_index`	`kylin-docai-vllm.runtime.backends[].gpu_uuid`
`gpu_node_ips`	`dcgm-exporter.runtime.gpu_hosts`	multi 는 입력값(CSV), single 은 단일 노드 호스트 한 개로 자동
`metis.init_group_gpus`	`kylin-gaia.env_overrides.METIS_INIT_GROUP_GPUS`	single 은 `"gpu_index,gpu_index"` 입력에 단일 호스트 자동 prefix → `"<host>:gpu_index,gpu_index"`. multi 는 `"ip:gpu_index,gpu_index ip:gpu_index,gpu_index"` 입력의 IP 를 swarm hostname 으로 변환. 빈 값이면 skip
`retag.repo` / `retag.push`	(stack 에 반영 안 됨)	install 흐름의 image retag/push 단계가 직접 사용

single 모드의 자동 채움은 wrapper 가 감지한 단일 노드 호스트 이름($SINGLE_HOST 치환)을 사용하므로, 입력 파일에 host / GPU 노드 IP 를 비워 두어도 동작합니다. multi 모드에서는 위 키들이 필수 입력입니다.

cluster_node_ips 는 stack 에 반영되지 않고 wrapper 가 swarm cluster 구성에 사용합니다 (manager 자동 감지 + worker SSH join).

7. 대화식 입력 (싱글 노드 설치 한정)

싱글 노드 설치에서는 install 실행 중 입력 파일의 항목을 하나씩 묻는 대화식 입력 화면이 뜹니다.

[INFO] konanllm single-node interactive input 시작

[INFO] 항목: license.search_type
[INFO] 설명: kylin-search license type (필수).
[INFO] 현재값 (필수): <empty>
현재 값이 맞습니까? [Y/n]:

Y (Enter) → 현재 값 유지하고 다음 항목으로
n → 새 값 입력 → 한 번 더 확인 → 다음 항목으로

멀티 노드 설치에서는 대화식 입력이 뜨지 않고 입력 파일의 값을 그대로 반영합니다. 사전 검증에서 필수 값이 빠져 있으면 prepare 단계에서 중단됩니다.

8. 다음 문서

single-node 시작: 싱글 노드 설치 절차
multi-node 시작: 멀티 노드 설치 절차
세부 설정: 솔루션 스택 파일 컴포넌트별 세부 설정 (수동 편집·문제 해결용)
install 동작 세부 설명: install 단계별 정상 출력 + 재반영 시나리오