Men-deploy paket armada

Halaman ini menjelaskan cara menggunakan paket fleet Config Sync untuk men-deploy resource Kubernetes di seluruh cluster yang terdaftar ke fleet. Setelah Anda membuat dan men-deploy paket fleet, saat Anda menambahkan cluster baru ke fleet, paket fleet akan otomatis men-deploy file konfigurasi Kubernetes di repositori Git ke cluster baru.

FleetPackage adalah API deklaratif untuk men-deploy manifes mentah Kubernetes ke kumpulan cluster. Semua resource Kubernetes yang ingin Anda deploy dengan paket armada harus sudah di-hydrasi (WET).

Sebelum memulai

1. Buat, atau pastikan Anda memiliki akses ke, repositori Git dengan resource Kubernetes yang ingin Anda deploy di seluruh fleet.

2. Instal dan lakukan inisialisasi Google Cloud CLI, yang menyediakan perintah gcloud dan nomos. Jika Anda menggunakan Cloud Shell, Google Cloud CLI sudah terinstal. Jika sebelumnya Anda telah menginstal Google Cloud CLI, dapatkan versi terbaru dengan menjalankan gcloud components update.

   Catatan: Untuk penginstalan gcloud CLI yang ada, pastikan untuk menyetel compute/region dan compute/zone properti. Dengan menyetel lokasi default, Anda dapat menghindari error di gcloud CLI seperti berikut: One of [--zone, --region] must be supplied: Please specify location.

3. Aktifkan Config Sync (anthosconfigmanagement) API dan ConfigDelivery API:

   gcloud services enable anthosconfigmanagement.googleapis.com configdelivery.googleapis.com
   

4. Menetapkan lokasi default:

   gcloud config set config_delivery/location us-central1
   

   Catatan: satu-satunya lokasi yang tersedia untuk ConfigDelivery API adalah us-central1.

5. Menetapkan project default:

   gcloud config set project PROJECT_ID
   

   Ganti PROJECT_ID dengan project ID project host fleet.

6. Pastikan cluster Anda terdaftar ke fleet.

7. Gunakan repositori Cloud Build untuk membuat koneksi ke penyedia yang didukung seperti GitHub atau GitLab. Saat menggunakan paket armada, Anda hanya perlu menyiapkan Cloud Build satu kali per repositori yang ingin disinkronkan.

   Penting: Koneksi Cloud Build Anda harus berada di us-central1 karena koneksi Git dan FleetPackage harus berada di region yang sama. ConfigDelivery API hanya tersedia di us-central1.

Meninjau persyaratan cluster

Sebelum menginstal Config Sync di cluster, tinjau rekomendasi dan persyaratan konfigurasi cluster.

Menyiapkan lingkungan Anda

Untuk menyiapkan lingkungan Anda bagi paket fleet Config Sync, berikan peran IAM yang diperlukan kepada pengguna yang mendaftarkan cluster.

Menginstal Config Sync

Anda dapat menginstal Config Sync dengan Google Cloud konsol atau Google Cloud CLI.

Konsol

Untuk menginstal Config Sync, semua cluster harus didaftarkan ke fleet. Saat Anda menginstal Config Sync di konsol Google Cloud , memilih masing-masing cluster akan otomatis mendaftarkan cluster tersebut ke fleet Anda.

1. Di konsol Google Cloud , buka halaman Config di bagian Features.

   Buka Config

2. Klik Instal Config Sync.

3. Di bagian Installation options, pilih Install Config Sync on entire fleet (recommended).

4. Klik Install Config Sync. Di tab Setelan, setelah beberapa menit, Anda akan melihat Diaktifkan di kolom Status untuk cluster di fleet Anda.

gcloud

1. Aktifkan fitur fleet ConfigManagement:

   gcloud beta container fleet config-management enable
   

2. Untuk mengaktifkan Config Sync, buat file bernama apply-spec.yaml dengan konten berikut:

   applySpecVersion: 1
   spec:
     configSync:
       enabled: true
   

3. Terapkan file apply-spec.yaml:

   gcloud beta container fleet config-management apply \
       --membership=MEMBERSHIP_NAME \
       --config=apply-spec.yaml
   

   Ganti MEMBERSHIP_NAME dengan nama keanggotaan fleet yang Anda pilih saat mendaftarkan cluster. Untuk menemukan nama keanggotaan, jalankan perintah gcloud container fleet memberships list.

Buat akun layanan untuk Cloud Build

Paket fleet menggunakan Cloud Build untuk mengambil resource Kubernetes dari repositori Git Anda dan men-deploy ke cluster Anda. Cloud Build memerlukan akun layanan yang memiliki izin untuk menjalankan tugas ini. Untuk membuat akun layanan dan memberikan izin yang diperlukan, selesaikan langkah-langkah berikut:

1. Buat akun layanan:

   gcloud iam service-accounts create "SERVICE_ACCOUNT_NAME"
   

   Ganti SERVICE_ACCOUNT_NAME dengan nama untuk akun layanan. Nama harus berupa ID alfanumerik dengan panjang antara 6 dan 30 karakter, misalnya my-service-account. Setelah membuat akun layanan, Anda tidak dapat mengubah namanya.

2. Tambahkan binding kebijakan IAM untuk peran Resource Bundle Publisher:

   gcloud projects add-iam-policy-binding PROJECT_ID \
      --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
      --role='roles/configdelivery.resourceBundlePublisher'
   

   Jika diminta, pilih None sebagai kondisi untuk kebijakan.

3. Tambahkan binding kebijakan IAM untuk peran Logs Writer:

   gcloud projects add-iam-policy-binding PROJECT_ID \
      --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
      --role='roles/logging.logWriter'
   

   Jika diminta, pilih None sebagai kondisi untuk kebijakan.

4. Tambahkan binding kebijakan IAM untuk peran ArtifactRegistry Writer:

   gcloud projects add-iam-policy-binding PROJECT_ID \
      --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
      --role='roles/artifactregistry.writer'
   

   Jika diminta, pilih None sebagai kondisi untuk kebijakan.

Membuat paket fleet

Untuk membuat paket armada, Anda menentukan spesifikasi FleetPackage yang mengarah ke repositori dengan resource Kubernetes yang Anda hubungkan ke Cloud Build. Kemudian, Anda menerapkan FleetPackage yang mengambil resource dari Git dan men-deploy-nya di seluruh fleet.

1. Buat file bernama fleetpackage-spec.yaml dengan konten berikut:

   resourceBundleSelector:
     cloudBuildRepository:
       name: projects/PROJECT_ID/locations/us-central1/connections/CONNECTION_NAME/repositories/REPOSITORY_NAME
       tag: TAG
       serviceAccount: projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
       path: CONFIG_FILE_PATH
   target:
     fleet:
       project: projects/PROJECT_ID
   rolloutStrategy:
     rolling:
       maxConcurrent: MAX_CLUSTERS
   # set the state to SUSPENDED to pause new rollouts
   # set the state back to ACTIVE to resume rollouts
   # state: SUSPENDED
   

   Ganti kode berikut:

   • CONNECTION_NAME: nama yang Anda pilih saat menghubungkan host Git ke Cloud Build. Anda dapat melihat semua koneksi Cloud Build di project Anda dengan menjalankan gcloud builds connections list atau dengan membuka halaman Repositori di konsol Google Cloud :

     Buka halaman Repositori

   • REPOSITORY_NAME: nama repositori Anda. Nilai ini harus sama dengan nilai yang dimasukkan saat Anda menyiapkan koneksi Cloud Build.

   • TAG: tag Git repositori Anda. Formatnya harus berupa versi semantik lengkap dengan nomor utama, minor, dan patch. Misalnya, v1.0.0 adalah tag yang valid, sedangkan v1 atau v1.0 adalah tag yang tidak valid.

   • CONFIG_FILE_PATH: jalur ke resource Kubernetes Anda di repositori. Jika file Anda berada di root repositori, Anda dapat menghapus kolom ini.

   • MAX_CLUSTERS: jumlah maksimum cluster untuk men-deploy resource Kubernetes sekaligus. Misalnya, jika Anda menyetelnya ke 1, paket resource akan di-deploy ke satu cluster dalam satu waktu.

     Untuk mengetahui daftar lengkap semua kolom yang dapat Anda konfigurasi, lihat dokumentasi referensi FleetPackage.

2. Buat paket fleet:

   gcloud container fleet packages create FLEET_PACKAGE_NAME \
       --source=fleetpackage-spec.yaml
   

   Ganti FLEET_PACKAGE_NAME dengan nama peluncuran paket armada Anda.

3. Pastikan paket armada telah dibuat:

   gcloud container fleet packages list
   

   Output mencantumkan status pemicu build. Setelah beberapa detik, kolom MESSAGE akan diperbarui dengan output yang mirip dengan berikut ini:

   MESSAGES: Build status: WORKING. The release is still being built; see the build status on the following page:
   

   Anda dapat mengklik link yang diberikan untuk melihat log streaming untuk tugas Cloud Build. Cloud Build mungkin memerlukan waktu beberapa menit untuk memproses pemicu build.

   Jika pemicu build berhasil, paket armada akan mulai men-deploy resource Kubernetes di seluruh armada Anda.

4. Jika pemicu build berhasil diselesaikan, output gcloud container fleet packages list akan mirip dengan berikut ini:

   NAME               STATE   CREATE_TIME           ACTIVE_ROLLOUT            LAST_COMPLETED_ROLLOUT  MESSAGES
   my-fleet-package   ACTIVE  2024-07-09T15:15:56   rollout-20240709-153621
   

   Paket fleet mulai men-deploy resource Kubernetes di seluruh fleet Anda.

Setelah Anda men-deploy paket armada, saat Anda menambahkan cluster baru ke armada, resource Kubernetes yang ditentukan dalam paket armada akan otomatis di-deploy ke cluster baru.

Memperbarui paket armada

Anda dapat memperbarui paket armada untuk mengubah setelan atau mengubah resource yang di-deploy paket armada, seperti dalam contoh berikut:

• Ubah strategi peluncuran dengan mengubah nilai kolom maxConcurrent.
• Jeda paket armada untuk sementara dengan menyetel state: SUSPENDED. Saat paket armada ditangguhkan, semua peluncuran yang sedang berlangsung akan dilanjutkan. Tidak ada peluncuran baru yang dibuat atau dijadwalkan hingga Anda mengubah statusnya kembali menjadi ACTIVE.
• Perbarui resource Kubernetes yang di-deploy paket fleet dengan memperbarui kolom tag untuk menarik dari tag Git yang berbeda.

Untuk mengupdate paket armada, selesaikan langkah-langkah berikut:

1. Perbarui spesifikasi FleetPackage Anda dengan perubahan Anda.

2. Perbarui paket armada:

   gcloud container fleet packages update FLEET_PACKAGE_NAME \
       --source=fleetpackage-spec.yaml
   

   Mungkin perlu waktu beberapa menit sebelum perubahan diterapkan dan mulai di-roll out ke cluster Anda.

Mengelola peluncuran paket armada

Anda dapat memantau progres deployment paket armada dan mengelola peluncuran aktif. Saat paket armada diubah, peluncuran baru akan otomatis dibuat. Perintah berikut membantu Anda mendapatkan informasi mendetail tentang peluncuran. Misalnya, jika perlu men-debug masalah deployment, Anda dapat memeriksa detail peluncuran, dan menjeda atau membatalkan peluncuran jika diperlukan.

1. Mencantumkan peluncuran memungkinkan Anda melihat status semua peluncuran yang terkait dengan paket, termasuk error yang dapat menyebabkan peluncuran gagal. Untuk mencantumkan peluncuran dan melihat statusnya, jalankan perintah berikut:

   gcloud container fleet packages rollouts list --fleet-package FLEET_PACKAGE_NAME
   

   Outputnya akan terlihat seperti berikut:

   ROLLOUT                   RELEASE  START_TIME              END_TIME                STATE     MESSAGE
   rollout-20250515-132857   v2-0-0   2025-05-15T13:28:58Z                            STALLED
   rollout-20250418-165528   v1-0-0   2025-04-18T16:55:29Z    2025-04-18T16:57:47Z    COMPLETED
   

