Mengupgrade deployment Spanner Omni

Dokumen ini menjelaskan cara mengupgrade deployment Spanner Omni dari versi yang lebih lama ke versi yang lebih baru.

Spanner Omni menggunakan mesin status peluncuran bertahap asinkron untuk membantu memastikan upgrade yang aman tanpa gangguan layanan. Mengupgrade secara bertahap memungkinkan Anda melakukan hal berikut:

• Terapkan pembaruan skema database.
• Verifikasi kompatibilitas biner selama mulai ulang bertahap.
• Lakukan roll back ke versi sebelumnya jika Anda mendeteksi error sebelum penyelesaian.

Alur kerja upgrade

Proses upgrade Spanner Omni terdiri dari beberapa fase berurutan:

1. Fase skema: Menyiapkan deployment dengan menjalankan migrasi skema database internal menggunakan versi biner target. Migrasi skema tidak dapat di-roll back, tetapi kompatibel dengan versi biner sebelumnya.
2. Fase biner: Memperbarui biner server atau image container di semua server dalam deployment menggunakan mulai ulang bertahap. Jika mendeteksi error, Anda dapat melakukan roll back image biner atau container ke versi sebelumnya kapan saja sebelum finalisasi dimulai.
3. Fase pengaktifan fitur: Mengaktifkan fitur yang kompatibel dengan versi dan dimulai setelah Anda mengupgrade biner di semua server. Fase ini mungkin tidak berlaku jika upgrade tidak menyertakan fitur yang kompatibel dengan versi, dan dapat memerlukan beberapa putaran jika fitur saling bergantung. Untuk fase opsional yang mendukung rollback, Anda dapat memulai rollback menggunakan Spanner Omni CLI.
4. Fase penyelesaian: Menyelesaikan peluncuran, menyegel versi target. Setelah fase penyelesaian dimulai, rollback tidak dapat dilakukan.

Sebelum memulai

Sebelum mengupgrade deployment Spanner Omni, pastikan Anda memenuhi prasyarat berikut:

• Anda memiliki deployment Spanner Omni yang sedang berjalan. Untuk mengetahui informasi selengkapnya, lihat Membuat deployment di Kubernetes atau Membuat deployment di VM.
• Anda telah mendownload dan menginstal Spanner Omni CLI.
• Anda memiliki akses jaringan ke semua port internal Spanner Omni (TCP 15000 hingga 15027) dari mesin tempat Anda menjalankan perintah CLI, atau akses jaringan ke endpoint deployment Anda.
• Jika deployment Anda menggunakan enkripsi Transport Layer Security (TLS) atau mutual TLS (mTLS), pastikan sertifikat yang valid tersedia di direktori dasar Anda di bagian BASE_DIR/tls atau terpasang di cluster Anda.
• Anda telah mengidentifikasi rilis target:
  • Untuk deployment VM: download paket rilis target spanner-omni-server-TARGET_VERSION.tar.gz.
  • Untuk deployment Helm dan Kubernetes: identifikasi image container target di Artifact Registry, seperti us-docker.pkg.dev/spanner-omni/images/spanner-omni:TARGET_VERSION.

Langkah 1: Siapkan upgrade skema

Untuk memulai upgrade, siapkan peluncuran untuk versi target. Pada fase ini, Spanner Omni menjalankan migrasi skema database internal sementara server yang ada terus melayani traffic.

Pilih tab untuk lingkungan deployment Anda:

VM

Dalam deployment VM, download dan ekstrak paket rilis target, lalu gunakan Spanner Omni CLI yang diekstrak untuk memulai persiapan peluncuran.

Penting: Paket rilis Spanner Omni target mencakup CLI spanner dan biner spanner_server (biasanya di bawah bin/). Download dan ekstrak paket rilis target di host sebelum menjalankan fase persiapan.

1. Login ke server di deployment Anda yang memiliki akses jaringan ke semua port internal Spanner Omni (TCP 15000 hingga 15027).

2. Download dan ekstrak paket rilis target:

   tar -xzf spanner-omni-server-TARGET_VERSION.tar.gz -C EXTRACT_DIR
   

   Ganti kode berikut:

   • TARGET_VERSION: Versi target yang akan diupgrade, misalnya, 2026.r4-lts.
   • EXTRACT_DIR: Direktori tempat Anda mengekstrak paket rilis, misalnya, /tmp/target_spanner/.

