Introducción a la solución de problemas

Si tienes dificultades con Sincronizador de configuración, en esta página, se presentan algunas herramientas y procedimientos comunes que pueden ayudarte a identificar y resolver los problemas que experimentes.

Actualiza a una versión compatible.

Considera actualizar el Sincronizador de configuración a una versión compatible. La actualización suele resolver problemas comunes y te brinda acceso a las funcionalidades más recientes.

Usa la herramienta de línea de comandos de nomos

La herramienta de línea de comandos nomos proporciona estadísticas esenciales sobre la configuración del Sincronizador de configuración. Los comandos que se describen en las siguientes secciones son particularmente útiles cuando intentas determinar la fuente de tu problema o cuando necesitas trabajar con Atención al cliente de Cloud.

Consulta el estado del Sincronizador de configuración

El comando 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)

Crea un informe de errores

Si tienes un problema con el Sincronizador de configuración que requiera la ayuda del equipo de Atención al cliente de Cloud, puedes proporcionarles información de depuración valiosa con el comando nomos bugreport.

Este comando genera un archivo ZIP con marca de tiempo que contiene información sobre el conjunto de clústeres de Kubernetes en tu contexto kubectl. El archivo contiene registros de los pods del Sincronizador de configuración. No contiene información sobre los recursos sincronizados con el Sincronizador de configuración.

Cómo ver el panel de descripción general

El panel del Sincronizador de configuración te proporciona una descripción general del estado de los paquetes que administra el Sincronizador de configuración y el estado de los recursos en esos paquetes. Explorar este panel puede ayudarte a obtener una descripción general rápida del estado de tu instalación del Sincronizador de configuración y descubrir si hay paquetes con problemas.

  • Para acceder al panel, ve a la página Configuración en la sección Funciones de la consola de Google Cloud :

    Ir a Configuración

Usa la supervisión y el análisis de registros

Supervisar el Sincronizador de configuración y explorar sus registros puede ayudarte a determinar la fuente de los errores y a comprender mejor cualquier comportamiento inesperado.

Información sobre las métricas del Sincronizador de configuración

Usa las métricas del Sincronizador de configuración para obtener visibilidad del estado del Sincronizador de configuración.

Supervisa objetos RootSync y RepoSync

Cuando instalas el Sincronizador de configuración con la Google Cloud consola o Google Cloud CLI, el Sincronizador de configuración crea de forma automática un objeto RootSync por ti. Cuando configuras la sincronización desde varios repositorios, puedes crear objetos RepoSync que contienen información de configuración sobre tus repositorios de espacios de nombres.

La supervisión de estos objetos puede revelar información valiosa sobre el estado del Sincronizador de configuración. Para obtener más información, consulta Supervisa los objetos RepoSync y RootSync.

Usa indicadores de nivel de servicio (SLI)

Para recibir notificaciones cuando el Sincronizador de configuración no funcione según lo previsto, usa los SLIs del Sincronizador de configuración.

Registros de consultas

Puedes usar el Explorador de registros para recuperar, ver y analizar los datos de registro de Sincronizador de configuración. Estos registros pueden contener datos históricos valiosos que nomos bugreport no captura cuando se reinician los Pods del operador o del reconciliador. Si quieres ver ejemplos de consultas que pueden ayudarte a diagnosticar tu problema, consulta Consulta los registros del Sincronizador de configuración.

Examina recursos con la herramienta de línea de comandos kubectl

El Sincronizador de configuración se compone de varios recursos personalizados que puedes consultar mediante los comandos kubectl. Estos comandos te ayudan a comprender el estado de cada uno de los objetos del Sincronizador de configuración.

Debes conocer la siguiente información 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 y configsync.gke.io son los grupos de API que usamos para todos los recursos personalizados.

Ejemplos

En las siguientes secciones, se muestra cómo puedes usar los comandos de kubectl para examinar el Sincronizador de configuración.

Enumera 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.

    Reemplaza RESOURCE por el nombre del recurso que deseas consultar.

    Por ejemplo, el resultado del siguiente comando te permite verificar el estado de un objeto RootSync:

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

Comprueba la anotación de token de un objeto

Se recomienda que sepas cuándo el Sincronizador de configuración actualizó por última vez un objeto de Kubernetes administrado. Cada objeto administrado se anota con el hash de la confirmación de Git cuando se modificó por última vez y la ruta de acceso a la configuración que contenía la modificación.

Por ejemplo, para obtener la anotación de un ClusterRoleBinding llamado namespace-readers, ejecuta el siguiente comando:

kubectl get clusterrolebinding namespace-readers

El resultado es similar a este:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  annotations:
    configmanagement.gke.io/source-path: cluster/namespace-reader-clusterrolebinding.yaml
    configmanagement.gke.io/token: bbb6a1e2f3db692b17201da028daff0d38797771
  name: namespace-readers
...

Para obtener más información, consulta Etiquetas y anotaciones.

Acelera el diagnóstico con Gemini Cloud Assist

A veces, la causa del problema no es evidente de inmediato, incluso después de usar las herramientas que se describieron en las secciones anteriores. Investigar casos complejos puede llevar mucho tiempo y requiere una gran experiencia. En situaciones como esta, Gemini Cloud Assist puede ayudarte. Puede detectar automáticamente patrones ocultos, mostrar anomalías y proporcionar resúmenes para ayudarte a identificar rápidamente una causa probable.

