Usa el comando nomos

El comando nomos (nomos.exe en Windows) es una herramienta de línea de comandos opcional que puedes instalar de forma local, por ejemplo, en una estación de trabajo o una laptop. Puedes usar el comando nomos para verificar la sintaxis de los archivos de configuración antes de confirmarlos en el repositorio y depurar problemas. El Sincronizador de configuración, el clúster y el repositorio.

Requisitos previos

Antes de que puedas usar el comando nomos a fin de interactuar con un clúster, el operador ya debe estar instalado en el clúster de destino y debes configurar el comando kubectl para que se autentique en el clúster de destino mediante la generación de una entrada de kubeconfig.

Instala el comando nomos

El comando nomos es un objeto binario compilado a partir de código de Go. Es opcional y no se incluye cuando instalas el Sincronizador de configuración. Para instalar el comando nomos, instala el SDK de Cloud. Si usas Cloud Shell, el SDK de Cloud viene preinstalado.

Si no tienes el SDK de Cloud, puedes descargar el comando nomos para cada versión del Sincronizador de configuración. Para obtener más información, consulta Descargas de Anthos Config Management.

Pasos adicionales para clientes de macOS y Linux

Después de descargar el objeto binario, configúralo para que sea ejecutable:

chmod +x /path/to/nomos

Puedes mover el comando a una ubicación en la que tu sistema busque objetos binarios, como /usr/local/bin, o puedes ejecutar el comando mediante su ruta de acceso completamente calificada.

Uso básico

Para la sintaxis del comando básico, usa el argumento --help:

nomos --help

El comando nomos lee desde el clon local de tu repositorio. Usa la marca --path para especificar la ubicación del nivel superior del repositorio. De forma predeterminada, --path está configurado como . o el directorio actual. Por ejemplo:

nomos --path=path/to/your/repo vet

Comprueba el estado de la instalación

Puedes supervisar el estado del Sincronizador de configuración en todos los clústeres inscritos con el comando nomos status. Para cada clúster, nomos status informa sobre el hash de la confirmación de Git que se aplicó por última vez al clúster, así como los errores que se produjeron cuando se intentó aplicar los cambios recientes. Por ejemplo:

nomos status

Resultado de ejemplo:

my_managed_cluster-1
  --------------------
  <root>   git@github.com:foo-corp/acme@main
  SYNCED   f52a11e4

my_managed_cluster-2
  --------------------
  <root>   git@github.com:foo-corp/acme@main
  PENDING  9edf8444

my_managed_cluster-3
  --------------------
  <root>   git@github.com:foo-corp/acme@main
  ERROR    f52a11e4
  Error:   KNV1021: No CustomResourceDefinition is defined for the resource in the cluster.

my_managed_cluster-4
  --------------------
  NOT INSTALLED

my_managed_cluster-5
  --------------------
  <root>   git@github.com:foo-corp/acme@main
  SYNCED   f52a11e4

En este resultado, se ilustra lo siguiente:

  • my_managed_cluster-1 y my_managed_cluster-5 sincronizaron el cambio más reciente.
  • my_managed_cluster-2 todavía se está sincronizando.
  • my_managed_cluster-3 tiene un error que impidió que se aplicara el cambio. En este caso, a managed-cluster-3 le falta una CRD que los otros clústeres tienen instalada.
  • my-managed-cluster-4 no tiene instalado el Sincronizador de configuración.

Comprueba el estado de la instalación (varios repositorios)

Si habilitaste la opción varios repositorios en tu clúster, puedes sincronizar desde varios repositorios de Git. El comando nomos status imprime el estado de cada repositorio, agrupado por clúster. Por ejemplo:

nomos status

Resultado de ejemplo:

my_managed_cluster-1
  --------------------
  <root>   git@github.com:foo-corp/acme/admin@main
  SYNCED   f52a11e4
  --------------------
  bookstore  git@github.com:foo-corp/acme/bookstore@v1
  SYNCED     34d1a8c8

my_managed_cluster-2
  --------------------
  <root>   git@github.com:foo-corp/acme@main
  ERROR    f52a11e4
  Error:   KNV1021: No CustomResourceDefinition is defined for the resource in the cluster.
  --------------------
  bookstore  git@github.com:foo-corp/acme/bookstore@v1
  SYNCED     34d1a8c8

Puedes ver que cada uno de los clústeres está configurado con dos repositorios de Git. El repositorio <root> pertenece al administrador del clúster y el repositorio bookstore puede pertenecer a un equipo de desarrollo de aplicaciones.

Información sobre la última confirmación sincronizada

nomos status muestra el hash de confirmación de Git más reciente que se aplicó al clúster en la salida en status.sync.commit. Para obtener este valor, consulta el objeto RootSync o RepoSync y observa el campo status.sync:

Por ejemplo, para consultar un objeto RootSync, ejecuta el siguiente comando:

kubectl get rootsyncs.configsync.gke.io -n config-management-system root-sync -o yaml

Salida de ejemplo:

apiVersion: configsync.gke.io/v1beta1
kind: RootSync
status:
  sync:
    commit: f1739af550912034139aca51e382dc50c4036ae0
    lastUpdate: "2021-04-20T00:25:01Z"

Para consultar un objeto RepoSync, ejecuta el siguiente comando:

kubectl get reposync.configsync.gke.io -n NAMESPACE repo-sync -o yaml

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

Salida de ejemplo:

apiVersion: configsync.gke.io/v1beta1
kind: RepoSync
status:
  sync:
    commit: ed95b50dd918cf65d8908f7561cb8d8d1f179c2f
    lastUpdate: "2021-04-20T00:25:20Z"

Esta confirmación representa la confirmación más reciente en el clúster. Sin embargo, no todos los recursos del clúster se ven afectados por cada confirmación. Para ver la confirmación más reciente de un recurso específico, consulta el recurso específico y observa metadata.annotations.configmanagement.gke.io/token. Por ejemplo:

kubectl get clusterroles CLUSTER_ROLE_NAME -o yaml

Reemplaza CLUSTER_ROLE_NAME por el nombre de la función de clúster que deseas consultar.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  annotations:
    configmanagement.gke.io/token: ed95b50dd918cf65d8908f7561cb8d8d1f179c2f

Marcas de estado de nomos

Para personalizar nomos status, agrega las siguientes marcas:

Flag Descripción
--contexts Acepta una lista de contextos separados por comas para usar en comandos de varios clústeres. La configuración predeterminada es todos los contextos. Usa "" para no tener contextos.
-h o --help Ayuda para el comando nomos status.
--namespace Acepta una string. Usa la marca namespace para limitar el comando a un repositorio de espacio de nombres específico. Deja la configuración para obtener todos los repositorios. Esta marca solo está disponible si habilitaste el modo de varios repositorios.
--poll Usa la marca poll para ejecutar nomos status continuamente y hacer que vuelva a mostrar la tabla de estado a intervalos regulares. Por ejemplo 3s. Deja esta marca sin configurar para ejecutar nomos status una vez
--resources Se acepta true o false. Si es true, nomos status muestra el estado a nivel de recurso para el repositorio raíz o de espacio de nombres cuando se sincroniza desde varios repositorios. El valor predeterminado es true.
--timeout Tiempo de espera para conectarse a cada clúster. El valor predeterminado es 3s.

Verifica el estado de cada recurso

En nomos 1.8.0 o versiones posteriores, puedes verificar si los recursos administrados por el Sincronizador de configuración están listos con el comando nomos status. Este comando informa el estado de cada recurso individual de tu repositorio de Git. Por ejemplo:

nomos status --contexts my_managed_cluster_4

Resultado de ejemplo:

my_managed_cluster_4
  --------------------
  <root>   https:/github.com/GITHUB_USERNAME/anthos-config-management-samples/namespace-specific-policy/configsync@main
  SYNCED   bf8655aa
  Managed resources:
     NAMESPACE   NAME                                                             STATUS
                 namespace/foo                                                    Current
                 namespace/istio-system                                           Current
                 namespace/tenant-a                                               Current
                 namespace/tenant-b                                               Current
                 namespace/tenant-c                                               Current
     tenant-a    networkpolicy.networking.k8s.io/deny-all                         Current
     tenant-a    role.rbac.authorization.k8s.io/tenant-admin                      Current
     tenant-a    rolebinding.rbac.authorization.k8s.io/tenant-admin-rolebinding   Current
     tenant-b    networkpolicy.networking.k8s.io/deny-all                         Current
     tenant-b    role.rbac.authorization.k8s.io/tenant-admin                      Current
     tenant-b    rolebinding.rbac.authorization.k8s.io/tenant-admin-rolebinding   Current
     tenant-c    networkpolicy.networking.k8s.io/deny-all                         Current
     tenant-c    role.rbac.authorization.k8s.io/tenant-admin                      Current
     tenant-c    rolebinding.rbac.authorization.k8s.io/tenant-admin-rolebinding   Current

En este ejemplo, todos los recursos tienen un estado de Current, lo que significa que el estado del recurso coincide con el estado que deseas.

El estado puede ser uno de los siguientes valores:

  • InProgress: el estado real del recurso aún no alcanzó el estado que especificaste en el manifiesto del recurso. Esto significa que la conciliación del recurso aún no se completó. Los recursos recién creados suelen comenzar con este estado, aunque algunos recursos como ConfigMaps son Current de inmediato.

  • Failed: El proceso de conciliar el estado real con el estado que deseas encontró un error o realizó un progreso insuficiente.

  • Current: El estado real del recurso coincide con el estado que deseas. El proceso de conciliación se considera completo hasta que haya cambios en el estado deseado o el real.

  • Terminating: La instancia está en proceso de eliminación.

  • NotFound: El recurso no existe en el clúster.

  • Unknown: El Sincronizador de configuración no puede determinar el estado del recurso.

Para desactivar la visualización del estado a nivel de recursos, agrega --resources=false al comando nomos status.

Comprueba si hay errores en el repositorio

Antes de confirmar un archivo de configuración en el repositorio, usa el comando nomos vet para verificar la sintaxis y la validez de los archivos de configuración del repositorio:

nomos vet

Si se encuentran errores de sintaxis, el comando nomos vet se cierra con un estado distinto de cero y registra los mensajes de error en STDERR.

marcas de nomos vet

Para personalizar nomos vet, agrega las siguientes marcas:

Flag Descripción
--clusters Acepta una lista de nombres de clúster separados por comas para usar en comandos de varios clústeres. Se aplica de forma predeterminada a todos los clústeres. Usa "" para no usar clústeres.
-h o --help Ayuda para el comando nomos vet.
--namespace Acepta una string. Si se configura, valida el repositorio como un repositorio de espacio de nombres con el nombre proporcionado. Establece --source-format=unstructured de forma automática.
--no-api-server-check Acepta un valor booleano. Si es true, inhabilita la comunicación con el servidor de la API para la detección. Para obtener más información sobre esta marca, consulta la sección Validación del servidor.
--path Acepta una string. La ruta al directorio raíz del repositorio del Sincronizador de configuración. El color predeterminado es ".".
--source-format Se acepta hierarchy o unstructured. Si hierarchy o no se configura, valida el repositorio como un repositorio jerárquico. Si es unstructured, valida el repositorio como un repositorio no estructurado. Esta marca es obligatoria si usas un repositorio no estructurado.
--keep-output Acepta un valor booleano. Si es true, el resultado procesado se guarda en la ubicación que puedes especificar con la marca --output. Esta marca está disponible en las versiones 1.9.0 y posteriores.
--output Acepta una string. La ruta de acceso al resultado procesado. La configuración predeterminada es el directorio compiled. Si --keep-output se configura como false, esta marca se ignora. Esta marca está disponible en las versiones 1.9.0 y posteriores.
--format Se acepta yaml o json. El formato del resultado. El valor predeterminado es yaml. Esta marca está disponible en las versiones 1.9.0 y posteriores.

Validación del servidor