3. Mulai persiapan peluncuran dengan menjalankan perintah rollouts prepare dari CLI yang diekstrak:

   EXTRACT_DIR/bin/spanner deployment rollouts prepare \
     --target-server-binary=EXTRACT_DIR/bin/spanner_server \
     --root-server=ROOT_SERVERS \
     --base-dir=BASE_DIR
   

   Ganti kode berikut:

   • EXTRACT_DIR: Direktori ekstraksi yang berisi biner bin/spanner CLI dan bin/spanner_server target.
   • ROOT_SERVERS: Satu endpoint server root atau daftar beberapa server root yang dipisahkan koma, misalnya, localhost:15000 atau server1:15000,server2:15000,server3:15000.
   • BASE_DIR: Direktori dasar untuk Spanner Omni, misalnya, /spanner.
   • Jika deployment Anda menggunakan enkripsi TLS atau mTLS, tambahkan --ca-certificate-file=CA_CERT_FILE dan --client-certificate-directory=CERT_DIR yang mengarah ke sertifikat yang valid.

Helm

Dalam deployment Helm, penyiapan skema bergantung pada apakah Anda menjalankan deployment multi-server atau server tunggal:

• Deployment multi-server (Ketersediaan tinggi / Produksi): Helm secara otomatis menangani penyiapan skema. Saat Anda menjalankan helm upgrade di Langkah 3: Perbarui biner atau image container, diagram Helm memicu tugas hook pra-upgrade spanner-prepare-for-upgrade untuk menjalankan migrasi skema sebelum memperbarui StatefulSet. Lanjutkan langsung ke Langkah 2: Verifikasi status peluncuran aktif.

• Deployment server tunggal (deployment.singleServer=true): Karena mode server tunggal mengikat layanan internal secara ketat ke antarmuka loopback (127.0.0.1), tugas jaringan tidak dapat menjangkaunya. Jalankan migrasi skema secara lokal di dalam pod yang sedang berjalan menggunakan container debug sementara dengan image container target:

  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
  

  Ganti kode berikut:

  • POD_NAME: Nama pod server, misalnya, spanner-a-0.
  • NAMESPACE: Namespace Kubernetes deployment, misalnya, spanner-ns.
  • TARGET_VERSION: Versi target yang akan diupgrade, misalnya, 2026.r4-lts.

Kubernetes Standalone

Jika Anda men-deploy Spanner Omni di Kubernetes tanpa Helm, jalankan tugas batch Kubernetes mandiri untuk menjalankan migrasi skema terhadap server root aktif menggunakan image target.

1. Buat file bernama spanner-prepare-upgrade.yaml dengan manifes job berikut:

   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: {}
   

   Ganti kode berikut:

   • NAMESPACE: Namespace Kubernetes deployment, misalnya, spanner-ns.
   • TARGET_VERSION: Versi target yang akan diupgrade, misalnya, 2026.r4-lts.
   • ROOT_SERVER_ENDPOINT: Endpoint pod server root yang aktif, misalnya, spanner-a-0.pod.spanner-ns.

2. Terapkan manifes untuk menjalankan tugas persiapan:

   kubectl apply -f spanner-prepare-upgrade.yaml
   

Langkah 2: Verifikasi status peluncuran aktif

Setelah langkah persiapan selesai, pastikan peluncuran telah dibuat dan periksa status tahapannya.

Catatan: Dalam deployment Helm multi-server, Helm membuat peluncuran selama helm upgrade di Langkah 3. Anda dapat memverifikasi status peluncuran selama atau setelah menjalankan langkah tersebut.

1. Buat daftar peluncuran aktif untuk mengambil ID peluncuran:

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

   Ganti DEPLOYMENT_ENDPOINT dengan endpoint server dalam deployment Anda, misalnya, localhost:15000 atau spanner-a-0.pod.spanner-ns:15000.

   Outputnya mirip dengan hal berikut ini:

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

2. Periksa status fase peluncuran yang mendetail:

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

   Ganti kode berikut:

   • ROLLOUT_ID: ID peluncuran numerik, misalnya, 1788942172101727.
   • DEPLOYMENT_ENDPOINT: Endpoint server dalam deployment Anda.

   Outputnya mirip dengan hal berikut ini:

   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
   

   Verifikasi status fase berikut sebelum melanjutkan:

   • schema: Menampilkan SUCCEEDED, yang menunjukkan bahwa migrasi skema database internal telah selesai.
   • binary: Menampilkan IN_PROGRESS, yang menunjukkan bahwa mesin peluncuran siap untuk update biner.
   • finalize: Menampilkan PENDING, menunggu penyelesaian fase biner.

