Menggunakan paket armada di Distributed Cloud terhubung

Halaman ini menjelaskan cara menggunakan paket fleet Config Sync di lingkungan Google Distributed Cloud connected versi 1.12.0. Paket fleet adalah alat yang menggunakan repositori Git sebagai satu-satunya sumber tepercaya untuk konfigurasi cluster Anda.

Paket fleet di Distributed Cloud connected menggunakan teknologi dan perintah yang sama dengan cluster Google Kubernetes Engine standar. Dokumentasi GKE menjelaskan cara membuat dan mengelola paket fleet di halaman Men-deploy paket fleet. Halaman ini menjelaskan cara mengadaptasi panduan tersebut untuk lingkungan Distributed Cloud connected Anda.

Bagian berikut menjelaskan hal yang perlu Anda lakukan secara berbeda untuk Distributed Cloud connected dan langkah-langkah dalam dokumentasi GKE yang dapat Anda ikuti tanpa perubahan.

Persyaratan

Penggunaan paket fleet Config Sync di Distributed Cloud connected memiliki persyaratan berikut:

• Karena pengontrol peluncuran berada di cloud, repositori Git Anda harus dapat dijangkau melalui internet publik. Server Git internal atau lokal yang tidak diekspos secara publik tidak didukung.
• Distributed Cloud connected hanya mendukung penggunaan fleet Workload Identity Federation untuk melakukan autentikasi dengan Google Cloud layanan. Metode autentikasi Config Sync lainnya, seperti kunci SSH atau cookie, tidak didukung untuk koneksi antara cluster Anda dan repositori paket berversi. Untuk mengetahui informasi selengkapnya, lihat Autentikasi Cluster Workload Identity.
• Semua cluster dalam fleet harus berada dalam project yang sama. Distributed Cloud connected tidak mendukung pendaftaran cluster di beberapa project ke dalam satu project pusat untuk pengelolaan fleet.
• Manifes Kubernetes Anda harus mematuhi batasan workload Distributed Cloud connected. Manifes yang melanggar batasan ini akan diblokir oleh pengontrol penerimaan cluster.
• Paket fleet memerlukan Config Sync versi 1.16.0 atau yang lebih baru.

Perilaku sistem

Paket fleet di Distributed Cloud connected memiliki perilaku berikut:

• Paket fleet mengubah manifes Kubernetes Anda menjadi image OCI berversi. Image ini disimpan dalam repositori Artifact Registry terkelola bernama fleet-packages, yang otomatis dibuat di project Anda. Cluster Anda mengambil image ini langsung dari repositori untuk memastikan pengiriman yang konsisten dan andal.
• Paket fleet mewarisi perilaku koreksi penyimpangan Config Sync. Perubahan manual yang dilakukan pada resource di cluster akan otomatis ditimpa agar sesuai dengan paket OCI berversi.
• Jika cluster Distributed Cloud connected memasuki mode survivability, agen Config Sync akan terus menerapkan konfigurasi yang terakhir berhasil disinkronkan secara lokal. Namun, peluncuran atau update baru ke paket fleet akan dijeda hingga konektivitas cloud dipulihkan.
• Paket fleet mewarisi perilaku pemangkasan resource otomatis Config Sync. Saat Anda membuat tag baru di repositori Git dan memperbarui konfigurasi paket fleet dengan tag baru untuk memulai sinkronisasi, agen Config Sync akan menghapus resource yang sesuai dari cluster Anda jika Anda menghapus manifes dari repositori Git.
• Jika beberapa paket fleet mengelola resource yang sama, akan terjadi konflik kepemilikan. Jika Anda mencoba menghapus paket fleet saat paket tersebut mengalami konflik kepemilikan, penghapusan mungkin akan terhenti. Untuk mengatasi masalah ini, ubah salah satu paket fleet yang bersaing untuk menghapus resource yang mengalami konflik sebelum Anda mencoba menghapus paket.

Prasyarat Distributed Cloud connected

Sebelum mengikuti langkah-langkah di Men-deploy paket fleet, pastikan lingkungan Distributed Cloud connected dan izin pengguna Anda dikonfigurasi dengan benar.

Jaringan dan keamanan

Lingkungan jaringan Anda harus memenuhi persyaratan berikut:

• Kontrol Layanan VPC. Jika project Anda dilindungi oleh perimeter layanan VPC, pastikan agen layanan Cloud Build dan Config Delivery, misalnya, [e-mail], diizinkan untuk melintasi perimeter dan mengambil image dari Artifact Registry. Untuk mengetahui informasi selengkapnya, lihat Mengonfigurasi integrasi Kontrol Layanan VPC.
• Akses keluar. Cluster Distributed Cloud connected Anda harus memiliki akses keluar ke us-central1-docker.pkg.dev. Paket fleet menyimpan paket manifes Anda sebagai image OCI di Artifact Registry. Cluster harus dapat mengambil image ini langsung dari Artifact Registry.

Penyiapan repositori

Repositori Artifact Registry yang berisi paket manifes Anda harus berada dalam project yang sama dengan paket fleet, dan harus berada di us-central1.

Izin yang diperlukan

Untuk menyelesaikan langkah-langkah di lingkungan Distributed Cloud connected, Anda harus memiliki peran IAM berikut di project:

• Admin Config Delivery (roles/configdelivery.admin): diperlukan untuk membuat dan mengelola paket fleet dan peluncuran
• Admin Developer Connect (roles/developerconnect.admin): diperlukan untuk membuat dan mengelola koneksi repositori
• Project IAM Admin (roles/resourcemanager.projectIamAdmin): diperlukan untuk memberikan peran yang diperlukan ke akun layanan

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Memberi, mengubah, dan mencabut akses ke resource.

API yang diperlukan

Anda harus mengaktifkan API untuk koneksi repositori dan komunikasi yang aman dengan cluster Distributed Cloud connected. Untuk mengaktifkan API yang diperlukan, jalankan perintah berikut gcloud services enable:

gcloud services enable anthosconfigmanagement.googleapis.com \
    configdelivery.googleapis.com \
    cloudbuild.googleapis.com \
    connectgateway.googleapis.com \
    developerconnect.googleapis.com \
    artifactregistry.googleapis.com

API ini diperlukan untuk komponen berikut:

• anthosconfigmanagement.googleapis.com: mengelola agen Config Sync di cluster Anda
• configdelivery.googleapis.com: mengoordinasikan peluncuran resource Kubernetes di seluruh fleet cluster Anda
• cloudbuild.googleapis.com: mengambil manifes Kubernetes Anda dari Git dan mengemasnya ke dalam paket berversi
• connectgateway.googleapis.com: menyediakan koneksi yang aman antara layanan Config Delivery dan cluster Distributed Cloud connected Anda
• developerconnect.googleapis.com: memungkinkan koneksi yang aman ke host repositori Git eksternal Anda
• artifactregistry.googleapis.com: menyimpan paket berversi sebagai image OCI di project Anda

Setelan lingkungan default

Config Delivery API untuk paket fleet hanya didukung di us-central1. Untuk memastikan perintah Anda dirutekan dengan benar, gunakan perintah gcloud config set untuk menetapkan project dan lokasi default Anda:

1. Setel project default Anda:

   gcloud config set project PROJECT_ID
   

   Ganti PROJECT_ID dengan Google Cloud project ID Anda.

2. Tetapkan lokasi default untuk paket fleet. Semua koneksi repositori Cloud Build yang digunakan dengan paket fleet harus berada di region us-central1.

   gcloud config set config_delivery/location us-central1
   

Perbedaan prosedural

Gunakan tabel berikut untuk memahami cara menerapkan langkah-langkah di Men-deploy paket fleet ke lingkungan Distributed Cloud connected Anda.

Langkah standar	Penyesuaian Distributed Cloud connected
Mendaftarkan cluster ke fleet	Lewati langkah ini. Cluster Distributed Cloud connected otomatis didaftarkan ke fleet di project Anda saat dibuat.
Menginstal Config Sync	Ikuti langkah-langkah standar, tetapi sebaiknya gunakan metode Install on entire fleet (fleet default). Konfigurasikan metode ini di setelan Hub atau Fleet di Google Cloud konsol. Implementasi ini memastikan bahwa semua node Distributed Cloud connected yang ada atau yang akan datang di zona Anda akan otomatis menerima agen Config Sync. Untuk jenis anggota autentikasi, Anda harus memilih Workload Identity. Akun layanan yang Anda gunakan untuk Workload Identity harus memiliki peran roles/artifactregistry.reader di project agar agen Config Sync dapat mengambil paket manifes dari repositori fleet-packages terkelola.
Membuat akun layanan	Ikuti petunjuk untuk membuat akun layanan untuk Cloud Build dan memberikan izin yang diperlukan. Akun layanan harus berada dalam project yang sama dengan paket fleet Anda. Sebaiknya gunakan perintah berikut: Buat akun layanan dengan menjalankan gcloud iam service-accounts create perintah: gcloud iam service-accounts create "SERVICE_ACCOUNT_NAME" Ganti SERVICE_ACCOUNT_NAME dengan nama untuk akun layanan. Tambahkan peran Identity and Access Management wajib dengan menjalankan perintah gcloud projects add-iam-policy-binding untuk setiap peran berikut. Untuk mengetahui informasi selengkapnya tentang IAM, lihat Ringkasan IAM. roles/configdelivery.resourceBundlePublisher: memungkinkan akun layanan membuat dan mengelola paket dan rilis resource roles/cloudbuild.connectionUser: memungkinkan akun layanan menggunakan koneksi repositori Cloud Build roles/logging.logWriter: memungkinkan akun layanan menulis log build roles/artifactregistry.writer: memungkinkan akun layanan mengirim paket berversi ke Artifact Registry roles/developerconnect.connectionUser: memungkinkan akun layanan menggunakan koneksi Developer Connect Akun layanan juga memerlukan izin untuk membaca dari repositori Git yang terhubung di penyedia Git Anda. Untuk mengetahui informasi tentang cara mengotorisasi koneksi, lihat Menghubungkan ke repositori.
Mengidentifikasi nama keanggotaan	Saat perintah meminta MEMBERSHIP_NAME, gunakan nama cluster Distributed Cloud connected Anda. Anda dapat menemukan nama cluster dengan menjalankan gcloud container fleet memberships list perintah.
Mengidentifikasi cluster	Sebelum menargetkan cluster dengan paket fleet, jika workload Anda memerlukan konfigurasi jaringan tingkat host, seperti HugePages atau SR-IOV, terapkan dan verifikasi resource NodeSystemConfigUpdate di setiap node dalam cluster.
Mengidentifikasi tag Git	Pengontrol peluncuran memerlukan tag Git dalam format versi semantik lengkap (major.minor.patch). Misalnya, v1.0.0 valid, sedangkan v1 tidak.
Menargetkan cluster tertentu	Meskipun cluster otomatis terdaftar, Anda harus menambahkan label secara manual ke keanggotaan cluster jika ingin menargetkan subset cluster menggunakan pemilih label.
Strategi deployment	Gunakan label dan varian untuk menargetkan cluster tertentu. Untuk Distributed Cloud connected, variabel metadata keanggotaan, seperti project dan lokasi, yang digunakan dalam template varian Anda merujuk ke resource sisi cloud yang terkait dengan cluster Distributed Cloud connected Anda. Metadata keanggotaan khusus Distributed Cloud berikut tersedia untuk digunakan dalam template varian: cluster_name: nama cluster Distributed Cloud connected Anda location: region yang terkait dengan cluster Google Cloud project: project ID tempat cluster terdaftar labels: label apa pun yang telah Anda terapkan ke keanggotaan cluster

Prosedur bersama

Untuk tugas operasional berikut, sintaksis perintah dan perilaku layanan sama untuk Distributed Cloud connected dan GKE standar. Saat mengikuti petunjuk ini, gunakan setelan dan nilai yang ditentukan dalam tabel di bagian Perbedaan prosedural dalam dokumen ini.

• Membuat paket fleet: Tentukan resource FleetPackage untuk mengambil dan men-deploy konfigurasi Anda.
• Memperbarui paket fleet: Ubah paket Anda untuk meluncurkan perubahan atau memperbarui setelan.
• Mengelola peluncuran paket fleet: Menangguhkan, melanjutkan, atau membatalkan peluncuran aktif.
• Memeriksa paket dan rilis resource: Men-debug pembuatan dan pembuatan versi varian. Paket resource adalah container untuk konfigurasi Anda, dan rilis adalah instance berversi dari paket tersebut. Untuk memverifikasi pengiriman yang berhasil ke hardware Distributed Cloud connected Anda, gunakan perintah gcloud container fleet memberships get-credentials untuk mendapatkan akses ke cluster Anda, lalu gunakan kubectl untuk memeriksa status RootSync di cluster.
• Menghapus paket fleet: Hapus paket fleet dan resource terkelolanya. Untuk memastikan penghapusan yang bersih, verifikasi bahwa objek RootSync terkelola yang terkait dengan paket fleet dihapus dari cluster Anda.

Pemantauan dan pemecahan masalah

Untuk memantau deployment dengan lebih efektif, gunakan flag --format dengan perintah gcloud untuk mendapatkan pesan status mendetail selama peluncuran.

Misalnya, jalankan perintah gcloud container fleet packages rollouts describe berikut untuk melihat pesan status mendetail untuk setiap cluster di fleet Anda:

gcloud container fleet packages rollouts describe ROLLOUT_NAME \
    --fleet-package=FLEET_PACKAGE_NAME \
    --format=json

Ganti nilai berikut:

• ROLLOUT_NAME: Nama peluncuran.
• FLEET_PACKAGE_NAME: Nama paket fleet.

Jika build gagal atau macet, Anda dapat menemukan link ke log streaming untuk tugas Cloud Build di output perintah gcloud container fleet packages list. Jika peluncuran tetap dalam status PENDING atau STALLED, periksa konektivitas hardware Distributed Cloud connected Anda, seperti yang dijelaskan dalam Memecahkan masalah Distributed Cloud connected.

Untuk mengetahui informasi selengkapnya tentang mendiagnosis error terkait Cloud Build, lihat Memecahkan masalah error build.

Memverifikasi status sinkronisasi dalam cluster

Untuk memverifikasi bahwa cluster Anda berhasil disinkronkan dengan paket fleet, periksa resource RootSync di cluster. Nama objek RootSync di cluster sama dengan FLEET_PACKAGE_NAME yang Anda pilih untuk paket Anda.

Untuk memeriksa status, jalankan perintah berikut:

kubectl get rootsync FLEET_PACKAGE_NAME -n config-management-system

Sinkronisasi yang berhasil akan menampilkan status SYNCED. Jika Anda melihat status Error, jalankan perintah berikut untuk mendapatkan detail selengkapnya:

kubectl describe rootsync FLEET_PACKAGE_NAME -n config-management-system

Untuk mengetahui informasi selengkapnya, lihat Memantau objek RootSync dan RepoSync di dokumentasi GKE.

Untuk mendapatkan bantuan dalam mendekode kode error tertentu dalam output, lihat referensi error Config Sync.