Usare lo strumento a riga di comando nomos

Lo strumento a riga di comando nomos è uno strumento facoltativo per Config Sync. Lo strumento nomos fornisce i seguenti comandi:

Comando Utilizzo
nomos status Verificare lo stato di Config Sync
nomos vet Verificare la presenza di errori nel repository
nomos hydrate Visualizza tutte le configurazioni nel repository
nomos bugreport Creare una segnalazione di bug
nomos migrate Eseguire una migrazione da ConfigManagement a RootSync
nomos init Inizializza un repository gerarchico

Prerequisiti

Prima di poter utilizzare lo strumento nomos per interagire con un cluster, Config Sync deve essere già installato sul cluster di destinazione. Devi anche configurare lo strumento a riga di comando kubectl per eseguire l'autenticazione sul cluster di destinazione generando una voce kubeconfig.

Lo strumento nomos supporta l'anteprima e la convalida di configurazioni Kustomize e grafici Helm. Prima di poter utilizzare questa funzionalità, installa Kustomize e Helm nella tua workstation locale. Se il repository contiene solo configurazioni completamente visualizzate, Kustomize e Helm sono facoltativi.

Installa lo strumento nomos

Lo strumento nomos è un programma binario compilato dal codice Go e puoi installarlo localmente, ad esempio su una workstation o un laptop.

Lo strumento nomos non è incluso quando installi Config Sync. Puoi installare lo strumento nomos installando l'interfaccia a riga di comando di Google Cloud. Se utilizzi Cloud Shell, l'interfaccia a riga di comando di Google Cloud è preinstallata.

Se non disponi dell'interfaccia a riga di comando di Google Cloud, ti consigliamo di utilizzare gcloud components install nomos per installare lo strumento nomos. L'installazione dello strumento nomos con l'interfaccia a riga di comando di Google Cloud ti consente di utilizzare gcloud components update per aggiornare lo strumento nomos all'ultima versione.

Per informazioni sui modi alternativi per installare lo strumento nomos, consulta la sezione Download di Anthos Config Management.

Utilizzo di base

Per la sintassi dei comandi di base, utilizza l'argomento --help:

nomos --help

Lo strumento nomos legge dal clone locale del tuo repository. Utilizza il flag --path per specificare la posizione del livello superiore del repository. Per impostazione predefinita, --path è impostato su . o sulla directory corrente. Ad esempio:

nomos --path=PATH_TO_REPOSITORY vet

Verifica lo stato di Config Sync

Puoi monitorare lo stato di Config Sync su tutti i cluster registrati utilizzando il comando nomos status. Per ogni cluster, nomos status segnala l'hash del commit Git applicato l'ultima volta al cluster, nonché gli errori che si sono verificati durante il tentativo di applicare le modifiche recenti.

A partire dalla versione 1.8.0 dello strumento nomos, puoi anche utilizzare nomos status per verificare se le risorse gestite da Config Sync sono pronte. nomos status riporta lo stato di ogni singola risorsa dal tuo repository Git nella colonna STATUS della sezione Managed resources dell'output.

L'esempio seguente mostra alcune delle diverse condizioni che il comando nomos status potrebbe segnalare:

nomos status

Output di esempio:

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

In questo output:

  • MANAGED_CLUSTER_1 ha sincronizzato la modifica più recente nel repository e tutte le risorse gestite hanno lo stato Current. Lo stato Current indica che lo stato della risorsa corrisponde a quello desiderato.
  • La sincronizzazione di MANAGED_CLUSTER_2 è ancora in corso.
  • MANAGED_CLUSTER_3 contiene un errore che ha impedito l'applicazione della modifica. In questo esempio, MANAGED_CLUSTER_3 ha l'errore KNV1021 perché manca una CustomResourceDefinition (CRD) installata dagli altri cluster.
  • MANAGED_CLUSTER_4 non ha installato Config Sync.
  • MANAGED_CLUSTER_5 sta sincronizzando da due repository Git. Il repository <root> appartiene all'amministratore del cluster e il repository bookstore potrebbe appartenere a un team di sviluppo delle applicazioni.

