Memecahkan masalah Config Connector

Halaman ini menjelaskan teknik pemecahan masalah yang dapat Anda gunakan untuk memecahkan masalah Config Connector dan masalah umum yang mungkin Anda alami saat menggunakan produk ini.

Memeriksa status dan kondisi Config Connector

Memeriksa versi Config Connector

Jalankan perintah berikut untuk mendapatkan versi Config Connector yang diinstal, dan lakukan referensi silang catatan rilis untuk memverifikasi bahwa versi yang berjalan mendukung fitur dan resource yang ingin Anda gunakan:

kubectl get ns cnrm-system -o jsonpath='{.metadata.annotations.cnrm\.cloud\.google\.com/version}'

Memeriksa status dan peristiwa resource

Biasanya, Anda dapat menentukan masalah pada resource Config Connector dengan memeriksa status resource di Kubernetes. Memeriksa status dan peristiwa resource sangat membantu untuk menentukan apakah Config Connector gagal merekonsiliasi resource dan alasan kegagalan rekonsiliasi tersebut.

Memastikan Config Connector berjalan

Untuk memeriksa apakah Config Connector berjalan, pastikan semua Pod-nya READY:

kubectl get pod -n cnrm-system

Contoh output:

NAME                                            READY   STATUS    RESTARTS   AGE
cnrm-controller-manager-0                       1/1     Running   0          1h
cnrm-deletiondefender-0                         1/1     Running   0          1h
cnrm-resource-stats-recorder-77dc8cc4b6-mgpgp   1/1     Running   0          1h
cnrm-webhook-manager-58496b66f9-pqwhz           1/1     Running   0          1h
cnrm-webhook-manager-58496b66f9-wdcn4           1/1     Running   0          1h

Jika Anda telah menginstal Config Connector dalam mode namespace, Anda akan memiliki satu Pod pengontrol (cnrm-controller-manager) untuk setiap namespace yang bertanggung jawab mengelola resource Config Connector di namespace tersebut.

Anda dapat memeriksa status Pod pengontrol yang bertanggung jawab atas namespace tertentu dengan menjalankan:

kubectl get pod -n cnrm-system \
    -l cnrm.cloud.google.com/scoped-namespace=NAMESPACE \
    -l cnrm.cloud.google.com/component=cnrm-controller-manager

Ganti NAMESPACE dengan nama namespace.

Memeriksa log pengontrol

Pod pengontrol mencatat informasi dan error yang terkait dengan rekonsiliasi resource Config Connector.

Anda dapat memeriksa log Pod pengontrol dengan menjalankan:

kubectl logs -n cnrm-system \
    -l cnrm.cloud.google.com/component=cnrm-controller-manager \
    -c manager

Jika Anda telah menginstal Config Connector dalam mode-ber-namespace, perintah sebelumnya akan menampilkan log semua Pod pengontrol yang digabungkan. Anda dapat memeriksa log Pod pengontrol untuk namespace tertentu dengan menjalankan:

kubectl logs -n cnrm-system \
    -l cnrm.cloud.google.com/scoped-namespace=NAMESPACE \
    -l cnrm.cloud.google.com/component=cnrm-controller-manager \
    -c manager

Ganti NAMESPACE dengan nama namespace.

Baca selengkapnya tentang cara memeriksa dan mengkueri log Config Connector.

Melepaskan dan mendapatkan resource

Dalam beberapa kasus, Anda mungkin perlu memperbarui kolom yang tidak dapat diubah dalam resource. Karena Anda tidak dapat mengedit kolom yang tidak dapat diubah, Anda harus mengabaikan, lalu memperoleh resource:

1. Perbarui konfigurasi YAML resource Config Connector dan tetapkan anotasi cnrm.cloud.google.com/deletion-policy ke abandon.
2. Terapkan konfigurasi YAML yang telah diperbarui untuk mengupdate kebijakan penghapusan resource Config Connector.
3. Membatalkan resource Config Connector.
4. Perbarui kolom tetap yang perlu diubah dalam konfigurasi YAML.
5. Terapkan konfigurasi YAML yang telah diperbarui untuk mendapatkan resource yang ditinggalkan.

Memecahkan masalah menurut jenis masalah

Gunakan tabel berikut untuk membantu memecahkan masalah Anda berdasarkan jenis gejala.

Jenis masalah	Masalah umum
Rekonsiliasi	Resource terus diperbarui setiap 5-15 menit Rekonsiliasi gagal atau berulang karena pembaruan kolom otomatis Resource tidak memiliki status KNV2005: sinkronisasi mengupdate resource secara berlebihan Resource dihapus oleh Config Connector Controller Pod OOMKilled
Penghapusan	Penghapusan namespace yang macet di Terminating Penghapusan resource macet di DeleteFailed setelah project dihapus
Izin	Metadata Compute Engine tidak ditentukan Error 403: Request had insufficient authentication scopes 403 Forbidden: Pemanggil tidak memiliki izin Error 403: Pemanggil tidak memiliki izin IAM Error pembaruan dengan IAMPolicy, IAMPartialPolicy, dan IAMPolicyMember
Penginstalan dan upgrade	Versi tidak didukung dalam penginstalan add-on Config Connector failed calling webhook PodSecurityPolicy mencegah upgrade
Konfigurasi	Tidak dapat membuat perubahan pada kolom yang tidak dapat diubah Tidak ada kecocokan untuk jenis "Foo" Label tidak diteruskan ke resource Google Cloud Error karena karakter khusus dalam nama resource Tidak dapat menghapus kolom dari spesifikasi resource Nilai "gabungkan" tidak valid untuk anotasi state-into-spec

Rekonsiliasi

Bagian berikut mencantumkan masalah umum terkait rekonsiliasi resource oleh Config Connector.

Resource terus diperbarui setiap 5-15 menit

Gejala

Resource Config Connector Anda terus beralih dari status UpToDate ke status Updating setiap 5-10 menit.

Penyebab

