영속화

영속화 (Persistence)

컨테이너는 기본적으로 휘발성이에요. 컨테이너가 사라지면 그 안에 있던 데이터도 함께 사라지죠. Weaviate를 Docker나 Kubernetes로 운영할 때는 볼륨을 마운트해서 데이터를 컨테이너 밖에 저장하고, 재시작할 때 그 볼륨에서 다시 불러오도록 해야 데이터가 보존됩니다. 이 페이지가 그 영속화(persistence) 설정을 다뤄요.

출처: 공식문서 — Persistence

Docker Compose에서 영속화

Docker Compose로 Weaviate를 실행할 때는 weaviate 서비스 아래 volumes 변수와, 환경변수로 고유한 클러스터 호스트명을 설정하면 됩니다.

services:
  weaviate:
    volumes:
    - /var/weaviate:/var/lib/weaviate
    environment:
      CLUSTER_HOSTNAME: 'node1'
      PERSISTENCE_DATA_PATH: '/var/lib/weaviate'

볼륨에 대해: /var/weaviate는 로컬 머신에서 데이터를 저장하고 싶은 위치예요. 콜론(:) 뒤의 /var/lib/weaviate는 컨테이너 안의 저장 위치로, 반드시 PERSISTENCE_DATA_PATH 변수와 일치해야 합니다.
호스트명에 대해: CLUSTER_HOSTNAME은 아무 이름이나 가능해요.

더 상세한 출력을 원하면 LOG_LEVEL 환경변수를 바꿉니다.

services:
  weaviate:
    environment:
      LOG_LEVEL: 'debug'

모듈 없이 외부 마운트 볼륨과 더 상세한 출력을 쓰는 완전한 Weaviate 예시:

services:
  weaviate:
    command:
    - --host
    - 0.0.0.0
    - --port
    - '8080'
    - --scheme
    - http
    image: cr.weaviate.io/semitechnologies/weaviate:1.39.0
    ports:
    - 8080:8080
    - 50051:50051
    restart: on-failure:0
    volumes:
    - /var/weaviate:/var/lib/weaviate  # <== 여기에 볼륨을 설정
    environment:
      QUERY_DEFAULTS_LIMIT: 25
      AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'true'
      PERSISTENCE_DATA_PATH: '/var/lib/weaviate'
      CLUSTER_HOSTNAME: 'node1'  # <== 임의의 이름으로 설정 가능

백업과의 관계

Weaviate는 v1.15(단일 노드), v1.16(멀티 노드)부터 네이티브 백업 모듈을 제공합니다. 그보다 오래된 버전에서는 여기서 설명한 방식으로 데이터를 영속화하면 백업이 됩니다. 자세한 내용은 백업 페이지를 참고하세요.

Kubernetes에서 영속화

Kubernetes 환경에서는 PersistentVolumeClaims를 통한 PersistentVolumes만 필요하다는 점만 기억하면 돼요. 다만 Helm 차트는 이미 외부 볼륨에 데이터를 저장하도록 구성되어 있습니다.

디스크 사용량 알림과 조치

v1.12.0부터 환경변수로 구성되는 두 단계의 디스크 사용량 알림·조치가 있어요. 두 변수 모두 선택이며, 설정하지 않으면 아래 기본값을 씁니다.

변수	기본값	설명
`DISK_USE_WARNING_PERCENTAGE`	`80`	디스크 사용량이 해당 %보다 높으면 영향받는 노드 디스크의 모든 샤드가 경고를 로깅
`DISK_USE_READONLY_PERCENTAGE`	`90`	디스크 사용량이 해당 %보다 높으면 영향받는 노드의 모든 샤드가 `READONLY`로 표시되고, 이후 모든 쓰기 요청이 실패

디스크 압박 때문에 샤드가 READONLY로 표시됐다가(공간을 확보했거나 임계값을 바꿨거나 해서) 다시 준비 상태로 만들고 싶으면 Shards API를 사용할 수 있어요.

메모리 매핑 전략

Weaviate는 디스크의 데이터를 메모리에 매핑합니다. 가상 메모리 사용 방식을 구성하려면 PERSISTENCE_LSM_ACCESS_STRATEGY 환경변수를 설정합니다. 기본값은 mmap이고, 대안으로 pread를 쓸 수 있어요.

두 방식은 내부 메모리 관리 동작이 달라요. mmap은 메모리 매핑 파일을 사용해서 파일을 프로세스의 가상 메모리에 매핑하고, pread는 주어진 오프셋에서 파일 디스크립터로부터 데이터를 읽는 함수입니다.

일반적으로 mmap이 메모리 관리상 유리한 선택일 수 있어요. 다만 메모리 부하가 높을 때 멈춤(stalling) 현상이 생기면 pread를 시도해 보는 걸 권장합니다.

TTL (Time-To-Live)

v1.36에 추가. 컬렉션 레벨의 Time-To-Live(TTL) 설정으로 지정 시간이 지난 뒤 객체를 자동 삭제하도록 구성할 수 있어요. 자세한 내용은 이 개념 문서와 설정 방법을 참고하세요.

영속화