Accede a Gemini Cloud Assist

Para acceder a Gemini Cloud Assist, completa los siguientes pasos:

  1. En la consola de Google Cloud , ve a cualquier página.

  2. En la barra de herramientas de la consola de Google Cloud , haz clic en Abrir o cerrar el chat de Gemini Cloud Assist.

    Se abrirá el panel de Cloud Assist. Puedes hacer clic en las instrucciones de ejemplo si se muestran, o bien ingresar una instrucción en el campo Ingresa una instrucción.

Explora ejemplos de instrucciones

Para ayudarte a comprender cómo Gemini Cloud Assist puede ayudarte, aquí tienes algunos ejemplos de instrucciones:

Tema Situación Ejemplo de instrucción Cómo puede ayudar Gemini Cloud Assist
Configuración inicial Un ingeniero de plataformas está configurando Sincronizador de configuración por primera vez para poder administrar clústeres de GKE desde un repositorio de Git. ¿Cómo configuro el Sincronizador de configuración para sincronizar manifiestos de mi repositorio de GitHub con mi clúster de GKE? Gemini Cloud Assist proporciona una guía paso a paso para configurar Sincronizador de configuración, que abarca el registro de la flota y la habilitación de la función, y explica detalles como la URL del repositorio, la rama, la ruta y los métodos de autenticación (por ejemplo, public, token o ssh).
Soluciona problemas de errores de sincronización Un desarrollador confirma un manifiesto nuevo, pero el recurso no se aplica al clúster y el estado de sincronización muestra un código de error. Mi objeto RootSync de Config Sync muestra "KNV2009: the server could not find the requested resource". ¿Qué significa y cómo lo soluciono? Gemini Cloud Assist analiza el código de error y explica que, por lo general, indica que Sincronizador de configuración no puede ubicar un recurso de Kubernetes esperado ni interactuar con él. Luego, se detallan las causas comunes, como la falta de permisos de RBAC, el exceso de límites de tamaño de objetos de recursos, las rutas de directorio incorrectas, los conflictos de inventario externos y los problemas con los recursos no administrados, y se proporcionan pasos específicos para solucionar problemas en cada caso.
Administra varios equipos Una organización necesita permitir que los equipos de aplicaciones administren sus propias configuraciones en espacios de nombres específicos sin darles acceso al repositorio central de la plataforma. ¿Cuál es la diferencia entre un objeto RootSync y un objeto RepoSync en Sincronizador de configuración? ¿Cuándo debo usar RepoSync?

Gemini Cloud Assist explica la diferencia principal entre los objetos RootSync y RepoSync: Los objetos RootSync tienen alcance en todo el clúster y, por lo general, los usan los administradores para las configuraciones en todo el clúster, mientras que los objetos RepoSync tienen alcance en el espacio de nombres y están diseñados para que los equipos de aplicaciones administren los recursos dentro de un espacio de nombres específico, lo que promueve la delegación y la arquitectura multiusuario.

Gemini Cloud Assist también detalla situaciones en las que se deben usar objetos RepoSync y enfatiza sus beneficios para la arquitectura de múltiples arrendatarios y la reducción del área afectada por errores de configuración.
Validación proactiva Un desarrollador quiere asegurarse de que su manifiesto nuevo sea válido antes de confirmarlo en el repositorio para evitar que se interrumpa la sincronización en producción. ¿Cómo puedo verificar si hay errores de Sincronizador de configuración en mis manifiestos de Kubernetes en mi máquina local antes de enviarlos al repositorio de Git? Gemini Cloud Assist explica cómo verificar los manifiestos de Kubernetes para detectar errores del Sincronizador de configuración con la herramienta de línea de comandos de nomos. Se detalla cómo usar el comando nomos vet para la validación de sintaxis y el comando nomos hydrate para obtener una vista previa de las configuraciones renderizadas de Kustomize o Helm. Gemini Cloud Assist también describe un flujo de trabajo recomendado para integrar estas verificaciones antes de enviar los cambios a Git.

Para obtener más información, consulta los siguientes recursos:

Usa las investigaciones de Gemini Cloud Assist

Además del chat interactivo, Gemini Cloud Assist puede realizar análisis más automatizados y detallados a través de las investigaciones de Gemini Cloud Assist. Esta función se integra directamente en flujos de trabajo como el Explorador de registros y es una poderosa herramienta de análisis de causa raíz.

Cuando inicias una investigación a partir de un error o un recurso específico, Gemini Cloud Assist analiza los registros, las configuraciones y las métricas. Utiliza estos datos para generar observaciones e hipótesis clasificadas sobre las posibles causas raíz y, luego, te proporciona los próximos pasos recomendados. También puedes transferir estos resultados a un caso de asistencia para proporcionar contexto valioso que te ayude a resolver el problema más rápido. Google Cloud

Para obtener más información, consulta Investigaciones de Gemini Cloud Assist en la documentación de Gemini.

Lee documentación adicional para solucionar problemas

Si los problemas persisten, los siguientes recursos pueden ser útiles:

  • Si recibiste un mensaje de error, consulta la página de referencia de errores para obtener sugerencias sobre cómo resolverlo.

  • Comprueba si el problema que tienes se debe a un problema conocido.

  • Si tienes dificultades con un área específica, es posible que te ayude una de las guías de solución de problemas específicas que se enumeran en la sección Soluciona problemas por tipo del índice.

¿Qué sigue?