Stati delle risorse gestite

Lo stato delle risorse gestite può essere uno dei seguenti valori:

  • InProgress: lo stato effettivo della risorsa non ha ancora raggiunto lo stato specificato nel manifest della risorsa. Questo stato indica che la riconciliazione delle risorse non è ancora completa. In genere, le risorse create di recente iniziano con questo stato, anche se alcune risorse come ConfigMap sono Current immediatamente.

  • Failed: la procedura di riconciliazione dello stato effettivo con quello che vuoi avere riscontrato si è verificato un errore o non è stata completata correttamente.

  • Current: lo stato effettivo della risorsa corrisponde a quello desiderato. Il processo di riconciliazione è considerato completo finché non vengono apportate modifiche allo stato desiderato o effettivo.

  • Terminating: la risorsa è in fase di eliminazione.

  • NotFound: la risorsa non esiste nel cluster.

  • Unknown: Config Sync non è in grado di determinare lo stato della risorsa.

Per disattivare la visualizzazione dello stato a livello di risorsa, aggiungi --resources=false al comando nomos status.

Informazioni sull'ultimo commit sincronizzato

Il comando nomos status mostra l'hash di commit Git più recente applicato al cluster nel suo output in status.sync.commit. Per ottenere questo valore, esegui una query sull'oggetto RootSync o RepoSync e controlla il campo status.sync.

Ad esempio, per eseguire una query su un oggetto RootSync, esegui il comando seguente:

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

Output di esempio:

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

Per eseguire una query su un oggetto RepoSync, esegui il comando seguente:

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

Sostituisci NAMESPACE con lo spazio dei nomi in cui hai creato il repository.

Output di esempio:

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

Questo commit rappresenta l'impegno più recente rispetto al cluster. Tuttavia, non tutte le risorse nel cluster sono interessate da ogni commit. Per visualizzare il commit più recente di una risorsa specifica, esegui una query sulla risorsa specifica e guarda metadata.annotations.configmanagement.gke.io/token. Ad esempio:

kubectl get clusterroles CLUSTER_ROLE_NAME -o yaml

Sostituisci CLUSTER_ROLE_NAME con il nome del ruolo cluster in cui vuoi eseguire la query.

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

flag di stato nomos

Per personalizzare il comando nomos status, aggiungi i seguenti flag:

Flag Descrizione
--contexts Accetta un elenco di contesti separati da virgole da utilizzare nei comandi multi-cluster. Il valore predefinito è tutti i contesti. Utilizza " per nessun contesto.
-h o --help Guida per il comando nomos status.
--namespace Accetta una stringa. Utilizza il flag namespace per limitare il comando a un repository di spazio dei nomi specifico. Non impostare per ottenere tutti i repository. Questo flag è disponibile solo se hai abilitato la sincronizzazione da più repository.
--poll Utilizza il flag poll per eseguire nomos status continuamente e fare in modo che ristampa la tabella di stato a intervalli regolari. Ad esempio 3s. Non impostare questo flag per eseguire nomos status una volta
--resources Accetta true o false. Se true, nomos status mostra lo stato a livello di risorsa per il repository principale o dello spazio dei nomi durante la sincronizzazione da più repository. Il valore predefinito è true.
--timeout Timeout per la connessione a ciascun cluster. Il valore predefinito è 3s.

Autorizzazioni obbligatorie

Se sei un proprietario del progetto, hai il ruolo RBAC (cluster-admin) e puoi utilizzare il comando nomos status per tutti i cluster del progetto senza aggiungere ulteriori autorizzazioni. Se non hai il ruolo cluster-admin, puoi utilizzare nomos status creando il seguente ClusterRole:

  1. Crea un file denominato nomos-status-reader.yaml e copiaci il seguente ClusterRole. Le regole di cui hai bisogno variano a seconda che tu stia utilizzando gli oggetti root e RepoSync.

    Utilizzo di oggetti RootSync e 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"]

    Non sono utilizzati oggetti RootSync e 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. Applica il file nomos-status-reader.yaml:

    kubectl apply -f nomos-status-reader.yaml

