Skip to content

install 동작 세부 설명

1. 문서 목적

이 문서는 ./instctl.sh install 한 줄로 진행되는 표준 설치 흐름의 단계별 정상 출력·점검 포인트 를 정리한 가이드입니다.

처음 설치는 single-node 시작 또는 multi-node 시작를 먼저 보고, 입력 파일·매핑 참조는 install 입력 세부 설명, 솔루션 스택 키 참조는 세부 설정을 참고하세요.

2. 주요 명령 개요

  • install : 입력값 확인, 준비 작업, 서비스 배포까지 한 번에 수행
  • status : 전체 또는 특정 컴포넌트 상태 확인
  • setup : 설정 파일 또는 external_files 반영
  • up : 서비스 배포 또는 재적용
  • restart : 특정 컴포넌트 재기동
  • destroy : 서비스와 스택 리소스 제거
  • uninstall : 환경 전체 제거

3. install 의 단계별 정상 출력

./instctl.sh install

내부적으로 init → 입력 반영 → (missing image preload) → (필요 시 image-load · retag/push) → setup → up 이 순서대로 실행됩니다. 단계마다 어떤 로그가 정상 출력인지, 무엇을 같이 확인하면 좋은지 정리합니다.

3.1 init 구간

솔루션 스택 이름을 Pulumi 에 등록하고 현재 작업 대상으로 설정합니다.

[INFO] stack 초기화: <stack 이름>
[INFO] stack 초기화 완료: <stack 이름>
[INFO] solution: konanllm

점검 포인트:

  • 의도한 솔루션 스택 이름이 출력되었는지
  • solution: konanllm 으로 인식되었는지

참고: init 을 단독으로 실행한 경우엔 추가로 [HINT] 다음 단계 … 두 줄이 출력됩니다. install 흐름 안에서는 setup·up 이 이어서 자동 실행되므로 같은 안내는 출력되지 않습니다.

3.2 입력 반영 구간 (대화식 입력 / prop)

입력 파일(inputs/konanllm-input.prop, inputs/konanllm-input.multi.prop) 의 값을 매핑 yaml 기준으로 솔루션 스택 파일에 반영합니다.

싱글 노드 설치의 경우 대화식 입력 화면이 항목별로 묻습니다.

[INFO] konanllm single-node interactive input 시작

[INFO] 항목: license.search_type
[INFO] 설명: kylin-search license type (필수).
[INFO] 현재값 (필수): <empty>
현재 값이 맞습니까? [Y/n]:
...
[INFO] 입력값 요약
  - license.search_type (필수) = ...
[INFO] 항목 설명 요약
  - license.search_type: ...
이 입력값으로 진행하시겠습니까? [Y/n]:

멀티 노드 설치는 대화식 입력 없이 inputs/konanllm-input.multi.prop 의 값을 그대로 솔루션 스택 파일에 반영합니다.

점검 포인트:

  • 필수 항목 (license.search_type) 이 빈 값으로 통과되지 않았는지
  • 마지막 "이 입력값으로 진행" 확인에 의도한 값들이 모두 나타나는지

3.3 image-load · retag/push 구간 (해당될 때만)

먼저 workspace/images/ 에서 enabled component 의 stack image 와 정확히 매칭되는 tar 를 찾아, local Docker daemon 에 없는 이미지가 있으면 best-effort 로 docker load 합니다. 같은 repository 추정 tar 가 있어도 tag/version 이 다르면 경고만 출력하고 계속 진행합니다.

그 다음, 입력 파일의 retag.repo 가 비어 있지 않으면 workspace/images/ 에 둔 이미지 tar 를 docker daemon 에 load 한 뒤 사이트 내부 레지스트리로 retag 하고 (옵션) push 합니다.

Harbor 같은 private registry 를 사용하는 경우에는 host 에서 먼저 docker login <registry> 를 1회 수행해야 합니다. installer container 내부가 아니라 host Docker daemon 의 인증 상태를 사용합니다.

[INFO] 이미지 로드 시작: N개 파일 (workspace/images)
[INFO] installer 이미지 tar 는 제외: ...
[INFO] loading: <tar>
[INFO]   <load 결과>
...
[INFO] <component>: <source> -> <target>
[INFO]   retag 완료: <target>

점검 포인트:

  • images/ 에 둔 tar 파일이 모두 load 되었는지
  • preload summary 에서 missing / mismatch / load_failed 가 없는지
  • retag 가 실패한 항목이 없는지 ([ERROR] retag 실패: <component>)
  • 실패 시 tag mismatch hint 가 나오면 stack YAML 의 image tag 와 workspace/images/ tar 의 tag 가 일치하는지 확인
  • Harbor 대상이면 host 의 ~/.docker/config.json 에 로그인 정보가 있는지

retag.repo 가 비어 있으면 retag/push 는 건너뛰지만, 그 전에 수행되는 missing image preload 는 계속 동작합니다.

3.4 setup 구간

배포에 필요한 작업 영역을 준비합니다 — 컴포넌트별 기본 설정·데이터를 workspace/components/ 로 복사하고, external_files/ 의 외부 파일을 작업 영역으로 옮기고, swarm 노드 라벨·소유주 정정 같은 host-action 을 적용합니다.

[INFO] stack 현황
  solution: konanllm
[INFO] external file 처리 (...)
[INFO] external file 복사 완료 (...): ...

setup 종료 직후 host-action 이 처리됩니다 — 컴포넌트별 chown, 필요 시 config 파일의 owner-preserve overwrite 등.

점검 포인트:

  • external_files/<컴포넌트>/... 가 실제로 workspace 로 복사되었는지
  • [HOST ACTION] container chown ... 류 메시지가 정상 적용되었는지

3.5 up 구간

Pulumi 가 솔루션 스택 파일을 읽어 컴포넌트 service 를 swarm 에 생성·갱신합니다 — 실제로 컨테이너가 떠오르는 단계입니다.

Previewing update (<stack>):
...
Updating (<stack>):
+ <component> created
...
Resources:
    + N created
    ~ M updated

점검 포인트:

  • + created / ~ updated 의 컴포넌트 수가 의도와 맞는지
  • ERROR 가 없는지

3.6 마무리 — status 로 상태 확인

배포된 service 가 정상 기동됐는지 확인합니다.

./instctl.sh status

각 service 가 Ready / Running 상태로 표시되면 정상입니다. 처음 설치에서는 이미지 pull 지연으로 Preparing 상태가 잠시 보일 수 있습니다.

4. 설치 후 운영 / 재반영

설치가 끝난 뒤 설정 변경, 외부 파일 반영, 이미지 교체처럼 운영 중 자주 수행하는 재반영 흐름은 운영 포인트 에서 다룹니다.

5. 다음 문서

  • single-node 시작: single-node 설치 절차
  • 세부 설정: 솔루션 스택 파일의 컴포넌트별 세부 설정 (수동 편집·문제 해결 시 참조)
  • 운영 포인트: 운영 중 자주 보는 상태와 컴포넌트별 주의점·트러블 케이스