Kubernetes (Helm)

nora-onprem Helm 차트는 Docker Compose 와 같은 다섯 개 서비스를 Kubernetes 클러스터에 배포합니다. 차트는 플랫폼 레포의 infra/onprem/helm/nora-onprem 에 있습니다.

설치

새 설치에서 필수 값은 postgres.password 하나뿐입니다.

helm install nora ./nora-onprem \
  --namespace nora --create-namespace \
  --set postgres.password='CHANGE_ME' \
  --set publicUrl='http://nora.example.internal'

차트는 릴리스 이름 아래 Deployment, StatefulSet, Service 를 프로비저닝합니다. 정확한 리소스 목록은 아래 차트가 만드는 것 을 참고하세요.

흔한 오버라이드

인그레스와 TLS 켜기

--set ingress.enabled=true \
--set ingress.host=nora.example.internal \
--set ingress.className=nginx \
--set ingress.tlsSecret=nora-tls

ingress.tlsSecret 을 세팅하면 NORA_COOKIE_SECURE=1 이 자동으로 켜집니다. 브라우저는 TLS 위의 세션 쿠키에 Secure 속성을 요구합니다.

프라이빗 레지스트리 사용 (에어갭)

tarball 이미지를 자체 레지스트리에 load 한 뒤 각 repository 를 오버라이드합니다. tarball 은 에어갭 tarball 을 참고하세요.

--set image.server.repository=registry.internal/nora-server \
--set image.server.tag=1.0.0 \
--set image.llmBridge.repository=registry.internal/nora-llm-bridge \
--set image.llmBridge.tag=1.0.0 \
--set imagePullSecrets[0].name=my-registry-secret

에어갭 부팅 프로브 켜기

--set deploy.airgap=true

프로브 타겟(기본 1.1.1.1:443) 이 여전히 도달 가능하면 서버가 부팅 시점에 exit 78 로 종료합니다. 운영자의 egress 격리에 대한 스모크 테스트입니다.

오프라인 라이선스 첨부

kubectl -n nora create secret generic nora-license \
  --from-file=license.json=./license.json

helm upgrade nora ./nora-onprem -n nora \
  --set license.fileSecret=nora-license --reuse-values

차트가 이 시크릿을 /etc/nora/license.json 에 마운트하고 서버에 NORA_LICENSE_FILE 을 지정합니다.

검색을 Qdrant 로 스위치

--set vectorStore.backend=qdrant

기본은 pgvector (Postgres pod 내장) 입니다. 벡터 검색을 전용 pod 에서 돌리고 싶을 때 qdrant 로 바꿉니다.

차트가 만드는 것

리소스	타입	용도
`<release>-nora-onprem-server`	Deployment + Service	Rust API 와 SPA (포트 8090)
`<release>-nora-onprem-llm-bridge`	Deployment + Service	LLM 서브프로세스 브릿지 (포트 8091)
`<release>-nora-onprem-postgres`	StatefulSet + Service	pgvector 붙은 Postgres (레플리카당 PVC)
`<release>-nora-onprem-redis`	Deployment + Service	캐시
`<release>-nora-onprem-qdrant`	StatefulSet + Service	벡터 스토어 (선택)
`<release>-nora-onprem-secrets`	Secret	DB 비밀번호와 라이선스 키
`<release>-nora-onprem`	Ingress	`ingress.enabled=true` 일 때만

아직 지원하지 않는 것

서버 멀티 레플리카. LLM 서브프로세스의 HOME 격리가 아직 미착륙이라 서버 pod 는 concurrency=1 로 돕니다.
HPA 와 오토스케일링. 위 항목에 의존합니다.
백업 · 복원 job. StatefulSet 의 PVC 에 표준 Postgres 도구를 사용하세요.
cert-manager Issuer 배선. 차트는 ingress.tlsSecret 이 가리키는 Secret 만 소비하므로 Issuer 는 여러분이 준비하세요.

업그레이드

helm upgrade nora ./nora-onprem -n nora \
  --set image.server.tag=1.2.0 \
  --set image.llmBridge.tag=1.2.0 \
  --reuse-values

새 서버 pod 의 첫 부팅에서 마이그레이션이 자동으로 실행됩니다 (NORA_RUN_MIGRATIONS=1).

마이그레이션은 additive-only 입니다. 스키마가 앞선 상태를 넘어 다운그레이드하려면 매칭되는 DB 스냅샷을 준비해 두세요.

언인스톨

helm uninstall nora -n nora
kubectl delete namespace nora   # PVC 까지 함께 삭제

helm uninstall 만 실행하면 PVC 는 남습니다. 실수로 삭제하는 경우에도 데이터가 살아남도록 하기 위해서입니다. 확실할 때 네임스페이스를 지우세요.

Docker Compose

같은 다섯 개 서비스를 호스트 한 대에.

에어갭 tarball

프라이빗 레지스트리에 push 할 이미지를 담는 아카이브.

CLI

SDK

Local App

Kubernetes (Helm)

설치

흔한 오버라이드

인그레스와 TLS 켜기

프라이빗 레지스트리 사용 (에어갭)

에어갭 부팅 프로브 켜기

오프라인 라이선스 첨부

검색을 Qdrant 로 스위치

차트가 만드는 것

아직 지원하지 않는 것

업그레이드

언인스톨

관련

Docker Compose

에어갭 tarball

​설치

​흔한 오버라이드

​인그레스와 TLS 켜기

​프라이빗 레지스트리 사용 (에어갭)

​에어갭 부팅 프로브 켜기

​오프라인 라이선스 첨부

​검색을 Qdrant 로 스위치

​차트가 만드는 것

​아직 지원하지 않는 것

​업그레이드

​언인스톨

​관련

Docker Compose

에어갭 tarball

설치

흔한 오버라이드

인그레스와 TLS 켜기

프라이빗 레지스트리 사용 (에어갭)

에어갭 부팅 프로브 켜기

오프라인 라이선스 첨부

검색을 Qdrant 로 스위치

차트가 만드는 것

아직 지원하지 않는 것

업그레이드

언인스톨

관련