Si nomos vet no puede determinar si el tipo tiene espacios de nombres, nomos se conecta al servidor de la API. Debido a que nomos comprende de forma predeterminada los tipos principales de Kubernetes y las CRD del Sincronizador de configuración, este solo intenta conectarse al servidor de la API si hay CR que no tengan una CRD correspondiente declarada. En este caso, si el servidor de la API no tiene una CRD aplicada, nomos vet muestra un error. Para inhabilitar esta comprobación y suprimir los errores de CRD faltantes, pasa la marca --no-api-server-check.

Almacena en caché los metadatos del servidor de la API

En lugar de suprimir las verificaciones del servidor de la API, puedes almacenar en caché los datos en el servidor de API para nomos vet. Para almacenar en caché tu api-resources, completa los siguientes pasos:

  1. Conéctate a un clúster que tenga todas las CRD que necesitas para tu repositorio. El clúster no necesita tener el Sincronizador de configuración habilitado.
  2. Ve al policyDir de tu repositorio. Este es el mismo directorio que se especifica en tu recurso ConfigManagement o RootSync.
  3. Ejecuta el siguiente comando: kubectl api-resources > api-resources.txt Este comando crea un archivo llamado api-resources.txt que contiene el resultado exacto de kubectl api-resources.

A partir de ahora, las ejecuciones de nomos vet dentro del repositorio conocen esas definiciones de tipos. Si se quita el archivo api-resources.txt o se le cambia el nombre, nomos vet no podrá encontrarlo. nomos vet seguirá intentando conectarse al clúster si encuentra manifiestos de tipos no declarados en api-resources.txt (a menos que se ingrese --no-api-server-check).

El archivo api-resources.txt solo afecta la forma en que funciona la CLI. No modifica el comportamiento del Sincronizador de configuración de ningún modo.

Es posible tener entradas adicionales en el archivo api-resources.txt, que son para tipos que no están en la validación del repositorio. nomos vet importa las definiciones, pero no realiza ninguna acción con ellas.

Actualiza api-resources.txt

Después de asegurarte de que todas las CRD que deseas están en el clúster, ejecuta el siguiente comando:

kubectl api-resources > api-resources.txt

Comprueba de forma automática si hay errores de sintaxis durante la confirmación

Si confirmas un archivo con errores de JSON o YAML, el Sincronizador de configuración no aplica el cambio. Sin embargo, puedes evitar que estos tipos de errores ingresen al repositorio si usas hooks del cliente o del servidor.

Usa nomos vet en un hook de confirmación previa de Git

Puedes configurar un hook de confirmación previa que ejecute nomos vet para verificar si hay errores de sintaxis cuando confirmas un cambio en el clon local de Git de tu repositorio. Si un hook de confirmación previa sale con un estado distinto de cero, la operación git commit fallará.

Para ejecutar el comando nomos vet como un hook de confirmación previa, edita el archivo .git/hooks/pre-commit en tu repositorio (ten en cuenta que .git comienza con un carácter .). Es posible que debas crear el archivo de forma manual. Agrega el comando nomos vet a una línea nueva en la secuencia de comandos. El argumento --path es opcional.

nomos vet --path=/path/to/repo

Asegúrate de que el archivo pre-commit sea ejecutable:

chmod +x .git/hooks/pre-commit

Ahora, cuando ejecutes un comando git commit en el clon de tu repositorio, nomos vet se ejecutará de manera automática.

El repositorio en sí no realiza un seguimiento del contenido del directorio .git/ del repositorio. Este contenido no puede confirmarse en el repositorio en la misma ubicación. Puedes crear un directorio en el repositorio para los hooks de Git, y las personas que usan el repositorio pueden copiar los hooks en el lugar apropiado en su clon local.

Usa nomos vet en un hook del servidor

Git proporciona un mecanismo para ejecutar comprobaciones en el servidor, en lugar de en el cliente, durante una operación git push. Si la verificación falla, el git push también falla. El cliente no puede pasar por alto estos hooks del servidor. El método para configurar los hooks del servidor depende de cómo esté alojado tu servidor de Git. Consulta uno de los siguientes vínculos para obtener más información o consulta la documentación de tu servicio de hosting de Git.

Visualiza todas las configuraciones del repositorio

Puedes usar el comando nomos hydrate para ver el contenido combinado de tu repositorio en cada clúster inscrito.

Si ejecutas nomos hydrate sin opciones, se crea un directorio compiled/ en el directorio de trabajo actual. Dentro de ese directorio, se crea un subdirectorio para cada clúster inscrito, con los archivos de configuración completamente resueltos que el operador aplica al clúster.

Este comando también se puede usar para convertir un repositorio jerárquico en uno o más repositorios no estructurados mediante el contenido del directorio compiled/.

Marcas de nomos hyte

Para personalizar nomos hydrate, agrega las siguientes marcas:

Flag Descripción
--clusters Acepta una lista de nombres de clúster separados por comas. Usa esta marca para limitar la salida a un solo clúster o a una lista de clústeres. Se aplica de forma predeterminada a todos los clústeres. Usa "" para no usar clústeres.
--flat Si está habilitada, imprime todos los resultados en un solo archivo. Usa esta marca si deseas emular el comportamiento de nomos view.
-h o --help Ayuda para el comando nomos hydrate.
--format Acepta yaml o json. El formato del resultado. El valor predeterminado es yaml. Esta marca está disponible en las versiones 1.9.0 y posteriores.
--no-api-server-check Acepta un valor booleano. Si es true, inhabilita la comunicación con el servidor de la API para la detección. Para obtener más información sobre esta marca, consulta la sección Validación del servidor.
--output Acepta una string. La ubicación en la que se escribe la configuración hidratada. El valor predeterminado es el directorio compiled. Si --flat no está habilitado, se escribe cada manifiesto de recurso como un archivo independiente. Si --flat está habilitado, se escribe en un archivo único que contiene todos los manifiestos de recursos.
--path Acepta una string. La ruta al directorio raíz del repositorio del Sincronizador de configuración. El color predeterminado es ".".
--source-format Se acepta hierarchy o unstructured. Si hierarchy o no se configura, valida el repositorio como un repositorio jerárquico. Si es unstructured, valida el repositorio como un repositorio no estructurado. Esta marca es obligatoria si usas un repositorio no estructurado y está disponible en las versiones 1.9.0 y posteriores.

nomos view

Cuando el Sincronizador de configuración importa archivos de configuración del repositorio, los convierte en CustomResourceDefinitions (CRD) de tipo ClusterConfig o NamespaceConfig. El comando nomos view te permite ver las CRD resultantes del estado actual de tu repositorio en formato JSON. Esto puede ser útil antes de confirmar los cambios o para depurar problemas de los archivos de configuración que no son obvios mediante el comando nomos vet.

nomos view --path=/path/to/your/repo

Crea un informe de errores

Si tienes un problema con el Sincronizador de configuración que requiera la ayuda del equipo de asistencia de Google Cloud, puedes proporcionarles información de depuración valiosa mediante el comando nomos bugreport. Puedes usar este comando en uno o varios repositorios.

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.

Inicializa un repositorio jerárquico

Puedes organizar tu repositorio de manera arbitraria si usas un repositorio no estructurado. Si usas un repositorio jerárquico, debes ejecutar el comando nomos init para inicializar un directorio jerárquico:

nomos init

Esto crea la estructura de directorios básica de un repositorio jerárquico, incluidos los directorios system/, cluster/ y namespaces/.

Marcas init de nomos

Para personalizar nomos init, agrega las siguientes marcas:

Flag Descripción
--force Escribir en el directorio incluso si no está vacío y reemplaza los archivos en conflicto
-h o --help Ayuda para el comando nomos init.
--path Acepta una string. El directorio raíz para usar en el repositorio de Anthos Config Management. El valor predeterminado es ".".

Soluciona problemas

En Linux, es posible que veas el siguiente error cuando ejecutes un comando nomos:

failed to create client configs: while getting config path: failed to get current user: user: Current not implemented on linux/amd64

Para solucionar este problema, crea una variable de entorno USER:

export USER=$(whoami)

¿Qué sigue?