Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

Spanner Omni 배포 업그레이드

이 문서에서는 이전 버전에서 최신 버전으로 Spanner Omni 배포를 업그레이드하는 방법을 설명합니다.

Spanner Omni는 비동기식 단계적 출시 상태 머신을 사용하여 서비스 중단 없이 안전하게 업그레이드할 수 있도록 지원합니다. 단계별 업그레이드를 사용하면 다음 작업을 할 수 있습니다.

데이터베이스 스키마 업데이트 적용
순차적 재시작 중에 바이너리 호환성을 확인합니다.
최종화 전에 오류가 감지되면 이전 버전으로 롤백합니다.

워크플로 업그레이드

Spanner Omni 업그레이드 프로세스는 여러 순차적 단계로 구성됩니다.

스키마 단계: 타겟 바이너리 버전을 사용하여 내부 데이터베이스 스키마 마이그레이션을 실행하여 배포를 준비합니다. 스키마 이전은 롤백할 수 없지만 이전 바이너리 버전과 하위 호환됩니다.
바이너리 단계: 순차적 다시 시작을 사용하여 배포의 모든 서버에서 서버 바이너리 또는 컨테이너 이미지를 업데이트합니다. 오류가 감지되면 최종화가 시작되기 전 언제든지 바이너리 또는 컨테이너 이미지를 이전 버전으로 롤백할 수 있습니다.
기능 사용 설정 단계: 버전 호환 기능을 사용 설정하며 모든 서버에서 바이너리를 업그레이드한 후에 시작됩니다. 업그레이드에 버전 호환 기능이 포함되지 않는 경우 이 단계가 적용되지 않을 수 있으며 기능이 상호 의존적인 경우 여러 라운드가 필요할 수 있습니다. 롤백을 지원하는 선택적 단계의 경우 Spanner Omni CLI를 사용하여 롤백을 시작할 수 있습니다.
완료 단계: 출시를 완료하여 타겟 버전을 봉인합니다. 최종화 단계가 시작된 후에는 롤백이 불가능합니다.

시작하기 전에

Spanner Omni 배포를 업그레이드하기 전에 다음 기본 요건을 충족해야 합니다.

실행 중인 Spanner Omni 배포가 있습니다. 자세한 내용은 Kubernetes에 배포 만들기 또는 VM에 배포 만들기를 참고하세요.
Spanner Omni CLI를 다운로드하고 설치했습니다.
CLI 명령어를 실행하는 머신에서 모든 Spanner Omni 내부 포트(TCP 15000~15027)에 대한 네트워크 액세스 권한이 있거나 배포 엔드포인트에 대한 네트워크 액세스 권한이 있습니다.
배포에서 전송 계층 보안 (TLS) 또는 상호 TLS (mTLS) 암호화를 사용하는 경우 유효한 인증서가 BASE_DIR/tls 아래의 기본 디렉터리에 있거나 클러스터에 마운트되어 있는지 확인하세요.
다음과 같이 타겟 출시를 식별했습니다.
- VM 배포의 경우 대상 출시 패키지 spanner-omni-server-TARGET_VERSION.tar.gz를 다운로드합니다.
- Helm 및 Kubernetes 배포의 경우 Artifact Registry에서 대상 컨테이너 이미지를 식별합니다(예: us-docker.pkg.dev/spanner-omni/images/spanner-omni:TARGET_VERSION).

1단계: 스키마 업그레이드 준비

업그레이드를 시작하려면 대상 버전의 출시를 준비합니다. 이 단계에서 Spanner Omni는 기존 서버가 계속 트래픽을 처리하는 동안 내부 데이터베이스 스키마 마이그레이션을 실행합니다.

배포 환경에 해당하는 탭을 선택합니다.

VM

VM 배포에서는 대상 출시 패키지를 다운로드하고 추출한 다음 추출된 Spanner Omni CLI를 사용하여 출시 준비를 시작합니다.