Verifica che non siano presenti errori nel repository

Prima di eseguire il commit di una configurazione nel repository, utilizza il comando nomos vet per verificare la sintassi e la validità delle configurazioni nel repository:

nomos vet

Se vengono rilevati errori di sintassi, il comando nomos vet esce con uno stato diverso da zero e registra i messaggi di errore in STDERR.

Bandiere veterinarie nomos

Per personalizzare il comando nomos vet, aggiungi i seguenti flag:

Flag Descrizione
--clusters Accetta un elenco separato da virgole di nomi dei cluster da utilizzare nei comandi multi-cluster. Il valore predefinito è tutti i cluster. Utilizza "" per nessun cluster.
-h o --help Guida per il comando nomos vet.
--namespace Accetta una stringa. Se impostato, convalida il repository come repository di spazio dei nomi con il nome fornito. Imposta automaticamente --source-format=unstructured.
--no-api-server-check Accetta valori booleani. Se true, disabilita la comunicazione con il server API per il rilevamento. Per ulteriori informazioni su questo flag, consulta la sezione Convalida lato server.
--path Accetta una stringa. Il percorso della directory principale del repository di Config Sync. L'impostazione predefinita è &.;
--source-format Accetta hierarchy o unstructured. Se hierarchy o non viene configurato, convalida il repository come repository gerarchico. Se unstructured, convalida il repository come repository non strutturato. Il flag è obbligatorio se utilizzi un repository non strutturato.
--keep-output Accetta valori booleani. Se true, l'output sottoposto a rendering viene salvato nella posizione che puoi specificare con il flag --output. Questo flag è disponibile nelle versioni 1.9.0 e successive.
--output Accetta una stringa. Il percorso dell'output sottoposto a rendering. Il valore predefinito è la directory compiled. Se --keep-output è impostato su false, questo flag viene ignorato. Questo flag è disponibile nelle versioni 1.9.0 e successive.
--format Accetta yaml o json. Il formato dell'output. Il valore predefinito è yaml. Questo flag è disponibile nelle versioni 1.9.0 e successive.

Convalida lato server

Se il comando nomos vet non riesce a stabilire se il tipo contiene uno spazio dei nomi, lo strumento nomos si connette al server API. Per impostazione predefinita, lo strumento nomos comprende i tipi principali di Kubernetes e i CRD di Config Sync, tenta di connettersi al server API solo se sono presenti CR non specificate. In questo caso, se al server API non è applicato il CRD, il comando nomos vet restituisce error KNV1021. Per disattivare questo controllo ed eliminare gli errori relativi a CRD mancanti, passa il flag --no-api- server-check.

Metadati del server API Caching

Anziché eliminare i controlli del server API, puoi memorizzare nella cache i dati sul server API per il comando nomos vet. Per memorizzare gli elementi api-resources nella cache, procedi nel seguente modo:

  1. Connettiti a un cluster che contiene tutti gli CRD necessari per il repository. Per il cluster non è necessario abilitare Config Sync.
  2. Vai al criterioDir del repository. Si tratta della stessa directory specificata nella risorsa ConfigManagement o RootSync.
  3. Esegui il comando seguente: kubectl api-resources > api-resources.txt Questo comando crea un file denominato api-resources.txt contenente l'esatto output di kubectl api-resources.

D'ora in poi, le esecuzioni di nomos vet all'interno del repository sono a conoscenza di queste definizioni di tipo. Se il file api-resources.txt viene rimosso o rinominato, nomos vet non riesce a trovarlo. nomos vet proverà comunque a connettersi al cluster se rileva manifest per i tipi non dichiarati in api-resources.txt (a meno che non venga passato --no-api-server-check).

Il file api-resources.txt influisce solo sul funzionamento dello strumento nomos. non modifica in alcun modo il comportamento di Config Sync.

Nel file api-resources.txt è consentito avere voci aggiuntive destinate ai tipi che non sono presenti nel repository in fase di convalida. nomos vet importa le definizioni, ma non le utilizza.

Aggiorna api-resources.txt

Dopo aver verificato che tutti gli CRD che ti interessano siano nel cluster, esegui il seguente comando:

kubectl api-resources > api-resources.txt

Controlla automaticamente la presenza di errori di sintassi durante il commit

Se esegui il commit di un file con errori JSON o YAML, Config Sync non applica la modifica. Tuttavia, puoi evitare che questi tipi di errore accedano al repository utilizzando hook lato client o lato server.

Usa nomos vet in un hook pre-impegno per Git

Puoi configurare un hook pre-commit che esegue il comando nomos vet per verificare la presenza di errori di sintassi quando esegui il commit di una modifica nel clone Git locale del repository. Se un hook pre-commit esce con uno stato diverso da zero, l'operazione git commit non riesce.

Per eseguire il comando nomos vet come hook pre-impegno, modifica il file .git/hooks/pre-commit nel tuo repository (tieni presente che .git inizia con un carattere .). Potrebbe essere necessario creare il file manualmente. Aggiungi il comando nomos vet a una nuova riga nello script. L'argomento --path è facoltativo.

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

Assicurati che il file pre-commit sia eseguibile:

chmod +x .git/hooks/pre-commit

Ora, quando esegui un comando git commit nel clone del tuo repository, nomos vet viene eseguito automaticamente.

I contenuti della directory .git/ del repository non vengono monitorati dal repository stesso e non possono essere assegnati al repository nella stessa località. Puoi creare una directory nel repository per gli hook Git e le persone che utilizzano il repository possono copiare gli hook in una posizione appropriata nel clone locale.

Utilizza nomos vet in un hook lato server

Git fornisce un meccanismo per eseguire i controlli sul server, anziché sul client, durante un'operazione git push. Se il controllo non va a buon fine, anche git push non riesce. Questi hook lato server non possono essere aggirati dal client. Il metodo per la configurazione dei hook lato server dipende dal modo in cui è ospitato il server Git. Per ulteriori informazioni, visita uno dei seguenti link oppure consulta la documentazione del servizio di hosting Git.

Visualizza tutte le configurazioni nel repository

Puoi utilizzare il comando nomos hydrate per visualizzare i contenuti combinati del tuo repository su ogni cluster registrato.

Se esegui nomos hydrate senza opzioni, viene creata una directory compiled/ nella directory di lavoro attuale. All'interno della directory viene creata una sottodirectory per ogni cluster registrato, con le configurazioni completamente risolte che l'operatore applicherà al cluster.

Questo comando può essere utilizzato anche per convertire un repository gerarchico in uno o più repository non strutturati, utilizzando i contenuti nella directory compiled/.

Bandiere nomos idrata

Per personalizzare il comando nomos hydrate, aggiungi i seguenti flag:

Flag Descrizione
--clusters Accetta un elenco di nomi dei cluster separati da virgole. Utilizza questo flag per limitare l'output a un singolo cluster o a un elenco di cluster. Il valore predefinito è tutti i cluster. Utilizza "" per nessun cluster.
--flat Se questa opzione è attivata, stampa tutto l'output in un singolo file. Utilizza questo flag se vuoi emulare il comportamento di nomos view.
-h o --help Guida per il comando nomos hydrate.
--format Accetta yaml o json. Il formato dell'output. Il valore predefinito è yaml. Questo flag è disponibile nelle versioni 1.9.0 e successive.
--no-api-server-check Accetta valori booleani. Se true, disabilita la comunicazione con il server API per il rilevamento. Per ulteriori informazioni su questo flag, consulta la sezione Convalida lato server.
--output Accetta una stringa. La località in cui scrivere la configurazione idratata. L'impostazione predefinita è la directory compiled. Se --flat non è abilitato, scrive ogni manifest della risorsa come file separato. Se --flat è abilitato, scrive nel file, scrive un singolo file contenente tutti i manifest delle risorse.
--path Accetta una stringa. Il percorso della directory principale del repository di Config Sync. L'impostazione predefinita è &.;
--source-format Accetta hierarchy o unstructured. Se hierarchy o non viene configurato, convalida il repository come repository gerarchico. Se unstructured, convalida il repository come repository non strutturato. Questo flag è obbligatorio se utilizzi un repository non strutturato ed è disponibile nella versione 1.9.0 e successive.

