Usa la herramienta de línea de comandos nomos

La herramienta de línea de comandos nomos es una herramienta opcional del Sincronizador de configuración que puedes usar para obtener el estado del Sincronizador de configuración y el estado de sincronización de tu fuente de información. La herramienta de nomos te proporciona los siguientes comandos:

Requisitos previos

Antes de que puedas usar la herramienta nomos para interactuar con un clúster, el Sincronizador de configuración ya debe estar instalado en el clúster de destino. También debes instalar y configurar la herramienta de línea de comandos de kubectl. Si interactúas con clústeres de Google Kubernetes Engine, asegúrate de instalar también gke-gcloud-auth-plugin.

La herramienta nomos admite la vista previa y la validación de los parámetros de configuración de Kustomize y los gráficos de Helm. Antes de poder usar esta función, instala Kustomize y Helm en tu estación de trabajo local. Si tu fuente de información solo contiene parámetros de configuración renderizados por completo, Kustomize y Helm son opcionales.

Instala la herramienta nomos

La herramienta nomos es un objeto binario compilado a partir de código de Go y puedes instalarlo de forma local, por ejemplo, en una estación de trabajo o una laptop.

La herramienta nomos no se incluye cuando instalas el Sincronizador de configuración. Para instalar la herramienta nomos, puedes realizar la instalación de Google Cloud CLI. Si usas Cloud Shell, Google Cloud CLI viene preinstalada.

Si no tienes Google Cloud CLI, te recomendamos que uses gcloud components install nomos para instalar la herramienta nomos. Instalar la herramienta nomos con Google Cloud CLI te permite usar gcloud components update para actualizar la herramienta nomos a la versión más reciente.

Para obtener más información sobre las formas alternativas de instalar la herramienta nomos, consulta Descargas.

Uso básico

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

nomos --help

La herramienta nomos lee desde la clonación local de tu fuente de información. Usa la marca --path para especificar la ubicación del nivel superior de la fuente de información. De forma predeterminada, --path está configurado como . o el directorio actual. Por ejemplo:

nomos vet --path=PATH_TO_SOURCE --source-format unstructured

Verifica el estado del Sincronizador de configuració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 que se aplicó por última vez al clúster, así como los errores que se produjeron cuando se intentó aplicar los cambios recientes.

También puedes usar nomos status para verificar si los recursos administrados por el Sincronizador de configuración están listos. nomos status informa el estado de cada recurso individual en la columna STATUS de la sección Managed resources del resultado.

En el siguiente ejemplo, se muestran algunas de las diferentes condiciones que podría informar el comando nomos status:

nomos status

Resultado de ejemplo:

MANAGED_CLUSTER_1
  --------------------
  <root>   git@github.com:foo-corp/acme@main
  SYNCED   f52a11e4
  Managed resources:
   NAMESPACE   NAME                                                                   STATUS
               k8snoexternalservices.constraints.gatekeeper.sh/no-internet-services   Current
               namespace/hello                                                        Current

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

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.

MANGED_CLUSTER_4
  --------------------
  NOT INSTALLED

MANAGED_CLUSTER_5
  --------------------
  <root>   git@github.com:foo-corp/acme/admin@main
  SYNCED   f52a11e4
  Managed resources:
   NAMESPACE   NAME                                                                   STATUS
                namespace/gamestore                                                   Current
                namespace/monitoring                                                  Current
   gamestore    reposync.configsync.gke.io/repo-sync                                  Current
   gamestore    rolebinding.rbac.authorization.k8s.io/gamestore-admin                 Current
   gamestore    rolebinding.rbac.authorization.k8s.io/gamestore-webstore-admin        Current
   monitoring   deployment.apps/prometheus-operator                                   Current
   monitoring   prometheus.monitoring.coreos.com/acm                                  Current
   monitoring   service/prometheus-acm                                                Current
   monitoring   service/prometheus-operator                                           Current
   monitoring   serviceaccount/prometheus-acm                                         Current
   monitoring   serviceaccount/prometheus-operator                                    Current
   monitoring   servicemonitor.monitoring.coreos.com/acm-service                      Current
  --------------------
  bookstore  git@github.com:foo-corp/acme/bookstore@v1
  SYNCED     34d1a8c8
  Managed resources:
   NAMESPACE   NAME                                 STATUS
   gamestore   configmap/store-inventory            Current
   gamestore   webstore.marketplace.com/gameplace   Current

En este resultado, se ilustra lo siguiente:

• MANAGED_CLUSTER_1 sincronizó el cambio más reciente en la fuente de información y todos los recursos administrados tienen el estado Current. Un estado de Current significa que el estado del recurso coincide con el estado que deseas.
• MANAGED_CLUSTER_2 todavía se está sincronizando.
• MANAGED_CLUSTER_3 tiene un error que impidió que se aplicara el cambio. En este ejemplo, MANAGED_CLUSTER_3 tiene el error KNV1021, ya que falta una CustomResourceDefinition (CRD) que los otros clústeres tienen instalada.
• MANAGED_CLUSTER_4 no tiene instalado el Sincronizador de configuración.
• MANAGED_CLUSTER_5 se está sincronizando desde dos repositorios de Git. La fuente de información de <root> pertenece al administrador del clúster y la fuente de información de bookstore puede pertenecer a un equipo de desarrollo de aplicaciones.

Estados de recursos administrados

El estado de tus recursos administrados 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 ha completado. 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.

Información sobre la última confirmación sincronizada

El comando nomos status muestra el hash de confirmación 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

Resultado 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 la fuente de información de tu espacio de nombres.

Resultado 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 del rol del 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 el comando nomos status, agrega las siguientes marcas:

Permisos necesarios

Si eres propietario del proyecto, tienes el rol de RBAC cluster-admin y puedes usar el comando nomos status para cualquier clúster de tu proyecto sin agregar más permisos. Si no tienes el rol cluster-admin, puedes usar nomos status si creas el siguiente ClusterRole:

1. Crea un archivo llamado nomos-status-reader.yaml y copia el ClusterRole siguiente en él: Las reglas que necesitas difieren en función de si usas objetos RootSync y RepoSync.

   Usar objetos RootSync y RepoSync

   # nomos-status-reader.yaml
   apiVersion: rbac.authorization.k8s.io/v1
   kind: ClusterRole
   metadata:
     name: nomos-status-reader
   rules:
   - apiGroups: ["configsync.gke.io"]
     resources: ["reposyncs", "rootsyncs"]
     verbs: ["get"]
   - nonResourceURLs: ["/"]
     verbs: ["get"]
   

   No usar objetos RootSync y RepoSync

   apiVersion: rbac.authorization.k8s.io/v1
   kind: ClusterRole
   metadata:
     name: nomos-status-reader
   rules:
   - apiGroups: ["configmanagement.gke.io"]
     resources: ["configmanagements", "repos"]
     verbs: ["get", "list"]
   - nonResourceURLs: ["/"]
     verbs: ["get"]
   

2. Aplica el archivo nomos-status-reader.yaml:

   kubectl apply -f nomos-status-reader.yaml
   

Comprueba si hay errores en la fuente de información

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

nomos vet --source-format unstructured

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 el comando nomos vet, agrega las siguientes marcas:

Validación del servidor

Si el comando nomos vet no puede determinar si el tipo tiene espacios de nombres, la herramienta nomos se conecta al servidor de la API. Debido a que la herramienta 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, el comando nomos vet muestra el error KNV1021. 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 el comando 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 fuente de información. El clúster no necesita tener el Sincronizador de configuración habilitado.
2. Ve al policyDir de tu fuente de información. 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 de la fuente de información 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 herramienta nomos. 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 fuente de validación. 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 a la fuente de información si usas hooks del cliente o del servidor.

Usa nomos vet en un hook de confirmación previa

Puedes configurar un hook de confirmación previa que ejecute el comando nomos vet para verificar si hay errores de sintaxis cuando confirmas un cambio en la clonación 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 fuente de información (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. Establece el argumento --source-format en el formato de origen del repositorio.

nomos vet --path=/path/to/repo --source-format unstructured

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

chmod +x .git/hooks/pre-commit

Ahora, cuando ejecutes un comando git commit en la clonación de tu fuente de información, nomos vet se ejecutará de manera automática.

La fuente de información en sí no realiza un seguimiento del contenido del directorio .git/. Este contenido no puede confirmarse en la fuente de información en la misma ubicación. Puedes crear un directorio en la fuente de información para los hooks de Git, y las personas que usan la fuente de información pueden copiar los hooks en el lugar apropiado en su clonación 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.

• GitHub
• Cloud Source Repositories
• Bitbucket
• GitLab
• Servidor de Git que se aloja a sí mismo

Cómo ver todas las configuraciones en la fuente de información

Puedes usar el comando nomos hydrate para ver el contenido combinado de tu fuente de confianza 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 puede convertir una fuente de información jerárquica en una o más fuentes de información no estructuradas mediante el contenido del directorio compiled/.

Marcas de nomos hydrate

Para personalizar el comando nomos hydrate, agrega las siguientes marcas:

Crea un informe de errores

Si tienes un problema con el Sincronizador de configuración que requiera la ayuda del equipo de asistencia deGoogle Cloud , puedes proporcionarles información de depuración valiosa mediante el comando nomos bugreport. Puedes usar este comando en una sola fuente de información y 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. Para obtener más información sobre el contenido del archivo ZIP, consulta la referencia de informes de errores de Nomos.

Limitaciones

El comando nomos bugreport falla y produce un archivo ZIP incompleto si cualquier archivo individual supera los 1 GiB. Esto suele ocurrir debido a archivos de registro grandes.

En la siguiente tabla, se incluyen las causas más comunes de los archivos de registro grandes y cómo puedes resolverlas:

Migra de un objeto ConfigManagement a un objeto RootSync

Puedes ejecutar el comando nomos migrate para migrar de tu objeto ConfigManagement a un objeto RootSync a fin de habilitar las API RootSync y RepoSync.

Si usaste spec.enableLegacyFields para iniciar un RootSync, sigue la guía para desactivar los campos heredados en lugar de usar nomos migrate. Los campos heredados no son compatibles a partir de la versión 1.19.0.

nomos migrate admite la ejecución de prueba para obtener una vista previa del proceso de migración.

nomos migrate modifica directamente tu objeto ConfigManagement en el clúster. Para evitar que se reviertan los cambios realizados a través de nomos migrate, asegúrate de que el objeto ConfigManagement no se marque en tu fuente de información.

nomos migrate --contexts=KUBECONFIG_CONTEXTS --dry-run

Si el resultado de la ejecución de prueba se ve bien, puedes migrar el objeto ConfigManagement mediante nomos migrate:

nomos migrate --contexts=KUBECONFIG_CONTEXTS

El resultado es similar a este:

--------------------
Enabling the multi-repo mode on cluster "my_managed_cluster-1" ...
- A RootSync object is generated and saved in "/tmp/nomos-migrate/my_managed_cluster-1/root-sync.yaml".
- The original ConfigManagement object is saved in "/tmp/nomos-migrate/my_managed_cluster-1/cm-original.yaml".
- The ConfigManagement object is updated and saved in "/tmp/nomos-migrate/my_managed_cluster-1/cm-multi.yaml".
- Resources for the multi-repo mode have been saved in a temp folder. If the migration process is terminated, it can be recovered manually by running the following commands:
  kubectl apply -f /tmp/nomos-migrate/my_managed_cluster-1/cm-multi.yaml && \
  kubectl wait --for condition=established crd rootsyncs.configsync.gke.io && \
  kubectl apply -f /tmp/nomos-migrate/my_managed_cluster-1/root-sync.yaml.
- Updating the ConfigManagement object ....
- Waiting for the RootSync CRD to be established ....
- The RootSync CRD has been established.
- Creating the RootSync object ....
- Waiting for the reconciler-manager Pod to be ready ....
-   Haven't detected running Pods with the label selector "app=reconciler-manager".
-   Haven't detected running Pods with the label selector "app=reconciler-manager".
-   Haven't detected running Pods with the label selector "app=reconciler-manager".
- The reconciler-manager Pod is running.
- Waiting for the root-reconciler Pod to be ready ....
-   Haven't detected running Pods with the label selector "configsync.gke.io/reconciler=root-reconciler".
-   Haven't detected running Pods with the label selector "configsync.gke.io/reconciler=root-reconciler".
-   Haven't detected running Pods with the label selector "configsync.gke.io/reconciler=root-reconciler".
- The root-reconciler Pod is running.
- The migration process is done. Please check the sync status with `nomos status`.

Finished migration on all the contexts. Please check the sync status with `nomos status`.

Cómo revertir a la configuración anterior

Si necesitas revertir después de realizar la migración con nomos migrate, aplica el objeto ConfigManagement original. nomos migrate guarda el objeto ConfigManagement original en un archivo y lo imprime en la terminal. El nombre del archivo tiene el formato /tmp/nomos-migrate/CURRENT_CONTEXT/cm-original.yaml.

Para revertir a la configuración anterior, copia la ruta de acceso del archivo de cm-original.yaml y aplícala al clúster:

kubectl apply -f CM_ORIGINAL_PATH

Marcas de migración de nomos

Para personalizar el comando nomos migrate, agrega las siguientes marcas:

Inicializa una fuente de información jerárquica

Puedes organizar tu fuente de información de manera arbitraria si usas una fuente de información no estructurada. Si usas una fuente de información jerárquica, debes ejecutar el comando nomos init para inicializar un directorio jerárquico:

nomos init

Esto crea la estructura de directorios básica de una fuente de información jerárquica, incluidos los directorios system/, cluster/ y namespaces/.

Marcas de nomos init

Para personalizar nomos init, agrega las siguientes marcas:

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?

• Comienza a usar el Sincronizador de configuración