Memecahkan masalah sinkronisasi konfigurasi ke cluster Anda

Menyelesaikan masalah sinkronisasi konfigurasi di Config Sync membantu memastikan bahwa cluster Anda tetap selaras dengan sumber tepercaya pusat. Jika sinkronisasi gagal, deployment dapat terhenti dan konfigurasi cluster dapat bergeser dari status yang dideklarasikan. Anda dapat mendiagnosis dan memperbaiki error sinkronisasi KNV2009 yang umum—seperti izin role-based access control (RBAC) yang tidak ada, objek ResourceGroup yang melebihi batas ukuran etcd, dan latensi webhook—untuk memulihkan rekonsiliasi otomatis.

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 mengatasinya.

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, berarti rekonsiler 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 kepada akun layanan untuk rekonsiler 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 rekonsiler mencoba menerapkan konfigurasi ke cluster, objek ResourceGroup 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 Anda membagi repositori Git menjadi beberapa repositori. Jika Anda tidak dapat memecah repositori Git, karena objek sudah terlalu besar dan perubahan tidak dipertahankan, Anda dapat menguranginya dengan mengonfigurasi RootSync atau RepoSync untuk menonaktifkan sementara penulisan status objek ke ResourceGroup. Anda dapat melakukannya dengan menetapkan kolom .spec.override.statusMode dari objek RootSync atau RepoSync ke disabled. Dengan demikian, Config Sync akan berhenti mengupdate status resource terkelola di objek ResourceGroup. Tindakan ini akan mengurangi ukuran objek ResourceGroup. Namun, Anda tidak dapat melihat status resource terkelola dari nomos status.

Jika Anda tidak melihat error dari objek RootSync atau RepoSync, berarti objek dari sumber kebenaran 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, berarti resource ResourceGroup masih melakukan rekonsiliasi.

  2. Periksa log untuk ResourceGroup Controller:

    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"

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

Waktu tunggu penerapan rekonsiliasi dependensi

Jika Anda menyinkronkan objek dengan dependensi, Anda mungkin menerima error yang mirip dengan contoh berikut saat rekonsiler 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 sesuai urutan yang Anda inginkan. Anda dapat mengganti waktu tunggu rekonsiliasi default ke waktu yang lebih lama dengan menetapkan spec.override.reconcileTimeout.

Dependensi juga mungkin akan direkonsiliasi setelah upaya sinkronisasi awal selesai. Dalam hal ini, dependensi harus terdeteksi sebagai direkonsiliasi pada upaya percobaan ulang sinkronisasi berikutnya, sehingga tidak memblokir penerapan dependen apa pun. Jika hal ini terjadi, error mungkin dilaporkan sebentar, lalu dihapus. Memperpanjang waktu tunggu rekonsiliasi dapat membantu menghindari error yang dilaporkan sesekali.

Info inventaris tidak ada

Jika Anda menerima error berikut saat rekonsiler 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 menyiapkan sinkronisasi saat 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 rekonsiler mencoba menerapkan konfigurasi ke cluster, kemungkinan Anda memiliki konfigurasi inventaris yang dihasilkan oleh kpt di sumber kebenaran, 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 menyelesaikan 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 kebenaran. Upaya melakukan perubahan tersebut akan menyebabkan error yang mirip dengan berikut ini:

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 hingga Config Sync menghapus objek dari cluster, lalu buat ulang objek di sumber kebenaran dengan update Anda.

Polling untuk status gagal

Anda dapat mengizinkan 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 mengetahui 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 di sumber Anda dan memantau resource tersebut untuk mengetahui perubahan dalam cluster.

Sebelum Kubernetes versi 1.28, setiap kali backend APIService tidak responsif atau menampilkan hasil daftar kosong, API Discovery akan gagal, sehingga menyebabkan Config Sync dan beberapa komponen Kubernetes lainnya mengalami error. Banyak backend APIService umum tidak memiliki ketersediaan tinggi, sehingga hal ini dapat terjadi relatif sering, hanya dengan mengupdate backend atau menjadwalkannya 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 responsif.

Setelah Kubernetes versi 1.28, dengan fitur Penemuan Gabungan diaktifkan, backend APIService yang tidak responsif tidak lagi menyebabkan error yang tidak tertangani. Sebagai gantinya, grup resource yang ditangani oleh APIService tersebut ditampilkan tidak memiliki resource. Tindakan ini memungkinkan sinkronisasi berlanjut, selama resource yang tidak responsif tidak ditentukan di sumber Anda.

Pemulihan mandiri yang tertunda

Self-healing memantau resource terkelola, mendeteksi penyimpangan dari sumber tepercaya, dan mengembalikan penyimpangan tersebut.

Pemulihan mandiri dijeda saat sinkronisasi sedang dicoba. Perilaku ini berarti bahwa pemulihan mandiri mungkin tertunda, terutama jika ada error sinkronisasi yang mencegah penyelesaian rekonsiliasi. Untuk mengaktifkan kembali pemulihan mandiri, perbaiki semua error sinkronisasi yang dilaporkan.

Jumlah permintaan API Kubernetes yang tinggi

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

Untuk melakukan sinkronisasi, Config Sync menggunakan Server-Side Apply. Tindakan ini 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 dibuat sudah benar, meskipun versi grup resource di sumber tidak cocok dengan versi grup resource default di cluster. Namun, Anda mungkin melihat permintaan PATCH di log audit, meskipun tidak ada perubahan pada sumber atau penyimpangan dari status yang Anda inginkan. Hal ini normal, tetapi bisa 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 API Kubernetes.

Pencopotan penginstalan KubeVirt diblokir oleh finalizer

KubeVirt adalah paket Kubernetes yang menggunakan beberapa finalizer, sehingga memerlukan urutan penghapusan yang tepat untuk memfasilitasi pembersihan. Jika objek KubeVirt dihapus dalam urutan yang salah, penghapusan objek KubeVirt lainnya mungkin akan 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 antara objek resource untuk memastikan objek tersebut dihapus dalam urutan dependensi terbalik.

Penghapusan objek diblokir oleh finalizer

Finalizer Kubernetes adalah entri metadata yang memberi tahu Kubernetes untuk tidak mengizinkan penghapusan objek hingga 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 responsif atau telah dihapus.

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

Jika pengontrol tidak responsif, memperbaiki akar masalah akan memungkinkan pembersihan resource selesai, sehingga penghapusan objek tidak diblokir.

Jika pengontrol responsif, pengontrol seharusnya 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 macet saat dihapus merupakan indikasi bahwa objek dihapus dalam urutan yang salah. Untuk mencegah masalah semacam ini di masa mendatang, deklarasikan dependensi di antara objek resource, untuk memastikan objek tersebut 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 berubah bolak-balik. Hal ini normal, tetapi mungkin mengejutkan.

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

Config Sync 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 sinkronisasi, sehingga Config Sync menghapus kolom yang sebelumnya diterapkan dengan benar 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.

Config Sync tidak mempertahankan kolom dari penerapan sisi klien kubectl saat mengadopsi objek

Karena Config Sync menggunakan Server-Side Apply, saat Config Sync mengadopsi objek yang awalnya dibuat dengan kubectl client-side apply, Config Sync akan membatalkan penetapan kolom apa pun yang ditetapkan dengan client-side apply, tetapi tidak dideklarasikan di sumber.

Jika Anda ingin mempertahankan kolom tersebut, gunakan kolom yang sama persis di sumber saat Anda pertama kali mengadopsi objek, atau buat objek menggunakan Server-Side Apply.

Langkah berikutnya

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

Jika Anda tidak dapat menemukan solusi untuk masalah Anda dalam dokumentasi, lihat Mendapatkan dukungan untuk mendapatkan bantuan lebih lanjut, termasuk saran tentang topik berikut: