Solucionar problemas del Sincronizador de configuración

En esta página, encontrarás ayuda para solucionar problemas de instalación del Sincronizador de configuración.

Si bien nos esforzamos por que la experiencia del Sincronizador de configuración para que funcione siempre, hay situaciones en las que te podrías encontrar que requieren que soluciones los problemas de configuración. En esta guía, se explican algunos mecanismos comunes que pueden ayudarte a resolver cualquier problema que encuentres.

Prácticas recomendadas generales

nomos status es tu amigo

Invertimos mucha energía intentando garantizar que tengas la mayor cantidad de datos disponible a tu alcance con el comando nomos status. nomos status te proporciona datos y errores agregados para ayudarte a comprender lo que sucede en la instalación del Sincronizador de configuración. La siguiente información está disponible con nomos status:

  • Estado de la instalación por clúster
  • Errores de sincronización (lectura de Git y conciliación de los cambios)

Recursos de KRM kubectl get para uso avanzado

El sincronizador de configuración está compuesto por varios recursos personalizados que se pueden consultar de manera individual mediante kubectl para comprender exactamente el estado de cada uno de sus objetos.

Estos son algunos aspectos clave que debes saber sobre los recursos de Kubernetes que administra el Sincronizador de configuración:

  • config-management-system es el espacio de nombres que usamos para ejecutar todos los componentes principales del sistema del Sincronizador de configuración.
  • configmanagement.gke.io/v1 y configsync.gke.io son los prefijos de versión que usamos para todos los recursos personalizados.

Puedes obtener una lista completa de los recursos personalizados si ejecutas el siguiente comando:

kubectl api-resources | grep -E "configmanagement.gke.io|configsync.gke.io"

Puedes consumir recursos personalizados individuales si ejecutas el siguiente comando: kubectl get RESOURCE -o yaml.

Por ejemplo, en el resultado del siguiente comando, puedes verificar los objetos RootSync:

kubectl get rootsync -n config-management-system -o yaml

Para obtener más información, consulta Explora los objetos RootSync y RepoSync.

Usa registros de auditoría

Los registros de auditoría pueden ser una herramienta de depuración útil.

Si instalaste el Sincronizador de configuración con Cloud Console o la herramienta de línea de comandos de gcloud, completa los siguientes pasos para usar los registros de auditoría a fin de investigar el Sincronizador de configuración.

Console

  1. Habilita los registros de auditoría de las API de GKE Connect/Hub.

    1. En Cloud Console, ve a la página de Registros de auditoría de IAM.

      Ir a la página Registros de auditoría

    2. En la tabla, selecciona la casilla de verificación API de GKE Connect/Hub.

    3. Selecciona las siguientes casillas de verificación:

      • Lectura de administración
      • Lectura de datos
      • Escritura de datos
    4. Haz clic en Guardar.

  2. Ir a la página Explorador de registros.

    Ir a la página Explorador de registros

  3. En el cuadro de texto Compilador de consultas, agrega los siguientes filtros:

    resource.type="audited_resource" resource.labels.service="gkehub.googleapis.com"
    
  4. Haz clic en Run Query.

  5. En la sección Resultados de consultas, selecciona entradas para obtener más información sobre los eventos.

CPU insuficiente

La salida de kubectl get events podría incluir un evento con el tipo FailedScheduling. El evento se ve como en el siguiente ejemplo:

LAST SEEN   TYPE      REASON              OBJECT                                       MESSAGE
9s          Warning   FailedScheduling    pod/config-management-operator-74594dc8f6    0/1 nodes are available: 1 Insufficient cpu.

Para corregir este error, elige una de las siguientes opciones:

  • agregar un nodo a un grupo de nodos de GKE existente, o
  • crear un grupo de nodos con nodos más grandes

Objeto ConfigManagement válido pero incorrecto

Si la instalación falla debido a un problema con el objeto ConfigManagement que no se debe a un error de sintaxis de YAML o JSON, es posible que se cree una instancia del objeto ConfigManagement en el clúster, pero que no funcione de manera correcta. En este caso, puedes usar el comando nomos status para verificar si hay errores en el objeto ConfigManagement.

Una instalación válida sin problemas tiene el estado PENDING o SYNCED.

Una instalación no válida tiene un estado de NOT CONFIGURED y enumera uno de los siguientes errores:

  • missing git-creds Secret
  • missing required syncRepo field
  • git-creds Secret is missing the key specified by secretType

Para solucionar el problema, corrige el error de configuración. Según el tipo de error, es posible que debas volver a aplicar el manifiesto de ConfigManagement al clúster.

Si el problema es que te olvidaste de crear el Secret git-creds, el Sincronizador de configuración detecta el Secret en cuanto lo creas y no es necesario que vuelvas a aplicar la configuración.

Los campos ResourceGroup cambian constantemente

Para un repositorio de Git sincronizado con el clúster, el estado de conciliación de todos los recursos se agrega en un recurso llamado ResourceGroup. Para cada objeto RootSync o RepoSync, se genera un ResourceGroup a fin de capturar el conjunto de recursos aplicados al clúster y los estados agregados.

En ocasiones, ResourceGroup puede ingresar un bucle que continúa con la actualización del spec de ResourceGroup. Si esto sucede, es posible que observes los siguientes problemas:

  • El metadata.generation de un ResourceGroup sigue aumentando en un período breve.
  • El ResourceGroup spec cambia constantemente.
  • El ResourceGroup spec no incluye el status.resourceStatuses de los recursos que se están sincronizando con el clúster.

Si observas estos problemas, significa que algunos de los recursos en los repositorios de Git no se aplicaron al clúster. La causa de estos problemas es que no tienes los permisos necesarios para aplicar esos recursos.

Para verificar que faltan los permisos, obtén el estado de los recursos de RepoSync:

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

Reemplaza NAMESPACE por el espacio de nombres en el que creaste el repositorio de espacio de nombres.

También puedes usar nomos status.

Si ves los siguientes mensajes en el estado, significa que el conciliador en NAMESPACE carece del permiso necesario para aplicar el recurso:

errors:
  - code: "2009"
    errorMessage: |-
      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"

      For more information, see https://g.co/cloud/acm-errors#knv2009

Para solucionar este problema, debes declarar una configuración de RoleBinding que otorgue a la cuenta de servicio ns-reconciler-NAMESPACE permiso para administrar el recurso con errores en ese espacio de nombres. Los detalles sobre cómo agregar un RoleBinding se incluyen en la sección Configura la sincronización desde repositorios de espacios de nombres.

Gran cantidad de recursos en el repositorio de Git

Cuando el repositorio de Git sincronizado por los objetos RepoSync o RootSync contiene la configuración para más de unos miles de recursos, puede hacer que ResourceGroup supere el límite de tamaño de los objetos etcd. Cuando esto sucede, no puedes ver el estado agregado para los recursos de el repositorio de Git. Si bien no podrás ver el estado agregado, tu repositorio aún estará sincronizado. Si no ves errores en los objetos RepoSync o RootSync, significa que el repositorio de Git se sincroniza con el clúster de manera correcta.

Para verificar si el recurso de ResourceGroup supera el límite de tamaño de los objetos etcd, debes verificar el estado del recurso de ResourceGroup y el registro del controlador de ResourceGroup:

  1. Verifica el estado de ResourceGroup con el siguiente comando:

    • Para verificar RootSync, ejecuta el siguiente comando:
     kubectl get resourcegroup.kpt.dev root-sync -n config-management-system
    
    • Para verificar RepoSync, ejecuta el siguiente comando:
    # For the RepoSync:
    kubectl get resourcegroup.kpt.dev repo-sync -n NAMESPACE
    

    Deberías ver un resultado similar al siguiente:

    NAME        RECONCILING   STALLED   AGE
    root-sync   True          False     35m
    

    Si el valor en la columna RECONCILING es True, significa que el recurso de ResourceGroup todavía se encuentra en conciliación.

  2. Verifica los registros del controlador de ResourceGroup con el siguiente comando:

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

    Si ves el siguiente error en el resultado, el recurso de ResourceGroup es demasiado grande y supera el límite de tamaño de los objetos etcd:

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

Para evitar que ResourceGroup se vuelva demasiado grande, reduce la cantidad de recursos en el repositorio de Git. Por ejemplo, divide el repositorio y usa un objeto RootSync con varios objetos RepoSync en lugar de usar solo un objeto RootSync para sincronizar todos los recursos.

Sin sincronizar con el repositorio de Git

Si se envían confirmaciones nuevas al repositorio de Git, pero el estado del Sincronizador de configuración de tu clúster sigue siendo Synced para una confirmación anterior y durante mucho tiempo (más de spec.git.period), debes verificar los registros del contenedor git-sync:

# check git-sync logs for a root reconciler
kubectl logs -n config-management-system deployment/root-reconciler -c git-sync

# check git-sync logs for a namespace reconciler
kubectl logs -n config-management-system deployment/ns-reconciler-NAMESPACE -c git-sync

Es probable que git-sync no se sincronice desde el repositorio de Git, pero el conciliador continúe con la sincronización desde la confirmación sincronizada con anterioridad. El siguiente resultado de ejemplo indica que tienes un problema git-sync:

"msg"="unexpected error syncing repo, will retry" "error"="Run(git fetch -f --tags --depth 1 origin develop): exit status 128: { stdout: "", stderr: "fatal: couldn't find remote ref develop\n" }"

Este es un problema conocido de las versiones 1.8.1 y anteriores del Sincronizador de configuración. Para solucionarlo, debes seguir el mensaje de error en el registro. Es posible que debas actualizar el repositorio de Git o los campos spec.git en el objeto RootSync o RepoSync.

admission-webhook.configsync.gke.io rechaza la solicitud para actualizar o borrar un recurso que un RootSync/RepoSync ya borrado administra

Borrar un objeto RootSync o RepoSync no borra las anotaciones y etiquetas del Sincronizador de configuración, y el webhook de admisión del Sincronizador de configuración rechazaría las solicitudes de modificación o eliminación de estos recursos si el Sincronizador de configuración aún está habilitado en el clúster.

Si el intent es mantener estos recursos administrados, primero puedes dejar de administrar estos recursos si configuras la anotación configmanagement.gke.io/managed en disabled en cada Recurso administrado declarado en el repositorio de Git. Esto quitaría las anotaciones y etiquetas de Sincronizador de configuración de los recursos administrados, pero no los borraría. Una vez que se complete la sincronización, puedes quitar el objeto RootSync o RepoSync.

Si la intención es borrar estos recursos administrados, primero puedes borrar los recursos administrados mediante la modificación del objeto RootSync o RepoSync para sincronizar desde un directorio de Git vacío. Una vez que se complete la sincronización, puedes quitar el objeto RootSync o RepoSync.

Si se borró el objeto RootSync o RepoSync antes de dejar de administrar o borrar recursos administrados, puedes volver a agregar el objeto RootSync o RepoSync, dejar de administrar o borrar los recursos administrados y, luego, borrar el objeto RootSync o RepoSync de nuevo.

Soluciona problemas de mensajes de error

Error: Permiso denegado.

Si recibes un error similar al siguiente ejemplo cuando intentas configurar el Sincronizador de configuración, es posible que no tengas la función de administrador de GKE Hub:

Permission 'gkehub.features.create' denied on 'projects/PROJECT_ID/locations/global/features/configmanagement'

A fin de asegurarte de que tienes los permisos necesarios, consulta la sección sobre cómo preparar los permisos.

Error: el webhook de admisión rechazó una solicitud

Si recibes el siguiente error cuando intentas aplicar un cambio en un campo que administra el Sincronizador de configuración, es posible que hayas realizado un cambio conflictivo:

error: OBJECT could not be patched: admission webhook "v1.admission-webhook.configsync.gke.io"
denied the request: fields managed by Config Sync can not be modified

Cuando declaras un campo en una configuración y el repositorio se sincroniza con un clúster, el Sincronizador de configuración administra ese campo. Cualquier cambio que intentes hacer en ese campo es un cambio conflictivo.

Por ejemplo, si tienes una configuración de implementación en el repositorio con una etiqueta environment:prod y tratas de cambiar esa etiqueta a environment:dev en el clúster, habrá un cambio conflictivo y recibirás el mensaje de error anterior. Sin embargo, si agregas una etiqueta nueva (por ejemplo, tier:frontend) a la implementación, no habrá un conflicto.

Si quieres que el Sincronizador de configuración ignore los cambios en un objeto, puedes agregar la anotación que se describe en Ignora las mutaciones de objetos.

Error: se agotó el tiempo de espera de E/S de la solicitud de webhook

Si recibes el siguiente error cuando el conciliador intenta aplicar una configuración al clúster:

KNV2009: Internal error occurred: failed calling webhook "v1.admission-webhook.configsync.gke.io": Post https://admission-webhook.config-management-system.svc:8676/admission-webhook?timeout=3s: dial tcp 10.1.1.186:8676: i/o timeout

Esto puede deberse a que el firewall bloquea el puerto del webhook de admisión 8676 en la red del plano de control. Para resolver este problema, agrega una regla de firewall a fin de admitir el puerto 8676, que el webhook de admisión del Sincronizador de configuración usa para la prevención de desvíos.

Error: se rechazó la conexión de webhook de admisión

Si recibes el siguiente error cuando el conciliador intenta aplicar una configuración al clúster:

KNV2009: Internal error occurred: failed calling webhook "v1.admission-webhook.configsync.gke.io": Post "https://admission-webhook.config-management-system.svc:8676/admission-webhook?timeout=3s": dial tcp 10.92.2.14:8676: connect: connection refused

Esto significa que el webhook de admisión aún no está listo. Es un error transitorio que puedes ver cuando se inicializa el Sincronizador de configuración.

Si el problema persiste, consulta la implementación del webhook de admisión para ver si sus pods se pueden programar y están en buen estado.

kubectl describe deploy admission-webhook -n config-management-system

kubectl get pods -n config-management-system -l app=admission-webhook

Error: No se puede activar el Secret de Git

Si recibes el siguiente error cuando el contenedor git-sync intenta sincronizar un repositorio con un Secret:

KNV2004: unable to sync repo Error in the git-sync container: ERROR: can't configure SSH: can't access SSH key: stat /etc/git-secret/ssh: no such file or directory: lstat /repo/root/rev: no such file or directory

Esto significa que el Secret de Git no se activó correctamente en el contenedor git-sync. Esto puede deberse a que cambiaste el tipo de autenticación del repositorio de Git de none, gcenode o gcpserviceaccount a otros tipos que necesiten un Secret. Para resolver este problema, ejecuta los siguientes comandos a fin de reiniciar Reconciler Manager y los conciliadores:

# Stop the reconciler-manager Pod. The reconciler-manager Deployment will spin
# up a new Pod which can pick up the latest `spec.git.auth`.
kubectl delete po -l app=reconciler-manager -n config-management-system

# Delete the reconciler Deployments. The reconciler-manager will recreate the
# reconciler Deployments with correct volume mount.
kubectl delete deployment -l app=reconciler -n config-management-system

Los contenedores reconciler o git-sync son OOMKilled

En la versión 1.8.2 y versiones posteriores de Anthos Config Management, cuando configuras la sincronización desde varios repositorios con kubectl, puedes anular los límites de CPU o memoria de una raíz. o un repositorio de espacio de nombres. Para anular estos valores, usa el campo spec.override.resources de un objeto RootSync o RepoSync.

En el siguiente ejemplo, se muestra cómo anular los límites de CPU y memoria del contenedor reconciler y el límite de memoria del contenedor git-sync de un conciliador raíz. Solo se puede anular los contenedores git-sync y reconciler. La anulación parcial está permitida: cuando no se proporciona un valor de anulación para un límite de recursos, se usa el límite predeterminado.

apiVersion: configsync.gke.io/v1beta1
kind: RootSync
metadata:
  name: root-sync
  namespace: config-management-system
spec:
  sourceFormat: "unstructured"
  override:
    resources:
    - containerName: "reconciler"
      cpuLimit: "888m"
      memoryLimit: "444Mi"
    - containerName: "git-sync"
      memoryLimit: "333Mi"
  git:
     ...

Ejecute el siguiente comando para verificar que se apliquen los límites de recursos nuevos:

kubectl get deployment.apps/root-reconciler -n config-management-system -o yaml

Puedes anular los límites de recursos de un conciliador de espacio de nombres de manera similar.

KNV2004: no se puede sincronizar el error de repositorio en el contenedor de git-sync (git fetch falló con el error remote did not send all necessary objects)

El Sincronizador de configuración crea una clonación superficial de tu repositorio de Git. En raras ocasiones, es posible que no pueda encontrar la confirmación a partir de la clonación superficial y que se requiera aumentar la cantidad de confirmaciones de Git para recuperar.

En la versión 1.8.2 y las posteriores de Anthos Config Management, puedes configurar la cantidad de confirmaciones de Git para recuperar mediante la configuración del campo spec.override.gitSyncDepth en un objeto RootSync o RepoSync:

  • Si no se proporciona este campo, el Sincronizador de configuración lo configura de forma automática.
  • El Sincronizador de configuración realizaría una clonación completo si este campo es 0 y una clonación superficial si este campo es mayor que 0.
  • No se puede establecer este campo en un valor negativo.

A continuación, se muestra un ejemplo de la configuración de la cantidad de confirmaciones de Git para recuperar en 88:

apiVersion: configsync.gke.io/v1beta1
kind: RootSync
metadata:
  name: root-sync
  namespace: config-management-system
spec:
  override:
    gitSyncDepth: 88
  git:
    ...

Ejecuta el siguiente comando para verificar que el cambio tenga efecto (GIT_SYNC_DEPTH debe configurarse como 88 en el campo data del ConfigMap de root-reconciler-git-sync):

kubectl get cm root-reconciler-git-sync -n config-management-system -o yaml

Puedes anular la cantidad de confirmaciones de Git para recuperar en un conciliador de espacio de nombres de manera similar.

Error: No se pudieron actualizar las implementaciones de conciliación

Cuando se actualiza el Sincronizador de configuración de las versiones entre 1.6.2 y 1.7.0 a versiones entre 1.7.x y 1.8.x, es posible que la versión de la imagen de la implementación de la conciliación no se actualice. Esto se debe a cambios en el campo .spec.selector.labels de la plantilla de implementación. Se agregó una nueva matchLabel en la versión 1.6.2 y, luego, se quitó en 1.7.0. El selector de etiquetas es inmutable, por lo que el administrador del conciliador no puede actualizar los conciliadores.

Puedes verificar el error si verificas los registros del conciliador-administrador:

kubectl logs -n config-management-system deployment/reconciler-manager -c reconciler-manager

A continuación, se muestra un ejemplo del error en el registro:

Deployment.apps "root-reconciler" is invalid: spec.selector: Invalid value: v1.LabelSelector{MatchLabels:map[string]string{"app":"reconciler"}, MatchExpressions:[]v1.LabelSelectorRequirement(nil)}: field is immutable

Para resolver el problema, borra los conciliadores actuales:

kubectl delete deployment -n config-management-system -l app=reconciler

Error: Un espacio de nombres se atasca en la fase de Terminating

Un espacio de nombres atascado en la fase de Terminating debe tener la siguiente condición:

    message: 'Failed to delete all resource types, 1 remaining: admission webhook
      "v1.admission-webhook.configsync.gke.io" denied the request: system:serviceaccount:kube-system:namespace-controller
      is not authorized to delete managed resource "_configmap_bookstore_cm1"'
    reason: ContentDeletionFailed
    status: "True"
    type: NamespaceDeletionContentFailure

Esto sucede cuando intentas borrar un espacio de nombres de un repositorio raíz, pero algunos objetos bajo el espacio de nombres todavía están administrados de manera activa por un conciliador de espacio de nombres. Cuando se borra un espacio de nombres, el controlador de espacio de nombres, cuya cuenta de servicio es system:serviceaccount:kube-system:namespace-controller, intenta borrar todos los objetos que se encuentran en ese espacio de nombres. Sin embargo, el webhook de admisión del Sincronizador de configuración solo permite que el conciliador raíz o de espacio de nombres borre estos objetos y no permite que el controlador de espacio de nombres los pueda borrar.

La solución alternativa es borrar el webhook de admisión del Sincronizador de configuración:

kubectl delete deployment.apps/admission-webhook -n config-management-system

El operador de Config Management volverá a crear el webhook de admisión del Sincronizador de configuración.

Si esta solución alternativa no funciona, es posible que debas volver a instalar el Sincronizador de configuración.

Para no volver a encontrar el error, debes asegurarte de que se quite el repositorio del espacio de nombres (aquí se encuentran las instrucciones sobre cómo quitar un repositorio de espacio de nombres) antes de quitar el espacio de nombres.

Error: No se encontró el campo webhooks en ValidtingWebhookConfiguration

Si encuentras los siguientes errores en los registros de webhook de admisión del Sincronizador de configuración cuando ejecutas kubectl logs -n config-management-system -l app=admission-webhook, haz lo siguiente:

cert-rotation "msg"="Unable to inject cert to webhook." "error"="`webhooks` field not found in ValidatingWebhookConfiguration" "gvk"={"Group":"admissionregistration.k8s.io","Version":"v1","Kind":"ValidatingWebhookConfiguration"} "name"="admission-webhook.configsync.gke.io"
controller-runtime/manager/controller/cert-rotator "msg"="Reconciler error" "error"="`webhooks` field not found in ValidatingWebhookConfiguration" "name"="admission-webhook-cert" "namespace"="config-management-system"

Esto significa que root-reconciler no sincronizó ningún recurso con el clúster. Esto podría deberse a que root-reconciler aún no está listo o no hay nada que sincronizar desde el repositorio de Git (por ejemplo, el directorio de sincronización está vacío). Si el problema persiste, verifica el estado de root-reconciler:

kubectl get pods -n config-management-system -l configsync.gke.io/reconciler=root-reconciler

Si root-reconciler está en un bucle de fallas o OOMKilled, debes aumentar sus límites de recursos.