2. Deskripsi peluncuran memberikan informasi mendetail tentang peluncuran tertentu, termasuk status untuk setiap cluster yang ditargetkan dan error khusus cluster. Untuk mendeskripsikan peluncuran, jalankan perintah berikut:

   gcloud container fleet packages rollouts describe ROLLOUT_NAME --fleet-package FLEET_PACKAGE_NAME
   

   Ganti ROLLOUT_NAME dengan nama peluncuran Anda. Anda bisa mendapatkan nama peluncuran lengkap dari perintah list di langkah sebelumnya.

   Outputnya akan terlihat seperti berikut:

   CLUSTER    CURRENT_VERSION  SYNC_STATE  DESIRED_VERSION  START_TIME              END_TIME                STATE      MESSAGES
   cluster1   v2.0.0           SYNCED      v2.0.0           2025-05-15T13:28:58Z    2025-05-15T13:30:27Z    COMPLETED
   cluster2   v1.0.0           SYNCED      v2.0.0           2025-05-15T13:30:27Z                            ERROR      Membership no longer exists
   

3. Anda dapat mengelola peluncuran aktif dengan menjalankan perintah berikut:

   • Menangguhkan peluncuran akan membuat peluncuran yang sedang berlangsung menjadi dalam status SUSPENDED. Semua update paket yang sedang berlangsung akan dilanjutkan, dan tidak ada lagi update paket yang dijadwalkan. Untuk menangguhkan peluncuran, jalankan perintah berikut:

     gcloud container fleet packages rollouts suspend ROLLOUT_NAME --fleet-package FLEET_PACKAGE_NAME
     

   • Melanjutkan peluncuran akan mengubah peluncuran SUSPENDED kembali ke status IN_PROGRESS. Update paket di-deploy ke cluster target sesuai rencana. Untuk melanjutkan peluncuran, jalankan perintah berikut:

     gcloud container fleet packages rollouts resume ROLLOUT_NAME --fleet-package FLEET_PACKAGE_NAME
     

   • Membatalkan peluncuran yang sedang berlangsung akan segera menghentikan peluncuran, sehingga peluncuran tersebut berada dalam status ABORTED. Semua update paket yang tertunda yang direncanakan sebagai bagian dari peluncuran dibatalkan. Untuk membatalkan peluncuran, jalankan perintah berikut:

     gcloud container fleet packages rollouts abort ROLLOUT_NAME --fleet-package FLEET_PACKAGE_NAME
     

Menggunakan label untuk men-deploy ke cluster yang berbeda

Label adalah pasangan nilai kunci yang Anda lampirkan ke objek. Paket fleet hanya mendukung label keanggotaan fleet. Label cluster GKE tidak didukung.

Anda dapat menggunakan label untuk men-deploy paket fleet ke subkumpulan cluster di fleet Anda.

Menambahkan label keanggotaan

Untuk menambahkan label keanggotaan, selesaikan langkah-langkah berikut:

1. Mendapatkan daftar langganan di armada:

   gcloud container fleet memberships list
   

2. Menambahkan label ke langganan:

   gcloud container fleet memberships update MEMBERSHIP_NAME \
       --update-labels=KEY=VALUE
   

   Ganti kode berikut:

   • MEMBERSHIP_NAME: nama cluster yang terdaftar ke fleet.
   • KEY dan VALUE: label yang akan ditambahkan ke keanggotaan. Jika label ada, nilainya akan diubah. Jika tidak, label baru akan dibuat. Kunci harus diawali dengan huruf kecil dan hanya berisi tanda hubung (-), garis bawah (_), huruf kecil, dan angka. Nilai hanya boleh berisi tanda hubung (-), garis bawah (_), karakter huruf kecil, dan angka.

   Ulangi perintah ini untuk setiap keanggotaan yang ingin Anda tambahkan labelnya.

Men-deploy ke subset cluster

Anda dapat men-deploy ke subset cluster dengan menentukan kolom target.fleet.selector.matchLabels dengan pasangan nilai kunci Anda. Misalnya, jika Anda menetapkan matchLabels sebagai country: "us", layanan paket fleet akan men-deploy resource Anda hanya ke cluster dengan label country yang cocok dengan "us".

Untuk men-deploy paket armada ke subset cluster, selesaikan langkah-langkah berikut:

1. Buat atau perbarui spesifikasi FleetPackage dengan pemilih label:

   resourceBundleSelector:
     cloudBuildRepository:
       name: projects/PROJECT_ID/locations/us-central1/connections/CONNECTION_NAME/repositories/REPOSITORY_NAME
       tag: TAG
       serviceAccount: projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
       path: CONFIG_FILE_PATH
   target:
     fleet:
       project: projects/PROJECT_ID
       selector:
         matchLabels:
           KEY: "VALUE"
   rolloutStrategy:
     rolling:
       maxConcurrent: MAX_CLUSTERS
   

2. Buat atau perbarui paket armada:

   Membuat paket fleet

   gcloud container fleet packages create FLEET_PACKAGE_NAME \
       --source=fleetpackage-spec.yaml
   

   Memperbarui paket armada

   gcloud container fleet packages update FLEET_PACKAGE_NAME \
       --source=fleetpackage-spec.yaml
   

Men-deploy resource varian ke cluster

Varian adalah versi lain dari resource. Resource ini mungkin memiliki nilai yang berbeda, bergantung pada lokasi, project, atau nama cluster. Anda dapat men-deploy resource varian ke cluster yang berbeda dengan menentukan kolom variantsPattern dan variantNameTemplate.

Anda dapat menggunakan label keanggotaan atau metadata keanggotaan lainnya seperti lokasi, project, atau nama untuk mencocokkan varian.

Untuk men-deploy paket armada dengan varian, selesaikan langkah-langkah berikut:

1. Buat atau perbarui spesifikasi FleetPackage Anda dengan detail varian:

   resourceBundleSelector:
     cloudBuildRepository:
       name: projects/PROJECT_ID/locations/us-central1/connections/CONNECTION_NAME/repositories/REPOSITORY_NAME
       tag: TAG
       serviceAccount: projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
       path: CONFIG_FILE_PATH
       variantsPattern: VARIANT_PATTERN
   target:
     fleet:
       project: projects/PROJECT_ID
   rolloutStrategy:
     rolling:
       maxConcurrent: MAX_CLUSTERS
   target:
     fleet:
       project: projects/PROJECT_ID
    variantSelector:
     variantNameTemplate: VARIANT_NAME_TEMPLATE
   

   Ganti kode berikut:

   • VARIANT_PATTERN: pola untuk varian, misalnya "variants/*.yaml" atau "us-*".
   • VARIANT_NAME_TEMPLATE : String template yang merujuk ke variabel yang berisi metadata keanggotaan cluster seperti lokasi, project, nama, atau label untuk menentukan nama varian untuk cluster target. Untuk contoh lainnya, lihat dokumentasi referensi FleetPackage.

2. Buat atau perbarui paket armada:

   Membuat paket fleet

   gcloud container fleet packages create FLEET_PACKAGE_NAME \
       --source=fleetpackage-spec.yaml
   

   Memperbarui paket armada

   gcloud container fleet packages update FLEET_PACKAGE_NAME \
       --source=fleetpackage-spec.yaml
   

Menghapus paket armada

Menghapus paket armada juga akan menghapus resource berikut:

• Resource Kubernetes yang di-deploy di cluster Anda
• Histori peluncuran paket armada

Untuk menghapus paket armada, jalankan perintah berikut:

gcloud container fleet packages delete FLEET_PACKAGE_NAME --force

Memecahkan masalah

Untuk menemukan metode mendiagnosis dan menyelesaikan error terkait Cloud Build, lihat Memecahkan masalah error build.

Langkah berikutnya

• Lihat halaman referensi kolom FleetPackage