모든 Spanner Omni 내부 포트 (TCP 15000~15027)에 대한 네트워크 액세스 권한이 있는 배포의 서버에 로그인합니다.
타겟 출시 버전 패키지를 다운로드하고 압축을 풉니다.
```
tar -xzf spanner-omni-server-TARGET_VERSION.tar.gz -C EXTRACT_DIR
```
다음을 바꿉니다.
- TARGET_VERSION: 업그레이드할 대상 버전입니다(예: 2026.r4-lts).
- EXTRACT_DIR: 출시 패키지를 추출하는 디렉터리입니다(예: /tmp/target_spanner/).
추출된 CLI에서 rollouts prepare 명령어를 실행하여 출시 준비를 시작합니다.
```
EXTRACT_DIR/bin/spanner deployment rollouts prepare \
  --target-server-binary=EXTRACT_DIR/bin/spanner_server \
  --root-server=ROOT_SERVERS \
  --base-dir=BASE_DIR
```
다음을 바꿉니다.
- EXTRACT_DIR: 타겟 bin/spanner CLI와 bin/spanner_server 바이너리가 포함된 추출 디렉터리입니다.
- ROOT_SERVERS: 하나의 루트 서버 엔드포인트 또는 쉼표로 구분된 여러 루트 서버 목록입니다(예: localhost:15000 또는 server1:15000,server2:15000,server3:15000).
- BASE_DIR: Spanner Omni의 기본 디렉터리입니다(예: /spanner).
- 배포에서 TLS 또는 mTLS 암호화를 사용하는 경우 유효한 인증서를 가리키는 --ca-certificate-file=CA_CERT_FILE 및 --client-certificate-directory=CERT_DIR를 추가합니다.

Helm

Helm 배포에서 스키마 준비는 다중 서버 배포를 실행하는지 단일 서버 배포를 실행하는지에 따라 다릅니다.

다중 서버 배포 (고가용성 / 프로덕션): Helm이 스키마 준비를 자동으로 처리합니다. 3단계: 바이너리 또는 컨테이너 이미지 업데이트에서 helm upgrade를 실행하면 Helm 차트에서 spanner-prepare-for-upgrade 사전 업그레이드 후크 작업을 트리거하여 StatefulSet을 업데이트하기 전에 스키마 마이그레이션을 실행합니다. 바로 2단계: 활성 출시 상태 확인으로 진행합니다.
단일 서버 배포 (deployment.singleServer=true): 단일 서버 모드는 내부 서비스를 루프백 인터페이스 (127.0.0.1)에 엄격하게 바인딩하므로 네트워크 작업이 서비스에 도달할 수 없습니다. 타겟 컨테이너 이미지가 있는 임시 디버그 컨테이너를 사용하여 실행 중인 포드 내에서 로컬로 스키마 마이그레이션을 실행합니다.
```
kubectl debug pod/POD_NAME -n NAMESPACE \
  --image=us-docker.pkg.dev/spanner-omni/images/spanner-omni:TARGET_VERSION \
  --container=upgrade-prepare -i \
  -- /google/spanner/bin/spanner_server prepare_for_upgrade --root_server=127.0.0.1
```
다음을 바꿉니다.
- POD_NAME: 서버 포드의 이름입니다(예: spanner-a-0).
- NAMESPACE: 배포의 Kubernetes 네임스페이스입니다(예: spanner-ns).
- TARGET_VERSION: 업그레이드할 대상 버전입니다(예: 2026.r4-lts).

독립형 Kubernetes

Helm 없이 Kubernetes에 Spanner Omni를 배포하는 경우 타겟 이미지를 사용하여 활성 루트 서버에 대해 스키마 마이그레이션을 실행하는 독립형 Kubernetes 일괄 작업을 실행합니다.

다음 작업 매니페스트를 사용하여 spanner-prepare-upgrade.yaml이라는 파일을 만듭니다.

apiVersion: batch/v1
kind: Job
metadata:
  namespace: NAMESPACE
  name: spanner-prepare-for-upgrade
