이 문서에서는 가상 머신 (VM) 및 Kubernetes에서 Spanner Omni 작업자를 배포, 확장, 사용 중단, 모니터링하는 방법을 설명합니다.
작업자는 Spanner Omni 서버에서 백그라운드 및 리소스 집약적 작업을 오프로드하도록 설계된 전용 스테이트리스(Stateless) 컴퓨팅 노드입니다. 작업자는 사용자 데이터를 호스팅하거나 리더 선출, 트랜잭션 또는 기타 핵심 데이터베이스 활동에 참여하지 않습니다. 서버와 달리 작업자는 특정 영역과 연결되지 않습니다. 대신 작업자는 위치에 등록하고 해당 위치의 모든 영역에 대해 작업을 실행할 수 있습니다. 작업자는 스테이트리스(Stateless)이며 데이터 이동이나 재조정이 필요하지 않으므로 작업자를 추가하고 삭제하는 것은 간단하고 즉각적입니다.
근사 최근접 이웃 (ANN) 검색 쿼리를 위해 대규모 테이블 (100만 개 이상의 행)에 벡터 색인을 빌드하려면 작업자가 필요합니다. 자세한 내용은 Spanner Omni 벡터 검색 개요를 참고하세요.
작업자는 Spanner Omni의 상업용 버전에서만 사용할 수 있습니다. 개발자 버전에서는 작업자를 지원하지 않습니다. 작업자의 컴퓨팅은 배포의 서버와 동일한 요금으로 청구됩니다 (vCPU당). 자세한 내용은 Spanner Omni 버전 개요를 참고하세요.
시작하기 전에
기존 Spanner Omni 배포에 작업자를 추가하기 전에 환경이 다음 요구사항을 충족하는지 확인하세요.
기존 배포: 상업용 버전으로 구성된
READY상태의 실행 중인 Spanner Omni 배포 (단일 서버 배포 아님)가 있는지 확인합니다. 개발자 버전은 작업자를 지원하지 않습니다. 작업자의 컴퓨팅은 배포의 서버와 동일한 요율로 청구됩니다. 자세한 내용은 Spanner Omni 버전 개요를 참고하세요. 다음 정보가 있는지 확인합니다.- 배포 구성에 정의된 타겟 위치 이름 (예:
us-central1)입니다. - 배포 엔드포인트(
HOST:PORT, 예:my-spanner-deployment:15003) 또는 클러스터 검색을 위한 루트 서버 주소 목록(ROOT_HOST_1:PORT,ROOT_HOST_2:PORT, 예:root-server-1:15000,root-server-2:15000)입니다.
- 배포 구성에 정의된 타겟 위치 이름 (예:
시스템 및 하드웨어 리소스: 작업자에게 할당하는 컴퓨팅 리소스가 허용되는 시간 내에 필요한 작업을 실행하기에 충분한지 확인합니다.
vSphere 구성: vSphere 가상화 플랫폼에서 Spanner Omni를 실행하는 경우 타임스탬프 카운터 (TSC)의 가상화를 사용 중지합니다. 가상 머신의
.vmx구성 파일에monitor_control.virtual_rdtsc = FALSE를 추가합니다.네트워크 및 방화벽 구성: 작업자는 표준 서버 통신 포트 (
15000~15025) 외에 포트15027를 사용합니다. 네트워크 구성에서 포트15000~15027의 통신을 허용하는지 확인하세요.
VM에 작업자 배포
가상 머신 (VM)에 작업자를 배포하려면 배포 엔드포인트 또는 루트 서버 목록을 사용하여 작업자 프로세스를 시작합니다.
옵션 A: 배포 엔드포인트 사용 시작
배포 엔드포인트를 사용하여 작업자를 시작하려면 spanner workers start 명령어를 실행합니다.
spanner workers start \
--location=LOCATION_NAME \
--address=WORKER_HOSTNAME:WORKER_PORT_BASE \
--deployment=DEPLOYMENT_ENDPOINT \
--base-dir=BASE_DIR \
--license-file-path=LICENSE_FILE_PATH
다음을 바꿉니다.
LOCATION_NAME: 대상 위치 이름(예:us-central1)WORKER_HOSTNAME: 작업자 VM의 확인 가능한 호스트 이름 또는 IP 주소입니다.WORKER_PORT_BASE: 작업자가 시작되는 기본 포트입니다(예:15000또는20000).DEPLOYMENT_ENDPOINT: 배포 엔드포인트의 호스트 및 포트입니다(예:my-spanner-deployment:15003).BASE_DIR: 작업자 데이터 및 로그의 기본 디렉터리입니다(예:/var/spanner).LICENSE_FILE_PATH: Spanner Omni 라이선스 파일의 경로입니다.
옵션 B: 루트 서버 목록 사용 시작
루트 서버 목록을 사용하여 작업자를 시작하려면 spanner workers start 명령어를 실행합니다.
spanner workers start \
--location=LOCATION_NAME \
--address=WORKER_HOSTNAME:WORKER_PORT_BASE \
--join-servers=ROOT_SERVER_1_HOST:ROOT_SERVER_PORT_BASE,\
ROOT_SERVER_2_HOST:ROOT_SERVER_PORT_BASE \
--base-dir=BASE_DIR \
--license-file-path=LICENSE_FILE_PATH
다음을 바꿉니다.
LOCATION_NAME: 대상 위치 이름(예:us-central1)WORKER_HOSTNAME: 작업자 VM의 확인 가능한 호스트 이름 또는 IP 주소입니다.WORKER_PORT_BASE: 작업자가 시작되는 기본 포트입니다(예:15000또는20000).ROOT_SERVER_1_HOST,ROOT_SERVER_2_HOST: 배포의 루트 서버 호스트 이름 또는 IP 주소ROOT_SERVER_PORT_BASE: 루트 서버의 기본 포트(예:15000)BASE_DIR: 작업자 데이터 및 로그의 기본 디렉터리입니다(예:/var/spanner).LICENSE_FILE_PATH: Spanner Omni 라이선스 파일의 경로입니다.
암호화 구성
Spanner Omni 배포에서 TLS 또는 mTLS 암호화를 사용하는 경우 각 작업자의 암호화를 구성합니다.
- 아직 작업자 호스트 이름을 포함하지 않은 경우 작업자 호스트 이름을 포함하도록 서버 인증서를 업데이트합니다.
ca.crt,server.crt,server.key가 포함된 인증서 디렉터리를 작업자 VM에 복사합니다.spanner workers start를 실행할 때--certificate-directory플래그를 추가합니다.spanner workers start \ --location=LOCATION_NAME \ --address=WORKER_HOSTNAME:WORKER_PORT_BASE \ --deployment=DEPLOYMENT_ENDPOINT \ --base-dir=BASE_DIR \ --certificate-directory=CERTIFICATE_DIRECTORY \ --license-file-path=LICENSE_FILE_PATHCERTIFICATE_DIRECTORY을ca.crt,server.crt,server.key이 포함된 디렉터리로 바꿉니다.
인증서 및 보안 배포 구성에 대한 자세한 내용은 VM에 보안 배포 만들기를 참고하세요.
Kubernetes에 작업자 배포
Google Kubernetes Engine (GKE) 또는 Amazon Elastic Kubernetes Service (Amazon EKS)와 같은 Kubernetes 환경에서는 클러스터와 동일한 네임스페이스에 기존 Spanner Omni Helm 출시의 일부로 작업자를 배포합니다.
Helm 차트는 작업자를 헤드리스 서비스가 있는 Kubernetes StatefulSet로 배포하여 각 작업자 포드에 안정적인 네트워크 ID와 PersistentVolumeClaims(PVC)를 제공하므로 루트 서버가 각 작업자와 안정적으로 통신할 수 있습니다.
기본적으로 Helm 차트는 spanner-role=workers 라벨이 지정된 노드에서만 작업자 포드를 예약하고, spanner-role=workers:NoSchedule 테인트를 허용하며, 노드당 최대 하나의 작업자 포드를 실행합니다. 작업자를 사용 설정하기 전에 이 라벨과 workers.replicas만큼 이상의 노드가 있는 테인트가 있는 노드 풀을 추가합니다. 각 노드에는 workers.resources.cpu 및 workers.resources.memory에 의해 설정된 대로 작업자 포드 하나에 할당 가능한 CPU와 메모리가 충분해야 합니다.
Kubernetes는 시스템 구성요소에 각 노드의 용량 일부를 예약하므로 이러한 값보다 큰 노드를 선택하세요. 다른 라벨을 사용하려면 workers.nodeLabelKey 및 workers.nodeLabelValue을 설정하세요. 라벨 요구사항을 삭제하려면 workers.nodeLabelKey=""를 설정합니다. 기본 일정 규칙을 대체하려면 workers.affinity을 설정하세요.
기존 배포에서 작업자를 사용 설정하려면 helm upgrade 명령어를 실행합니다.
helm upgrade spanner-omni HELM_CHART_PATH \
--reuse-values \
--set workers.enabled=true \
--namespace NAMESPACE
다음을 바꿉니다.
HELM_CHART_PATH: Spanner Omni Helm 차트의 경로NAMESPACE: Spanner Omni 클러스터가 배포된 Kubernetes 네임스페이스입니다(예:spanner-ns).
작업자가 할당 가능한 CPU와 메모리가 충분한 노드에서 실행되도록 하려면 workers.nodeLabelKey을 빈 문자열로 설정합니다. 이렇게 하면 노드 라벨 요구사항과 테인트 톨러레이션이 모두 삭제됩니다.
helm upgrade spanner-omni HELM_CHART_PATH \
--reuse-values \
--set workers.enabled=true \
--set workers.nodeLabelKey="" \
--namespace NAMESPACE
선택적 구성 설정에는 다음이 포함됩니다.
--set workers.replicas=WORKER_REPLICAS: 배포할 작업자 복제본 수입니다. 기본값은1입니다.--set workers.resources.cpu=CPU_CORES: 각 작업자의 CPU 한도 및 요청입니다. 기본값은6입니다.--set workers.resources.memory=MEMORY_LIMIT: 각 작업자의 메모리 한도 및 요청입니다. 기본값은24Gi입니다.--set workers.storage.size=STORAGE_SIZE: 각 작업자의 스토리지 용량입니다. 기본값은20Gi입니다.--set workers.storage.storageClassName=STORAGE_CLASS: 작업자 스토리지에 사용할 스토리지 클래스입니다(예: GKE의hyperdisk-balanced-rwo또는 Amazon EKS의aws-gp3). 기본값은 빈 문자열로, 클러스터 기본 스토리지 클래스를 상속합니다.--set workers.port=WORKER_PORT: 작업자가 리슨하는 네트워크 포트입니다. 기본값은deployment.basePort이며 이는15000입니다.--set workers.joinServers={ROOT_HOST_1:PORT,ROOT_HOST_2:PORT}: 참여할 루트 서버 주소의 명시적 쉼표로 구분된 목록입니다. 기본값은 빈 목록 ([])으로, 배포 토폴로지에서 모든 활성 루트 서버를 검색합니다.--set workers.nodeLabelKey=NODE_LABEL_KEY: 작업자를 전용 노드 풀로 격리하는 노드 어피니티 및 톨러레이션에 사용되는 Kubernetes 노드 라벨 키입니다. 기본값은spanner-role입니다. 노드 어피니티 및 허용 오차를 사용 중지하려면 빈 문자열""로 설정합니다.--set workers.nodeLabelValue=NODE_LABEL_VALUE: 노드 어피니티 및 톨러레이션에 사용되는 Kubernetes 노드 라벨 값입니다. 기본값은workers입니다.--set workers.pdbMaxUnavailable=MAX_UNAVAILABLE:PodDisruptionBudget의 자발적 중단 중에 사용할 수 없는 최대 작업자 포드 수입니다. 기본값은1입니다.workers.affinity: 작업자 포드의 맞춤 Kubernetes 어피니티 규칙입니다. 지정하지 않으면 기본 노드 선호도 (workers.nodeLabelKey및workers.nodeLabelValue사용)와 호스트 이름 간 포드 비선호도(kubernetes.io/hostname)가 적용됩니다. 중첩된 객체이므로-f플래그를 사용하여values.yaml파일에 지정합니다.
작업자 배포 확인
작업자 포드가 실행 중이고 준비되었는지 확인하려면 다음 명령어를 실행합니다.
kubectl get pods --namespace NAMESPACE -l app.kubernetes.io/component=spanner-worker
작업자 확장 및 사용 중단
작업자는 사용자 데이터를 저장하거나 데이터베이스 컨센서스에 참여하지 않습니다. 작업자 확장 및 해제는 즉시 이루어집니다. 벡터 색인 생성을 시작하기 전이나 후에 작업자를 시작할 수 있으며, 색인 생성이 완료된 후 즉시 작업자를 사용 중단할 수 있습니다.
작업자 확장 자동화
작업자 생성 및 확장을 자동화하려면 spanner_box_compute_heavy_workers_required 측정항목을 모니터링하세요. 측정항목 값이 0보다 크면 대규모 테이블에서 벡터 색인을 빌드하는 등 보류 중인 백그라운드 작업을 완료하기 위해 하나 이상의 작업자가 배포에 필요합니다.
측정항목 값이 0로 돌아가면 보류 중인 모든 작업이 완료된 것이므로 작업자를 사용 중단할 수 있습니다.
VM 작업자 사용 중단
VM에서 실행되는 작업자 프로세스를 중지하려면 작업자 프로세스를 실행하는 터미널에서 Control+C를 누르거나 프로세스 ID (PID)를 사용하여 프로세스를 중지합니다.
kill -TERM PID
PID를 spanner workers 프로세스의 프로세스 ID로 바꿉니다. 또는 작업자 VM을 종료합니다.
Kubernetes 작업자 사용 중단
Kubernetes에서 작업자를 사용 중단하려면 Helm 출시에서 작업자를 사용 중지하거나 kubectl를 사용하여 작업자 복제본을 직접 축소합니다.
작업자 사용 중지: 배포의 나머지 부분을 유지하면서 클러스터에서 작업자
StatefulSet및 서비스를 삭제하려면workers.enabled=false와 함께helm upgrade명령어를 실행합니다.helm upgrade spanner-omni HELM_CHART_PATH \ --reuse-values \ --set workers.enabled=false \ --namespace NAMESPACE다음을 바꿉니다.
HELM_CHART_PATH: Spanner Omni Helm 차트의 경로NAMESPACE: Spanner Omni 클러스터가 배포된 Kubernetes 네임스페이스입니다(예:spanner-ns).
작업자 복제본 축소: 클러스터에서 작업자 구성을 활성 상태로 유지하면서 작업자 포드를 복제본 0개로 축소하려면
kubectl scale명령어를 실행합니다.kubectl scale statefulset spanner-worker \ --replicas=0 \ --namespace NAMESPACENAMESPACE를 Spanner Omni 클러스터가 배포된 Kubernetes 네임스페이스로 바꿉니다(예:spanner-ns).
작업자 모니터링 및 문제 해결
배포에서 모니터링이 사용 설정된 경우 Prometheus 또는 Grafana 대시보드를 사용하여 작업자를 모니터링할 수 있습니다. 작업자는 Spanner Omni 서버와 유사한 측정항목을 노출합니다. Grafana 대시보드에는 각 작업자의 리소스 사용률을 모니터링할 수 있는 작업자 통계 대시보드가 포함되어 있습니다.
작업자는 --base-dir로 지정된 기본 디렉터리 내의 logs 하위 디렉터리에 로그 파일을 씁니다.
BASE_DIR/logs
spanner admin diagnostics create 명령어는 작업자로부터 로그나 진단을 수집하지 않습니다. 작업자 로그를 검사하려면 작업자 머신이나 포드에서 BASE_DIR/logs의 파일을 직접 보거나 Kubernetes 작업자 포드의 경우 kubectl logs를 실행합니다.
모니터링 및 대시보드 구성에 대한 자세한 내용은 모니터링 개요 및 Grafana 대시보드를 사용한 모니터링을 참고하세요.
벡터 색인 생성이 진행되지 않음
대규모 테이블에 벡터 색인을 만들었는데 색인 생성이 진행되지 않고 대기 상태로 유지되는 경우 하나 이상의 작업자가 실행 중이고 배포에 연결되어 있는지 확인합니다.
Spanner Omni를 사용하면 작업자가 활성 상태가 아니더라도 벡터 색인을 만들 수 있으므로 필요한 경우에만 작업자를 배포할 수 있습니다. 활성 작업자가 없으면 작업자가 배포될 때까지 색인 생성 작업이 무기한 일시중지됩니다. 작업자가 시작되고 배포에 등록되면 색인 생성이 자동으로 다시 시작됩니다.