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.

KNV2009-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 und Möglichkeiten zur Behebung dieser Fehler erläutert.

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 gewährt wurden. Wenn Sie dieses Feld nicht festgelegt haben, wird RootSync-Objekten standardmäßig die Rolle cluster-admin gewährt.

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

Wenn Sie den folgenden Fehler erhalten, wenn ein Abgleicher versucht, Konfigurationen auf den Cluster anzuwenden, überschreitet das ResourceGroup-Objekt das Limit für die 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 setzen Sie das Feld .spec.override.statusMode des RootSync- oder RepoSync-Objekts auf disabled. Dadurch aktualisiert Config Sync den Status der verwalteten Ressourcen im ResourceGroup-Objekt. Diese Aktion reduziert die Größe des ResourceGroup-Objekts. Sie können den Status für verwaltete Ressourcen jedoch nicht über 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 Limit für die Objektgröße von etcd ü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 ist, 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 für die 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 Abschluss des ersten Synchronisierungsversuchs abgeglichen wird. In diesem Fall sollte die Abhängigkeit beim nächsten Synchronisierungsversuch als abgeglichen erkannt werden, wodurch die Anwendung aller abhängigen Objekte freigegeben wird. Wenn dies geschieht, wird der Fehler möglicherweise kurz gemeldet und dann entfernt. Wenn Sie das Zeitlimit für den Abgleich verlängern, kann es helfen, zu vermeiden, dass der Fehler zeitweise 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 Inventarobjektvorlagen

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.

Änderungen an unveränderlichen Feldern nicht möglich

Sie können kein unveränderliches Feld in einer Konfiguration ändern, indem Sie den Wert in der „Source of Truth“ ändern. Bei einem solchen Versuch wird ein Fehler ähnlich dem folgenden 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 Aktualisierungen in Ihrer „Source of Truth“ neu.

Polling für Status fehlgeschlagen

Sie können Config Sync autorisieren, Ressourcen in einem Namespace mit einem RepoSync-Objekt zu verwalten. Wenn diese Art von RepoSync Objekt ein RoleBinding Objekt verwendet, das auf eine benutzerdefinierte ClusterRole oder Role verweist, erhalten Sie möglicherweise die folgende Fehlermeldung vom Abgleicher-Deployment:

KNV2009: polling for status failed: unknown

Achten Sie darauf, dass Ihre ClusterRole und Role Objekte mindestens die folgenden Berechtigungen für jede Ressource haben, die vom RepoSync Objekt verwaltet wird, um dieses Problem zu beheben:

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

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

API-Erkennung fehlgeschlagen

Wenn Sie eine Fehlermeldung ähnlich der folgenden sehen, 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 zu ermitteln, 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 eine leere Liste zurückgab. Dies führte zu Fehlern in Config Sync und mehreren anderen Kubernetes-Komponenten. Viele gängige APIService-Backends sind nicht hochverfügbar. Daher kann dies relativ häufig vorkommen, z. B. wenn das Backend aktualisiert oder auf einem anderen Knoten neu geplant wird.

Beispiele für APIService-Backends mit einem einzelnen Replikat sind metrics-server und custom-metrics-stackdriver-adapter. Einige APIService-Backends geben immer leere Listen 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 Selbstreparatur

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

Die Selbstreparatur wird während des Synchronisierungsversuchs pausiert. Das bedeutet, dass sich die Selbstreparatur verzögern kann, insbesondere wenn Synchronisierungsfehler auftreten, die den Abgleicher daran hindern, den Vorgang abzuschließen. Beheben Sie alle gemeldeten Synchronisierungsfehler, um die Selbstreparatur wieder zu aktivieren.

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 jedes RootSync- und RepoSync-Objekt eine eigene Abgleicherinstanz. Neben der Synchronisierung bei jeder Änderung der Quelle wird jede Abgleicherinstanz auch regelmäßig im Rahmen der Selbstreparatur synchronisiert, um alle Änderungen rückgängig zu machen, die bei der aktiven Abweichungsbehebung übersehen wurden. Wenn Sie RootSync- oder RepoSync-Objekte hinzufügen, steigt die Anzahl der API-Anfragen, die von den Abgleichern gesendet werden, die Ressourcen mit Kubernetes synchronisieren, linear an. Wenn Sie also viele RootSync- und RepoSync-Objekte haben, kann dies manchmal zu einer erheblichen Trafficlast auf der Kubernetes API führen.

Für die Synchronisierung verwendet Config Sync die serverseitige Anwendung. Dadurch wird der normale GET- und PATCH-Anfragefluss durch eine einzelne PATCH-Anfrage ersetzt, wodurch die Gesamtzahl der API-Aufrufe reduziert, aber die Anzahl der PATCH-Aufrufe erhöht wird. 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 Wiederholungen werden exponentiell zurückgefahren. Wenn jedoch viele RootSync- oder RepoSync-Objekte gleichzeitig nicht synchronisiert werden können, kann dies zu einer erheblichen Trafficlast auf der Kubernetes API führen.

Versuchen Sie Folgendes, um diese Probleme zu beheben:

  • Beheben Sie Konfigurationsfehler schnell, damit sie sich nicht ansammeln.
  • Kombinieren Sie mehrere RootSync- oder RepoSync-Objekte, um die Anzahl der Abgleicher zu reduzieren, die Kubernetes API-Anfragen senden.

Deinstallation von KubeVirt durch Finalizer blockiert

KubeVirt ist ein Kubernetes-Paket, das mehrere Finalizer verwendet. Daher ist eine genaue Reihenfolge beim Löschen erforderlich, um die Bereinigung zu erleichtern. Wenn die KubeVirt-Objekte in der falschen Reihenfolge gelöscht werden, kann die Löschung anderer KubeVirt-Objekte auf unbestimmte Zeit verzögert werden oder nicht mehr reagieren.

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

Um dieses Problem in Zukunft zu vermeiden, deklarieren Sie Abhängigkeiten zwischen Ressourcenobjekten 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, ermitteln Sie, 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 hinzugefügt haben, in der erläutert wird, warum die Bereinigung verzögert wurde. Prüfen Sie andernfalls die Controllerlogs 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 resourceVersion der ResourceGroup mit jeder Aktualisierung und der Synchronisierungsstatus wechselt hin und her. 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-Abgleicher die Berechtigung zum Verwalten der Ressourcen zu erteilen, die nicht synchronisiert werden können.

Config Sync entfernt oder macht keine Felder rückgängig, die nicht in der Quelle angegeben sind

Config Sync verwendet die serverseitige Anwendung , um Manifeste aus der Quelle auf Kubernetes anzuwenden. Dies ist erforderlich, damit andere Controller die Felder metadata und spec verwalten können. Ein Beispiel dafü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 bei der Übernahme 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 der clientseitigen Anwendung von kubectl bei

Da Config Sync die serverseitige Anwendung verwendet, werden beim Übernehmen eines Objekts, das ursprünglich mit der clientseitigen Anwendung von kubectl erstellt wurde, alle Felder entfernt, die mit der clientseitigen Anwendung festgelegt, aber nicht in der Quelle deklariert wurden.

Wenn diese Felder beibehalten werden sollen, verwenden Sie bei der ersten Übernahme des Objekts genau dieselben Felder in der Quelle, wenn Sie das Objekt erstmalig übernehmen, oder erstellen Sie das Objekt mit der serverseitigen Anwendung.

Nächste Schritte

  • Wenn weiterhin Probleme auftreten, prüfen Sie, ob Ihr Problem ein bekanntes Problem ist.

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