Langkah 3: Perbarui image biner atau container

Setelah fase skema berhasil, update biner atau image container server yang sedang berjalan di semua node dalam deployment ke versi target.

Tips: Jika Anda melihat error atau penurunan performa, Anda dapat melakukan rollback biner atau image container ke versi sebelumnya kapan saja sebelum penyelesaian. Untuk mengetahui informasi selengkapnya, lihat Mengembalikan upgrade.

Pilih tab untuk lingkungan deployment Anda:

VM

Dalam deployment VM, update program biner spanner_server di semua VM menggunakan mulai ulang berkelanjutan:

• Perbarui satu domain atau zona yang gagal dalam satu waktu: Dalam deployment multi-zona, perbarui server di satu zona dan verifikasi stabilitasnya sebelum memperbarui zona berikutnya. Hal ini memastikan bahwa grup konsensus Paxos mempertahankan kuorum.
• Mulai ulang secara progresif: Mulai ulang tidak lebih dari 5% server secara bersamaan untuk mempertahankan ketersediaan kueri berkelanjutan.
• Verifikasi kondisi server: Pastikan semua server yang dimulai ulang dalam kondisi baik dan telah bergabung kembali ke cluster sebelum memperbarui domain kegagalan berikutnya.

Helm

Dalam deployment Helm, jalankan helm upgrade sambil mempertahankan nilai konfigurasi yang ada dengan meneruskan --reuse-values atau menyediakan file nilai:

