Fehlerbehebung bei der Synchronisierung von Konfigurationen mit Ihrem Cluster

Auf dieser Seite erfahren Sie, wie Sie Probleme beim Synchronisieren von Konfigurationen mit Ihrem Cluster beheben.

KNV 2009-Fehler beheben

KNV2009-Fehler geben an, dass Config Sync einige Konfigurationen nicht mit dem Cluster synchronisieren konnte. In den folgenden Abschnitten werden einige der häufigsten Ursachen erläutert und ihre Behebung erklärt.

Vorgang für bestimmte Ressourcen ist verboten

Da Sie RepoSync-Objekten ihre RBAC gewähren müssen, fehlen möglicherweise die Berechtigungen, die zum Anwenden von Ressourcen erforderlich sind.

Sie können überprüfen, ob die Berechtigungen fehlen, indem Sie den RepoSync-Ressourcenstatus abrufen:

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

Ersetzen Sie NAMESPACE durch den Namespace, in dem Sie Ihr Namespace-Repository erstellt haben.

Sie können auch den Befehl nomos status verwenden:

Wenn die folgenden Nachrichten im Status angezeigt werden, bedeutet das, dass der Abgleicher in NAMESPACE nicht berechtigt ist, die Ressource anzuwenden:

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"

Um dieses Problem zu beheben, müssen Sie eine RoleBinding-Konfiguration deklarieren, die dem Dienstkonto für den Abgleicher die Berechtigung erteilt, die fehlerhafte Ressource in diesem Namespace zu verwalten. Weitere Informationen zum Hinzufügen eines RoleBinding finden Sie unter Synchronisierung aus mehreren Repositories konfigurieren.

Dieses Problem kann sich auch auf RootSync-Objekte auswirken, wenn Sie spec.override.roleRefs verwendet haben, um die Rollen zu ändern, die dem RootSync-Objekt zugewiesen sind. Wenn Sie dieses Feld nicht festgelegt haben, wird RootSync-Objekten standardmäßig die Rolle cluster-admin zugewiesen.

ResourceGroup-Objekt überschreitet die Objektgröße von etcd

Wenn der folgende Fehler angezeigt wird, wenn ein Abgleicher versucht, Konfigurationen auf den Cluster anzuwenden, überschreitet das ResourceGroup-Objekt das Limit der Objektgröße von 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.

Wir empfehlen, das Git-Repository in mehrere Repositories aufzuteilen. Wenn Sie das Git-Repository nicht aufteilen können, da das Objekt bereits zu groß ist und Änderungen nicht beibehalten werden, können Sie dies umgehen. Konfigurieren Sie dazu RootSync oder RepoSync so, dass das Schreiben des Objektstatus in die ResourceGroup vorübergehend deaktiviert wird. Dazu legen Sie das Feld .spec.override.statusMode des RootSync- oder RepoSync-Objekts auf disabled fest. Dadurch aktualisiert Config Sync den Status der verwalteten Ressourcen im ResourceGroup-Objekt. Dadurch wird die Größe des ResourceGroup-Objekts reduziert. Sie können den Status für verwaltete Ressourcen jedoch nicht von nomos status aufrufen.

Wenn kein Fehler vom RootSync- oder RepoSync-Objekt angezeigt wird, wurden die Objekte aus Ihrer „Source of Truth“ mit dem Cluster synchronisiert. Um zu prüfen, ob die Ressource vom Typ „ResourceGroup“ das etcd-Objektgrößenlimit überschreitet, prüfen Sie sowohl den Ressourcenstatus der ResourceGroup als auch das Log des ResourceGroup-Controllers:

  1. Prüfen Sie den Status der ResourceGroup:

    • Führen Sie zum Prüfen des RootSync-Objekts den folgenden Befehl aus:

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

    • Führen Sie zum Prüfen des RepoSync-Objekts den folgenden Befehl aus:

      kubectl get resourcegroup repo-sync -n NAMESPACE

      Ersetzen Sie NAMESPACE durch den Namespace, in dem Sie Ihr Namespace-Repository erstellt haben.

    Die Ausgabe sieht etwa so aus wie im folgenden Beispiel.

    NAME        RECONCILING   STALLED   AGE
root-sync   True          False     35m

    Wenn der Wert in der Spalte RECONCILING True lautet, bedeutet dies, dass die Ressource vom Typ "ResourceGroup" noch abgeglichen wird.

  2. Prüfen Sie die Logs für den ResourceGroup-Controller:

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

    Wenn in der Ausgabe ein Fehler wie im folgenden Beispiel angezeigt wird, ist die Ressource "ResourceGroup" zu groß und überschreitet das Limit der Objektgröße von etcd:

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

Verringern Sie die Anzahl der Ressourcen im Git-Repository, um zu verhindern, dass die ResourceGroup zu groß wird. Sie können ein Stamm-Repository in mehrere Stamm-Repositories aufteilen.

Zeitüberschreitung bei der Anwendung von Abhängigkeiten für Abgleich

Wenn Sie Objekte mit Abhängigkeiten synchronisiert haben, erhalten Sie möglicherweise eine Fehlermeldung ähnlich dem folgenden Beispiel, wenn der Abgleicher versucht, Objekte mit der Annotation config.kubernetes.io/depends-on auf den Cluster anzuwenden:

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

Dieser Fehler bedeutet, dass das Abhängigkeitsobjekt nicht innerhalb des Standardabgleichzeitlimits von 5 Minuten abgeglichen wurde. Config Sync kann das abhängige Objekt nicht anwenden, da Config Sync mit der Annotation config.kubernetes.io/depends-on nur Objekte in der gewünschten Reihenfolge anwendet. Sie können das Standardzeitlimit für den Abgleich über einen längeren Zeitraum überschreiben, indem Sie spec.override.reconcileTimeout festlegen.

Es ist auch möglich, dass die Abhängigkeit nach dem ersten Synchronisierungsversuch abgeglichen wird. In diesem Fall sollte die Abhängigkeit beim nächsten Synchronisierungsversuch als abgeglichen erkannt werden, wodurch die Anwendung aller abhängigen Elemente freigegeben wird. In diesem Fall wird der Fehler möglicherweise kurz gemeldet und dann entfernt. Wenn Sie das Zeitlimit für den Abgleich verlängern, kann das dazu beitragen, dass der Fehler nicht mehr sporadisch gemeldet wird.

Inventarinformationen sind null

Wenn Sie den folgenden Fehler erhalten, wenn der Abgleicher versucht, Konfigurationen auf den Cluster anzuwenden, ist es wahrscheinlich, dass Ihr Inventar keine Ressourcen hat oder das Manifest eine nicht verwaltete Annotation hat:

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

Versuchen Sie Folgendes, um dieses Problem zu beheben:

  1. Richten Sie keine Synchronisierungen ein, bei denen alle Ressourcen die Annotation configmanagement.gke.io/managed: disabled haben. Achten Sie dazu darauf, dass mindestens eine Ressource von Config Sync verwaltet wird.
  2. Fügen Sie die Annotation configmanagement.gke.io/managed: disabled erst hinzu, wenn Sie eine erste Synchronisierung der Ressource ohne diese Annotation abgeschlossen haben.

Mehrere Vorlagen für Inventarobjekte

Wenn Sie den folgenden Fehler erhalten, wenn der Abgleicher versucht, Konfigurationen auf den Cluster anzuwenden, haben Sie wahrscheinlich eine von kpt generierte Inventarkonfiguration in der Source of Truth, z. B. einem Git-Repository:

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

Das Problem tritt auf, weil Config Sync seine eigene Inventarkonfiguration verwaltet. Löschen Sie die Inventarkonfiguration in Ihrer „Source of Truth“, um dieses Problem zu beheben.

Unveränderliche Felder können nicht geändert werden

Sie können kein unveränderliches Feld in einer Konfiguration ändern, indem Sie den Wert in der Quelle der Wahrheit ändern. Bei einem entsprechenden Versuch wird ein Fehler wie der folgende ausgegeben:

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):

Wenn Sie ein unveränderliches Feld ändern müssen, löschen Sie das Objekt aus Ihrer „Source of Truth“, warten Sie, bis Config Sync das Objekt aus dem Cluster gelöscht hat, und erstellen Sie das Objekt dann mit Ihren Änderungen in Ihrer „Source of Truth“ neu.

Fehler beim Abrufen des Status

Sie können Config Sync autorisieren, Ressourcen in einem Namespace mit einem RepoSync-Objekt zu verwalten. Wenn für diesen Typ von RepoSync-Objekt ein RoleBinding-Objekt verwendet wird, das auf ein benutzerdefiniertes ClusterRole oder Role verweist, erhalten Sie möglicherweise die folgende Fehlermeldung vom Reconciler-Deployment:

KNV2009: polling for status failed: unknown

Damit dieses Problem behoben wird, müssen Ihre ClusterRole- und Role-Objekte für jede Ressource, die vom RepoSync-Objekt verwaltet wird, mindestens die folgenden Berechtigungen haben:

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

Eine Anleitung zum Hinzufügen dieser Berechtigungen finden Sie unter RoleBinding erstellen.

API-Suche fehlgeschlagen

Wenn Sie eine Fehlermeldung wie die folgende erhalten, liegt möglicherweise ein API-Erkennungsfehler vor:

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 verwendet die Kubernetes API-Erkennung, um herauszufinden, welche Ressourcen vom Cluster unterstützt werden. So kann Config Sync die in Ihrer Quelle angegebenen Ressourcentypen validieren und diese Ressourcen auf Änderungen im Cluster überwachen.

Vor Kubernetes Version 1.28 schlug die API-Erkennung fehl, wenn ein APIService-Backend fehlerhaft war oder ein leeres Ergebnis zurückgab. Dies führte zu Fehlern in Config Sync und mehreren anderen Kubernetes-Komponenten. Viele gängige APIService-Back-Ends sind nicht hochverfügbar. Daher kann dies relativ häufig passieren, z. B. wenn das Back-End aktualisiert oder auf einem anderen Knoten neu geplant wird.

Beispiele für APIService-Back-Ends mit einem einzelnen Replikat sind metrics-server und custom-metrics-stackdriver-adapter. Einige APIService-Back-Ends geben immer leere Ergebnislisten zurück, z. B. custom-metrics-stackdriver-adapter. Eine weitere häufige Ursache für Fehler bei der API-Erkennung sind fehlerhafte Webhooks.

Ab Kubernetes Version 1.28 mit aktivierter Aggregated Discovery-Funktion verursacht ein fehlerhaftes APIService-Backend keine unbehandelten Fehler mehr. Stattdessen wird für die von diesem APIService verwaltete Ressourcengruppe angezeigt, dass sie keine Ressourcen enthält. So kann die Synchronisierung fortgesetzt werden, solange die fehlerhafte Ressource nicht in Ihrer Quelle angegeben ist.

Verzögerte automatische Reparatur

Die Selbstreparatur überwacht verwaltete Ressourcen, erkennt eine Abweichung von der "Source of Truth" und macht diese Abweichung rückgängig.

Die automatische Reparatur wird pausiert, während die Synchronisierung versucht wird. Das bedeutet, dass die automatische Reparatur verzögert werden kann, insbesondere wenn Synchronisierungsfehler auftreten, die den Abschluss des Abgleichs verhindern. Um die automatische Reparatur wieder zu aktivieren, müssen Sie alle gemeldeten Synchronisierungsfehler beheben.

Hohe Anzahl von Kubernetes API-Anfragen

Config Sync verwendet eine Mehr-Instanz-Strategie, um Mandanten und Fehlerdomains zu skalieren und zu isolieren. Aus diesem Grund erhält jede RootSync und RepoSync eine eigene Abgleichsinstanz. Neben der Synchronisierung bei jeder Änderung der Quelle wird jede Abgleichsinstanz im Rahmen ihres Self-Healing-Verhaltens auch regelmäßig synchronisiert, um alle Änderungen rückgängig zu machen, die bei der aktiven Driftkorrektur übersehen wurden. Wenn Sie RootSync- oder RepoSync-Objekte hinzufügen, führt dies zu einem linearen Anstieg der Anzahl der API-Anfragen, die von den Abgleichern zum Synchronisieren von Ressourcen mit Kubernetes gestellt werden. Wenn Sie also viele RootSync- und RepoSync-Objekte haben, kann dies manchmal zu einer erheblichen Traffic-Last für die Kubernetes API führen.

