Usar 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, como en una estación de trabajo o una laptop. Puedes usar el comando nomos para interactuar con el operador de Config Management, verificar la sintaxis de los archivos de configuración antes de confirmarlos en el repositorio y depurar los problemas con el Sincronizador de configuración, tu clúster o tu repositorio.

Requisitos previos

Antes de que puedas usar el comando nomos para interactuar con un clúster, el operador ya debe estar instalado en el clúster de destino y el comando kubectl debe estar configurado para autenticarse en este clúster. Para obtener más información, consulta Genera una entrada 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 en una instalación predeterminada del Sincronizador de configuración.

A fin de descargar el comando nomos según la versión del Sincronizador de configuración, consulta Descargas.

Nota: El Sincronizador de configuración requiere una autorización de Anthos activa. De lo contrario, la descarga fallará con un error 404 File not found.
Para obtener más información, consulta los precios de Anthos.

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

Los comandos nomos y nomos.exe incluyen subcomandos para inicializar tu repositorio, comprobar errores de sintaxis, obtener el estado de cada clúster inscrito y ver tu repositorio como una serie de CustomResourceDefinitions.

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.

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

Comprueba el estado de la instalación

Puedes verificar si el Sincronizador de configuración está instalado y configurado de forma correcta en todos tus clústeres mediante el comando nomos status. Informa sobre cualquier error que impida que se ejecute el Sincronizador de configuración. Por ejemplo:

nomos status
my_managed_cluster-1
  --------------------
  NOT INSTALLED

my_managed_cluster-2
  --------------------
  <root>   git@github.com:foo-corp/acme@main
  ERROR
  Error:   git-creds not found. Create git-creds secret in config-management-system namespace.

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

En esta salida, el Sincronizador de configuración no está instalado en managed-cluster-1. Está instalado, pero no está configurado de manera correcta en managed-cluster-2. Está instalado y se ejecuta de manera correcta en managed-cluster-3.

Además, el motivo por el que managed-cluster-2 no está configurado es que el Secret git-creds no está presente.

Marcas de estado de nomos

Para personalizar nomos status, agrega las siguientes marcas:

Flag Descripción
--contexts strings 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 string Repositorio de espacio de nombres para el que se debe obtener el estado (solo varios repositorios, no lo configures para obtener todos los repositorios).
--poll duration Intervalo de sondeo (dejar sin configurar para que se ejecute una vez).
--timeout duration Tiempo de espera para conectarse a cada clúster (el valor predeterminado es 3 segundos).

Inicializa un repositorio nuevo

Para inicializar un nuevo repositorio del Sincronizador de configuración, crea un directorio vacío, cambia a él y, luego, inicializa un repositorio de Git nuevo:

mkdir my-repo
cd my-repo
git init

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

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.

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 el resultado de todos los archivos de configuración en el 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/.

Puedes especificar el nombre del directorio de salida si proporcionas una ruta de acceso de directorio como argumento del comando:

nomos hydrate [/path/to/directory]

Para limitar la salida a un solo clúster o a una lista de clústeres, usa la marca --clusters y proporciona una lista de nombres de clúster separados por comas.

Para emular el comportamiento de nomos view y guardar la configuración efectiva en un solo archivo, usa la marca --flat.

Para obtener más información, usa la marca --help.

nomos hydrate --flat

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

Comprueba si hay errores en los clústeres

Cada vez que envías una confirmación de Git al repositorio, el operador detecta el cambio y aplica la configuración nueva a todos los clústeres inscritos. Puedes supervisar el estado del Sincronizador de configuración en todos los clústeres inscritos con el comando nomos status. Para cada clúster, 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
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

Puedes ver que dos de los clústeres sincronizaron el cambio más reciente, un clúster todavía se está sincronizando y un clúster tiene un error que impidió que se aplicara el cambio. En este caso, parece que a managed-cluster-3 le falta una CRD que los otros clústeres tienen instalada.

De forma predeterminada, el comando nomos status imprime el estado de cada clúster y, luego, se cierra. Sin embargo, puedes usar la marca poll para ejecutar el comando de forma continua y hacer que vuelva a mostrar la tabla de estado a intervalos regulares.

nomos status --poll 2s

Verifica si hay errores en tus clústeres (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
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.

De forma predeterminada, el comando nomos status imprime el estado de todos los repositorios del clúster. Sin embargo, puedes usar la marca namespace para limitar el comando a un repositorio específico de espacio de nombres. Esto permite al equipo de aplicaciones usar nomos status en su repositorio:

nomos status --namespace bookstore

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

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.

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

Crea una variable de entorno USER para solucionar este problema:

export USER=$(whoami)

¿Qué sigue?