Memecahkan masalah sinkronisasi konfigurasi ke cluster

Halaman ini menunjukkan cara menyelesaikan masalah terkait sinkronisasi konfigurasi ke cluster Anda.

Memecahkan masalah error KNV 2009

Error KNV2009 menunjukkan bahwa Config Sync gagal menyinkronkan beberapa konfigurasi ke cluster. Bagian berikut menjelaskan beberapa penyebab paling umum dan cara menyelesaikannya.

Operasi pada resource tertentu dilarang

Karena Anda perlu memberikan RBAC ke objek RepoSync, objek tersebut mungkin tidak memiliki izin yang diperlukan untuk menerapkan resource.

Anda dapat memverifikasi bahwa izin tidak ada dengan mendapatkan status resource RepoSync:

kubectl get reposync repo-sync -n NAMESPACE -o yaml

Ganti NAMESPACE dengan namespace tempat Anda membuat repositori namespace.

Anda juga dapat menggunakan perintah nomos status.

Jika Anda melihat pesan berikut dalam status, artinya rekonsiliator di NAMESPACE tidak memiliki izin yang diperlukan untuk menerapkan resource:

KNV2009: deployments.apps "nginx-deployment" is forbidden: User "system:serviceaccount:config-management-system:ns-reconciler-default" cannot get resource "deployments" in API group "apps" in the namespace "default"

Untuk memperbaiki masalah ini, Anda perlu mendeklarasikan konfigurasi RoleBinding yang memberikan izin akun layanan untuk rekonsiliator guna mengelola resource yang gagal di namespace tersebut. Detail tentang cara menambahkan RoleBinding disertakan dalam Mengonfigurasi sinkronisasi dari beberapa repositori.

Masalah ini juga dapat memengaruhi objek RootSync jika Anda telah menggunakan spec.override.roleRefs untuk mengubah peran yang diberikan ke objek RootSync. Jika Anda belum menetapkan kolom ini, objek RootSync akan diberi peran cluster-admin secara default.

Objek ResourceGroup melebihi batas ukuran objek etcd

Jika Anda menerima error berikut saat rekonsiliator mencoba menerapkan konfigurasi ke cluster, objek ResourceGroup akan melebihi batas ukuran objek etcd:

KNV2009: too many declared resources causing ResourceGroup.kpt.dev, config-management-system/root-sync failed to be applied: task failed (action: "Inventory", name: "inventory-add-0"): Request entity too large: limit is 3145728. To fix, split the resources into multiple repositories.

Sebaiknya bagi repositori Git Anda menjadi beberapa repositori. Jika tidak dapat membagi repositori Git, karena objek sudah terlalu besar dan perubahan tidak dipertahankan, Anda dapat menguranginya dengan mengonfigurasi RootSync atau RepoSync untuk menonaktifkan status penulisan objek ke ResourceGroup untuk sementara. Anda dapat melakukannya dengan menetapkan kolom .spec.override.statusMode objek RootSync atau RepoSync ke disabled. Dengan demikian, Config Sync berhenti memperbarui status resource terkelola di objek ResourceGroup. Tindakan ini akan mengurangi ukuran objek ResourceGroup. Namun, Anda tidak dapat melihat status untuk resource terkelola dari nomos status atau gcloud alpha anthos config sync.

Jika Anda tidak melihat error dari objek RootSync atau RepoSync, berarti objek dari sumber tepercaya Anda telah disinkronkan ke cluster. Untuk memeriksa apakah resource ResourceGroup melebihi batas ukuran objek etcd, periksa status resource ResourceGroup dan log pengontrol ResourceGroup:

1. Periksa status ResourceGroup:

   • Untuk memeriksa objek RootSync, jalankan perintah berikut:

     kubectl get resourcegroup root-sync -n config-management-system
     

   • Untuk memeriksa objek RepoSync, jalankan perintah berikut:

     kubectl get resourcegroup repo-sync -n NAMESPACE
     

     Ganti NAMESPACE dengan namespace tempat Anda membuat repositori namespace.

   Outputnya mirip dengan contoh berikut:

   NAME        RECONCILING   STALLED   AGE
   root-sync   True          False     35m
   

   Jika nilai di kolom RECONCILING adalah True, artinya resource ResourceGroup masih melakukan rekonsiliasi.

2. Periksa log untuk pengontrol ResourceGroup:

   kubectl logs deployment resource-group-controller-manager -c manager -n resource-group-system
   

   Jika Anda melihat error yang mirip dengan contoh berikut dalam output, resource ResourceGroup terlalu besar dan melebihi batas ukuran objek etcd:

   "error":"etcdserver: request is too large"
   

Untuk mencegah ResourceGroup menjadi terlalu besar, kurangi jumlah resource di repositori Git Anda. Anda dapat membagi satu repositori root menjadi beberapa repositori root.

