Menggunakan paket armada di Distributed Cloud terhubung

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

Paket armada 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 menyesuaikan panduan tersebut untuk lingkungan yang terhubung Distributed Cloud Anda.

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

Persyaratan

Penggunaan paket fleet Config Sync di Distributed Cloud yang terhubung 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 layanan Google Cloud . Metode autentikasi Config Sync lainnya, seperti kunci SSH atau cookie, tidak didukung untuk koneksi antara cluster Anda dan repositori paket yang diberi versi. Untuk mengetahui informasi selengkapnya, lihat Autentikasi Cluster Workload Identity.
• Semua cluster dalam armada harus berada dalam project yang sama. Distributed Cloud yang terhubung tidak mendukung pendaftaran cluster di beberapa project ke dalam satu project pusat untuk pengelolaan fleet.
• Manifes Kubernetes Anda harus mematuhi batasan workload yang terhubung ke Distributed Cloud. Manifes yang melanggar batasan ini akan diblokir oleh pengontrol penerimaan cluster.
• Paket armada memerlukan Config Sync versi 1.16.0 atau yang lebih baru.

Perilaku sistem

Paket armada di Distributed Cloud terhubung memiliki perilaku berikut:

• Paket fleet mengubah manifes Kubernetes Anda menjadi image OCI yang diberi versi. Image ini disimpan dalam repositori Artifact Registry terkelola bernama fleet-packages, yang otomatis dibuat di project Anda. Cluster Anda menarik 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 diganti untuk mencocokkan paket OCI yang diberi versi.
• Jika cluster yang terhubung ke Distributed Cloud memasuki mode kemampuan bertahan, agen Config Sync akan terus menerapkan konfigurasi yang terakhir berhasil disinkronkan secara lokal. Namun, peluncuran atau update baru pada paket armada akan dijeda hingga konektivitas cloud dipulihkan.
• Paket armada mewarisi perilaku pemangkasan resource otomatis Config Sync. Saat Anda membuat tag baru di repositori Git dan memperbarui konfigurasi paket armada dengan tag baru untuk memulai sinkronisasi, agen Config Sync akan menghapus resource yang sesuai dari cluster jika Anda menghapus manifes dari repositori Git.
• Jika beberapa paket armada mengelola resource yang sama, akan terjadi konflik kepemilikan. Jika Anda mencoba menghapus paket armada saat paket tersebut mengalami konflik kepemilikan, penghapusan mungkin akan tertunda. Untuk mengatasi masalah ini, ubah salah satu paket armada yang bersaing untuk menghapus resource yang bertentangan sebelum Anda mencoba menghapus paket.

Prasyarat Distributed Cloud terhubung

Sebelum mengikuti langkah-langkah di Men-deploy paket armada, pastikan lingkungan yang terhubung dengan Distributed Cloud 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 Anda, misalnya, [e-mail], diizinkan untuk melintasi perimeter dan menarik image dari Artifact Registry. Untuk mengetahui informasi selengkapnya, lihat Mengonfigurasi integrasi Kontrol Layanan VPC.
• Akses keluar. Cluster yang terhubung ke Distributed Cloud Anda harus memiliki akses keluar ke us-central1-docker.pkg.dev. Paket armada 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 armada, dan harus berada di us-central1.

Izin yang diperlukan

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

• Admin Pengiriman Konfigurasi (roles/configdelivery.admin): diperlukan untuk membuat dan mengelola paket serta peluncuran armada
• 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 cara memberikan peran, lihat Memberikan, mengubah, dan mencabut akses ke resource.

API yang diperlukan

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

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 Pengiriman Konfigurasi dan cluster yang terhubung ke Distributed Cloud Anda
• developerconnect.googleapis.com: memungkinkan koneksi aman ke host repositori Git eksternal Anda
• artifactregistry.googleapis.com: menyimpan paket yang diberi versi sebagai image OCI di project Anda

Setelan lingkungan default

Config Delivery API untuk paket armada 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 project ID Google Cloud Anda.

2. Menetapkan lokasi default untuk paket armada. Semua koneksi repositori Cloud Build yang digunakan dengan paket armada 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 armada ke lingkungan yang terhubung dengan Distributed Cloud Anda.

Langkah standar	Penyesuaian Distributed Cloud terhubung
Mendaftarkan cluster ke fleet	Lewati langkah ini. Cluster yang terhubung ke Distributed Cloud secara otomatis didaftarkan ke fleet di project Anda saat dibuat.
Menginstal Config Sync	Ikuti langkah-langkah standar, tetapi sebaiknya gunakan metode Instal di seluruh armada (default armada). Konfigurasi metode ini di setelan Hub atau Fleet di konsol Google Cloud . Implementasi ini memastikan bahwa semua node Distributed Cloud yang terhubung yang sudah 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 menarik paket manifes dari repositori fleet-packages terkelola.
Membuat akun layanan	Ikuti petunjuk untuk membuat akun layanan bagi Cloud Build dan memberikan izin yang diperlukan. Akun layanan harus berada dalam project yang sama dengan paket armada Anda. Sebaiknya gunakan perintah berikut: Buat akun layanan dengan menjalankan perintah gcloud iam service-accounts create: 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: mengizinkan akun layanan membuat dan mengelola paket resource dan rilisan roles/cloudbuild.connectionUser: mengizinkan akun layanan menggunakan koneksi repositori Cloud Build roles/logging.logWriter: mengizinkan akun layanan untuk menulis log build roles/artifactregistry.writer: memungkinkan akun layanan untuk mengirimkan paket versi ke Artifact Registry roles/developerconnect.connectionUser: mengizinkan 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 memberikan otorisasi koneksi, lihat Menghubungkan ke repositori.
Mengidentifikasi nama keanggotaan	Saat perintah meminta MEMBERSHIP_NAME, gunakan nama cluster yang terhubung ke Distributed Cloud. Anda dapat menemukan nama cluster dengan menjalankan perintah gcloud container fleet memberships list.
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 terdaftar secara otomatis, Anda harus menambahkan label secara manual ke keanggotaan cluster jika ingin menargetkan subset cluster dengan menggunakan pemilih label.
Strategi deployment	Gunakan label dan varian untuk menargetkan cluster tertentu. Untuk Distributed Cloud terhubung, variabel metadata keanggotaan, seperti project dan lokasi, yang digunakan dalam template varian Anda merujuk ke resource sisi cloud yang terkait dengan cluster Distributed Cloud terhubung Anda. Metadata keanggotaan khusus Distributed Cloud berikut tersedia untuk digunakan dalam template varian: cluster_name: nama cluster terhubung Distributed Cloud Anda location: Google Cloud region yang terkait dengan cluster project: project ID tempat cluster didaftarkan labels: label yang telah Anda terapkan ke keanggotaan cluster

Prosedur bersama

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

• Buat paket armada: Tentukan resource FleetPackage untuk mengambil dan men-deploy konfigurasi Anda.
• Memperbarui paket armada: Ubah paket Anda untuk meluncurkan perubahan atau memperbarui setelan.
• Mengelola peluncuran paket armada: Menangguhkan, melanjutkan, atau membatalkan peluncuran yang aktif.
• Periksa paket dan rilis resource: Men-debug pembuatan dan pembuatan versi varian. Paket resource adalah penampung untuk konfigurasi Anda, dan rilis adalah instance berversi dari paket tersebut. Untuk memverifikasi keberhasilan pengiriman ke hardware yang terhubung ke Distributed Cloud, 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 armada: Menghapus paket armada dan resource terkelolanya. Untuk memastikan penghapusan yang bersih, pastikan objek RootSync terkelola yang terkait dengan paket fleet dihapus dari cluster Anda.

Memantau dan memecahkan masalah

Untuk memantau deployment secara 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 armada.

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 yang terhubung, seperti yang dijelaskan dalam Memecahkan masalah Distributed Cloud yang terhubung.

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.

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, untuk mendapatkan detail selengkapnya, jalankan perintah berikut:

kubectl describe rootsync FLEET_PACKAGE_NAME -n config-management-system

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

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