spec:
  # Fail fast on the first error to stop the rollout immediately.
  backoffLimit: 0
  template:
    metadata:
      namespace: NAMESPACE
    spec:
      restartPolicy: Never
      containers:
        - name: spanner-upgrade
          image: us-docker.pkg.dev/spanner-omni/images/spanner-omni:TARGET_VERSION
          command: ["/google/spanner/bin/spanner_server"]
          args:
            - "prepare_for_upgrade"
            - "--root_server=ROOT_SERVER_ENDPOINT"
          volumeMounts:
            - name: tls-certs
              mountPath: "/spanner/tls"
              readOnly: true
            - name: spanner-data
              mountPath: /spanner
      volumes:
        - name: tls-certs
          secret:
            secretName: tls-certs
            optional: true
            defaultMode: 256
        - name: spanner-data
          emptyDir: {}

다음을 바꿉니다.

NAMESPACE: 배포의 Kubernetes 네임스페이스입니다(예: spanner-ns).
TARGET_VERSION: 업그레이드할 대상 버전입니다(예: 2026.r4-lts).
ROOT_SERVER_ENDPOINT: 활성 루트 서버 포드의 엔드포인트입니다(예: spanner-a-0.pod.spanner-ns).

매니페스트를 적용하여 준비 작업을 실행합니다.
```
kubectl apply -f spanner-prepare-upgrade.yaml
```

2단계: 활성 출시 상태 확인

준비 단계가 완료되면 출시가 생성되었는지 확인하고 단계 상태를 검사합니다.

활성 출시를 나열하여 출시 ID를 가져옵니다.

spanner deployment rollouts list \
  --deployment-endpoint=DEPLOYMENT_ENDPOINT

DEPLOYMENT_ENDPOINT을 배포의 서버 엔드포인트(예: localhost:15000 또는 spanner-a-0.pod.spanner-ns:15000)로 바꿉니다.

출력은 다음과 비슷합니다.

NAME                         STATE          TARGET_VERSION    START_TIME                     END_TIME
rollouts/1788942172101727    IN_PROGRESS    2026.r3-beta      2026-09-09T08:22:52.101727Z    -

자세한 출시 단계 상태를 검사합니다.
```
spanner deployment rollouts describe ROLLOUT_ID \
  --deployment-endpoint=DEPLOYMENT_ENDPOINT
```
다음을 바꿉니다.
- ROLLOUT_ID: 숫자 출시 ID입니다(예: 1788942172101727).
- DEPLOYMENT_ENDPOINT: 배포에 있는 서버의 엔드포인트입니다.
출력은 다음과 비슷합니다.
```
name: rollouts/1788942172101727
phases:
    - name: rollouts/1788942172101727/phases/schema
      startTime: "2026-09-09T08:22:52.101727Z"
      state: SUCCEEDED
    - name: rollouts/1788942172101727/phases/binary
      startTime: "2026-09-09T08:23:29.585375Z"
      state: IN_PROGRESS
    - name: rollouts/1788942172101727/phases/finalize
      state: PENDING
sourceVersion: 2026.r2-beta.3
startTime: "2026-09-09T08:22:52.101727Z"
state: IN_PROGRESS
targetVersion: 2026.r3-beta
```
계속하기 전에 다음 단계 상태를 확인하세요.
- schema: 내부 데이터베이스 스키마 마이그레이션이 완료되었음을 나타내는 SUCCEEDED을 표시합니다.
- binary: IN_PROGRESS를 표시하여 출시 엔진이 바이너리 업데이트를 준비하고 있음을 나타냅니다.
- finalize: 바이너리 단계의 완료를 기다리는 PENDING를 표시합니다.

3단계: 바이너리 또는 컨테이너 이미지 업데이트

스키마 단계가 성공하면 배포의 모든 노드에서 실행 중인 서버 바이너리 또는 컨테이너 이미지를 타겟 버전으로 업데이트합니다.

배포 환경에 해당하는 탭을 선택합니다.

VM

VM 배포에서 순차적 재시작을 사용하여 모든 VM에서 spanner_server 바이너리를 업데이트합니다.

한 번에 하나의 장애 도메인 또는 영역 업데이트: 멀티 영역 배포에서 한 영역의 서버를 업데이트하고 안정성을 확인한 후 다음 영역을 업데이트합니다. 이렇게 하면 Paxos 합의 그룹이 정족수를 유지합니다.
점진적으로 다시 시작: 연속적인 쿼리 가용성을 유지하기 위해 동시에 다시 시작하는 서버가 5% 를 넘지 않도록 합니다.
서버 상태 확인: 다음 장애 도메인을 업데이트하기 전에 다시 시작된 모든 서버가 정상이고 클러스터에 다시 참여했는지 확인합니다.

Helm

Helm 배포에서 --reuse-values를 전달하거나 값 파일을 제공하여 기존 구성 값을 유지하면서 helm upgrade를 실행합니다.

다중 서버 배포 (프로덕션 / HA):
```
helm upgrade spanner-omni oci://us-docker.pkg.dev/spanner-omni/charts/spanner-omni \
  --version CHART_VERSION \
  -n NAMESPACE \
  --reuse-values \
  --set image.tag=TARGET_VERSION \
  --timeout 30m
```
Helm은 업그레이드 전 후크를 사용하여 1단계를 자동으로 실행한 다음 StatefulSet(rollout.staggered: true)의 순차적 영역별 순차적 업데이트를 시작합니다.

단일 서버 배포 (deployment.singleServer=true):

--set skipPrepareUpgrade=true를 명시적으로 전달하여 Helm이 사전 업그레이드 후크 작업을 건너뛰도록 합니다. 1단계를 이미 로컬에서 완료했기 때문입니다.

helm upgrade spanner-omni oci://us-docker.pkg.dev/spanner-omni/charts/spanner-omni \
  --version CHART_VERSION \
  -n NAMESPACE \
  --reuse-values \
  --set skipPrepareUpgrade=true \
  --set image.tag=TARGET_VERSION \
  --timeout 30m

다음을 바꿉니다.

CHART_VERSION: 대상 Helm 차트 버전입니다(예: 1.0.0).
NAMESPACE: 배포의 Kubernetes 네임스페이스입니다(예: spanner-ns).
TARGET_VERSION: 대상 컨테이너 이미지 태그입니다(예: 2026.r4-lts).

독립형 Kubernetes

Helm이 없는 맞춤 Kubernetes 배포에서는 StatefulSet 또는 Deployment 사양의 컨테이너 이미지를 TARGET_VERSION로 업데이트합니다.

장애 도메인에서 순차적 업데이트를 실행하여 한 번에 하나의 영역을 업데이트하고 쿼럼을 유지하기 위해 동시에 5% 이하의 포드를 다시 시작합니다.

4단계: 바이너리 단계 진행 확인

모든 서버 또는 포드를 타겟 버전으로 업데이트한 후 바이너리 단계가 성공적으로 완료되었는지 확인합니다.

출시 단계 상태를 확인합니다.

spanner deployment rollouts describe ROLLOUT_ID \
  --deployment-endpoint=DEPLOYMENT_ENDPOINT

다음을 바꿉니다.

ROLLOUT_ID: 숫자 출시 ID입니다(예: 1788942172101727).
DEPLOYMENT_ENDPOINT: 배포의 서버 엔드포인트입니다.

출력은 다음과 비슷합니다.

name: rollouts/1788942172101727
phases:
    - name: rollouts/1788942172101727/phases/schema
      startTime: "2026-09-09T08:22:52.101727Z"
      state: SUCCEEDED
    - name: rollouts/1788942172101727/phases/binary
      startTime: "2026-09-09T08:23:29.585375Z"
      state: SUCCEEDED
    - name: rollouts/1788942172101727/phases/finalize
      state: PENDING
sourceVersion: 2026.r2-beta.3
startTime: "2026-09-09T08:22:52.101727Z"
state: IN_PROGRESS
targetVersion: 2026.r3-beta

binary 단계 상태가 SUCCEEDED로 변경되었는지 확인합니다. 전체 출시 상태는 나머지 단계가 모두 완료될 때까지 IN_PROGRESS로 유지됩니다. phases/binary이 SUCCEEDED로 전환되면 배포가 나머지 단계로 진행될 준비가 된 것입니다.

5단계: 나머지 단계 예약 및 실행

바이너리 단계가 성공하고 배포가 안정적인지 확인되면 finalize 단계까지 출시의 나머지 단계를 예약합니다. finalize 단계 (출시의 마지막 단계)에서는 배포 전반에 걸쳐 새 버전을 봉인합니다. --deployment-endpoint를 지정하여 Spanner Omni 서비스에 대한 네트워크 액세스 권한이 있는 모든 머신에서 이 명령어를 실행할 수 있습니다.

PENDING 상태의 나머지 각 단계 (예: 있는 경우 enable_features, 그 다음 finalize)에 대해 다음 단계를 완료합니다.

단계를 예약합니다.

spanner deployment rollouts phases schedule PHASE_NAME \
  --rollout=ROLLOUT_ID \
  --deployment-endpoint=DEPLOYMENT_ENDPOINT

다음을 바꿉니다.

PHASE_NAME: 예약할 단계의 이름입니다(예: finalize 또는 enable_features).
ROLLOUT_ID: 숫자 출시 ID입니다(예: 1788942172101727).
DEPLOYMENT_ENDPOINT: 배포에 있는 서버의 엔드포인트입니다.

출력에 따르면 예약된 단계는 IN_PROGRESS입니다.

name: rollouts/1788942172101727
phases:
    - name: rollouts/1788942172101727/phases/schema
      startTime: "2026-09-09T08:22:52.101727Z"
      state: SUCCEEDED
    - name: rollouts/1788942172101727/phases/binary
      startTime: "2026-09-09T08:23:29.585375Z"
      state: SUCCEEDED
    - name: rollouts/1788942172101727/phases/finalize
      state: IN_PROGRESS
sourceVersion: 2026.r2-beta.3
startTime: "2026-09-09T08:22:52.101727Z"
state: IN_PROGRESS
targetVersion: 2026.r3-beta

단계가 성공할 때까지 기다리고 상태를 확인합니다.

spanner deployment rollouts describe ROLLOUT_ID \
  --deployment-endpoint=DEPLOYMENT_ENDPOINT

finalize까지의 모든 단계가 완료될 때까지 남은 각 단계에 대해 이 단계를 반복합니다.

최종 단계 (finalize)가 완료되면 모든 단계와 전체 출시 상태가 SUCCEEDED로 전환됩니다.

endTime: "2026-09-09T08:45:43.949702Z"
name: rollouts/1788942172101727
phases:
    - name: rollouts/1788942172101727/phases/schema
      startTime: "2026-09-09T08:22:52.101727Z"
      state: SUCCEEDED
    - name: rollouts/1788942172101727/phases/binary
      startTime: "2026-09-09T08:23:29.585375Z"
      state: SUCCEEDED
    - name: rollouts/1788942172101727/phases/finalize
      startTime: "2026-09-09T08:45:43.898111Z"
      state: SUCCEEDED
sourceVersion: 2026.r2-beta.3
startTime: "2026-09-09T08:22:52.101727Z"
state: SUCCEEDED
targetVersion: 2026.r3-beta

출시 목록에서 완료 상태를 확인합니다.

spanner deployment rollouts list \
  --deployment-endpoint=DEPLOYMENT_ENDPOINT

출력에서 출시가 완료되었음을 확인할 수 있습니다.

NAME                         STATE        TARGET_VERSION    START_TIME                     END_TIME
rollouts/1788942172101727    SUCCEEDED    2026.r3-beta      2026-09-09T08:22:52.101727Z    2026-09-09T08:45:43.949702Z

업그레이드 롤백

업그레이드 중에 문제가 발생한 경우 업그레이드를 롤백할 수 있는지 여부는 현재 출시 단계에 따라 달라집니다.

스키마 단계: 롤백할 수 없습니다. 준비 중에 적용된 내부 데이터베이스 스키마 이전은 순방향 전용이며 되돌릴 수 없습니다. 하지만 스키마 이전은 소스 버전과 하위 호환되므로 이전 서버 바이너리가 계속 정상적으로 작동할 수 있습니다.
바이너리 단계: 최종화가 시작되기 전 언제든지 이전 버전으로 롤백할 수 있습니다. 자세한 내용은 바이너리 또는 컨테이너 이미지 롤백을 참고하세요.
선택적 출시 단계: 자동 롤백을 지원하는 선택적 단계 (예: 기능 사용 설정)의 경우 Spanner Omni CLI를 사용하여 롤백을 시작합니다.
최종 단계: 롤백할 수 없습니다. 최종화가 시작되면 타겟 버전이 배포 전반에 걸쳐 영구적으로 봉인되며 롤백은 불가능합니다.

바이너리 또는 컨테이너 이미지 롤백

최종화가 시작되기 전에 바이너리 단계를 롤백하려면 모든 서버 또는 포드에서 순차적 다시 시작을 실행하여 이전 (소스) 버전을 복원합니다.

VM

VM 배포에서 모든 VM에 걸쳐 spanner_server 바이너리를 롤백합니다.

이전 spanner_server 바이너리 버전을 호스트에 배포합니다.
장애 도메인에서 점진적으로 서버를 다시 시작하여 한 번에 하나의 영역을 업데이트하고 Paxos 쿼럼을 유지하기 위해 동시에 5% 이하의 서버를 다시 시작합니다.
다음 장애 도메인으로 진행하기 전에 다시 시작된 모든 서버가 정상이고 클러스터에 다시 참여했는지 확인합니다.

Helm

Helm 배포에서 컨테이너 이미지 태그를 이전 버전으로 업데이트합니다.

helm upgrade spanner-omni oci://us-docker.pkg.dev/spanner-omni/charts/spanner-omni \
  --version CHART_VERSION \
  -n NAMESPACE \
  --reuse-values \
  --set image.tag=SOURCE_VERSION \
  --timeout 30m

다음을 바꿉니다.

CHART_VERSION: Helm 차트 버전입니다(예: 1.0.0).
NAMESPACE: 배포의 Kubernetes 네임스페이스입니다(예: spanner-ns).
SOURCE_VERSION: 되돌릴 이전 컨테이너 이미지 태그입니다(예: 2026.r2-beta.3).

독립형 Kubernetes

Helm이 없는 맞춤 Kubernetes 배포에서 StatefulSet 또는 Deployment 사양의 컨테이너 이미지를 SOURCE_VERSION로 업데이트합니다.

장애 도메인에서 순차적 업데이트를 실행하여 한 번에 하나의 영역을 업데이트하고 쿼럼을 유지하기 위해 동시에 5% 이하의 포드를 다시 시작합니다.

선택적 출시 단계 롤백

롤백을 지원하는 선택적 출시 단계 (예: 기능 사용 설정 단계)의 경우 rollouts rollback 명령어를 실행하여 롤백을 시작합니다.

spanner deployment rollouts rollback ROLLOUT_ID \
  --deployment-endpoint=DEPLOYMENT_ENDPOINT

다음을 바꿉니다.

ROLLOUT_ID: 숫자 출시 ID입니다.
DEPLOYMENT_ENDPOINT: 배포의 서버 엔드포인트입니다.

다음 단계

배포를 유지관리하는 방법을 알아보세요.
Kubernetes 배포를 확장하거나 VM 배포를 확장하는 방법을 알아봅니다.
모니터링 개요 알아보기

Spanner Omni 배포 업그레이드 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

워크플로 업그레이드

시작하기 전에

1단계: 스키마 업그레이드 준비

VM

Helm

독립형 Kubernetes

2단계: 활성 출시 상태 확인

3단계: 바이너리 또는 컨테이너 이미지 업데이트

VM

Helm

독립형 Kubernetes

4단계: 바이너리 단계 진행 확인

5단계: 나머지 단계 예약 및 실행

업그레이드 롤백

바이너리 또는 컨테이너 이미지 롤백

VM

Helm

독립형 Kubernetes

선택적 출시 단계 롤백

다음 단계

Spanner Omni 배포 업그레이드