Waktu tunggu rekonsiliasi penerapan dependensi habis

Jika menyinkronkan objek dengan dependensi, Anda mungkin menerima error yang mirip dengan contoh berikut saat rekonsiliator mencoba menerapkan objek dengan anotasi config.kubernetes.io/depends-on ke cluster:

KNV2009: skipped apply of Pod, bookstore/pod4: dependency apply reconcile timeout: bookstore_pod3__Pod  For more information, see https://g.co/cloud/acm-errors#knv2009

Error ini berarti objek dependensi tidak direkonsiliasi dalam waktu tunggu rekonsiliasi default selama lima menit. Config Sync tidak dapat menerapkan objek dependen karena dengan anotasi config.kubernetes.io/depends-on, Config Sync hanya menerapkan objek dalam urutan yang Anda inginkan. Anda dapat mengganti waktu tunggu rekonsiliasi default menjadi waktu yang lebih lama dengan menetapkan spec.override.reconcileTimeout.

Dependensi juga dapat direkonsiliasi setelah upaya sinkronisasi awal selesai. Dalam hal ini, dependensi harus dideteksi sebagai disesuaikan pada upaya percobaan ulang sinkronisasi berikutnya, yang akan membatalkan pemblokiran penerapan dependen. Jika hal ini terjadi, error mungkin dilaporkan sebentar, lalu dihapus. Memperpanjang waktu tunggu rekonsiliasi dapat membantu menghindari error yang dilaporkan secara berkala.

Info inventaris tidak ada

Jika Anda menerima error berikut saat rekonsiliator mencoba menerapkan konfigurasi ke cluster, kemungkinan inventaris Anda tidak memiliki resource atau manifes memiliki anotasi yang tidak dikelola:

KNV2009: inventory info is nil\n\nFor more information, see https://g.co/cloud/acm-errors#knv2009

Untuk mengatasi masalah ini, coba langkah berikut:

1. Hindari penyiapan sinkronisasi jika semua resource memiliki anotasi configmanagement.gke.io/managed: disabled, dengan memastikan setidaknya satu resource dikelola oleh Config Sync.
2. Tambahkan anotasi configmanagement.gke.io/managed: disabled hanya setelah menyelesaikan sinkronisasi awal resource tanpa anotasi ini.

Beberapa template objek inventaris

Jika Anda menerima error berikut saat rekonsiliator mencoba menerapkan konfigurasi ke cluster, kemungkinan Anda memiliki konfigurasi inventaris yang dihasilkan oleh kpt di sumber tepercaya, misalnya repositori Git:

KNV2009: Package has multiple inventory object templates.  The package should have one and only one inventory object template.   For more information, see https://g.co/cloud/acm-errors#knv2009

Masalah ini terjadi karena Config Sync mengelola konfigurasi inventarisnya sendiri. Untuk mengatasi masalah ini, hapus konfigurasi inventaris di sumber tepercaya Anda.

Tidak dapat membuat perubahan pada kolom yang tidak dapat diubah

Anda tidak dapat mengubah kolom yang tidak dapat diubah dalam konfigurasi dengan mengubah nilai di sumber tepercaya. Mencoba perubahan tersebut akan menyebabkan error yang mirip dengan berikut:

KNV2009: failed to apply RESOURCE: admission webhook "deny-immutable-field-updates.cnrm.cloud.google.com" denied the request: cannot make changes to immutable field(s):

Jika Anda perlu mengubah kolom yang tidak dapat diubah, hapus objek dari sumber kebenaran, tunggu Config Sync menghapus objek dari cluster, lalu buat ulang objek di sumber kebenaran dengan pembaruan Anda.

Polling untuk status gagal

Anda dapat memberikan otorisasi kepada Config Sync untuk mengelola resource dalam namespace menggunakan objek RepoSync. Jika jenis objek RepoSync ini menggunakan objek RoleBinding yang mereferensikan ClusterRole atau Role kustom, Anda mungkin mendapatkan pesan error berikut dari Deployment Reconciler:

KNV2009: polling for status failed: unknown

Untuk mengatasi masalah ini, pastikan objek ClusterRole dan Role Anda memiliki setidaknya izin berikut untuk setiap resource yang dikelola objek RepoSync:

• list
• watch
• get
• patch
• delete
• create

Untuk petunjuk cara menambahkan izin ini, lihat Membuat RoleBinding.

Penemuan API gagal

Jika Anda melihat pesan error yang mirip dengan yang berikut ini, Anda mungkin mengalami error penemuan API:

KNV2002: API discovery failed: APIServer error: unable to retrieve the complete list of server APIs: external.metrics.k8s.io/v1beta1: received empty response for: external.metrics.k8s.io/v1beta1

Config Sync menggunakan penemuan Kubernetes API untuk mencari resource yang didukung oleh cluster. Hal ini memungkinkan Config Sync memvalidasi jenis resource yang ditentukan dalam sumber Anda dan memantau resource tersebut untuk melihat perubahan di cluster.

Sebelum Kubernetes versi 1.28, setiap kali backend APIService tidak berfungsi atau menampilkan hasil daftar kosong, API Discovery akan gagal, sehingga Config Sync dan beberapa komponen Kubernetes lainnya mengalami error. Banyak backend APIService umum yang tidak tersedia secara maksimal, sehingga hal ini dapat terjadi cukup sering, hanya dengan mengupdate backend atau menjadwalkan ulang ke node lain.

Contoh backend APIService dengan satu replika mencakup metrics-server dan custom-metrics-stackdriver-adapter. Beberapa backend APIService selalu menampilkan hasil daftar kosong, seperti custom-metrics-stackdriver-adapter. Penyebab umum lain kegagalan penemuan API adalah webhook yang tidak sehat.

Setelah Kubernetes versi 1.28, dengan mengaktifkan fitur Discovery Gabungan, backend APIService yang tidak sehat tidak lagi menyebabkan error yang tidak ditangani. Sebagai gantinya, grup resource yang ditangani oleh APIService tersebut ditampilkan tidak memiliki resource. Tindakan ini memungkinkan sinkronisasi berlanjut, selama resource yang tidak sehat tidak ditentukan dalam sumber Anda.

Catatan: Discovery Gabungan ditambahkan sebagai fitur beta di Kubernetes versi 1.27.0, tetapi memiliki bug yang menyebabkannya dinonaktifkan di GKE versi 1.27.4-gke.1600. Fitur ini diaktifkan kembali di GKE versi 1.28.0 dengan perbaikan.

Pemulihan mandiri yang tertunda

Pemulihan mandiri memantau resource terkelola, mendeteksi penyimpangan dari sumber tepercaya, dan mengembalikan penyimpangan tersebut.

Pemulihan mandiri dijeda saat sinkronisasi sedang dicoba. Perilaku ini berarti bahwa perbaikan mandiri mungkin tertunda, terutama jika ada error sinkronisasi yang mencegah penyelaras menyelesaikan tugasnya. Untuk mengaktifkan kembali perbaikan mandiri, perbaiki semua error sinkronisasi yang dilaporkan.

Jumlah permintaan Kubernetes API yang tinggi

Config Sync menggunakan strategi multi-instance untuk menskalakan dan mengisolasi tenant dan domain error. Oleh karena itu, setiap RootSync dan RepoSync mendapatkan instance rekonsiliatornya sendiri. Selain menyinkronkan setiap kali perubahan dilakukan pada sumber, setiap instance rekonsiliator juga menyinkronkan secara berkala sebagai bagian dari perilaku perbaikan mandiri, untuk mengembalikan perubahan yang terlewat oleh perbaikan drift aktif. Saat Anda menambahkan objek RootSync atau RepoSync, hal ini menyebabkan peningkatan linear jumlah permintaan API yang dibuat oleh rekonsiliator yang menyinkronkan resource ke Kubernetes. Jadi, jika Anda memiliki banyak objek RootSync dan RepoSync, hal ini terkadang dapat menyebabkan beban traffic yang signifikan pada Kubernetes API.

Untuk melakukan sinkronisasi, Config Sync menggunakan Penerapan Sisi Server. Tindakan ini akan menggantikan alur permintaan GET dan PATCH normal dengan satu permintaan PATCH, sehingga mengurangi jumlah total panggilan API, tetapi meningkatkan jumlah panggilan PATCH. Hal ini memastikan bahwa perubahan yang dilakukan sudah benar, meskipun versi grup resource di sumber tidak cocok dengan versi grup resource default di cluster. Namun, Anda mungkin melihat permintaan PATCH dalam log audit, meskipun tidak ada perubahan pada sumber atau penyimpangan dari status yang Anda inginkan. Hal ini normal, tetapi dapat mengejutkan.

Jika terjadi error, sinkronisasi akan dicoba lagi hingga berhasil. Namun, jika hal ini memerlukan interaksi manusia, Config Sync mungkin mengalami error dan mencoba lagi selama beberapa waktu, sehingga meningkatkan jumlah permintaan yang dibuat ke Kubernetes API. Percobaan ulang akan mundur secara eksponensial, tetapi jika banyak objek RootSync atau RepoSync gagal disinkronkan secara bersamaan, hal ini dapat menyebabkan beban traffic yang signifikan pada Kubernetes API.

Untuk mengurangi masalah ini, coba salah satu opsi berikut:

• Perbaiki error konfigurasi dengan cepat agar tidak menumpuk.
• Gabungkan beberapa objek RootSync atau RepoSync, untuk mengurangi jumlah reconciler yang membuat permintaan Kubernetes API.

Uninstal KubeVirt diblokir oleh finalizer

KubeVirt adalah paket Kubernetes yang menggunakan beberapa finalizer, yang memerlukan urutan penghapusan yang tepat untuk memfasilitasi pembersihan. Jika objek KubeVirt dihapus dalam urutan yang salah, penghapusan objek KubeVirt lainnya mungkin terhenti atau berhenti merespons tanpa batas waktu.

Jika Anda mencoba meng-uninstal KubeVirt dan diblokir, ikuti petunjuk untuk menghapus KubeVirt secara manual.

Untuk mengurangi masalah ini di masa mendatang, deklarasikan dependensi di antara objek resource untuk memastikannya dihapus dalam urutan dependensi terbalik.

Penghapusan objek diblokir oleh finalizer

Finalizer Kubernetes adalah entri metadata yang memberi tahu Kubernetes untuk tidak mengizinkan objek dihapus hingga setelah pengontrol tertentu melakukan pembersihan. Hal ini dapat menyebabkan sinkronisasi atau rekonsiliasi gagal, jika kondisi untuk pembersihan tidak terpenuhi atau pengontrol yang melakukan pembersihan untuk resource tersebut tidak berfungsi atau telah dihapus.

Untuk mengurangi masalah ini, identifikasi resource mana yang masih menyelesaikan dan pengontrol mana yang harus melakukan pembersihan.

Jika pengontrol tidak berfungsi, memperbaiki penyebab utamanya akan memungkinkan pembersihan resource selesai, sehingga penghapusan objek tidak diblokir.

Jika pengontrol berfungsi dengan baik, pengontrol harus telah menerapkan kondisi status ke objek yang dihapus untuk menjelaskan alasan pembersihan terhenti. Jika tidak, periksa log pengontrol untuk mengetahui indikasi penyebab utamanya.

Sering kali, objek yang tidak dapat dihapus adalah indikasi bahwa objek dihapus dalam urutan yang salah. Untuk mencegah masalah semacam ini di masa mendatang, deklarasikan dependensi di antara objek resource, untuk memastikannya dihapus dalam urutan dependensi terbalik.

Kolom ResourceGroup terus berubah

Saat sinkronisasi dicoba, inventaris akan diperbarui untuk mengubah status resource menjadi tertunda. Jika sinkronisasi gagal, inventaris akan diperbarui untuk mengubah status resource menjadi gagal. Saat sinkronisasi dicoba ulang setelah gagal, pola ini akan berulang, sehingga menyebabkan pembaruan berkala pada inventaris. Hal ini menyebabkan ResourceGroup resourceVersion meningkat dengan setiap update dan status sinkronisasi beralih bolak-balik. Hal ini normal, tetapi dapat mengejutkan.

Kegagalan sinkronisasi dapat disebabkan oleh sejumlah masalah. Salah satu yang paling umum adalah izin tidak memadai untuk mengelola resource yang ditentukan dalam sumber. Untuk memperbaiki error ini, tambahkan RoleBinding atau ClusterRoleBinding yang sesuai untuk memberikan izin rekonsiliator RepoSync atau RootSync untuk mengelola resource yang gagal disinkronkan.

Penerapan sisi server tidak menghapus atau mengembalikan kolom yang tidak ditentukan di sumber

Config Sync menggunakan Server-Side Apply untuk menerapkan manifes dari sumber ke Kubernetes. Hal ini diperlukan untuk memungkinkan pengontrol lain mengelola kolom metadata dan spec. Salah satu contohnya adalah Horizontal Pod Autoscaler, yang memperbarui jumlah replika dalam Deployment. Oleh karena itu, Config Sync hanya mengelola kolom yang ditentukan dalam manifes sumber. Hal ini memiliki efek samping bahwa saat mengadopsi objek resource yang ada, kolom apa pun yang tidak ditentukan dalam sumber tidak akan diubah, yang terkadang dapat menyebabkan konfigurasi gabungan menjadi tidak valid atau salah.

Untuk menghindari masalah ini saat mengadopsi resource, gunakan kolom yang sama persis di sumber saat pertama kali mengadopsi, lalu ubah kolom di sumber setelah menyinkronkan, sehingga Config Sync menghapus kolom dengan benar yang sebelumnya diterapkan dan menggantinya dengan kolom baru dari sumber. Cara lain untuk menghindari masalah ini adalah dengan menghapus resource dari cluster terlebih dahulu dan mengizinkan Config Sync menerapkan versi baru.

Langkah berikutnya

• Jika Anda masih mengalami masalah, periksa apakah masalah Anda adalah masalah umum.