nomos-Befehl verwenden

Der Befehl nomos (nomos.exe unter Windows) ist ein optionales Befehlszeilentool, das Sie lokal installieren können, z. B. auf einer Workstation oder einem Laptop. Sie können den Befehl nomos verwenden, um mit dem Config Sync-Operator zu interagieren, die Syntax von Konfigurationen zu prüfen, bevor Sie sie per Commit in Ihr Repository übertragen, und Probleme mit Config Sync, Ihrem Cluster oder Ihrem Repository zu debuggen.

Voraussetzungen

Der Operator muss bereits auf dem Zielcluster installiert und der Befehl kubectl muss für die Authentifizierung beim Zielcluster konfiguriert sein, bevor Sie für die Interaktion mit einem Cluster den Befehl nomos verwenden können. Weitere Informationen finden Sie unter Config Sync installieren.

Befehl nomos installieren

Der nomos-Befehl ist eine Binärdatei, die aus dem Go-Code kompiliert wurde. Er ist optional und in einer Standardinstallation von Config Sync nicht enthalten.

Informationen zum Herunterladen des nomos-Befehls für alle Versionen von Config Sync finden Sie unter Downloads.

Zusätzliche Schritte für macOS- und Linux-Clients

Konfigurieren Sie die Binärdatei nach dem Herunterladen so, dass sie ausführbar ist:

chmod +x /path/to/nomos

Sie können den Befehl an einen Ort verschieben, an dem Ihr System nach Binärdateien sucht, z. B. /usr/local/bin, oder Sie können den Befehl unter Verwendung seines voll qualifizierten Pfads ausführen.

Grundlegende Nutzung

Die Befehle nomos und nomos.exe enthalten Unterbefehle, mit denen Sie das Repository initialisieren, nach Syntaxfehlern suchen, den Status von jedem registrierten Cluster und das Repository als Reihe von CustomResourceDefinitions ansehen können.

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

nomos --help

Mit dem nomos-Befehl wird der lokale Klon des Repositorys gelesen. Verwenden Sie das Flag --path, um die Position der obersten Ebene des Repositorys anzugeben. Standardmäßig ist --path auf . oder das aktuelle Verzeichnis festgelegt.

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

Installationsstatus prüfen

Mit dem Befehl nomos status können Sie prüfen, ob Config Sync auf allen Clustern ordnungsgemäß installiert und konfiguriert ist. Es werden alle Fehler gemeldet, die das Ausführen von Config Sync verhindern. Beispiel:

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

In dieser Ausgabe ist Config Sync nicht auf managed-cluster-1 installiert. Es ist installiert, aber nicht korrekt auf managed-cluster-2 konfiguriert. Es ist installiert und läuft korrekt auf managed-cluster-3.

Außerdem ist managed-cluster-2 nicht korrekt konfiguriert, da das git-creds-Secret nicht vorhanden ist.

Neues Repository initialisieren

Zum Initialisieren eines neuen Config Sync-Repositorys erstellen Sie ein leeres Verzeichnis. Dann rufen Sie es auf, initialisieren ein neues Git-Repository und führen den Befehl nomos init aus:

mkdir my-repo
cd my-repo
git init
nomos init

Dadurch wird die grundlegende Verzeichnisstruktur Ihres Repositorys erstellt, einschließlich der Verzeichnisse system/, cluster/ und namespaces/.

Repository auf Fehler prüfen

Bevor Sie eine Konfiguration für das Repository festlegen, prüfen Sie mit dem Befehl nomos vet die Syntax und Gültigkeit der Konfigurationen in Ihrem Repository:

nomos vet

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

Wenn nomos vet nicht feststellen kann, ob der Typ einen Namespace hat, stellt nomos eine Verbindung zum API-Server her. Da nomos die Kubernetes-Kerntypen und Config Sync-CRDs 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 nomos vet einen Fehler 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.

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 das Repository übertragen werden.

nomos vet in einem Git-Pre-Commit-Hook verwenden

Sie können einen Pre-Commit-Hook konfigurieren, der 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 Ihrem Repository (beachten Sie, 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 des Repositorys jetzt einen git commit-Befehl ausführen, wird nomos vet automatisch ausgeführt.

Der Inhalt des .git/-Verzeichnisses des Repositorys wird vom Repository selbst nicht verfolgt und kann nicht an derselben Stelle darin übernommen werden. Sie können im Repository ein Verzeichnis für Git-Hooks erstellen. Nutzer, die das Repository 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.

Ergebnis aller Konfigurationen im Repository anzeigen

Mit dem Befehl nomos hydrate können Sie den kombinierten Inhalt Ihres Repositorys 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.

Sie können den Namen des Ausgabeverzeichnisses festlegen, indem Sie als Argument des Befehls einen Verzeichnispfad angeben:

nomos hydrate [/path/to/directory]

Zum Beschränken der Ausgabe auf einen einzelnen Cluster oder eine Liste von Clustern verwenden Sie das Flag --clusters und geben eine durch Kommas getrennte Liste von Clusternamen an.

Verwenden Sie das Flag --flat, um das Verhalten von nomos view zu emulieren und die effektive Konfiguration in einer einzelnen Datei zu speichern.

Verwenden Sie für weitere Informationen das Flag --help:

nomos hydrate --flat

nomos view

Wenn Config Sync Konfigurationen aus dem Repository importiert, werden sie in CustomResourceDefinitions (CRDs) vom Typ ClusterConfig oder NamespaceConfig konvertiert. Mit dem Befehl nomos view können Sie die CRDs aufrufen, die sich aus dem aktuellen Status Ihres Repositorys im JSON-Format ergeben. Dies kann nützlich sein, bevor eine Änderung per Commit gespeichert wird, oder um Probleme mit Konfigurationen zu debuggen, die mit dem Befehl nomos vet nicht erkannt werden.

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

Cluster auf Fehler prüfen

Immer wenn Sie ein Git-Commit auf das Repository übertragen, erkennt der Operator die Änderung und übernimmt die neuen Konfigurationen für alle registrierten Cluster. Mit dem Befehl nomos status können Sie den Status von Config Sync auf allen registrierten Clustern überwachen. Für jeden Cluster werden der Hash des Git-Commits, der zuletzt auf den Cluster angewendet wurde, sowie alle Fehler gemeldet, die beim Versuch aufgetreten sind, die letzten Änderungen zu übernehmen. Beispiel:

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

Sie können sehen, dass die letzte Änderung bei zwei Clustern synchronisiert wurde, die Synchronisierung bei einem Cluster noch läuft und ein Cluster einen Fehler aufweist, der das Übernehmen der Änderung verhindert hat. In diesem Fall scheint managed-cluster-3 eine CRD zu fehlen, die bei den anderen Clustern installiert sind.

Standardmäßig gibt der Befehl nomos status den Status für jeden Cluster aus und wird dann beendet. Sie können jedoch das Flag poll verwenden, um den Befehl kontinuierlich auszuführen und die Statustabelle in regelmäßigen Abständen noch einmal ausgeben zu lassen

nomos status --poll 2s

In Clustern nach Fehlern suchen (Multi-Repo)

Wenn Sie die Multi-Repo-Option für Ihren Cluster aktiviert haben, können Sie Daten aus mehreren Git-Repositories synchronisieren. Der Befehl nomos status gibt den Status für jedes Repository aus, gruppiert nach Cluster. Beispiel:

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

Sie sehen, dass jeder Cluster mit zwei Git-Repositories konfiguriert ist. Das <root>-Repository gehört zum Clusteradministrator und das bookstore-Repository gehört möglicherweise zu einem Team in der Anwendungsentwicklung.

Standardmäßig gibt der Befehl nomos status den Status für alle Repositories im Cluster aus. Mit dem Flag namespace können Sie den Befehl jedoch auf ein bestimmtes Namespace-Repository beschränken. Dadurch kann das Anwendungsteam nomos status für sein Repository verwenden:

nomos status --namespace bookstore

Letzte synchronisierte Tokens

nomos status zeigt in der Ausgabe unter Last Synced Token den neuesten Git-Commit-Hash an, der auf den Cluster angewendet wurde. Fragen Sie das Repo-Objekt ab und sehen Sie sich das Feld status.sync an, um diesen Wert zu erhalten:

kubectl get repos.configmanagement.gke.io -o yaml
apiVersion: v1
kind: Repo
items:
- status:
    sync:
      lastUpdate: "2019-09-26T10:17:57Z"
      latestToken: f1739af550912034139aca51e382dc50c4036ae0

Dieser Commit stellt den letzten Commit für den Cluster dar. Allerdings ist nicht jeder Namespace im Cluster von jedem Commit betroffen. Fragen Sie das betreffende NamespaceConfig-Objekt ab und sehen Sie sich das Feld status an, um den neuesten Commit aufzurufen. Beispiel:

kubectl get namespaceconfigs.configmanagement.gke.io my-namespace -o yaml
apiVersion: configmanagement.gke.io/v1
kind: NamespaceConfig
status:
  syncState: synced
      lastUpdate: "2019-09-26T08:24:32Z"
      latestToken: 1850bad9419d3baec8af220c15d5e952dbeb3b25

Obwohl ein Namespace von einem Commit betroffen sein kann, ist möglicherweise nicht jede Ressource im Namespace betroffen. Fragen Sie die betreffende Ressource ab und sehen Sie sich metadata.annotations.configmanagement.gke.io/token an, um den zuletzt synchronisierten Commit für eine bestimmte Ressource zu finden. Beispiel:

kubectl get clusterrolebindings.rbac.authorization.k8s.io my-role-binding -o yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  annotations:
    configmanagement.gke.io/token: e56b09554ca8004a2c38185a4ed11364fd6986c4

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 zur Verfügung stellen.

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 Logs aus den Config Sync-Pods. Sie enthält keine Informationen aus den mit Config Sync synchronisierten Ressourcen.

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 zur Behebung dieses Fehlers die Umgebungsvariable USER:

export USER=$(whoami)

Weitere Informationen