nomos-Befehlszeilentool verwenden

Das nomos-Befehlszeilentool ist ein optionales Tool für Config Sync, mit dem Sie den Status von Config Sync und den Synchronisierungsstatus Ihrer Source of Truth abrufen können. Das nomos-Tool bietet folgende Befehle:

Vorbereitung

Bevor Sie mit dem nomos-Tool mit einem Cluster interagieren können, muss Config Sync bereits auf dem Zielcluster installiert sein. Sie müssen das kubectl-Befehlszeilentool auch installieren und konfigurieren. Wenn Sie mit Google Kubernetes Engine-Clustern interagieren, müssen Sie auch den gke-gcloud-auth-plugin installieren.

Das nomos-Tool unterstützt die Vorschau auf und Validierung von Kustomize-Konfigurationen und Helm-Diagrammen. Bevor Sie dieses Feature verwenden können, installieren Sie Kustomize und Helm auf Ihrer lokalen Workstation. Wenn Ihre "Source of Truth" nur vollständig gerenderte Konfigurationen enthält, sind Kustomize und Helm optional.

Installieren Sie das nomos-Tool.

Das nomos-Tool ist eine aus Go-Code kompilierte Binärdatei, die Sie lokal installieren können, z. B. auf einer Workstation oder einem Laptop.

Das nomos-Tool ist bei der Installation von Config Sync nicht enthalten. Sie können den Befehl nomos installieren. Installieren Sie dazu die Google Cloud CLI. Wenn Sie Cloud Shell verwenden, ist die Google Cloud CLI vorinstalliert.

Wenn Sie die Google Cloud CLI nicht zur Verfügung haben, empfehlen wir gcloud components install nomos zur Installation des nomos-Tools. Wenn Sie das nomos-Tool mit der Google Cloud CLI installieren, können Sie das nomos-Tool mithilfe von gcloud components update auf die neueste Version aktualisieren.

Informationen zu alternativen Möglichkeiten für die Installation des nomos-Tools finden Sie unter Downloads.

Grundlegende Nutzung

Mit dem Argument --help können Sie die grundlegende Befehlssyntax aufrufen:

nomos --help

Das nomos-Tool liest aus dem lokalen Klon Ihrer "Source of Truth". Verwenden Sie das Flag --path, um die Position der obersten Ebene der "Source of Truth" anzugeben. Standardmäßig ist --path auf . oder das aktuelle Verzeichnis festgelegt. Beispiel:

nomos --path=PATH_TO_SOURCE vet

Config Sync-Status prüfen

Mit dem Befehl nomos status können Sie den Status von Config Sync in allen registrierten Clustern überwachen. Für jeden Cluster meldet nomos status den Hash des Commits, der zuletzt auf den Cluster angewendet wurde, sowie alle Fehler, die beim Versuch aufgetreten sind, die letzten Änderungen anzuwenden.

Sie können auch nomos status verwenden, um zu prüfen, ob die von Config Sync verwalteten Ressourcen bereit sind. nomos status erfasst den Status für jede einzelne Ressource in der Spalte STATUS des Abschnitts Managed resources der Ausgabe.

Das folgende Beispiel zeigt einige der verschiedenen Bedingungen, die der Befehl nomos status melden kann:

nomos status

Beispielausgabe:

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 dieser Ausgabe gilt:

• MANAGED_CLUSTER_1 hat die letzte Änderung an der "Source of Truth" synchronisiert und alle verwalteten Ressourcen haben den Status Current. Der Status Current bedeutet, dass der Status der Ressource mit dem gewünschten Status übereinstimmt.
• MANAGED_CLUSTER_2 wird noch synchronisiert.
• MANAGED_CLUSTER_3 hat einen Fehler, der verhindert hat, dass die Änderung angewendet wurde. In diesem Beispiel weist MANAGED_CLUSTER_3 den Fehler KNV1021 auf, da eine CRD (CustomResourceDefinition) fehlt, die auf den anderen Clustern installiert ist.
• In MANAGED_CLUSTER_4 ist Config Sync nicht installiert.
• MANAGED_CLUSTER_5 wird aus zwei Git-Repositories synchronisiert. Die "Source of Truth" <root> gehört dem Clusteradministrator und die "Source of Truth" bookstore gehört möglicherweise zu einem Team in der Anwendungsentwicklung.

Status verwalteter Ressourcen

Der Status Ihrer verwalteten Ressourcen kann einer der folgenden Werte sein:

• InProgress: Der tatsächliche Status der Ressource hat noch nicht den Status erreicht, den Sie im Ressourcenmanifest angegeben haben. Dies bedeutet, dass der Ressourcenabgleich noch nicht abgeschlossen ist. Neu erstellte Ressourcen beginnen in der Regel mit diesem Status, einige Ressourcen wie ConfigMaps haben jedoch sofort den Status Current.

• Failed: Bei dem Prozess, bei dem der tatsächliche Status mit dem gewünschten Status abgeglichen wird, ist ein Fehler aufgetreten oder er ist nicht ausreichend vorangeschritten.

• Current: Der tatsächliche Status der Ressource entspricht dem gewünschten Status. Der Abgleichsprozess gilt so lange als abgeschlossen, bis Änderungen am gewünschten oder tatsächlichen Status vorgenommen werden.

• Terminating: Die Ressource wird gerade gelöscht.

• NotFound: Die Ressource ist nicht im Cluster vorhanden.

• Unknown: Config Sync kann den Status der Ressource nicht ermitteln.

Wenn Sie das Anzeigen des Status der Ressourcenebene deaktivieren möchten, fügen Sie dem Befehl nomos status das Flag --resources=false hinzu.

Letzte synchronisierte Commits

Der Befehl nomos status zeigt in der Ausgabe unter status.sync.commit den neuesten Commit-Hash an, der auf den Cluster angewendet wurde. Fragen Sie das RootSync oder RepoSync-Objekt ab und sehen Sie sich das Feld status.sync an, um diesen Wert zu erhalten:

Führen Sie beispielsweise den folgenden Befehl aus, um ein RootSync-Objekt abzufragen:

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

Beispielausgabe:

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

Führen Sie den folgenden Befehl aus, um ein RepoSync-Objekt abzufragen:

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

Ersetzen Sie NAMESPACE durch den Namespace, in dem Sie die Namespace-„Source of Truth“ erstellt haben.

Beispielausgabe:

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

Dieser Commit stellt den letzten Commit für den Cluster dar. Allerdings ist nicht jede Ressource im Cluster von jedem Commit betroffen. Fragen Sie die spezifische Ressource ab und sehen Sie sich metadata.annotations.configmanagement.gke.io/token an, um den neuesten Commit für eine spezifische Ressource aufzurufen. Beispiel:

kubectl get clusterroles CLUSTER_ROLE_NAME -o yaml

Ersetzen Sie CLUSTER_ROLE_NAME durch den Namen der Clusterrolle, die Sie abfragen möchten.

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

nomos-Status-Flags

Fügen Sie die folgenden Flags hinzu, um den Befehl nomos status anzupassen:

Erforderliche Berechtigungen

Wenn Sie Projektinhaber sind, haben Sie die RBAC-Rolle cluster-admin und können den Befehl nomos status für alle Cluster in Ihrem Projekt verwenden, ohne weitere Berechtigungen hinzuzufügen. Wenn Sie die Rolle cluster-admin nicht haben, können Sie nomos status verwenden. Erstellen Sie dazu die folgende ClusterRole:

1. Erstellen Sie eine Datei namens nomos-status-reader.yaml und kopieren Sie die folgende ClusterRole hinein: Welche Regeln Sie benötigen, hängt davon ab, ob Sie RootSync- und RepoSync-Objekte verwenden.

   RootSync- und RepoSync-Objekte verwenden

   # 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"]
   

   Keine RootSync- und RepoSync-Objekte verwenden

   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. Wenden Sie die Datei nomos-status-reader.yaml an:

   kubectl apply -f nomos-status-reader.yaml
   

In der "Source of Truth" nach Fehlern suchen

Bevor Sie eine Konfiguration für die "Source of Truth" festlegen, prüfen Sie mit dem Befehl nomos vet die Syntax und Gültigkeit der Konfigurationen in Ihrer "Source of Truth":

nomos vet

Wenn Syntaxfehler gefunden werden, wird der Befehl nomos vet mit einem Status ungleich Null beendet und Fehlermeldungen werden in STDERR protokolliert.

Nomos vet-Flags

Fügen Sie die folgenden Flags hinzu, um den Befehl nomos vet anzupassen:

Serverseitige Validierung

Wenn der Befehl nomos vet nicht feststellen kann, ob der Typ einen Namespace hat, stellt das nomos-Tool eine Verbindung zum API-Server her. Da das nomos-Tool die Kubernetes-Kerntypen und Config Sync-CRDs standardmäßig versteht, wird nur dann versucht, eine Verbindung zum API-Server herzustellen, wenn Antwortvorlagen vorhanden sind, die keine entsprechende deklarierte CRD haben. In diesem Fall gibt der Befehl nomos vet error KNV1021 zurück, wenn auf dem API-Server nicht die CRD angewendet wurde. Übergeben Sie das Flag --no-api-server-check, um diese Prüfung zu deaktivieren und Fehler aufgrund fehlender CRDs zu unterdrücken.

Caching von API-Servermetadaten

Anstatt API-Serverprüfungen zu unterdrücken, können Sie die Daten auf dem API-Server für den Befehl nomos vet im Cache speichern. Wenn Sie Ihre api-resources im Cache speichern möchten, führen Sie folgende Schritte aus:

1. Stellen Sie eine Verbindung zu einem Cluster her, der alle CRDs enthält, die Sie für Ihre "Source of Truth" benötigen. Für den Cluster muss Config Sync nicht aktiviert werden.
2. Rufen Sie das policyDir-Element Ihrer "Source of Truth" auf. Dies ist dasselbe Verzeichnis, das in Ihrer ConfigManagement- oder RootSync-Ressource angegeben ist.
3. Führen Sie den folgenden Befehl aus: kubectl api-resources > api-resources.txt. Dieser Befehl erstellt eine Datei mit dem Namen „api-resources.txt”, die die genaue Ausgabe von kubectl api-resources enthält.

Ab jetzt kennen nomos vet-Ausführungen innerhalb der "Source of Truth" diese Typdefinitionen. Wenn die Datei api-resources.txt entfernt oder umbenannt wird, kann nomos vet die Datei nicht finden. nomos vet versucht weiterhin, eine Verbindung zum Cluster herzustellen, wenn es Manifeste für Typen findet, die nicht in api-resources.txt deklariert sind (es sei denn, --no-api-server-check wird übergeben).

Die Datei api-resources.txt wirkt sich nur auf die Funktionsweise des nomos-Tools aus. Sie ändert das Verhalten von Config Sync in keiner Weise.

Sie können zusätzliche Einträge in der Datei „api-resources.txt” haben, die sich auf Typen beziehen, die nicht in der zu validierenden "Source of Truth" enthalten sind. nomos vet importiert die Definitionen, hat aber keine Auswirkungen.

api-resources.txt aktualisieren

Nachdem Sie alle gewünschten CRDs im Cluster abgelegt haben, führen Sie den folgenden Befehl aus:

kubectl api-resources > api-resources.txt

Automatische Überprüfung auf Syntaxfehler beim Commit

Wenn Sie einen Commit für eine Datei mit JSON- oder YAML-Fehlern durchführen, übernimmt Config Sync die Änderung nicht. Mit clientseitigen oder serverseitigen Hooks können Sie jedoch verhindern, dass solche Fehler jemals an die "Source of Truth" übertragen werden.

nomos vet in einem Pre-Commit-Hook verwenden

Sie können einen Pre-Commit-Hook konfigurieren, der den Befehl nomos vet ausführt, um nach Syntaxfehlern zu suchen, wenn Sie eine Änderung am lokalen Git-Klon Ihres Repositorys festschreiben. Wenn ein Pre-Commit-Hook mit einem Status ungleich Null beendet wird, schlägt der git commit-Vorgang fehl.

Zum Ausführen des Befehls nomos vet als Pre-Commit-Hook bearbeiten Sie die Datei .git/hooks/pre-commit in Ihrer "Source of Truth" (beachten Sie dabei, dass .git mit einem .-Zeichen beginnt). Möglicherweise müssen Sie die Datei manuell erstellen. Fügen Sie den Befehl nomos vet zu einer neuen Zeile im Skript hinzu. Das Argument --path ist optional.

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

Achten Sie darauf, dass die Datei pre-commit ausführbar ist:

chmod +x .git/hooks/pre-commit

Wenn Sie im Klon der "Source of Truth" jetzt einen git commit-Befehl ausführen, wird nomos vet automatisch ausgeführt.

Der Inhalt des .git/-Verzeichnisses wird von der "Source of Truth" selbst nicht verfolgt und kann nicht an derselben Stelle darin übernommen werden. Sie können in der "Source of Truth" ein Verzeichnis für Git-Hooks erstellen. Nutzer, die die "Source of Truth" verwenden, können die Hooks dann an den entsprechenden Speicherort in ihrem lokalen Klon kopieren.

nomos vet in einem serverseitigen Hook verwenden

Git bietet einen Mechanismus, um während eines git push-Vorgangs Prüfungen auf dem Server auszuführen, statt auf dem Client. Wenn die Prüfung fehlschlägt, schlägt auch git push fehl. Diese serverseitigen Hooks können vom Client nicht umgangen werden. Die Methode zum Konfigurieren serverseitiger Hooks hängt davon ab, wie Ihr Git-Server gehostet wird. Weitere Informationen finden Sie unter einem der folgenden Links oder in der Dokumentation zu Ihrem Git-Hostingdienst.

• GitHub
• Cloud Source Repositories
• Bitbucket
• GitLab
• Selbstgehosteter Git-Server

Alle Konfigurationen in der "Source of Truth" ansehen

Mit dem Befehl nomos hydrate können Sie den zusammengefassten Inhalt Ihrer „Source of Truth“ für jeden registrierten Cluster aufrufen.

Wenn Sie nomos hydrate ohne Optionen ausführen, wird im aktuellen Arbeitsverzeichnis ein Verzeichnis compiled/ erstellt. Innerhalb dieses Verzeichnisses wird für jeden registrierten Cluster ein Unterverzeichnis mit den vollständig aufgelösten Konfigurationen erstellt, die der Operator auf den Cluster anwenden würde.

Mit diesem Befehl kann auch eine hierarchische "Source of Truth" in eine oder mehrere unstrukturierte "Sources of Truth" mithilfe des Inhalts im Verzeichnis compiled/ konvertiert werden.

Flags für „nomos hydrate“

Fügen Sie die folgenden Flags hinzu, um den Befehl nomos hydrate anzupassen:

Fehlerbericht erstellen

Wenn Sie ein Problem mit Config Sync haben, für das Sie die Unterstützung des Google Cloud-Supports benötigen, können Sie mit dem Befehl nomos bugreport wertvolle Debugging-Informationen für den Support bereitstellen. Sie können diesen Befehl für eine Single Source of Truth und mehrere Repositories verwenden.

nomos bugreport

Dieser Befehl generiert eine zeitgestempelte Zip-Datei mit Informationen zum Kubernetes-Cluster, der in Ihrem kubectl-Kontext festgelegt ist. Die Datei enthält auch Logs aus den Config Sync-Pods. Sie enthält keine Informationen aus den mit Config Sync synchronisierten Ressourcen. Weitere Informationen zum Inhalt der ZIP-Datei finden Sie in der Referenz zum nomos-Fehlerbericht.

Beschränkungen

Der Befehl nomos bugreport schlägt fehl und erzeugt eine unvollständige ZIP-Datei, wenn eine einzelne Datei 1 GiB überschreitet. Dies ist oft auf große Logdateien zurückzuführen.

In der folgenden Tabelle sind die häufigsten Ursachen für große Logdateien und deren Behebung aufgeführt:

Von einem ConfigManagement-Objekt zu einem RootSync-Objekt migrieren

Sie können den Befehl nomos migrate ausführen, um von Ihrem ConfigManagement-Objekt zu einem RootSync-Objekt zu migrieren, um die APIs RootSync und RepoSync zu aktivieren.

Wenn Sie spec.enableLegacyFields zum Bootstrapping einer RootSync verwendet haben, folgen Sie der Anleitung zum Deaktivieren von Legacy-Feldern, anstatt nomos migrate zu verwenden. Ab Version 1.19.0 werden Legacy-Felder nicht mehr unterstützt.

nomos migrate unterstützt den Probelauf für die Vorschau des Migrationsprozesses.

nomos migrate ändert Ihr ConfigManagement-Objekt direkt auf dem Cluster. Achten Sie darauf, dass das ConfigManagement-Objekt nicht in Ihre "Source of Truth" eingecheckt ist, damit Änderungen, die durch nomos migrate vorgenommen wurden, nicht rückgängig gemacht werden.

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

Wenn das Probelaufergebnis gut aussieht, können Sie Ihr ConfigManagement-Objekt mit nomos migrate migrieren:

nomos migrate --contexts=KUBECONFIG_CONTEXTS

Die entsprechende Ausgabe sieht etwa so aus:

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

Rollback zur vorherigen Konfiguration

Wenn Sie nach der Migration mit nomos migrate ein Rollback machen müssen, wenden Sie das ursprüngliche ConfigManagement-Objekt an. nomos migrate speichert das ursprüngliche ConfigManagement-Objekt in einer Datei und gibt den Namen im Terminal aus. Der Name der Datei hat das Format /tmp/nomos-migrate/CURRENT_CONTEXT/cm-original.yaml.

Wenn Sie ein Rollback zur vorherigen Konfiguration machen möchten, kopieren Sie den Dateipfad für cm-original.yaml und wenden die Datei auf Ihren Cluster an:

kubectl apply -f CM_ORIGINAL_PATH

Flags für „nomos migrate“

Fügen Sie die folgenden Flags hinzu, um den Befehl nomos migrate anzupassen:

Hierarchische "Source of Truth" initialisieren

Sie können Ihre "Source of Truth" beliebig organisieren, wenn Sie eine unstrukturierte "Source of Truth" verwenden. Wenn Sie eine hierarchische "Source of Truth" verwenden, müssen Sie den Befehl nomos init ausführen, um ein hierarchisches Verzeichnis zu initialisieren:

nomos init

Dadurch wird die grundlegende Verzeichnisstruktur einer hierarchischen "Source of Truth" erstellt, einschließlich der Verzeichnisse system/, cluster/ und namespaces/.

Flags für „nomos init“

Fügen Sie die folgenden Flags hinzu, um nomos init anzupassen:

Fehlerbehebung

Unter Linux wird möglicherweise der folgende Fehler angezeigt, wenn ein nomos-Befehl ausgeführt wird:

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

Erstellen Sie eine USER-Umgebungsvariable, um dieses Problem zu beheben:

export USER=$(whoami)

Nächste Schritte

• Erste Schritte mit Config Sync