nomos view

Quando Config Sync importa le configurazioni dal repository, le converte in CRD di tipo ClusterConfig o NamespaceConfig. Il comando nomos view consente di visualizzare i CRD derivanti dallo stato attuale del repository in formato JSON. Questo può essere utile prima di eseguire il commit della modifica o per eseguire il debug di problemi con configurazioni non ovvie utilizzando il comando nomos vet.

nomos view --path=PATH_TO_REPOSITORY

Creare una segnalazione di bug

Se hai un problema con Config Sync che richiede l'assistenza dell'assistenza Google Cloud, puoi fornire informazioni di debug utili utilizzando il comando nomos bugreport. Puoi utilizzare questo comando per singoli repository e più repository.

nomos bugreport

Questo comando genera un file ZIP con timestamp con informazioni sul cluster Kubernetes impostato nel tuo contesto kubectl. Il file contiene anche i log dei pod di Config Sync. Non contiene informazioni dalle risorse sincronizzate con Config Sync.

Esegui la migrazione da un oggetto ConfigManagement a un oggetto RootSync

Puoi eseguire il comando nomos migrate per eseguire la migrazione dall'oggetto ConfigManagement a un oggetto RootSync per attivare le API RootSync e RepoSync. Il comando è disponibile nello strumento nomos versione 1.10.0 e successive.

nomos migrate supporta la prova dell'anteprima del processo di migrazione.

nomos migrate --dry-run

Se il risultato del test di prova è corretto, puoi eseguire la migrazione dell'oggetto ConfigManagement utilizzando nomos migrate:

nomos migrate

L'output è simile al seguente:

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

Flag di migrazione di Nomos

Per personalizzare il comando nomos migrate, aggiungi i seguenti flag:

Flag Descrizione
--connect-timeout Accetta una durata. Durata del timeout per la connessione a ciascun cluster. Il valore predefinito è 3s.
--contexts Accetta un elenco di contesti separati da virgole da utilizzare in ambienti multi-cluster. Il valore predefinito è il contesto attuale. Utilizza "all" per tutti i contesti.
--dry-run Accetta valori booleani. Se true, stampa solo l'output della migrazione.
-h o --help Guida per il comando nomos migrate.
--wait-timeout Accetta una durata. Durata del timeout in attesa che le condizioni di Kubernetes siano vere. Il valore predefinito è 10m.

Inizializza un repository gerarchico

Puoi organizzare il repository in modo arbitrario se utilizzi un repository non strutturato. Se utilizzi un repository gerarchico, devi eseguire il comando nomos init per inizializzare una directory gerarchica:

nomos init

Viene creata la struttura di directory di base di un repository gerarchico, incluse le directory system/, cluster/ e namespaces/.

Flag nomos init

Per personalizzare nomos init, aggiungi i seguenti flag:

Flag Descrizione
--force Scrivi nella directory anche se non è vuoto, sovrascrive i file in conflitto
-h o --help Guida per il comando nomos init.
--path Accetta una stringa. La directory radice da utilizzare per il repository di Anthos Config Management. Il valore predefinito è "."

Risolvere i problemi

Su Linux, potrebbe essere visualizzato il seguente errore durante l'esecuzione di un comando nomos:

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

Per risolvere questo problema, crea una variabile di ambiente USER:

export USER=$(whoami)

Passaggi successivi