Kemungkinan Config Connector mendeteksi perbedaan yang tidak disengaja antara status yang diinginkan dan status sebenarnya resource, sehingga menyebabkan Config Connector terus memperbarui resource.

Resolusi

Pertama, pastikan Anda tidak memiliki sistem eksternal yang terus-menerus mengubah resource Config Connector atau Google Cloud (misalnya, pipeline CI/CD, pengontrol kustom, cron job, dll.).

Jika perilaku tersebut bukan disebabkan oleh sistem eksternal, periksa apakah Google Cloud mengubah nilai yang ditentukan dalam resource Config Connector Anda. Misalnya, dalam beberapa kasus, Google Cloud mengubah format (misalnya, kapitalisasi) nilai kolom yang menyebabkan perbedaan antara status yang diinginkan dan status sebenarnya resource Anda.

Dapatkan status resource Google Cloud menggunakan REST API (misalnya, untuk ContainerCluster) atau Google Cloud CLI. Kemudian, bandingkan status tersebut dengan resource Config Connector Anda. Cari kolom yang nilainya tidak cocok, lalu perbarui resource Config Connector Anda agar cocok. Secara khusus, cari nilai apa pun yang diformat ulang oleh Google Cloud. Misalnya, lihat masalah GitHub #578 dan #294.

Perhatikan bahwa metode ini tidak sempurna karena model resource Config Connector dan Google Cloud berbeda, tetapi metode ini akan memungkinkan Anda menangkap sebagian besar kasus perbedaan yang tidak diinginkan.

Jika Anda tidak dapat menyelesaikan masalah, lihat Bantuan tambahan.

Rekonsiliasi gagal atau berulang karena pembaruan kolom otomatis

Masalah ini terjadi saat Google Cloud memperbarui kolom secara otomatis pada resource yang menggunakan anotasi cnrm.cloud.google.com/state-into-spec: merge.

Gejala

Resource Config Connector Anda memasuki status UpdateFailed atau berulang kali beralih ke status Updating setelah Google Cloud memperbarui kolom yang tidak Anda tentukan dalam manifes YAML secara otomatis.

Misalnya, setelah Cloud SQL melakukan update pemeliharaan otomatis pada resource SQLInstance, rekonsiliasi mungkin gagal dengan error yang mirip dengan berikut ini:

Update call failed: error updating: patching SQLInstance ... maintenanceVersion failed: googleapi: Error 400: Invalid request: The requested maintenance version is not an available maintenance version to upgrade. Please refer to the availableMaintenanceVersions on the instance resource to see the available maintenance versions.., invalid

Penyebab

Resource memiliki anotasi cnrm.cloud.google.com/state-into-spec: merge. Anotasi ini adalah default untuk resource yang dibuat sebelum Config Connector versi 1.123.1 untuk CustomResourceDefinitions (CRD) yang ditambahkan dalam versi 1.113.0 dan yang lebih lama. Resource Anda mungkin juga memiliki anotasi ini jika kolom spec.stateIntoSpec disetel ke Merge di resource kustom (CR) ConfigConnector atau ConfigConnectorContext.

Jika anotasi cnrm.cloud.google.com/state-into-spec ditetapkan ke merge, Config Connector akan mengisi kolom yang tidak ditentukan, seperti kolom spec.maintenanceVersion, ke dalam kolom spec resource Kubernetes selama rekonsiliasi awal. Saat Google Cloud kemudian otomatis memperbarui kolom tersebut pada resource yang mendasarinya, Config Connector memperlakukan nilai lama yang disimpan di kolom spec sebagai status target dan mencoba mengembalikan perubahan tersebut. Jika Google Cloud API menolak downgrade (seperti yang dilakukan Cloud SQL untuk kolom spec.maintenanceVersion), rekonsiliasi akan gagal.

Resolusi

Untuk mengatasi masalah ini, migrasikan resource dari perilaku Merge ke perilaku Absent agar Config Connector berhenti mengisi kolom yang tidak ditentukan ke dalam kolom spec:

1. Dalam manifes YAML resource, hapus kolom yang diperbarui secara otomatis (seperti kolom spec.maintenanceVersion) dan tetapkan anotasi cnrm.cloud.google.com/state-into-spec ke absent.
2. Ikuti langkah-langkah di Memigrasikan resource dari Merge ke Absent untuk membatalkan resource Kubernetes dan mendapatkannya kembali dengan manifes YAML yang telah diupdate.

Resource tidak memiliki status

Gejala

Resource Anda tidak memiliki kolom status.

Penyebab

Kemungkinan Config Connector tidak berjalan dengan benar.

Resolusi

Pastikan Config Connector berjalan.

KNV2005: sinkronisasi mengupdate resource secara berlebihan

Gejala

Anda menggunakan Config Sync dan melihat error KNV2005 untuk resource Config Connector, seperti berikut:

KNV2005: detected excessive object updates, approximately 6 times per
minute. This may indicate Config Sync is fighting with another controller over
the object.

Penyebab

Kemungkinan Config Sync dan Config Connector memperebutkan resource.

Config Sync dan Config Connector dikatakan "bertengkar" memperebutkan resource jika terus mengupdate kolom yang sama ke nilai yang berbeda. Pembaruan satu resource memicu resource lain untuk bertindak dan memperbarui resource, yang menyebabkan resource lain bertindak dan memperbarui resource, dan hal ini berulang tanpa akhir.

Perkelahian bukanlah masalah bagi sebagian besar bidang. Kolom yang ditentukan di Config Sync tidak diubah oleh Config Connector. Demikian pula, kolom yang tidak ditentukan di Config Sync dan ditetapkan secara default oleh Config Connector akan diabaikan oleh Config Sync. Oleh karena itu, untuk sebagian besar kolom, Config Sync dan Config Connector tidak perlu memperbarui kolom yang sama.

Satu pengecualian adalah kolom daftar. Mirip dengan cara Config Connector dapat menggunakan subkolom default di kolom objek, Config Connector juga dapat menggunakan subkolom default di objek dalam daftar. Namun, karena kolom daftar di resource Config Connector bersifat atomik, penetapan default subkolom dianggap sebagai perubahan nilai daftar sepenuhnya.

Oleh karena itu, Config Sync dan Config Connector akan "memperebutkan" resource jika Config Sync menetapkan kolom daftar dan Config Connector menetapkan subkolom apa pun dalam daftar tersebut secara default.

Resolusi

Untuk mengatasi masalah ini, Anda memiliki opsi berikut:

1. Perbarui manifes resource di repositori Config Sync agar sesuai dengan yang ingin ditetapkan oleh Config Connector untuk resource tersebut.

   Salah satu cara untuk melakukannya adalah dengan menghentikan sinkronisasi konfigurasi untuk sementara, menunggu Config Connector selesai merekonsiliasi resource, lalu mengupdate manifes resource agar sesuai dengan resource di Server API Kubernetes.

2. Hentikan Config Sync agar tidak bereaksi terhadap update resource di Server API Kubernetes dengan menyetel anotasi client.lifecycle.config.k8s.io/mutation ke ignore. Baca selengkapnya tentang cara agar Config Sync mengabaikan mutasi objek.

3. Hentikan Config Connector agar tidak mengupdate spesifikasi resource sepenuhnya dengan menetapkan anotasi cnrm.cloud.google.com/state-into-spec ke absent pada resource. Anotasi ini tidak didukung untuk semua resource. Untuk melihat apakah resource Anda mendukung anotasi, periksa halaman referensi resource yang sesuai. Baca selengkapnya tentang anotasi.

Resource dihapus oleh Config Connector

Gejala

Resource dihapus dari cluster Anda, dan Anda mencurigai Config Connector menghapusnya.

Penyebab

Config Connector tidak pernah menghapus resource Anda tanpa penyebab eksternal. Misalnya, menjalankan kubectl delete, menggunakan alat pengelolaan konfigurasi seperti Argo CD, atau menggunakan klien API yang disesuaikan dapat menyebabkan penghapusan resource.

Kesalahpahaman yang umum adalah bahwa Config Connector telah memulai dan menghapus beberapa resource di cluster Anda. Misalnya, jika Anda menggunakan Config Connector, Anda mungkin melihat permintaan penghapusan dari pengelola pengontrol Config Connector terhadap resource tertentu dari pesan log container atau log audit cluster Kubernetes. Permintaan penghapusan ini adalah hasil dari pemicu eksternal dan Config Connector mencoba merekonsiliasi permintaan penghapusan.

Resolusi

Untuk menentukan alasan resource dihapus, Anda perlu melihat permintaan penghapusan pertama yang dikirim ke resource terkait. Cara terbaik untuk memeriksanya adalah dengan memeriksa log audit cluster Kubernetes.

Misalnya, jika menggunakan GKE, Anda dapat menggunakan Cloud Logging untuk mengkueri log audit cluster GKE. Misalnya, jika Anda ingin mencari permintaan penghapusan awal untuk resource BigQueryDataset bernama foo di namespace bar, Anda akan menjalankan kueri seperti berikut:

resource.type="k8s_cluster"
resource.labels.project_id="my-project-id"
resource.labels.cluster_name="my-cluster-name"
protoPayload.methodName="com.google.cloud.cnrm.bigquery.v1beta1.bigquerydatasets.delete"
protoPayload.resourceName="bigquery.cnrm.cloud.google.com/v1beta1/namespaces/bar/bigquerydatasets/foo"

Dengan menggunakan kueri ini, Anda akan mencari permintaan penghapusan pertama, lalu memeriksa authenticationInfo.principalEmail dari pesan log penghapusan tersebut untuk menentukan penyebab penghapusan.

Pod Pengontrol OOMKilled

Gejala

Anda melihat error OOMKilled di Pod pengontrol Config Connector. Status Pod dapat muncul sebagai OOMKilled atau Terminating.

Penyebab

Container atau seluruh Pod dihentikan karena menggunakan lebih banyak memori daripada yang diizinkan. Hal ini dapat diverifikasi dengan menjalankan perintah kubectl describe:

kubectl describe pod POD_NAME -n cnrm-system

Ganti POD_NAME dengan Pod yang sedang Anda pecahkan masalahnya.

Selain itu, memeriksa log peristiwa Pod dapat mengungkapkan terjadinya peristiwa terkait OOM.

Resolusi

Untuk mengatasi masalah ini, Anda dapat menggunakan resource kustom ControllerResource untuk meningkatkan permintaan memori dan batas memori untuk Pod.

Penghapusan

Bagian berikut mencantumkan masalah umum terkait operasi penghapusan yang dimulai pengguna yang dapat menyebabkan konflik dengan Config Connector.

Penghapusan namespace terjebak di "Terminating"

Gejala

Penghapusan namespace terhenti pada tahap Terminating.

Penyebab

Masalah ini dapat terjadi jika Anda menginstal Config Connector dalam mode namespace dan jika ConfigConnectorContext namespace dihapus sebelum semua resource Config Connector di namespace tersebut dihapus. Saat ConfigConnectorContext namespace dihapus, Config Connector akan dinonaktifkan untuk namespace tersebut, sehingga mencegah penghapusan resource Config Connector yang tersisa di namespace tersebut.

Resolusi

Untuk memperbaiki masalah ini, Anda harus melakukan pembersihan paksa, lalu menghapus resource Google Cloud yang mendasarinya secara manual setelahnya.

Untuk mengurangi masalah ini di masa mendatang, hanya hapus ConfigConnectorContext setelah semua resource Config Connector di namespace-nya dihapus dari Kubernetes. Hindari menghapus seluruh namespace sebelum semua resource Config Connector di namespace tersebut dihapus karena ConfigConnectorContext mungkin dihapus terlebih dahulu.

Penghapusan resource terhenti di "DeleteFailed" setelah project dihapus

Gejala

Penghapusan resource Config Connector gagal dengan status DeleteFailed.

Penyebab

Masalah ini dapat terjadi jika Google Cloud project dihapus sebelum resource.

Resolusi

Untuk memperbaiki masalah ini, pulihkan project di Google Cloud agar Config Connector dapat menghapus resource anak yang tersisa dari Kubernetes. Atau, Anda dapat melakukan pembersihan paksa.

Untuk mengurangi masalah ini di masa mendatang, hanya hapus project Google Cloud setelah semua resource Config Connector turunannya dihapus dari Kubernetes. Hindari menghapus seluruh namespace yang mungkin berisi resource Project dan resource Config Connector turunannya karena resource Project mungkin akan dihapus terlebih dahulu.

Izin dan autentikasi

Bagian berikut mencantumkan masalah umum terkait izin dan autentikasi.

Metadata Compute Engine tidak ditentukan

Gejala

Resource Config Connector Anda memiliki status UpdateFailed dengan pesan yang menyatakan bahwa metadata Compute Engine tidak ditentukan, mirip dengan error berikut:

Update call failed: error fetching live state: error reading underlying
resource: summary: Error when reading or editing SpannerInstance
"my-project/my-spanner- instance": Get
"https://spanner.googleapis.com/v1/projects/my-project/instances/my-spanner-instance?alt=json":
metadata: Compute Engine metadata "instance/service-accounts/default/token?
scopes=https%!A(MISSING)%!F(MISSING)%!F(MISSING)www.googleapis.com%!F(MISSING)auth%!F(MISSING)compute%!C(MISSING)https%!A(MISSING)%!F(MISSING)%!F(MISSING)www.googleapis.com%!F(MISSIN
G)auth%!F(MISSING)cloud-platform%!C(MISSING)https%!A(MISSING)%!F(MISSING)%!F(MISSING)www.googleapis.com%!F(MISSING)auth%!F(MISSING)cloud-identity%!C(MISSING)https%!A(MISSING)%!F(MISS
ING)%!F(MISSING)www.googleapis.com%!F(MISSING)auth%!F(MISSING)ndev.clouddns.readwrite%!C(MISSING)https%!A(MISSING)%!F(MISSING)%!F(MISSING)www.googleapis.com%!F(MISSING)auth%!F(MISSIN
G)devstorage.full_control%!C(MISSING)https%!A(MISSING)%!F(MISSING)%!F(MISSING)www.googleapis.com%!F(MISSING)auth%!F(MISSING)userinfo.email%!C(MISSING)https%!A(MISSING)%!F(MISSING)%!F
(MISSING)www.googleapis.com%!F(MISSING)auth%!F(MISSING)drive.readonly" not
defined, detail:

Penyebab

Kemungkinan akun layanan IAM yang digunakan oleh Config Connector tidak ada.

Resolusi

Untuk memperbaiki masalah ini, pastikan akun layanan IAM yang digunakan oleh Config Connector ada.

Untuk mengurangi masalah ini di masa mendatang, pastikan Anda mengikuti petunjuk penginstalan Config Connector.

Error 403: Permintaan memiliki cakupan autentikasi yang tidak memadai

Gejala

Resource Config Connector Anda memiliki status UpdateFailed dengan pesan yang menunjukkan error 403 karena cakupan autentikasi yang tidak memadai, mirip dengan error berikut:

Update call failed: error fetching live state: error reading underlying
resource: summary: Error when reading or editing SpannerInstance
"my-project/my-spanner-instance": googleapi: Error 403: Request had
insufficient authentication scopes.

Penyebab

Workload Identity Federation for GKE kemungkinan tidak diaktifkan di cluster GKE Anda.

Untuk mengonfirmasi bahwa Workload Identity Federation untuk GKE tidak diaktifkan, selesaikan langkah-langkah berikut:

1. Simpan konfigurasi Pod berikut sebagai wi-test.yaml:

   apiVersion: v1
   kind: Pod
   metadata:
     name: workload-identity-test
     namespace: cnrm-system
   spec:
     containers:
     - image: google/cloud-sdk:slim
       name: workload-identity-test
       command: ["sleep","infinity"]
     serviceAccountName: cnrm-controller-manager
   

   Jika Anda menginstal Config Connector menggunakan mode namespace, serviceAccountName harus berupa cnrm-controller-manager-NAMESPACE. Ganti NAMESPACE dengan namespace yang Anda gunakan selama penginstalan.

2. Buat Pod di cluster GKE Anda:

   kubectl apply -f wi-test.yaml
   

3. Buka sesi interaktif di Pod:

   kubectl exec -it workload-identity-test \
       --namespace cnrm-system \
       -- /bin/bash
   

4. Mencantumkan identitas Anda:

   gcloud auth list
   

5. Verifikasi bahwa identitas yang tercantum cocok dengan akun layanan Google yang terikat ke resource Anda.

   Jika Anda melihat akun layanan default Compute Engine, berarti Workload Identity Federation for GKE tidak diaktifkan di cluster GKE dan/atau node pool Anda.

6. Keluar dari sesi interaktif, lalu hapus Pod dari cluster GKE Anda:

   kubectl delete pod workload-identity-test \
       --namespace cnrm-system
   

Resolusi

Untuk memperbaiki masalah ini, pastikan Workload Identity Federation untuk GKE diaktifkan di cluster Anda.

Jika Anda masih melihat error yang sama, pastikan Anda juga telah mengaktifkan Workload Identity Federation untuk GKE di node pool cluster.

403 Forbidden: Pemanggil tidak memiliki izin

Gejala

Resource Config Connector Anda memiliki status UpdateFailed dengan pesan yang menunjukkan error 403 karena Workload Identity Federation for GKE, mirip dengan error berikut:

Update call failed: error fetching live state: error reading underlying
resource: summary: Error when reading or editing SpannerInstance
"my-project/my-spanner- instance": Get
"https://spanner.googleapis.com/v1/projects/my-project/instances/my-spanner-instance?alt=json":
compute: Received 403 `Unable to generate access token; IAM returned 403
Forbidden: The caller does not have permission
This error could be caused by a missing IAM policy binding on the target IAM
service account.
For more information, refer to the Workload Identity documentation:
  https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity#creating_a_relationship_between_ksas_and_gsas

Penyebab

Akun layanan Kubernetes Config Connector tidak memiliki izin IAM yang sesuai untuk meniru akun layanan IAM Anda sebagai pengguna Workload Identity Federation for GKE.

Resolusi

Untuk memperbaiki dan mengurangi masalah ini di masa mendatang, lihat petunjuk penginstalan Config Connector.

Error 403: Pemanggil tidak memiliki izin IAM

Gejala

Resource Config Connector Anda memiliki status UpdateFailed dengan pesan yang menyatakan bahwa pemanggil tidak memiliki izin IAM, mirip dengan error berikut:

Update call failed: error fetching live state: error reading underlying
resource: summary: Error when reading or editing SpannerInstance
"my-project/my-spanner- instance": googleapi: Error 403: Caller is missing IAM
permission spanner.instances.get on resource
projects/my-project/instances/my-spanner-instance., detail:

Penyebab

Akun layanan IAM yang digunakan oleh Config Connector tidak memiliki izin IAM yang dinyatakan dalam pesan yang diperlukan untuk mengelola resource Google Cloud .

Resolusi

Jika Anda masih melihat error yang sama setelah memberikan izin IAM yang sesuai kepada akun layanan IAM, periksa apakah resource Anda dibuat di project yang benar. Periksa kolom spec.projectRef resource Config Connector (atau anotasi cnrm.cloud.google.com/project-id-nya jika resource tidak mendukung kolom spec.projectRef) dan verifikasi bahwa resource tersebut mereferensikan project yang benar. Perhatikan bahwa Config Connector menggunakan nama namespace sebagai project ID jika resource maupun namespace tidak menentukan project target. Baca selengkapnya tentang cara mengonfigurasi project target untuk resource cakupan project.

Jika Anda masih melihat error yang sama, periksa apakah Workload Identity Federation untuk GKE diaktifkan di cluster GKE Anda.

Untuk mengatasi masalah ini pada masa mendatang, pastikan Anda mengikuti petunjuk penginstalan Config Connector.

Error update dengan IAMPolicy, IAMPartialPolicy, dan IAMPolicyMember

Gejala

Anda akan melihat status UpdateFailed dengan pesan error yang menunjukkan error 400 karena akun layanan tidak ada:

Update call failed: error setting policy member: error applying changes: summary: Request `Create IAM Members roles/[MYROLE] serviceAccount:[NAME]@[PROJECT_ID].iam.gserviceaccount.com for project \"projects/[PROJECT_ID]\"` returned error: Error applying IAM policy for project \"projects/[PROJECT_ID]\": Error setting IAM policy for project \"projects/[PROJECT_ID]\": googleapi: Error 400: Service account [NAME]@[PROJECT_ID].iam.gserviceaccount.com does not exist., badRequest

Penyebab

Jika Anda menghapus resource Config Connector IAMServiceAccount sebelum membersihkan resource IAMPolicy,IAMPartialPolicy, dan IAMPolicyMember yang bergantung pada akun layanan tersebut, Config Connector tidak dapat menemukan akun layanan yang direferensikan dalam resource IAM tersebut selama rekonsiliasi.

Resolusi

Untuk mengatasi masalah ini, periksa akun layanan Anda dan lihat apakah akun layanan yang diperlukan untuk resource IAM tersebut telah dihapus. Jika akun layanan dihapus, bersihkan juga resource IAM Config Connector terkait. Untuk IAMPolicyMember, hapus seluruh resource. Untuk IAMPolicy dan IAMParitialPolicy, hanya hapus binding yang melibatkan akun layanan yang dihapus. Namun, pembersihan tersebut tidak langsung menghapus binding peranGoogle Cloud . Binding peran Google Cloud dipertahankan selama 60 hari karena retensi pada akun layanan yang dihapus. Untuk mengetahui informasi selengkapnya, lihat Google Cloud dokumentasi IAM tentang Menghapus akun layanan.

Catatan: Jika Anda mengalami masalah selama penghapusan, Anda mungkin perlu melakukan pembersihan paksa. Jika Anda ingin menghapus binding IAM Google Cloud segera, Anda harus menghapus resource Google Cloud yang mendasarinya secara manual menggunakan gcloud.

Untuk menghindari masalah ini, Anda harus selalu membersihkan resource Config Connector IAMPolicy, IAMPartialPolicy, IAMPolicyMember sebelum menghapus IAMServiceAccount yang direferensikan.

ServiceIdentity resource gagal dengan Invalid service producer

Gejala

Resource ServiceIdentity Anda memiliki status UpdateFailed, dengan pesan error yang mirip dengan berikut ini:

Update call failed: error applying desired state: summary: Error creating Service Identity: Invalid service producer: ...

Penyebab

Error ini berarti resource yang ditentukan tidak mendukung pembuatan identitas layanan on-demand.

Resolusi

Resource ServiceIdentity hanya dapat membuat identitas layanan untuk layanan yang didukung. Untuk memverifikasi apakah layanan mendukung pembuatan identitas layanan on-demand sebelum menerapkan konfigurasi, jalankan perintah berikut:

gcloud beta services identity create --service SERVICE_NAME.googleapis.com

Ganti SERVICE_NAME dengan nama layanan, misalnya spanner.

Jika perintah berhasil, Config Connector dapat membuat identitas untuk layanan tersebut. Jika perintah gagal, berarti Config Connector tidak dapat membuat identitas untuk layanan tersebut.

Penginstalan dan upgrade

Bagian berikut mencantumkan masalah umum terkait penginstalan atau upgrade versi Config Connector.

Versi yang tidak didukung dalam penginstalan add-on Config Connector

Gejala

Jika Anda tidak dapat mengaktifkan add-on Config Connector, pesan error berikut akan muncul: Node version 1.15.x-gke.x s unsupported.

Pesan error juga muncul jika Workload Identity Federation for GKE atau GKE Monitoring dinonaktifkan.

Penyebab

Versi cluster GKE tidak memenuhi persyaratan atau fitur yang diperlukan dinonaktifkan.

Resolusi

Untuk mengatasi error ini, pastikan versi cluster GKE memenuhi persyaratan versi dan fitur. Pastikan Workload Identity Federation untuk GKE dan Pemantauan GKE diaktifkan.

Untuk mendapatkan semua versi yang valid untuk cluster Anda, jalankan perintah berikut:

gcloud container get-server-config --format "yaml(validMasterVersions)" \
    --zone ZONE

Ganti ZONE dengan zona Compute Engine.

Pilih versi dari daftar yang memenuhi persyaratan.

failed calling webhook

Gejala

Anda tidak dapat meng-uninstal Config Connector dan menerima error seperti berikut:

error during reconciliation: error building deployment objects: error finalizing the deletion of Config Connector system components deployed by ConfigConnector controller: error waiting for CRDs to be deleted: error deleting CRD accesscontextmanageraccesslevels.accesscontextmanager.cnrm.cloud.google.com: Internal error occurred: failed calling webhook "abandon-on-uninstall.cnrm.cloud.google.com": failed to call webhook: Post "https://abandon-on-uninstall.cnrm-system.svc:443/abandon-on-uninstall?timeout=3s": service "abandon-on-uninstall" not found

Penyebab

Masalah ini dapat terjadi saat menggunakan add-on Config Connector dan menonaktifkan Config Connector sebelum menghapus CRD Config Connector.

Resolusi

Untuk mengatasi error ini, Anda harus menghapus webhook secara manual terlebih dahulu:

kubectl delete validatingwebhookconfiguration abandon-on-uninstall.cnrm.cloud.google.com --ignore-not-found --wait=true
kubectl delete validatingwebhookconfiguration validating-webhook.cnrm.cloud.google.com --ignore-not-found --wait=true
kubectl delete mutatingwebhookconfiguration mutating-webhook.cnrm.cloud.google.com --ignore-not-found --wait=true

Kemudian, Anda dapat melanjutkan untuk meng-uninstal Config Connector.

PodSecurityPolicy mencegah upgrade

Gejala

Setelah beralih dari add-on Config Connector ke penginstalan manual dan mengupgrade Config Connector ke versi baru, Pod cnrm gagal diupdate.

Penyebab

Penggunaan PodSecurityPolicies dapat mencegah Pod cnrm diupdate.

Untuk mengonfirmasi bahwa PodSecurityPolicies mencegah upgrade Anda, periksa peristiwa config-connector-operator dan cari error yang mirip dengan berikut ini:

create Pod configconnector-operator-0 in StatefulSet configconnector-operator failed error: pods "configconnector-operator-0" is forbidden: PodSecurityPolicy: unable to admit pod: [pod.metadata.annotations[seccomp.security.alpha.kubernetes.io/pod]: Forbidden: seccomp may not be set pod.metadata.annotations[container.seccomp.security.alpha.kubernetes.io/manager]: Forbidden: seccomp may not be set]

Resolusi

Untuk mengatasi masalah ini, Anda harus menentukan anotasi di PodSecurityPolicy yang sesuai dengan anotasi yang disebutkan dalam error. Pada contoh sebelumnya, anotasinya adalah seccomp.security.alpha.kubernetes.io.

Konfigurasi

Bagian berikut mencantumkan masalah umum terkait konfigurasi resource.

Tidak dapat membuat perubahan pada kolom yang tidak dapat diubah

Config Connector menolak update pada kolom yang tidak dapat diubah saat penerimaan.

Misalnya, memperbarui kolom yang tidak dapat diubah dengan kubectl apply akan menyebabkan perintah langsung gagal.

Artinya, alat yang terus-menerus menerapkan ulang resource (misalnya, GitOps) mungkin akan mengalami masalah saat mengupdate resource jika tidak menangani error penerimaan.

Karena Config Connector tidak mengizinkan update pada kolom yang tidak dapat diubah, satu-satunya cara untuk melakukan update tersebut adalah dengan menghapus dan membuat ulang resource.

Error saat memperbarui kolom yang tidak dapat diubah jika tidak ada update

Anda mungkin melihat error berikut dalam status resource Config Connector segera setelah Anda membuat atau mendapatkan resource Google Cloud menggunakan Config Connector:

• Update call failed: error applying desired state: infeasible update: ({true \<nil\>}) would require recreation (contoh)

• Update call failed: cannot make changes to immutable field(s) (contoh)

Hal ini mungkin tidak berarti bahwa Anda benar-benar telah mengupdate resource, tetapi alasannya mungkin karena Google Cloud API telah melakukan perubahan pada kolom yang tidak dapat diubah yang Anda kelola di resource Config Connector. Hal ini menyebabkan ketidakcocokan antara status yang diinginkan dan status aktif kolom yang tidak dapat diubah.

Anda dapat menyelesaikan masalah ini dengan memperbarui nilai kolom yang tidak dapat diubah tersebut di resource Config Connector agar sesuai dengan status aktif. Untuk mencapainya, Anda harus menyelesaikan langkah-langkah berikut:

1. Perbarui konfigurasi YAML resource Config Connector dan tetapkan anotasi cnrm.cloud.google.com/deletion-policy ke abandon.
2. Terapkan konfigurasi YAML yang telah diperbarui untuk mengupdate kebijakan penghapusan resource Config Connector.
3. Abaikan resource Config Connector.
4. Cetak status aktif resource Google Cloud yang sesuai menggunakan gcloud CLI.
5. Temukan ketidakcocokan antara output gcloud CLI dan konfigurasi YAML resource Config Connector, lalu perbarui kolom tersebut dalam konfigurasi YAML.
6. Terapkan konfigurasi YAML yang telah diperbarui untuk memperoleh resource yang ditinggalkan.

Tidak ada kecocokan untuk jenis "Foo"

Gejala

Anda melihat error No matches for kind "Foo".

Penyebab

Cluster Kubernetes Anda belum menginstal CRD untuk jenis resource Foo.

Resolusi

Pastikan jenisnya adalah jenis resource yang didukung oleh Config Connector.

Jika jenisnya didukung, berarti penginstalan Config Connector Anda sudah tidak berlaku atau tidak valid.

Jika Anda menginstal Config Connector menggunakan add-on GKE, penginstalan Anda akan diupgrade secara otomatis. Jika Anda menginstal Config Connector secara manual, Anda harus melakukan upgrade manual.

Periksa repositori GitHub untuk menentukan jenis resource yang didukung oleh versi Config Connector tertentu (misalnya, berikut adalah jenis yang didukung oleh Config Connector v1.44.0).

Label tidak diterapkan ke resource Google Cloud

Gejala

Label di YAML Anda tidak muncul di resource Google Cloud .

Penyebab

Tidak semua Google Cloud resource mendukung label.

Resolusi

Config Connector menyebarkan label yang ditemukan di metadata.labels ke resource Google Cloud yang mendasarinya. Periksa dokumentasi REST API resource (misalnya, dokumentasi API untuk PubSubTopic di sini) untuk melihat apakah resource tersebut mendukung label.

Error karena karakter khusus dalam nama resource

Gejala

Anda melihat error terkait karakter tidak valid di metadata.name:

a lowercase RFC 1123 subdomain must consist of lower case alphanumeric characters, '-' or '.', and must start and end with an alphanumeric character (e.g. 'example.com', regex used for validation is '[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*')

Penyebab

Karakter khusus tidak valid di kolom metadata.name Kubernetes.

Resolusi

Jika Anda ingin memberi nama resource yang bukan nama Kubernetes yang valid, tetapi merupakan nama resource Google Cloud yang valid, Anda dapat menggunakan kolomresourceID, seperti yang ditunjukkan dalam contoh berikut:

apiVersion: sql.cnrm.cloud.google.com/v1beta1
kind: SQLUser
metadata:
  name: 'test'
spec:
  instanceRef:
    name: sqlinstance-sample-postgresql
  host: "%"
  type: CLOUD_IAM_USER
  resourceID: [e-mail]

Konfigurasi ini menyebabkan Config Connector menggunakan resourceID, bukan metadata.name, sebagai nama resource.

Tidak dapat menghapus kolom dari spesifikasi resource

Gejala

Menghapus kolom dari spesifikasi resource Config Connector tidak akan menghapusnya dari resource.

Penyebab

Menghapus kolom dari spesifikasi untuk resource yang dikelola oleh Config Connector tidak akan membuat kolom tersebut kosong atau kembali ke nilai default. Sebagai gantinya, hal ini menyebabkan kolom tersebut menjadi dikelola secara eksternal.

Catatan: Ada satu pengecualian: kolom di dalam daftar. Daftar bersifat atomik, yang berarti Config Connector akan mencoba menetapkan daftar di Google Cloud yang mendasarinya agar setara dengan yang ditentukan dalam spesifikasi.

Resolusi

Jika Anda ingin mengubah nilai kolom menjadi kosong atau default di resourceGoogle Cloud yang mendasarinya, Anda harus mengosongkan kolom tersebut dalam spesifikasi resource Config Connector:

• Untuk kolom jenis daftar, tetapkan kolom ke daftar kosong menggunakan [].

  Contoh berikut menunjukkan kolom targetServiceAccounts yang ingin kita hapus:

  spec:
    targetServiceAccounts:
      - external: "[e-mail]"
      - external: "[e-mail]"
  

  Untuk menghapus kolom ini, tetapkan nilainya ke kosong:

  spec:
    targetServiceAccounts: []
  

• Untuk kolom jenis primitif, tetapkan kolom ke kosong menggunakan salah satu cara berikut:

  Jenis	Nilai kosong
  string	""
  bool	"false"
  integer	0

  Contoh berikut menunjukkan kolom identityNamespace yang ingin kita hapus:

  spec:
    workloadIdentityConfig:
      identityNamespace: "foo-project.svc.id.goog"
  

  Untuk menghapus kolom ini, tetapkan nilai ke kosong:

  spec:
    workloadIdentityConfig:
      identityNamespace: ""
  

• Untuk kolom jenis objek, Anda dapat mencoba menyetel sub-kolom jenis objek menjadi kosong atau default dengan mengikuti panduan di bagian sebelumnya dan memverifikasi apakah berhasil. Namun, hal ini tidak dijamin akan berhasil.

Nilai "merge" tidak valid untuk anotasi state-into-spec

Masalah ini terjadi saat resource menggunakan anotasi cnrm.cloud.google.com/state-into-spec: merge, tetapi jenis resource atau versi Config Connector menolak nilai merge.

Gejala

Resource Config Connector Anda gagal direkonsiliasi dengan pesan error yang mirip dengan berikut ini:

Update call failed: error applying desired state: invalid value "merge" for "cnrm.cloud.google.com/state-into-spec" annotation

Penyebab

Error ini terjadi karena salah satu alasan berikut:

• Jenis resource tidak mendukung perilaku Merge, tetapi resource memiliki anotasi cnrm.cloud.google.com/state-into-spec: merge. Anotasi ini dapat ditetapkan langsung pada resource atau diwarisi dari setelan spec.stateIntoSpec: Merge di CR ConfigConnector atau ConfigConnectorContext Anda. CRD yang ditambahkan di Config Connector versi 1.114.0 dan yang lebih baru hanya mendukung perilaku Absent.
• Anda telah mengupgrade ke Config Connector versi 1.134.0 atau 1.134.1 dan memiliki resource SQLInstance yang sudah ada dan memiliki anotasi cnrm.cloud.google.com/state-into-spec: merge secara default dari versi sebelumnya. Versi 1.134.0 dan 1.134.1 memiliki masalah umum yang menolak nilai merge pada resource SQLInstance.

Resolusi

Untuk mengatasi masalah ini, selesaikan langkah-langkah yang berlaku untuk skenario Anda:

• Jenis resource Anda tidak mendukung perilaku Merge: tetapkan anotasi cnrm.cloud.google.com/state-into-spec: absent dalam manifes YAML resource Anda dan tetapkan kolom spec.stateIntoSpec ke Absent di ConfigConnector atau ConfigConnectorContext CR Anda. Untuk memverifikasi apakah jenis resource Anda mendukung perilaku Merge, lihat Jenis dengan dukungan Merge. Jika anotasi sudah ada di resource yang ada di cluster, ikuti langkah-langkah di Memigrasikan resource dari Merge ke Absent.
• Anda menggunakan resource SQLInstance yang ada di Config Connector versi 1.134.0 atau 1.134.1: upgrade Config Connector ke versi 1.134.2 atau yang lebih baru. Atau, migrasikan resource SQLInstance ke anotasi cnrm.cloud.google.com/state-into-spec: absent dengan mengikuti langkah-langkah di Memigrasikan resource dari Merge ke Absent.

Config Connector gagal dimulai di node berbasis Arm

Jika cluster Anda berisi node pool yang menggunakan arsitektur Arm (seperti seri mesin C4A, N4A, atau Tau T2A), komponen Config Connector mungkin gagal dijalankan. Ini adalah batasan umum karena Config Connector tidak mendukung sistem berbasis Arm.

Gejala

Jika instance Config Connector Anda terpengaruh oleh masalah ini, Anda mungkin mengalami gejala berikut:

• Pod di namespace cnrm-system tetap dalam status Pending.
• Pod dapat menampilkan CrashLoopBackOff dengan pesan error dalam log yang mirip dengan: exec user process caused "exec format error".
• Mendeskripsikan Pod akan mengungkapkan kegagalan penjadwalan atau ketidakcocokan arsitektur.

Resolusi

Untuk mengatasi masalah ini, pastikan komponen Config Connector dijadwalkan pada node dengan arsitektur x86:

• Tambahkan node pool x86: Jika cluster Anda hanya berisi node Arm, tambahkan setidaknya satu node pool menggunakan jenis mesin x86 (seperti e2-standard-2) untuk menghosting Pod pengontrol Config Connector.
• Verifikasi taint node: Node GKE Arm biasanya di-taint dengan kubernetes.io/arch=arm64:NoSchedule untuk mencegah workload khusus x86 dijadwalkan di node tersebut. Pastikan Anda belum menambahkan toleransi ke deployment Config Connector yang akan memungkinkannya berjalan di node ini.

Pembersihan paksa

Jika resource Config Connector Anda macet saat dihapus dan Anda hanya ingin menghapusnya dari cluster Kubernetes, Anda dapat menghapusnya secara paksa dengan menghapus finalizer-nya.

Peringatan: Operasi ini harus dilakukan sebagai upaya terakhir karena penghapusan finalizer berada di luar batas penggunaan normal untuk Config Connector dan dapat memiliki konsekuensi yang tidak diinginkan. Secara khusus, tidak ada jaminan terkait apa yang terjadi pada resource Google Cloud yang mendasarinya.

Anda dapat menghapus finalizer resource dengan mengedit resource menggunakan kubectl edit, menghapus kolom metadata.finalizers, lalu menyimpan file untuk mempertahankan perubahan Anda pada Server API Kubernetes.

Karena menghapus finalizer resource memungkinkan resource segera dihapus dari cluster Kubernetes, Config Connector mungkin (tetapi tidak selalu) tidak sempat menyelesaikan penghapusan resourceGoogle Cloud yang mendasarinya. Artinya, Anda mungkin ingin menghapus resource Google Cloud secara manual setelahnya.

Pemantauan

Memantau Config Connector dan menjelajahi log-nya dapat membantu Anda menentukan sumber masalah dan lebih memahami perilaku yang tidak terduga.

Metrik

Anda dapat menggunakan Prometheus untuk mengumpulkan dan menampilkan metrik dari Config Connector.

Logging

Semua Pod Config Connector menghasilkan log terstruktur dalam format JSON.

Log Pod pengontrol sangat berguna untuk men-debug masalah terkait rekonsiliasi resource.

Anda dapat membuat kueri untuk log resource tertentu dengan memfilter kolom berikut dalam pesan log:

• logger: berisi jenis resource dalam huruf kecil. Misalnya, resource PubSubTopic memiliki logger pubsubtopic-controller.
• resource.namespace: berisi namespace resource.
• resource.name: berisi nama resource.

Menggunakan Logging untuk kueri log lanjutan

Jika menggunakan GKE, Anda dapat menggunakan Cloud Logging untuk membuat kueri log untuk resource tertentu dengan kueri berikut:

Catatan: Sintaksis kueri tidak mendukung komentar. Kueri berikut menggunakan konvensi pemberian komentar, # komentar, untuk memberikan teks penjelasan, tetapi komentar ini tidak dapat disertakan dalam kueri.

# Filter to include only logs coming from the controller Pods
resource.type="k8s_container"
resource.labels.container_name="manager"
resource.labels.namespace_name="cnrm-system"
labels.k8s-pod/cnrm_cloud_google_com/component="cnrm-controller-manager"

# Filter to include only logs coming from a particular GKE cluster
resource.labels.cluster_name="GKE_CLUSTER_NAME"
resource.labels.location="GKE_CLUSTER_LOCATION"

# Filter to include only logs for a particular Config Connector resource
jsonPayload.logger="RESOURCE_KIND-controller"
jsonPayload.resource.namespace="RESOURCE_NAMESPACE"
jsonPayload.resource.name="RESOURCE_NAME"

Ganti kode berikut:

• GKE_CLUSTER_NAME dengan nama cluster GKE yang menjalankan Config Connector
• GKE_CLUSTER_LOCATION dengan lokasi cluster GKE yang menjalankan Config Connector. Contoh, us-central1.
• RESOURCE_KIND dengan jenis resource dalam huruf kecil. Misalnya, pubsubtopic.
• RESOURCE_NAMESPACE dengan namespace resource.
• RESOURCE_NAME dengan nama resource.

Bantuan tambahan

Untuk mendapatkan bantuan tambahan, Anda dapat melaporkan masalah di GitHub atau menghubungi DukunganGoogle Cloud .