Für die Synchronisierung verwendet Config Sync Server-Side Apply. Dadurch wird der normale GET- und PATCH-Anfragefluss durch eine einzelne PATCH-Anfrage ersetzt. Die Gesamtzahl der API-Aufrufe wird reduziert, die Anzahl der PATCH-Aufrufe jedoch erhöht. Dadurch sind die vorgenommenen Änderungen auch dann korrekt, wenn die Version der Ressourcengruppe in der Quelle nicht mit der Standardversion der Ressourcengruppe im Cluster übereinstimmt. Möglicherweise werden jedoch PATCH-Anfragen im Audit-Log angezeigt, selbst wenn es keine Änderung an der Quelle oder eine Abweichung vom gewünschten Status gegeben hat. Das ist normal, kann aber überraschend sein.

Wenn bei der Synchronisierung ein Fehler auftritt, wird sie so lange wiederholt, bis sie erfolgreich ist. Wenn dies jedoch menschliche Interaktion erfordert, kann Config Sync einen Fehler machen und eine Weile noch einmal versuchen, wodurch die Anzahl der Anfragen an die Kubernetes API erhöht wird. Die Wiederholungsversuche werden exponentiell zurückgefahren. Wenn jedoch viele RootSync- oder RepoSync-Objekte gleichzeitig nicht synchronisiert werden können, kann dies zu einer erheblichen Traffic-Belastung der Kubernetes API führen.

Versuchen Sie Folgendes, um diese Probleme zu beheben:

  • Beheben Sie Konfigurationsfehler schnell, damit sie sich nicht häufen.
  • Kombinieren Sie mehrere RootSync- oder RepoSync-Objekte, um die Anzahl der Abgleichsfunktionen zu reduzieren, die Kubernetes API-Anfragen stellen.

Deinstallation von KubeVirt durch Finalizer blockiert

KubeVirt ist ein Kubernetes-Paket, das mehrere Finalizer verwendet. Für die Bereinigung ist daher eine genaue Löschreihenfolge erforderlich. Wenn die KubeVirt-Objekte in der falschen Reihenfolge gelöscht werden, kann das Löschen anderer KubeVirt-Objekte ins Stocken geraten oder die Reaktion kann auf unbestimmte Zeit ausbleiben.

Wenn Sie versucht haben, KubeVirt zu deinstallieren, und der Vorgang blockiert wurde, folgen Sie der Anleitung zum manuellen Löschen von KubeVirt.

Um dieses Problem in Zukunft zu vermeiden, sollten Sie Abhängigkeiten zwischen Ressourcenobjekten deklarieren, damit sie in umgekehrter Abhängigkeitsreihenfolge gelöscht werden.

Löschen von Objekten durch Finalizer blockiert

Kubernetes-Finalizer sind Metadateneinträge, die Kubernetes anweisen, das Entfernen eines Objekts erst zuzulassen, nachdem ein bestimmter Controller die Bereinigung durchgeführt hat. Dies kann dazu führen, dass die Synchronisierung oder der Abgleich fehlschlägt, wenn die Bedingungen für die Bereinigung nicht erfüllt sind oder der Controller, der die Bereinigung für diese Ressource durchführt, fehlerhaft ist oder gelöscht wurde.

Um dieses Problem zu beheben, müssen Sie herausfinden, welche Ressource noch finalisiert wird und welcher Controller die Bereinigung durchführen sollte.

Wenn der Controller fehlerhaft ist, sollte die Behebung der Ursache es ermöglichen, die Bereinigung der Ressourcen abzuschließen und die Entfernung des Objekts freizugeben.

Wenn der Controller fehlerfrei ist, sollte er dem zu löschenden Objekt eine Statusbedingung zugewiesen haben, um zu erklären, warum die Bereinigung ins Stocken geraten ist. Prüfen Sie andernfalls die Controller-Logs auf Hinweise zur Ursache.

Wenn ein Objekt beim Löschen hängen bleibt, ist das oft ein Hinweis darauf, dass Objekte in der falschen Reihenfolge gelöscht wurden. Um diese Art von Problem in Zukunft zu vermeiden, deklarieren Sie Abhängigkeiten zwischen Ressourcenobjekten, damit sie in umgekehrter Abhängigkeitsreihenfolge gelöscht werden.

ResourceGroup-Felder ändern sich ständig

Beim Synchronisierungsversuch wird das Inventar so aktualisiert, dass der Ressourcenstatus in „Ausstehend“ geändert wird. Wenn die Synchronisierung fehlschlägt, wird das Inventar aktualisiert, um den Ressourcenstatus auf „Fehlgeschlagen“ zu ändern. Wenn die Synchronisierung nach einem Fehler erneut versucht wird, wiederholt sich dieses Muster und führt zu regelmäßigen Aktualisierungen des Inventars. Dadurch erhöht sich die ResourceGroup resourceVersion mit jeder Aktualisierung und der Synchronisierungsstatus ändert sich ständig. Das ist normal, kann aber überraschend sein.

Ein Synchronisierungsfehler kann verschiedene Ursachen haben. Eines der häufigsten sind unzureichende Berechtigungen zum Verwalten der in der Quelle angegebenen Ressourcen. Um diesen Fehler zu beheben, fügen Sie die entsprechenden RoleBindings oder ClusterRoleBinding hinzu, um dem RepoSync- oder RootSync-Abstimmer die Berechtigung zum Verwalten der Ressourcen zu erteilen, die nicht synchronisiert werden können.

Beim Server-seitigem Anwenden werden Felder, die nicht in der Quelle angegeben sind, nicht entfernt oder rückgängig gemacht.

Config Sync verwendet Server-Side Apply, um Manifeste aus der Quelle auf Kubernetes anzuwenden. Dies ist erforderlich, damit andere Controller die Felder metadata und spec verwalten können. Ein Beispiel hierfür ist das horizontale Pod-Autoscaling, das die Anzahl der Replikate in einem Deployment aktualisiert. Aus diesem Grund verwaltet Config Sync nur Felder, die im Quellmanifest angegeben sind. Dies hat den Nebeneffekt, dass beim Übernehmen vorhandener Ressourcenobjekte alle Felder, die in der Quelle nicht angegeben sind, nicht geändert werden. Das kann manchmal dazu führen, dass die zusammengeführte Konfiguration ungültig oder falsch ist.

Um dieses Problem bei der Übernahme einer Ressource zu vermeiden, verwenden Sie bei der ersten Übernahme genau dieselben Felder in der Quelle und ändern Sie die Felder in der Quelle nach der Synchronisierung, damit Config Sync die zuvor angewendeten Felder korrekt entfernt und durch die neuen Felder aus der Quelle ersetzt. Eine weitere Möglichkeit, dieses Problem zu vermeiden, besteht darin, die Ressource zuerst aus dem Cluster zu löschen und Config Sync die neue Version anwenden zu lassen.

Config Sync behält beim Übernehmen von Objekten keine Felder aus kubectl-Client-Side Apply bei

Da Config Sync Server-Side Apply verwendet, werden beim Übernehmen eines Objekts, das ursprünglich mit kubectl Client-Side Apply erstellt wurde, alle Felder zurückgesetzt, die mit Client-Side Apply festgelegt, aber nicht in der Quelle deklariert wurden.

Wenn Sie möchten, dass diese Felder beibehalten werden, verwenden Sie bei der ersten Übernahme des Objekts genau dieselben Felder in der Quelle oder erstellen Sie das Objekt mit Server-Side Apply.

Nächste Schritte

  • Wenn weiterhin Probleme auftreten, sieh nach, ob dein Problem ein bekanntes Problem ist.

  • Wenn Sie in der Dokumentation keine Lösung für Ihr Problem finden, lesen Sie den Abschnitt Support erhalten. Dort finden Sie weitere Informationen, unter anderem zu den folgenden Themen: