Memecahkan masalah sinkronisasi konfigurasi ke cluster

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

Memecahkan masalah error KNV 2009

KNV2009 error menunjukkan bahwa Config Sync gagal menyinkronkan beberapa konfigurasi ke gugus ini. Bagian berikut menjelaskan beberapa penyebab yang paling umum dan cara mengatasinya.

Operasi pada resource tertentu dilarang

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

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

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

Ganti NAMESPACE dengan namespace yang Anda buat ke repositori namespace Anda.

Anda juga dapat menggunakan Perintah nomos status.

Jika Anda melihat pesan berikut dalam status, itu berarti rekonsiliasi di NAMESPACE tidak memiliki izin yang diperlukan untuk menerapkan referensi:

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 harus mendeklarasikan konfigurasi RoleBinding yang memberikan akun layanan untuk izin rekonsiliasi guna mengelola resource yang gagal dalam namespace tersebut. Detail tentang cara menambahkan RoleBinding disertakan dalam Mengonfigurasi sinkronisasi dari beberapa repositori Anda.

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 {i>field <i}ini, Objek RootSync 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 melebihi ukuran objek etcd batas:

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 Git repositori berbasis browser karena objek sudah terlalu besar dan tidak ada perubahan tetap ada, Anda dapat memitigasinya dengan mengonfigurasi RootSync atau RepoSync untuk menonaktifkan sementara penulisan status objek ke ResourceGroup. Anda bisa melakukannya dengan menyetel kolom .spec.override.statusMode dari RootSync atau RepoSync ke disabled. Dengan demikian, Config Sync akan berhenti memperbarui setelan status resource di objek ResourceGroup. Tindakan ini mengurangi ukuran objek ResourceGroup. Namun, Anda tidak dapat melihat status untuk layanan resource dari nomos status atau gcloud alpha anthos config sync.

Jika Anda tidak melihat error apa pun dari objek RootSync atau RepoSync, 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 yang telah Anda telah membuat repositori namespace.

    Outputnya mirip dengan contoh berikut: 

    NAME        RECONCILING   STALLED   AGE
root-sync   True          False     35m

    Jika nilai dalam kolom RECONCILING adalah True, ini berarti Resource ResourceGroup masih direkonsiliasi.

  2. Periksa log untuk pengontrol ResourceGroup:

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

    Jika Anda melihat pesan {i>error<i} yang mirip dengan contoh berikut dalam {i>output<i}, elemen 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 pisah satu repositori root menjadi beberapa repositori root.

Waktu tunggu rekonsiliasi penerapan dependensi

Jika menyinkronkan objek dengan dependensi, Anda mungkin menerima error mirip dengan contoh berikut ketika 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 nilai default waktu tunggu rekonsiliasi lima menit. Config Sync tidak dapat menerapkan 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

Mungkin juga dependensi tersebut akan direkonsiliasi setelah sinkronisasi awal percobaan telah selesai. Dalam hal ini, dependensi harus terdeteksi sebagai direkonsiliasi pada upaya percobaan ulang sinkronisasi berikutnya, membatalkan pemblokiran penerapan tanggungan. Ketika ini terjadi, kesalahan mungkin dilaporkan secara singkat dan kemudian dihapus. Memperpanjang waktu tunggu rekonsiliasi dapat membantu menghindari kesalahan dilaporkan sesekali.

Info inventaris tidak ada

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

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 yang semua resource-nya memiliki configmanagement.gke.io/managed: disabled, dengan memastikan setidaknya satu resource dikelola oleh Config Sync.
  2. Tambahkan anotasi configmanagement.gke.io/managed: disabled saja setelah menyelesaikan sinkronisasi awal resource tanpa anotasi ini.

Beberapa template objek inventaris

Jika Anda menerima error berikut saat rekonsiliasi mencoba menerapkan konfigurasi inventaris ke cluster, ada 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. Kepada 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 kolom yang sesungguhnya. Mencoba perubahan tersebut akan menyebabkan {i>error<i} yang serupa 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 memperbarui kolom yang tidak dapat diubah, hapus objek secara manual di . Kemudian, Config Sync dapat membuat ulang objek dengan kolom baru. dengan sejumlah nilai.

Penemuan API gagal

Jika melihat pesan {i>error<i} seperti 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

Penggunaan Config Sync Penemuan Kubernetes API untuk mencari resource yang didukung oleh cluster. Hal ini memungkinkan Config Sync memvalidasi jenis resource yang ditentukan di sumber dan smartwatch Anda resource tersebut untuk perubahan dalam cluster.

Sebelum Kubernetes versi 1.28, setiap backend APIService tidak responsif atau menampilkan hasil daftar kosong, Penemuan API akan gagal, sehingga menyebabkan Sinkronisasi Konfigurasi dan beberapa komponen Kubernetes lainnya mengalami error. Banyak Backend APIService tidak terlalu tersedia, sehingga hal ini bisa terjadi secara relatif sering, hanya dengan memperbarui {i>backend<i} atau memintanya untuk dijadwalkan 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. Hal umum lainnya penyebab 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. Ini memungkinkan sinkronisasi dilanjutkan, selama sumber daya yang tidak responsif tidak ditentukan dalam sumber.

Pemulihan diri tertunda

Pemulihan mandiri mengawasi resource yang dikelola, mendeteksi penyimpangan dari sumber kebenaran, dan mengembalikan penyimpangan tersebut.

Pemulihan mandiri dijeda saat sinkronisasi sedang dicoba. Perilaku ini berarti proses pemulihan mandiri tersebut mungkin tertunda, terutama jika terjadi error sinkronisasi sehingga mencegah rekonsiliasi selesai. Untuk mengaktifkan kembali pemulihan mandiri, perbaiki semua melaporkan error sinkronisasi.

Jumlah permintaan Kubernetes API yang tinggi

Config Sync menggunakan strategi multi-instancing untuk menskalakan dan mengisolasi tenant dan domain fault. Oleh karena itu, setiap RootSync dan RepoSync akan memiliki keduanya instance rekonsiliasi. Selain melakukan sinkronisasi setiap kali perubahan dibuat ke tambahan, setiap instance rekonsiliasi juga disinkronkan secara berkala sebagai bagian dari perilaku pemulihan mandiri, untuk mengembalikan setiap perubahan yang terlewatkan oleh penyimpangan aktif dan perbaikan. Saat Anda menambahkan objek RootSync atau RepoSync, hal ini akan menyebabkan peningkatan jumlah permintaan API yang dibuat oleh rekonsiliasi yang menyinkronkan resource ke Kubernetes. Jadi, jika Anda memiliki banyak objek RootSync dan RepoSync, objek ini dapat terkadang menyebabkan beban traffic yang signifikan pada Kubernetes API.

Untuk melakukan sinkronisasi, Config Sync menggunakan Penerapan Sisi Server. Cara ini menggantikan alur permintaan GET dan PATCH normal dengan satu permintaan PATCH, mengurangi jumlah total panggilan API, tetapi meningkatkan jumlah PATCH panggilan telepon. Hal ini memastikan bahwa perubahan yang dibuat benar, bahkan ketika sumber daya versi grup di sumber tidak cocok dengan versi grup resource default di . Namun, Anda mungkin melihat permintaan PATCH di log audit, bahkan ketika ada belum ada perubahan pada sumber atau penyimpangan dari status yang Anda inginkan. Ini itu normal, tetapi bisa mengejutkan.

Jika mengalami error, sinkronisasi akan dicoba lagi hingga berhasil. Namun, jika memerlukan interaksi manusia, Config Sync mungkin mengalami error dan mencoba lagi sekaligus meningkatkan jumlah permintaan yang dibuat ke Kubernetes API. Percobaan ulang mundur secara eksponensial, tetapi jika banyak objek RootSync atau RepoSync gagal untuk menyinkronkan secara bersamaan, hal ini dapat menyebabkan beban lalu lintas 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 rekonsiler yang membuat permintaan Kubernetes API.

Uninstal KubeVirt diblokir oleh finalis

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

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

Untuk memitigasi masalah ini di masa mendatang, mendeklarasikan dependensi antar-objek resource untuk memastikan mereka dihapus dalam urutan dependensi terbalik.

Penghapusan objek diblokir oleh finaler

Pengfinalisasi Kubernetes adalah entri metadata yang memberi tahu Kubernetes untuk tidak mengizinkan penghapusan objek hingga {i>controller<i} tertentu melakukan pembersihan. Hal ini dapat menyebabkan sinkronisasi atau merekonsiliasi yang gagal, jika kondisi pembersihan tidak terpenuhi atau {i>controller<i} yang melakukan pembersihan untuk sumber daya tersebut tidak sehat atau telah dihapus.

Untuk mengurangi masalah ini, identifikasi sumber daya mana yang masih dalam proses penyelesaian dan yang seharusnya melakukan pembersihan.

Jika pengontrol tidak responsif, memperbaiki akar masalahnya akan memungkinkan resource pembersihan data untuk menyelesaikan, membuka blokir penghapusan objek.

Jika pengontrol responsif, pengontrol seharusnya telah menerapkan status kondisi pada objek yang dihapus untuk menjelaskan mengapa pembersihan terhenti. Jika tidak, periksa log {i>controller<i} untuk mengetahui indikasi akar masalahnya.

Sering kali, objek yang macet dihapus adalah indikasi bahwa objek dalam urutan yang salah. Untuk mencegah masalah seperti ini di masa depan, mendeklarasikan dependensi antar-objek resource, untuk memastikan mereka dihapus dalam urutan dependensi terbalik.

Kolom ResourceGroup terus berubah

Saat sinkronisasi dicoba, inventaris akan diperbarui untuk mengubah status resource ke status menunggu persetujuan. Jika sinkronisasi gagal, inventaris akan diperbarui untuk mengubah resource gagal. Saat sinkronisasi dicoba lagi setelah kegagalan, pola ini akan berulang, yang menyebabkan pembaruan berkala pada inventaris. Ini menyebabkan ResourceGroup resourceVersion akan meningkat setiap kali update dilakukan dan status sinkronisasi akan berbalik bolak-balik. Hal ini normal, tetapi dapat mengejutkan.

Kegagalan sinkronisasi dapat disebabkan oleh beberapa masalah. Salah satu yang paling umum adalah tidak memiliki izin untuk mengelola resource yang ditentukan dalam sumber. Untuk memperbaiki error ini, tambahkan RoleBindings atau ClusterRoleBinding yang sesuai untuk memberikan Izin rekonsiliasi RepoSync atau RootSync untuk mengelola resource yang gagal disinkronkan.

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

Penggunaan Config Sync Penerapan Sisi Server untuk menerapkan manifes dari sumber ke Kubernetes. Hal ini diperlukan untuk mengizinkan pengontrol lain mengelola kolom metadata dan spec. Salah satu contoh ini adalah Horizontal Pod Autoscaler, yang memperbarui jumlah replika dalam Penyebaran. Oleh karena itu, Config Sync hanya mengelola kolom yang ditentukan dalam manifes sumber. Ini memiliki efek samping ketika mengadopsi objek resource, setiap kolom yang tidak ditentukan dalam sumber tidak akan berubah, sehingga bisa terkadang menyebabkan konfigurasi gabungan menjadi tidak valid atau salah.

Untuk menghindari masalah ini saat mengadopsi sumber daya, gunakan kolom yang sama persis di sumber saat pertama kali mengadopsi kemudian mengubah kolom dalam sumber setelah menyinkronkan, sehingga Config Sync menghapus kolom yang dimaksud 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 izinkan Config Sync untuk menerapkan versi baru.

Langkah selanjutnya

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