Memecahkan masalah sinkronisasi konfigurasi ke cluster

Halaman ini menunjukkan cara menyelesaikan masalah terkait menyinkronkan 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 mengatasinya.

Operasi pada resource tertentu dilarang

Karena Anda perlu memberikan RBAC untuk 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 merekonsiliasi 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 menyetel kolom ini, objek RootSync akan diberi peran cluster-admin secara default.

Objek ResourceGroup melebihi batas ukuran objek etcd

Jika Anda menerima error berikut saat rekonsiliasi mencoba menerapkan konfigurasi ke cluster, objek ResourceGroup melampaui 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 Anda tidak dapat memecah repositori Git karena objek sudah terlalu besar dan perubahan tidak dipertahankan, Anda dapat mengatasinya dengan mengonfigurasi RootSync atau RepoSync untuk menonaktifkan sementara penulisan status objek ke ResourceGroup. Anda dapat melakukannya dengan menyetel kolom .spec.override.statusMode objek RootSync atau RepoSync ke disabled. Dengan melakukannya, 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.

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

  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 dalam proses 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 Anda menyinkronkan objek dengan dependensi, Anda mungkin menerima error yang mirip dengan contoh berikut saat rekonsiliasi 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 ke waktu yang lebih lama dengan menyetel spec.override.reconcileTimeout.

Ada juga kemungkinan bahwa dependensi dapat disesuaikan setelah upaya sinkronisasi awal selesai. Dalam hal ini, dependensi harus terdeteksi sebagai direkonsiliasi pada upaya coba lagi sinkronisasi berikutnya, sehingga tidak memblokir 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 adalah nol

Jika Anda menerima error berikut saat reconciler 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 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 reconciler mencoba menerapkan konfigurasi ke cluster, kemungkinan Anda memiliki konfigurasi inventaris yang dibuat 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 melakukan perubahan pada kolom yang tidak dapat diubah

Anda tidak dapat mengubah kolom yang tidak dapat diubah dalam konfigurasi dengan mengubah nilai dalam sumber tepercaya. Mencoba melakukan 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 Anda, tunggu hingga Config Sync menghapus objek dari cluster, lalu buat ulang objek di sumber kebenaran Anda dengan pembaruan Anda.

Polling untuk status gagal

Anda dapat mengizinkan Config Sync untuk mengelola resource dalam namespace menggunakan objek RepoSync. Jika objek RepoSync jenis 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 tentang cara menambahkan izin ini, lihat Membuat RoleBinding.

Penemuan API gagal

Jika Anda melihat pesan error yang mirip dengan 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 mana yang didukung oleh cluster. Hal ini memungkinkan Config Sync memvalidasi jenis resource yang ditentukan di sumber Anda dan memantau resource tersebut untuk mengetahui perubahan di cluster.

Sebelum Kubernetes versi 1.28, setiap kali backend APIService tidak berfungsi dengan baik atau menampilkan hasil daftar kosong, Penemuan API 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 memperbarui 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 kegagalan penemuan API lainnya adalah webhook yang tidak berfungsi dengan baik.

Setelah Kubernetes versi 1.28, dengan fitur Penemuan Gabungan diaktifkan, backend APIService yang tidak berfungsi 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 sehat tidak ditentukan dalam sumber Anda.

Pemulihan otomatis tertunda

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

Perbaikan mandiri dijeda saat sinkronisasi sedang dicoba. Perilaku ini berarti bahwa pemulihan mandiri mungkin tertunda, terutama jika ada error sinkronisasi yang mencegah rekonsiliator selesai. Untuk mengaktifkan kembali pemulihan 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 kesalahan. Oleh karena itu, setiap RootSync dan RepoSync mendapatkan instance rekonsiliasinya sendiri. Selain menyinkronkan setiap kali perubahan dilakukan pada sumber, setiap instance rekonsiliasi juga menyinkronkan secara berkala sebagai bagian dari perilaku pemulihan mandirinya, untuk mengembalikan perubahan yang terlewat oleh perbaikan penyimpangan aktif. Saat Anda menambahkan objek RootSync atau RepoSync, hal ini menyebabkan peningkatan linear dalam 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. Hal 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 dilakukan 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 saat menyinkronkan, 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 menggunakan backoff eksponensial, tetapi jika banyak objek RootSync atau RepoSync gagal disinkronkan secara bersamaan, hal ini dapat menyebabkan beban traffic yang signifikan pada API Kubernetes.

Untuk mengurangi masalah ini, coba salah satu opsi berikut:

  • Perbaiki kesalahan konfigurasi dengan cepat, sehingga tidak menumpuk.
  • Gabungkan beberapa objek RootSync atau RepoSync untuk mengurangi jumlah rekonsiliasi yang membuat permintaan Kubernetes API.

Uninstal KubeVirt diblokir oleh finalizer

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

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

Untuk mengurangi masalah ini pada masa mendatang, nyatakan 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 objek dihapus hingga setelah pengontrol tertentu melakukan pembersihan. Hal ini dapat menyebabkan sinkronisasi atau rekonsiliasi gagal, jika kondisi pembersihan tidak terpenuhi atau pengontrol yang melakukan pembersihan untuk resource tersebut tidak berfungsi dengan baik atau telah dihapus.

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

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

Jika pengontrol dalam kondisi baik, pengontrol seharusnya telah menerapkan kondisi status ke objek yang sedang 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 telah dihapus dalam urutan yang salah. Untuk mencegah masalah semacam ini pada masa mendatang, deklarasikan dependensi antara objek resource, untuk memastikan objek tersebut dihapus dalam urutan dependensi terbalik.

Kolom ResourceGroup terus berubah

Saat sinkronisasi dicoba, inventaris diperbarui untuk mengubah status resource menjadi tertunda. Jika sinkronisasi gagal, inventaris akan diperbarui untuk mengubah status resource menjadi gagal. Saat sinkronisasi dicoba lagi setelah gagal, pola ini berulang, sehingga menyebabkan pembaruan inventaris secara berkala. Hal ini menyebabkan ResourceGroup resourceVersion bertambah dengan setiap update dan status sinkronisasi berubah bolak-balik. Hal ini normal, tetapi bisa mengejutkan.

Kegagalan sinkronisasi dapat disebabkan oleh sejumlah masalah. Salah satu penyebab 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 rekonsiliasi RepoSync atau RootSync untuk mengelola resource yang gagal disinkronkan.

Config Sync tidak menghapus atau mengembalikan kolom yang tidak ditentukan di sumber

Config Sync menggunakan Penerapan Sisi Server untuk menerapkan manifes dari sumber ke Kubernetes. Hal ini diperlukan untuk mengizinkan pengontrol lain mengelola kolom metadata dan spec. Salah satu contohnya adalah Horizontal Pod Autoscaler, yang mengupdate 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 yang tidak ditentukan dalam sumber tidak akan berubah, 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 mengadopsi untuk pertama kalinya, lalu ubah kolom di sumber setelah menyinkronkan, 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 Penerapan Sisi Server, saat Config Sync mengadopsi objek yang awalnya dibuat dengan penerapan sisi klien kubectl, Config Sync akan membatalkan setelan semua kolom yang ditetapkan dengan penerapan sisi klien, 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 Penerapan Sisi Server.

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: