Auf dieser Seite erfahren Sie, wie Sie Probleme bei der Synchronisierung von Konfigurationen mit Ihrem Cluster beheben.
KNV2009-Fehler beheben
Die Fehler KNV2009 geben an, dass Config Sync einige Konfigurationen nicht mit dem Cluster synchronisieren konnte. In den folgenden Abschnitten werden einige der häufigsten Ursachen und deren Behebung erläutert.
Der Vorgang für bestimmte Ressourcen ist unzulässig
Da Sie RepoSync-Objekten die RBAC zuweisen müssen, fehlen möglicherweise die Berechtigungen zum Anwenden von Ressourcen.
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 mit spec.override.roleRefs die dem Objekt RootSync zugewiesenen Rollen geändert haben. 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 ein Abgleicher versucht, Konfigurationen auf den Cluster anzuwenden, und folgender Fehler angezeigt wird, ü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. Setzen Sie dazu das Feld .spec.override.statusMode des RootSync- oder RepoSync-Objekts auf disabled. 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 weder von nomos status noch von gcloud alpha anthos config sync 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:
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-systemFühren Sie zum Prüfen des
RepoSync-Objekts den folgenden Befehl aus:kubectl get resourcegroup repo-sync -n NAMESPACEErsetzen Sie
NAMESPACEdurch 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 35mWenn der Wert in der Spalte
RECONCILINGTruelautet, bedeutet dies, dass die Ressource vom Typ "ResourceGroup" noch abgeglichen wird.Prüfen Sie die Logs für den ResourceGroup-Controller:
kubectl logs deployment resource-group-controller-manager -c manager -n resource-group-systemWenn 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 Abschluss des ersten Synchronisierungsversuchs abgeglichen wird. In diesem Fall sollte die Abhängigkeit beim nächsten Synchronisierungsversuch abgeglichen werden, um die Blockierung der Anwendung von Abhängigkeiten aufzuheben. In diesem Fall wird der Fehler möglicherweise kurz gemeldet und dann entfernt. Durch eine Verlängerung der Abgleichzeitüberschreitung kann verhindert werden, dass der Fehler periodisch 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:
- Richten Sie keine Synchronisierungen ein, bei denen alle Ressourcen die Annotation
configmanagement.gke.io/managed: disabledhaben. Achten Sie dazu darauf, dass mindestens eine Ressource von Config Sync verwaltet wird. - Fügen Sie die Annotation
configmanagement.gke.io/managed: disablederst 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 Inventarkonfiguration, die von kpt in der "Source of Truth" generiert wurde, z. B. ein 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.
Keine Änderungen an unveränderlichen Feldern möglich
Sie können ein unveränderliches Feld in einer Konfiguration nicht ändern, indem Sie den Wert in der "Source of Truth" ändern. Bei dem Versuch, eine solche Änderung vorzunehmen, tritt ein Fehler wie der folgende auf:
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 aktualisieren müssen, löschen Sie das Objekt manuell im Cluster. Config Sync kann das Objekt dann mit dem neuen Feldwert neu erstellen.
API-Erkennung fehlgeschlagen
Wenn eine Fehlermeldung ähnlich der folgenden angezeigt wird, ist möglicherweise ein API-Erkennungsfehler aufgetreten:
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. Dadurch kann Config Sync die in Ihrer Quelle angegebenen Ressourcentypen validieren und diese Ressourcen auf Änderungen im Cluster überwachen.
Vor Kubernetes Version 1.28 schlug API Discovery fehl, wenn ein APIService-Backend fehlerhaft war oder ein leeres Listenergebnis zurückgegeben wurde. Dies führte zu einem Fehler bei Config Sync und mehreren anderen Kubernetes-Komponenten. Viele gängige APIService-Back-Ends sind nicht hochverfügbar, sodass dies relativ häufig geschehen kann, indem Sie einfach das Back-End aktualisieren oder auf einen anderen Knoten neu planen.
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 Listenergebnisse zurück, z. B. custom-metrics-stackdriver-adapter. Eine weitere häufige Ursache für einen 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 angezeigt, dass die von diesem APIService verarbeitete Ressourcengruppe keine Ressourcen enthält. Auf diese Weise kann die Synchronisierung fortgesetzt werden, solange die fehlerhafte Ressource nicht in der 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 ist während des Synchronisierungsversuchs pausiert. Dieses Verhalten bedeutet, dass die Selbstreparatur verzögert sein kann, insbesondere wenn Synchronisierungsfehler den Abschluss des Abgleichs verhindern. Beheben Sie alle gemeldeten Synchronisierungsfehler, um die Selbstreparatur wieder zu aktivieren.
Hohe Anzahl von Kubernetes API-Anfragen
Config Sync verwendet eine Mehrinstanzstrategie, um Mandanten und Fehlerdomains zu skalieren und zu isolieren. Aus diesem Grund erhält jeder RootSync und RepoSync eine eigene Abgleicherinstanz. Zusätzlich zur Synchronisierung bei jeder Änderung an der Quelle wird jede Reconciler-Instanz auch regelmäßig als Teil ihrer Selbstreparatur synchronisiert, um Änderungen rückgängig zu machen, die bei der aktiven Drift-Abhilfe verpasst wurden. Wenn Sie RootSync- oder RepoSync-Objekte hinzufügen, erhöht sich die Anzahl der API-Anfragen der Abgleicher, die Ressourcen mit Kubernetes synchronisieren, linear. Wenn Sie also viele RootSync- und RepoSync-Objekte haben, kann dies manchmal zu einer erheblichen Trafficlast für die Kubernetes API führen.
Für die Synchronisierung verwendet Config Sync Server-Side Apply. Dies ersetzt den normalen GET- und PATCH-Anfrageablauf durch eine einzelne PATCH-Anfrage, 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 eine Synchronisierung fehlschlägt, 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 abgebrochen. Wenn jedoch viele RootSync- oder RepoSync-Objekte gleichzeitig nicht synchronisiert werden, kann dies zu einer erheblichen Traffic-Last auf der Kubernetes API führen.
Versuchen Sie Folgendes, um diese Probleme zu beheben:
- Konfigurationsfehler schnell beheben, damit sie sich nicht ansammeln
- Kombinieren Sie mehrere
RootSync- oderRepoSync-Objekte, um die Anzahl der Abgleicher zu reduzieren, die Kubernetes API-Anfragen stellen.
KubeVirt-Deinstallation durch Finalizer blockiert
KubeVirt ist ein Kubernetes-Paket, das mehrere Finalizer verwendet, die eine genaue Löschreihenfolge erfordern, um die Bereinigung zu erleichtern. Wenn die KubeVirt-Objekte in der falschen Reihenfolge gelöscht werden, kann das Löschen anderer KubeVirt-Objekte verzögert werden oder auf unbestimmte Zeit gestoppt werden.
Wenn Sie versucht haben, KubeVirt zu deinstallieren und es blockiert wurde, folgen Sie der Anleitung zum manuellen Löschen von KubeVirt.
Um dieses Problem in Zukunft zu beheben, 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, ein Objekt erst zu entfernen, nachdem ein bestimmter Controller eine 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 ausführen soll.
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 auf das zu löschende Objekt eine Statusbedingung angewendet haben, um zu erklären, warum die Bereinigung angehalten wurde. 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 wechselt hin und her. Das ist normal, kann aber überraschend sein.
Ein Synchronisierungsfehler kann durch verschiedene Probleme verursacht werden. Eines der häufigsten sind unzureichende Berechtigungen zum Verwalten der in der Quelle angegebenen Ressourcen. Zum Beheben dieses Fehlers fügen Sie die entsprechenden RoleBindings oder ClusterRoleBinding hinzu, um dem Abgleicher RepoSync oder RootSync 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 serverseitiges Apply, um Manifeste von 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 Nachteil, dass bei der Übernahme vorhandener Ressourcenobjekte Felder, die in der Quelle nicht angegeben sind, nicht geändert werden. Dies kann 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 zu erlauben, die neue Version anzuwenden.
Nächste Schritte
- Wenn weiterhin Probleme auftreten, prüfen Sie, ob es sich bei Ihrem Problem um ein bekanntes Problem handelt.