Solucionar problemas de sincronización de configuraciones con tu clúster

En esta página se explica cómo solucionar problemas de sincronización de configuraciones en tu clúster.

Solucionar errores de KNV 2009

Los errores KNV2009 indican que Config Sync no ha podido sincronizar algunas configuraciones con el clúster. En las secciones siguientes se explican algunas de las causas más habituales y cómo resolverlas.

Operación no permitida en determinados recursos

Como tienes que conceder el RBAC a los objetos RepoSync, puede que falten los permisos necesarios para aplicar recursos.

Para comprobar que faltan los permisos, obtén el estado del recurso RepoSync:

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

Sustituye NAMESPACE por el espacio de nombres en el que has creado el repositorio de espacios de nombres.

También puedes usar el comando nomos status.

Si ves los siguientes mensajes en el estado, significa que el reconciliador de NAMESPACE no tiene el permiso necesario para aplicar el recurso:

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"

Para solucionar este problema, debes declarar una configuración de RoleBinding que conceda a la cuenta de servicio del reconciliador permiso para gestionar el recurso fallido en ese espacio de nombres. En el artículo Configurar la sincronización desde varios repositorios se explica cómo añadir un RoleBinding.

Este problema también puede afectar a los objetos RootSync si has usado spec.override.roleRefs para cambiar los roles concedidos al objeto RootSync. Si no has definido este campo, los objetos RootSync tienen asignado el rol cluster-admin de forma predeterminada.

El objeto ResourceGroup supera el límite de tamaño de etcd objetos

Si recibe el siguiente error cuando un reconciliador intenta aplicar configuraciones al clúster, significa que el objeto ResourceGroup supera el límite de tamaño del objeto 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.

Te recomendamos que dividas tu repositorio de Git en varios repositorios. Si no puedes dividir el repositorio de Git porque el objeto ya es demasiado grande y los cambios no se conservan, puedes mitigar este problema configurando RootSync o RepoSync para inhabilitar temporalmente la escritura del estado del objeto en ResourceGroup. Para ello, puedes definir el campo .spec.override.statusMode del objeto RootSync o RepoSync como disabled. De esta forma, Config Sync deja de actualizar el estado de los recursos gestionados en el objeto ResourceGroup. Esta acción reduce el tamaño del objeto ResourceGroup. Sin embargo, no puedes ver el estado de los recursos gestionados desde nomos status.

Si no ve ningún error en el objeto RootSync o RepoSync, significa que los objetos de su fuente de información veraz se han sincronizado con el clúster. Para comprobar si el recurso ResourceGroup supera el límite de tamaño de objeto de etcd, consulta el estado del recurso ResourceGroup y el registro del controlador ResourceGroup:

  1. Comprueba el estado de ResourceGroup:

    • Para comprobar el objeto RootSync, ejecuta el siguiente comando:

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

    • Para comprobar el objeto RepoSync, ejecuta el siguiente comando:

      kubectl get resourcegroup repo-sync -n NAMESPACE

      Sustituye NAMESPACE por el espacio de nombres en el que has creado el repositorio de espacios de nombres.

    La salida es similar al siguiente ejemplo:

    NAME        RECONCILING   STALLED   AGE
root-sync   True          False     35m

    Si el valor de la columna RECONCILING es True, significa que el recurso ResourceGroup aún se está conciliando.

  2. Consulta los registros del controlador ResourceGroup:

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

    Si ves un error similar al del siguiente ejemplo en el resultado, significa que el recurso ResourceGroup es demasiado grande y supera el etcd límite de tamaño de objeto:

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

Para evitar que ResourceGroup sea demasiado grande, reduce el número de recursos de tu repositorio de Git. Puedes dividir un repositorio raíz en varios repositorios raíz.

Tiempo de espera de reconciliación de la aplicación de dependencia

Si has sincronizado objetos con dependencias, es posible que recibas un error similar al del siguiente ejemplo cuando el reconciliador intente aplicar objetos con la anotación config.kubernetes.io/depends-on al clúster:

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

Este error significa que el objeto de dependencia no se ha conciliado en el tiempo de espera de conciliación predeterminado de cinco minutos. Config Sync no puede aplicar el objeto dependiente porque, con la anotación config.kubernetes.io/depends-on, solo aplica los objetos en el orden que quieras. Puedes anular el tiempo de espera de conciliación predeterminado y establecer un tiempo más largo con spec.override.reconcileTimeout.

También es posible que la dependencia se reconcilie después de que se haya completado el intento de sincronización inicial. En este caso, la dependencia debería detectarse como conciliada en el siguiente intento de reintento de sincronización, lo que desbloqueará la aplicación de cualquier dependencia. Cuando esto ocurre, el error puede notificarse brevemente y, a continuación, eliminarse. Aumentar el tiempo de espera de la conciliación puede ayudar a evitar que el error se informe de forma intermitente.

Inventory info is nil

Si recibes el siguiente error cuando el reconciliador intenta aplicar configuraciones al clúster, es probable que tu inventario no tenga recursos o que el manifiesto tenga una anotación no gestionada:

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

Para solucionar este problema, sigue estos pasos:

  1. Evita configurar sincronizaciones en las que todos los recursos tengan la anotación configmanagement.gke.io/managed: disabled. Para ello, asegúrate de que al menos un recurso esté gestionado por Config Sync.
  2. Añade la anotación configmanagement.gke.io/managed: disabled solo después de completar una sincronización inicial del recurso sin esta anotación.

Varias plantillas de objeto de inventario

Si recibes el siguiente error cuando el reconciliador intenta aplicar configuraciones al clúster, es probable que tengas una configuración de inventario generada por kpt en la fuente de información veraz (por ejemplo, un repositorio de 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

El problema se debe a que Config Sync gestiona su propia configuración de inventario. Para resolver este problema, elimine la configuración de inventario de su fuente de información veraz.

No se pueden hacer cambios en los campos inmutables

No puedes cambiar ningún campo inmutable de una configuración modificando el valor de la fuente de información. Si intentas hacer este cambio, se producirá un error similar al siguiente:

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 necesitas cambiar un campo inmutable, elimina el objeto de tu fuente de información veraz, espera a que Config Sync elimine el objeto del clúster y, a continuación, vuelve a crear el objeto en tu fuente de información veraz con los cambios.

No se ha podido obtener el estado

Puedes autorizar a Config Sync para que gestione recursos en un espacio de nombres mediante un objeto RepoSync. Si este tipo de objeto RepoSync usa un objeto RoleBinding que hace referencia a un ClusterRole o Role personalizado, es posible que recibas el siguiente mensaje de error de la implementación de Reconciler:

KNV2009: polling for status failed: unknown

Para solucionar este problema, asegúrese de que los objetos ClusterRole y Role tengan al menos los siguientes permisos para cada recurso que gestione el objeto RepoSync:

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

Para obtener instrucciones sobre cómo añadir estos permisos, consulta Crear un RoleBinding.

No se ha podido detectar la API

Si ves un mensaje de error similar al siguiente, es posible que se haya producido un error de detección de la 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 usa la detección de APIs de Kubernetes para buscar qué recursos admite el clúster. De esta forma, Config Sync puede validar los tipos de recursos especificados en tu fuente y monitorizar esos recursos para detectar cambios en el clúster.

Antes de la versión 1.28 de Kubernetes, cada vez que el backend de un APIService no funcionaba correctamente o devolvía una lista vacía, se producía un error en API Discovery, lo que provocaba que Config Sync y otros componentes de Kubernetes fallaran. Muchos back-ends de APIService comunes no tienen una alta disponibilidad, por lo que esto puede ocurrir con relativa frecuencia, simplemente actualizando el back-end o reprogramándolo en otro nodo.

Entre los ejemplos de backends de APIService con una sola réplica se incluyen metrics-server y custom-metrics-stackdriver-adapter. Algunos backends de APIService siempre devuelven resultados de listas vacías, como custom-metrics-stackdriver-adapter. Otra causa habitual de errores de detección de APIs son los webhooks incorrectos.

Después de la versión 1.28 de Kubernetes, con la función de descubrimiento agregado habilitada, un backend de APIService en mal estado ya no provoca errores no controlados. En su lugar, se muestra que el grupo de recursos gestionado por ese APIService no tiene recursos. De esta forma, la sincronización puede continuar siempre que el recurso no esté especificado en tu fuente.

Autorreparación diferida

La función de reparación automática monitoriza los recursos gestionados, detecta las desviaciones de la fuente de información veraz y las revierte.

La reparación automática se pausa mientras se intenta la sincronización. Esto significa que la reparación automática puede retrasarse, sobre todo si hay errores de sincronización que impiden que el reconciliador se complete. Para volver a habilitar la reparación automática, corrige todos los errores de sincronización notificados.

Un número elevado de solicitudes a la API de Kubernetes

Config Sync usa una estrategia de varias instancias para escalar y aislar los tenants y los dominios de errores. Por este motivo, cada RootSync y RepoSync tiene su propia instancia de reconciliador. Además de sincronizarse cada vez que se hacen cambios en la fuente, cada instancia de reconciliador también se sincroniza periódicamente como parte de su comportamiento de autocorrección para revertir los cambios que no haya detectado la corrección de la deriva activa. Cuando añade objetos RootSync o RepoSync, se produce un aumento lineal del número de solicitudes de API realizadas por los reconciliadores que sincronizan recursos con Kubernetes. Por lo tanto, si tienes muchos objetos RootSync y RepoSync, a veces puede provocar una carga de tráfico significativa en la API de Kubernetes.

Para realizar la sincronización, Config Sync usa Server-Side Apply. De esta forma, se sustituye el flujo normal de solicitudes GET y PATCH por una sola solicitud PATCH, lo que reduce el número total de llamadas a la API, pero aumenta el número de llamadas PATCH. De esta forma, los cambios realizados son correctos, incluso cuando la versión del grupo de recursos de origen no coincide con la versión predeterminada del grupo de recursos del clúster. Sin embargo, es posible que veas solicitudes PATCH en el registro de auditoría, aunque no se haya producido ningún cambio en la fuente ni se haya desviado del estado que quieres. Esto es normal, pero puede sorprender.

Cuando se produce un error en la sincronización, se vuelve a intentar hasta que se realiza correctamente. Sin embargo, si esto requiere interacción humana, es posible que Config Sync genere errores y vuelva a intentarlo durante un tiempo, lo que aumentará el número de solicitudes realizadas a la API de Kubernetes. Los reintentos se retrasan de forma exponencial, pero si muchos objetos RootSync o RepoSync no se sincronizan simultáneamente, esto puede provocar una carga de tráfico significativa en la API de Kubernetes.

Para mitigar estos problemas, prueba una de las siguientes opciones:

  • Corrige los errores de configuración rápidamente para que no se acumulen.
  • Combina varios objetos RootSync o RepoSync para reducir el número de reconciliadores que hacen solicitudes a la API de Kubernetes.

La desinstalación de KubeVirt está bloqueada por finalizadores

KubeVirt es un paquete de Kubernetes que usa varios finalizadores, por lo que requiere un orden de eliminación preciso para facilitar la limpieza. Si los objetos de KubeVirt se eliminan en el orden incorrecto, es posible que la eliminación de otros objetos de KubeVirt se detenga o deje de responder indefinidamente.

Si has intentado desinstalar KubeVirt y se ha bloqueado, sigue las instrucciones para eliminar KubeVirt manualmente.

Para mitigar este problema en el futuro, declara las dependencias entre los objetos de recursos para asegurarte de que se eliminen en orden inverso a la dependencia.

La eliminación de objetos está bloqueada por finalizadores

Los finalizadores de Kubernetes son entradas de metadatos que indican a Kubernetes que no permita que se elimine un objeto hasta que un controlador específico haya realizado la limpieza. Esto puede provocar que la sincronización o la conciliación fallen si no se cumplen las condiciones de limpieza o si el controlador que realiza la limpieza de ese recurso no está en buen estado o se ha eliminado.

Para mitigar este problema, identifica qué recurso se está finalizando y qué controlador debe realizar la limpieza.

Si el controlador no está en buen estado, solucionar la causa principal debería permitir que se complete la limpieza de recursos, lo que desbloqueará la eliminación del objeto.

Si el controlador está en buen estado, debería haber aplicado una condición de estado al objeto que se va a eliminar para explicar por qué se ha detenido la limpieza. Si no es así, consulta los registros del controlador para ver si hay alguna indicación de la causa principal.

A menudo, que un objeto no se elimine indica que los objetos se han eliminado en el orden incorrecto. Para evitar este tipo de problemas en el futuro, declara las dependencias entre los objetos de recursos para asegurarte de que se eliminen en orden inverso a la dependencia.

Los campos de ResourceGroup cambian constantemente

Cuando se intenta sincronizar, el inventario se actualiza para cambiar el estado del recurso a pendiente. Si la sincronización falla, el inventario se actualiza para cambiar el estado del recurso a "failed" (error). Cuando se vuelve a intentar la sincronización tras un fallo, este patrón se repite, lo que provoca actualizaciones periódicas del inventario. Esto provoca que ResourceGroup resourceVersion aumente con cada actualización y que el estado de sincronización cambie constantemente. Es algo normal, pero puede resultar sorprendente.

La sincronización puede fallar por varios motivos. Uno de los más habituales es que no se tengan permisos suficientes para gestionar los recursos especificados en la fuente. Para solucionar este error, añade los RoleBindings o ClusterRoleBinding adecuados para conceder al reconciliador RepoSync o RootSync permiso para gestionar los recursos que no se pueden sincronizar.

Config Sync no elimina ni revierte los campos que no se especifican en la fuente

Config Sync usa la función Aplicación del lado del servidor para aplicar los manifiestos del origen a Kubernetes. Es necesario para permitir que otros controladores gestionen los campos metadata y spec. Un ejemplo de esto es la herramienta de escalado automático horizontal de pods, que actualiza el número de réplicas de una implementación. Por este motivo, Config Sync solo gestiona los campos especificados en el manifiesto de origen. Esto tiene como efecto secundario que, al adoptar objetos de recursos, los campos no especificados en la fuente no se cambian, lo que a veces puede provocar que la configuración combinada no sea válida o sea incorrecta.

Para evitar este problema al adoptar un recurso, usa los mismos campos en la fuente al adoptar el recurso inicialmente y, a continuación, cambia los campos de la fuente después de la sincronización. De esta forma, Config Sync eliminará correctamente los campos que haya aplicado anteriormente y los sustituirá por los nuevos campos de la fuente. Otra forma de evitar este problema es eliminar el recurso del clúster primero y permitir que Config Sync aplique la nueva versión.

Config Sync no conserva los campos de la aplicación del lado del cliente kubectl al adoptar objetos

Como Config Sync usa la aplicación del lado del servidor, cuando adopta un objeto que se creó originalmente con la aplicación del lado del cliente kubectl, anula los campos que se definieron con la aplicación del lado del cliente, pero que no se declararon en el origen.

Si quieres que se conserven esos campos, usa los mismos campos en el origen cuando adoptes el objeto por primera vez o crea el objeto con Aplicación del lado del servidor.

Siguientes pasos