Résoudre les problèmes de synchronisation des configurations avec votre cluster

Cette page explique comment résoudre les problèmes de synchronisation des configurations avec votre cluster.

Résoudre les erreurs KNV 2009

Les erreurs KNV2009 indiquent que Config Sync n'a pas réussi à synchroniser certaines configurations avec le cluster. Les sections suivantes expliquent certaines des causes les plus courantes et comment les résoudre.

Une opération est interdite sur certaines ressources

Étant donné que vous devez accorder le contrôle RBAC aux objets RepoSync, il se peut qu'ils ne disposent pas des autorisations nécessaires pour appliquer des ressources.

Vous pouvez vérifier que les autorisations sont manquantes en obtenant l'état de la ressource RepoSync:

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

Remplacez NAMESPACE par l'espace de noms dans lequel vous avez créé votre dépôt d'espaces de noms.

Vous pouvez également utiliser la commande nomos status.

Si les messages suivants apparaissent dans l'état, cela signifie que le rapprochement dans NAMESPACE ne dispose pas de l'autorisation nécessaire pour appliquer la ressource :

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"

Pour résoudre ce problème, vous devez déclarer une configuration RoleBinding qui accorde au compte de service l'autorisation de gérer la ressource ayant échoué dans cet espace de noms. Pour savoir comment ajouter un RoleBinding, consultez la section Configurer la synchronisation à partir de plusieurs dépôts.

Ce problème peut également affecter les objets RootSync si vous avez utilisé spec.override.roleRefs pour modifier les rôles attribués à l'objet RootSync. Si vous n'avez pas défini ce champ, le rôle cluster-admin est attribué par défaut aux objets RootSync.

L'objet ResourceGroup dépasse la taille maximale autorisée (etcd)

Si vous recevez l'erreur suivante lorsqu'un rapprochement tente d'appliquer des configurations au cluster, l'objet ResourceGroup dépasse la limite de taille d'objet 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.

Nous vous recommandons de scinder votre dépôt Git en plusieurs dépôts. Si vous ne parvenez pas à décomposer le dépôt Git, car l'objet est déjà trop volumineux et les modifications ne sont pas conservées, vous pouvez y remédier en configurant RootSync ou RepoSync pour désactiver temporairement l'écriture de l'état de l'objet dans le ResourceGroup. Pour ce faire, définissez le champ .spec.override.statusMode de l'objet RootSync ou RepoSync sur disabled. Ainsi, Config Sync cesse de mettre à jour l'état des ressources gérées dans l'objet ResourceGroup. Cette action réduit la taille de l'objet ResourceGroup. Toutefois, vous ne pouvez pas afficher l'état des ressources gérées à partir de nomos status ou de gcloud alpha anthos config sync.

Si vous ne voyez aucune erreur dans l'objet RootSync ou RepoSync, cela signifie que les objets de votre source de référence ont été synchronisés avec le cluster. Pour vérifier si la ressource ResourceGroup dépasse la limite de taille d'objet etcd, vérifiez l'état de la ressource ResourceGroup et le journal du contrôleur ResourceGroup:

  1. Vérifiez l'état de ResourceGroup:

    • Pour vérifier l'objet RootSync, exécutez la commande suivante:

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

    • Pour vérifier l'objet RepoSync, exécutez la commande suivante:

      kubectl get resourcegroup repo-sync -n NAMESPACE

      Remplacez NAMESPACE par l'espace de noms dans lequel vous avez créé votre dépôt d'espaces de noms.

    Le résultat ressemble à celui de l'exemple ci-dessous.

    NAME        RECONCILING   STALLED   AGE
root-sync   True          False     35m

    Si la valeur de la colonne RECONCILING est True, cela signifie que la ressource ResourceGroup est toujours en cours de rapprochement.

  2. Consultez les journaux du contrôleur ResourceGroup:

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

    Si une erreur semblable à l'exemple suivant s'affiche dans le résultat, la ressource ResourceGroup est trop volumineuse et dépasse la limite de taille d'objet de etcd:

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

Pour empêcher le ResourceGroup de devenir trop volumineux, réduisez le nombre de ressources de votre dépôt Git. Vous pouvez scinder un dépôt racine en plusieurs dépôts racines.

Dépendance appliquée avant expiration du rapprochement

Si vous synchronisez des objets avec des dépendances, vous pouvez recevoir une erreur semblable à l'exemple suivant lorsque le rapprochement tente d'appliquer des objets avec l'annotation config.kubernetes.io/depends-on au cluster:

KNV2009: skipped apply of Pod, bookstore/pod4: dependency apply reconcile timeout: bookstore_pod3__Pod  For more information, see https://g.co/cloud/acm-errors#knv2009

Cette erreur signifie que l'objet de dépendance n'a pas été rapproché dans le délai imparti de cinq minutes. Config Sync ne peut pas appliquer l'objet dépendant, car avec l'annotation config.kubernetes.io/depends-on, il n'applique que les objets dans l'ordre souhaité. Vous pouvez ignorer le délai de rapprochement par défaut en définissant spec.override.reconcileTimeout.

Il est également possible que la dépendance se rapproche une fois la tentative de synchronisation initiale terminée. Dans ce cas, la dépendance doit être détectée comme rapprochée lors de la prochaine tentative de nouvelle tentative de synchronisation, ce qui permet de débloquer l'application de tous les dépendants. Dans ce cas, l'erreur peut être signalée brièvement, puis supprimée. Allonger le délai de rapprochement peut aider à éviter que l'erreur ne soit signalée par intermittence.

Les informations sur l'inventaire sont "nil"

Si vous recevez l'erreur suivante lorsque le rapprochement tente d'appliquer des configurations au cluster, il est probable que votre inventaire ne dispose d'aucune ressource ou que le fichier manifeste présente une annotation non gérée:

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

Essayez les solutions suivantes pour résoudre ce problème :

  1. Évitez de configurer des synchronisations où toutes les ressources comportent l'annotation configmanagement.gke.io/managed: disabled, en vous assurant qu'au moins une ressource est gérée par Config Sync.
  2. Ajoutez l'annotation configmanagement.gke.io/managed: disabled uniquement après avoir terminé la synchronisation initiale de la ressource sans cette annotation.

Plusieurs modèles d'objets d'inventaire

Si vous recevez l'erreur suivante lorsque le rapprochement tente d'appliquer des configurations au cluster, il est probable que vous disposiez d'une configuration d'inventaire générée par kpt dans la source de référence, par exemple un dépôt Git:

KNV2009: Package has multiple inventory object templates.  The package should have one and only one inventory object template.   For more information, see https://g.co/cloud/acm-errors#knv2009

Le problème se produit, car Config Sync gère sa propre configuration d'inventaire. Pour résoudre ce problème, supprimez la configuration de l'inventaire dans votre source de référence.

Impossible de modifier des champs immuables

Vous ne pouvez pas modifier un champ immuable dans une configuration en modifiant la valeur dans la source de référence. Toute tentative de modification entraîne une erreur semblable à celle-ci:

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

Si vous devez mettre à jour un champ immuable, supprimez manuellement l'objet du cluster. Config Sync peut ensuite recréer l'objet avec la nouvelle valeur de champ.

Échec de la découverte de l'API

Si un message d'erreur semblable au suivant s'affiche, vous rencontrez peut-être une erreur de découverte d'API:

KNV2002: API discovery failed: APIServer error: unable to retrieve the complete list of server APIs: external.metrics.k8s.io/v1beta1: received empty response for: external.metrics.k8s.io/v1beta1

Config Sync utilise la détection d'API Kubernetes pour rechercher les ressources compatibles avec le cluster. Cela permet à Config Sync de valider les types de ressources spécifiés dans votre source et de surveiller les modifications apportées à ces ressources dans le cluster.

Avant la version 1.28 de Kubernetes, chaque fois qu'un backend APIService était non opérationnel ou renvoyait un résultat de liste vide, API Discovery échouait, provoquant une erreur de Config Sync et de plusieurs autres composants Kubernetes. De nombreux backends APIService courants ne sont pas disponibilité élevée. Cela peut donc se produire relativement fréquemment, simplement en mettant à jour le backend ou en le reprogrammant sur un autre nœud.

metrics-server et custom-metrics-stackdriver-adapter sont des exemples de backends APIService avec une seule instance répliquée. Certains backends APIService renvoient toujours des résultats de liste vide, comme custom-metrics-stackdriver-adapter. Les webhooks non opérationnels sont une autre cause courante d'échec de la découverte d'API.

Après la version 1.28 de Kubernetes, avec la fonctionnalité de découverte agrégée activée, un backend APIService non opérationnel ne provoque plus d'erreurs non gérées. À la place, le groupe de ressources géré par cet APIService apparaît comme ne disposant d'aucune ressource. Cela permet de poursuivre la synchronisation tant que la ressource non opérationnelle n'est pas spécifiée dans votre source.

Autoréparation différée

L'auto-réparation surveille les ressources gérées, détecte les dérives depuis la source de référence et les annule.

L'auto-réparation est suspendue pendant la tentative de synchronisation. Ce comportement signifie que l'autoréparation peut être retardée, en particulier si des erreurs de synchronisation empêchent le rapprochement. Pour réactiver l'auto-réparation, corrigez toutes les erreurs de synchronisation signalées.

Nombre élevé de requêtes API Kubernetes

Config Sync utilise une stratégie multi-instanciation pour procéder au scaling et à l'isolement des locataires et des domaines de défaillance. De ce fait, chaque RootSync et RepoSync obtient sa propre instance de rapprochement. En plus de se synchroniser chaque fois que des modifications sont apportées à la source, chaque instance de rapprochement se synchronise également régulièrement dans le cadre de son comportement d'auto-réparation, afin d'annuler toutes les modifications manquées par la correction des dérives actives. Lorsque vous ajoutez des objets RootSync ou RepoSync, cela entraîne une augmentation linéaire du nombre de requêtes API effectuées par les rapprochements synchronisant les ressources avec Kubernetes. Par conséquent, si vous avez de nombreux objets RootSync et RepoSync, cela peut parfois entraîner une charge de trafic importante sur l'API Kubernetes.

Pour effectuer la synchronisation, Config Sync utilise la fonction Server-Side Apply. Le flux de requêtes GET et PATCH normal est ainsi remplacé par une seule requête PATCH, ce qui réduit le nombre total d'appels d'API, mais augmente le nombre d'appels PATCH. Cela garantit que les modifications apportées sont correctes, même lorsque la version du groupe de ressources dans la source ne correspond pas à la version du groupe de ressources par défaut du cluster. Toutefois, des requêtes PATCH peuvent s'afficher dans le journal d'audit, même si la source n'a pas été modifiée ou qu'aucun écart n'a été observé par rapport à l'état souhaité. Ce phénomène est normal, mais peut surprendre.

En cas d'erreur, la synchronisation est relancée jusqu'à ce que l'opération réussisse. Toutefois, si cela nécessite une interaction humaine, Config Sync peut générer des erreurs et des tentatives pendant un certain temps, ce qui augmente le nombre de requêtes adressées à l'API Kubernetes. Les nouvelles tentatives diminuent de manière exponentielle, mais si de nombreux objets RootSync ou RepoSync ne se synchronisent pas simultanément, cela peut entraîner une charge de trafic importante sur l'API Kubernetes.

Pour limiter ces problèmes, essayez l'une des options suivantes:

  • Corrigez rapidement les erreurs de configuration afin d'éviter qu'elles ne s'accumulent.
  • Combinez plusieurs objets RootSync ou RepoSync pour réduire le nombre de rapprochements effectuant des requêtes API Kubernetes.

La désinstallation de KubeVirt est bloquée par les validateurs

KubeVirt est un package Kubernetes qui utilise plusieurs validateurs, nécessitant un ordre de suppression précis pour faciliter le nettoyage. Si les objets KubeVirt sont supprimés dans le mauvais ordre, la suppression d'autres objets KubeVirt peut se bloquer ou cesser de répondre indéfiniment.

Si vous avez essayé de désinstaller KubeVirt et qu'il a été bloqué, suivez les instructions pour supprimer manuellement KubeVirt.

Pour atténuer ce problème à l'avenir, déclarez les dépendances entre les objets de ressource afin de vous assurer qu'ils sont supprimés dans l'ordre inverse des dépendances.

La suppression d'objets est bloquée par les validateurs

Les finalistes Kubernetes sont des entrées de métadonnées qui indiquent à Kubernetes de ne pas autoriser la suppression d'un objet tant qu'un contrôleur spécifique n'a pas effectué le nettoyage. Cela peut entraîner l'échec de la synchronisation ou du rapprochement si les conditions de nettoyage ne sont pas remplies ou si le contrôleur qui effectue le nettoyage de cette ressource est non opérationnel ou a été supprimé.

Pour atténuer ce problème, identifiez la ressource en cours de finalisation et le contrôleur qui doit effectuer le nettoyage.

Si le contrôleur n'est pas opérationnel, la résolution de la cause racine devrait permettre de terminer le nettoyage des ressources et ainsi de débloquer la suppression de l'objet.

Si le contrôleur est opérationnel, il doit avoir appliqué une condition d'état à l'objet supprimé pour expliquer pourquoi le nettoyage a été bloqué. Si ce n'est pas le cas, consultez les journaux du contrôleur pour trouver la cause du problème.

Souvent, le blocage d'un objet lors de la suppression indique que les objets ont été supprimés dans le mauvais ordre. Pour éviter ce type de problème à l'avenir, déclarez les dépendances entre les objets de ressource afin de vous assurer qu'ils sont supprimés dans l'ordre inverse des dépendances.

Les champs ResourceGroup continuent de changer

Lors d'une tentative de synchronisation, l'inventaire est mis à jour pour faire passer l'état de la ressource à "En attente". En cas d'échec de la synchronisation, l'inventaire est mis à jour et définit l'état de la ressource sur "Échec". Lorsque vous relancez la synchronisation après un échec, ce modèle se répète, ce qui entraîne des mises à jour périodiques de l'inventaire. La valeur resourceVersion du ResourceGroup augmente à chaque mise à jour et l'état de la synchronisation s'inverse. Ce phénomène est normal, mais peut surprendre.

Les échecs de synchronisation peuvent avoir plusieurs causes. L'une des plus courantes concerne les autorisations insuffisantes pour gérer les ressources spécifiées dans la source. Pour corriger cette erreur, ajoutez les RoleBindings ou ClusterRoleBinding appropriés pour accorder à l'autorisation de rapprochement RepoSync ou RootSync l'autorisation de gérer les ressources qui ne parviennent pas à se synchroniser.

L'application côté serveur ne supprime pas et ne rétablit pas les champs non spécifiés dans la source

Config Sync utilise la fonctionnalité Application côté serveur pour appliquer les fichiers manifestes de la source à Kubernetes. Cela est obligatoire pour permettre aux autres contrôleurs de gérer les champs metadata et spec. L'autoscaler horizontal de pods, par exemple, met à jour le nombre d'instances répliquées dans un déploiement. De ce fait, Config Sync ne gère que les champs spécifiés dans le fichier manifeste source. Par conséquent, lors de l'adoption d'objets ressources existants, les champs non spécifiés dans la source ne sont pas modifiés, ce qui peut parfois rendre la configuration fusionnée non valide ou incorrecte.

Pour éviter ce problème lors de l'adoption d'une ressource, utilisez exactement les mêmes champs dans la source lors de l'adoption initiale, puis modifiez-les dans la source après la synchronisation, afin que Config Sync supprime correctement les champs précédemment appliqués et les remplace par les nouveaux champs de la source. Une autre façon d'éviter ce problème consiste à commencer par supprimer la ressource du cluster et à autoriser Config Sync à appliquer la nouvelle version.

Étapes suivantes