• Deployment multi-server (Produksi / 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 otomatis menjalankan Fase 1 menggunakan hook pra-upgrade, lalu memulai update berkelanjutan berurutan per zona dari StatefulSet (rollout.staggered: true).

• Deployment server tunggal (deployment.singleServer=true):

  Teruskan --set skipPrepareUpgrade=true secara eksplisit agar Helm melewati tugas hook pra-upgrade, karena Anda telah menyelesaikan Fase 1 secara lokal:

  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
  

Ganti kode berikut:

• CHART_VERSION: Versi diagram Helm target, misalnya, 1.0.
• NAMESPACE: Namespace Kubernetes deployment, misalnya, spanner-ns.
• TARGET_VERSION: Tag image container target, misalnya, 2026.r4-lts.

Kubernetes Standalone

Dalam deployment Kubernetes kustom tanpa Helm, update image container dalam spesifikasi StatefulSet atau Deployment Anda ke TARGET_VERSION.

Lakukan update berkelanjutan di seluruh domain kegagalan, perbarui satu zona dalam satu waktu, dan mulai ulang tidak lebih dari 5% pod secara bersamaan untuk mempertahankan kuorum.

Langkah 4: Verifikasi progres fase biner

Setelah Anda mengupdate semua server atau pod ke versi target, verifikasi bahwa fase biner selesai dengan berhasil.

Catatan: Setelah semua server dalam deployment diupdate, Spanner Omni melacak kesehatan server selama periode pengamatan hingga 15 menit sebelum menandai fase binary sebagai SUCCEEDED.

Periksa status fase peluncuran:

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

Ganti kode berikut:

• ROLLOUT_ID: ID peluncuran numerik, misalnya, 1788942172101727.
• DEPLOYMENT_ENDPOINT: Endpoint server dalam deployment Anda.

Outputnya mirip dengan hal berikut ini:

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

Konfirmasi bahwa status fase binary berubah menjadi SUCCEEDED. Status peluncuran keseluruhan tetap IN_PROGRESS hingga semua fase yang tersisa selesai. Setelah phases/binary bertransisi ke SUCCEEDED, deployment siap dilanjutkan ke fase berikutnya.

Langkah 5: Jadwalkan dan jalankan fase yang tersisa

Jika fase biner berhasil dan Anda memverifikasi bahwa deployment Anda stabil, jadwalkan fase yang tersisa untuk peluncuran hingga fase finalize. Fase finalize (fase terakhir peluncuran) mengamankan versi baru di seluruh deployment. Anda dapat menjalankan perintah ini dari komputer mana pun yang memiliki akses jaringan ke layanan Spanner Omni dengan menentukan --deployment-endpoint.

Perhatian: Pengembalian ke versi sebelumnya tidak dapat dilakukan setelah finalisasi dimulai. Selesaikan peluncuran hanya setelah Anda mengamati deployment selama waktu yang cukup dan memvalidasi bahwa deployment tersebut berfungsi dengan baik dan stabil dalam beban kerja yang umum. Untuk mengetahui informasi selengkapnya, lihat Mengembalikan upgrade.

Untuk setiap fase yang tersisa dalam status PENDING (seperti enable_features jika ada, diikuti dengan finalize), selesaikan langkah-langkah berikut:

1. Jadwalkan fase:

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

   Ganti kode berikut:

   • PHASE_NAME: Nama fase yang akan dijadwalkan, misalnya, finalize atau enable_features.
   • ROLLOUT_ID: ID peluncuran numerik, misalnya, 1788942172101727.
   • DEPLOYMENT_ENDPOINT: Endpoint server dalam deployment Anda.

   Output menunjukkan bahwa fase terjadwal adalah 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
   

2. Tunggu hingga fase berhasil, dan verifikasi statusnya:

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

   Ulangi langkah-langkah ini untuk setiap fase yang tersisa hingga semua fase hingga dan termasuk finalize selesai.

   Setelah fase akhir (finalize) selesai, semua fase dan keseluruhan status peluncuran akan bertransisi ke 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
   

3. Konfirmasi status selesai dalam daftar peluncuran:

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

   Output mengonfirmasi bahwa peluncuran telah selesai:

   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
   

Me-roll back upgrade

Jika Anda mengalami masalah selama upgrade, apakah Anda dapat melakukan roll back upgrade bergantung pada fase peluncuran saat ini:

• Fase skema: tidak dapat di-rollback. Migrasi skema database internal yang diterapkan selama persiapan hanya bersifat maju dan tidak dapat dikembalikan. Namun, migrasi skema kompatibel dengan versi sumber, sehingga biner server sebelumnya dapat terus beroperasi secara normal.
• Fase biner: dapat di-roll back ke versi sebelumnya kapan saja sebelum finalisasi dimulai. Untuk mengetahui informasi selengkapnya, lihat Mengembalikan biner atau image container.
• Fase peluncuran opsional: untuk fase opsional yang mendukung rollback otomatis (seperti pengaktifan fitur), mulai rollback menggunakan Spanner Omni CLI.
• Fase penyelesaian: tidak dapat di-roll back. Setelah finalisasi dimulai, versi target akan disegel secara permanen di seluruh deployment dan rollback tidak dapat dilakukan.

Melakukan roll back image biner atau container

Untuk meng-rollback fase biner sebelum finalisasi dimulai, lakukan mulai ulang bertahap di semua server atau pod untuk memulihkan versi sebelumnya (sumber).

VM

Dalam deployment VM, kembalikan biner spanner_server di semua VM:

1. Deploy versi biner spanner_server sebelumnya ke host Anda.
2. Mulai ulang server secara progresif di seluruh domain kegagalan, perbarui satu zona dalam satu waktu dan mulai ulang tidak lebih dari 5% server secara bersamaan untuk mempertahankan kuorum Paxos.
3. Pastikan semua server yang dimulai ulang berfungsi dengan baik dan telah bergabung kembali ke cluster sebelum melanjutkan ke domain kegagalan berikutnya.

Helm

Dalam deployment Helm, perbarui tag image container kembali ke versi sebelumnya:

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

Ganti kode berikut:

• CHART_VERSION: Versi diagram Helm, misalnya, 1.0.
• NAMESPACE: Namespace Kubernetes deployment, misalnya, spanner-ns.
• SOURCE_VERSION: Tag image container sebelumnya yang akan dikembalikan, misalnya, 2026.r2-beta.3.

Kubernetes Standalone

Dalam deployment Kubernetes kustom tanpa Helm, update image container dalam spesifikasi StatefulSet atau Deployment Anda kembali ke SOURCE_VERSION.

Lakukan update berkelanjutan di seluruh domain kegagalan, perbarui satu zona dalam satu waktu, dan mulai ulang tidak lebih dari 5% pod secara bersamaan untuk mempertahankan kuorum.

Mengembalikan fase peluncuran opsional

Untuk fase peluncuran opsional yang mendukung rollback (seperti fase pengaktifan fitur), mulai rollback dengan menjalankan perintah rollouts rollback:

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

Ganti kode berikut:

• ROLLOUT_ID: ID peluncuran numerik.
• DEPLOYMENT_ENDPOINT: Endpoint server dalam deployment Anda.

Langkah berikutnya

• Pelajari cara Memelihara deployment.
• Pelajari cara Menskalakan deployment Kubernetes atau Menskalakan deployment VM.
• Pelajari Ringkasan Monitoring.