Cluster zur Verwendung von Node Agent migrieren

In diesem Dokument wird beschrieben, wie Sie Cluster installieren und zu Node Agent migrieren, um sicherere Cluster-Vorgänge zu ermöglichen. Node Agent ist ein sichereres, agentenbasiertes Modell als Ansible über SSH für Cluster-Vorgänge und ab Version 1.33 verfügbar. Wenn Sie Cluster-Vorgänge mit Node Agent verwalten, können Sie ohne SSH auf Kundennodes in sensiblen Umgebungen zugreifen.

Die Node Agent-Binärdatei wird auf jedem Knoten ausgeführt. Node Agent kommuniziert mit Clients wie Controllern über einen sicheren gRPC-Kanal , um alle Knotenkonfigurationsaktivitäten zu verwalten. Google Distributed Cloud erzwingt die gegenseitige Transport Layer Security (mTLS) zwischen dem Cluster-Controller und Node Agent sowie zwischen bmctl und Node Agent für die Authentifizierung und Verschlüsselung der gRPC-Verbindungen.

Verwenden Sie bmctl nodeagent-Befehle, um den manuellen Aufwand zu reduzieren, die Konsistenz zwischen den Knoten zu verbessern und die Zertifikaterstellung und -rotation zu automatisieren. Die bmctl-Befehle werden hauptsächlich über SSH ausgeführt, sodass Sie Agents auch dann bereitstellen können, wenn der Cluster-Controller fehlerhaft ist oder seine Standardkommunikationskanäle beeinträchtigt sind.

Hinweis

Achten Sie darauf, dass alle Clusterknoten die folgenden Anforderungen erfüllen, bevor Sie einen Cluster zu Node Agent migrieren:

  • Ein offener Port, der für Node Agent reserviert ist. Node Agent verwendet standardmäßig Port 9192. Konfigurieren Sie diesen Port, wenn Sie einen neuen Cluster bereitstellen, aktivieren oder installieren. Weitere Informationen finden Sie unter Node Agent-Port anpassen.

  • Containerd-Version 1.7 oder höher.

  • 12 GB freier Speicherplatz im Verzeichnis /tmp auf dem Administrator- und allen Zielknoten. Wenn Sie die Größe des Verzeichnisses /tmp für Ihre Zielknoten nicht ändern können, lesen Sie die Informationen unter Lokale Speicherkapazität für Node Agent-Sicherungen erhöhen.

Zu Node Agent migrieren

Die Migration zu Node Agent erfolgt in zwei Schritten:

  1. Node Agent bereitstellen: Stellen Sie die Node Agent-Komponente auf allen Knoten im Cluster bereit.

  2. Node Agent-Modus aktivieren:

    • Aktivieren Sie für einen vorhandenen Cluster den Modus mit dem Befehl bmctl nodeagent.
    • Fügen Sie für einen neuen Cluster vor der Erstellung die Aktivierungsannotation und die entsprechenden Pfade zu den Anmeldedaten der Cluster-Konfigurationsdatei hinzu.

Node Agent bereitstellen

Mit dem Befehl bmctl nodeagent deploy wird der Node Agent-Dienst über SSH auf einem oder mehreren Zielknoten in einem angegebenen Cluster bereitgestellt. Mit diesem Befehl wird Node Agent installiert oder neu installiert. Er stellt eine Verbindung über SSH her und führt die erforderlichen Schritte aus, einschließlich der Übertragung von Binärdateien, der optionalen Generierung und Übertragung von Zertifikaten und der Einrichtung des systemd-Dienstes. Dazu sind SSH-Zugriff und sudo-Berechtigungen auf den Zielknoten erforderlich.

Sie können Zielknoten auf verschiedene Arten angeben: direkt über das Flag --nodes, über eine Cluster-Konfigurationsdatei mit dem Flag --cluster oder durch Verweis auf die benutzerdefinierte Cluster-Ressource. Weitere Informationen zu Node Agent Befehlen und -Optionen finden Sie in der bmctl-Befehlsreferenz.

In einer neuen Umgebung bereitstellen

Laden Sie für die Erstbereitstellung die Binärdatei nodeagentd herunter und generieren Sie neue Zertifizierungsstellen (CAs). Mit dem folgenden Befehl wird die Knotenliste aus der Cluster-Konfigurationsdatei abgerufen. Das Flag --sa-key enthält die erforderlichen Anmeldedaten zum Herunterladen der Binärdatei nodeagentd aus dem Cloud Storage-Bucket.

  • Verwenden Sie den folgenden Befehl, um Node Agent zum ersten Mal auf einem neuen Cluster bereitzustellen:

    bmctl nodeagent deploy \
    --pull-binaries=true \
    --generate-ca-creds=true \
    --cluster CLUSTER_NAME \
    --ssh-user USERNAME \
    --ssh-key SSH_KEY_PATH \
    --sa-key SERVICE_ACCOUNT_KEY_PATH

    Ersetzen Sie Folgendes:

    • CLUSTER_NAME: der Name des Clusters, auf dessen Knoten Sie Node Agent bereitstellen möchten.

    • USERNAME: der Nutzername, für den der SSH-Zugriff auf Knoten konfiguriert ist. Standardmäßig ist SSH für root konfiguriert. Wenn Sie jedoch einen Anmeldenutzer festlegen, verwenden Sie diesen Nutzernamen.

    • SSH_KEY_PATH: der Pfad der privaten SSH-Schlüsseldatei.

    • SERVICE_ACCOUNT_KEY_PATH: der Pfad der Dienstkontoschlüsseldatei mit Berechtigungen zum Abrufen von Registrierungs-Images. Standardmäßig ist dies die JSON-Schlüsseldatei für das Dienstkonto anthos-baremetal-gcr.

    Die Befehlsausgabe sieht dann ungefähr so aus:

    Please check the logs at bmctl-workspace/demo-cluster/log/nodeagent_deploy-20250819-175703/nodeagent_deploy.log
[2025-08-19 17:57:03+0000] INFO: Executing 'nodeagent deploy'...
[2025-08-19 17:57:05+0000] -------------------- Deployment Plan --------------------
[2025-08-19 17:57:05+0000]   Target Cluster:            demo-cluster
[2025-08-19 17:57:05+0000]   SSH User:                  root
[2025-08-19 17:57:05+0000]   SSH Key:                   rootSSH
[2025-08-19 17:57:05+0000]   Concurrency:               25
[2025-08-19 17:57:05+0000]   Generate Credentials:      true
[2025-08-19 17:57:05+0000]   Deploy Credentials:        true
[2025-08-19 17:57:05+0000]   Server Cert Validity Days: 1825
[2025-08-19 17:57:05+0000]   Verify SSH Host Keys:      true
[2025-08-19 17:57:05+0000]   Node Agent pull version:   1.33.0-gke.799
[2025-08-19 17:57:05+0000]   Target Nodes Source:       cluster YAML
[2025-08-19 17:57:05+0000]   Nodes Port:                9192
[2025-08-19 17:57:05+0000]   Target Nodes (4):          10.200.0.2, 10.200.0.3, 10.200.0.4, 10.200.0.5
[2025-08-19 17:57:05+0000] ---------------------------------------------------------
Proceed with deployment? [y/N]: y
[2025-08-19 17:57:07+0000] INFO: User confirmed.
[2025-08-19 17:57:07+0000] Downloading Node Agent binary (1.33.0-gke.799)... OK
[2025-08-19 17:57:08+0000] INFO: Node Agent binary pulled and stored at bmctl-workspace/bins/nodeagentd
[2025-08-19 17:57:08+0000] INFO: Starting generate credentials (CAs and client credentials) phase...
[2025-08-19 17:57:08+0000] Generating credentials for the cluster: demo-cluster, 2025-08-19T17:57:08Z
[2025-08-19 17:57:08+0000] ------------ Credentials Options ------------
[2025-08-19 17:57:08+0000] Cluster Name:           demo-cluster
[2025-08-19 17:57:08+0000] Key Algorithm:          rsa
[2025-08-19 17:57:08+0000] Key Length:             4096
[2025-08-19 17:57:08+0000] CA Validity (days):     3650
[2025-08-19 17:57:08+0000] Client Validity (days): 1825
[2025-08-19 17:57:08+0000] Server CA CN:           Node Agent Server CA
[2025-08-19 17:57:08+0000] Client CA CN:           Node Agent Client CA
[2025-08-19 17:57:08+0000] Creds path:             bmctl-workspace/demo-cluster/nodeagent-creds
[2025-08-19 17:57:08+0000] --------------------------------------------
[2025-08-19 17:57:08+0000] Generating credentials... OK
[2025-08-19 17:57:19+0000] Certificates have been created and stored in bmctl-workspace/demo-cluster/nodeagent-creds
[2025-08-19 17:57:19+0000] INFO: Attempting to load CAs from: bmctl-workspace/demo-cluster/nodeagent-creds
[2025-08-19 17:57:19+0000] INFO: Server CA loaded successfully. Subject: CN=Node Agent Server CA,O=GCD-SO,L=Sunnyvale,ST=California,C=US, Key Type: *rsa.PrivateKey
[2025-08-19 17:57:19+0000] INFO: Client CA loaded successfully. Subject: CN=Node Agent Client CA,O=GCD-SO,L=Sunnyvale,ST=California,C=US, Key Type: *rsa.PrivateKey
[2025-08-19 17:57:19+0000] ===============================================
[2025-08-19 17:57:19+0000] --- Starting Artifact Preparation ---
[2025-08-19 17:57:19+0000] Starting artifact preparation for 4 nodes (concurrency: 25)...
[2025-08-19 17:57:23+0000] --- Finished Artifact Preparation ---
[2025-08-19 17:57:23+0000] INFO: Preparation SUCCEEDED for node 10.200.0.2
[2025-08-19 17:57:23+0000] INFO: Preparation SUCCEEDED for node 10.200.0.3
[2025-08-19 17:57:23+0000] INFO: Preparation SUCCEEDED for node 10.200.0.4
[2025-08-19 17:57:23+0000] INFO: Preparation SUCCEEDED for node 10.200.0.5
[2025-08-19 17:57:23+0000] ===============================================
[2025-08-19 17:57:23+0000] --- Starting Deployment Phase ---
[2025-08-19 17:57:23+0000] INFO: Starting deployment to 4 nodes (Concurrency: 25)...
[2025-08-19 17:57:36+0000] INFO: All host deployments finished.
[2025-08-19 17:57:36+0000] INFO: --- Deployment Phase Completed Successfully ---
[2025-08-19 17:57:36+0000]
===============================================
--- Deployment Summary ---
  Host: 10.200.0.2, Status: SUCCESS
  Host: 10.200.0.3, Status: SUCCESS
  Host: 10.200.0.4, Status: SUCCESS
  Host: 10.200.0.5, Status: SUCCESS
-----------------------------------------------
Total Nodes Attempted: 4 | SUCCESS: 4 | FAILED: 0
===============================================

Node Agent-Version aktualisieren

Node Agent-Upgrades sind unabhängig von Cluster-Upgrades. Verwenden Sie den Befehl bmctl nodeagent deploy und setzen Sie --pull-binaries auf true, um Node Agent zu aktualisieren. Setzen Sie beim Aktualisieren von Node Agent --generate-ca-creds auf false, um vorhandene CAs zu verwenden, anstatt sie neu zu generieren. Für die Neugenerierung von CAs müssen die entsprechenden Clusteranmeldedaten aktualisiert werden. Dieser Vorgang ist für die Rotation von Anmeldedaten reserviert. Die Ausgabe ähnelt einer neuen Bereitstellung, jedoch ohne die von der CA generierten Logs.

Beim Aktualisieren von Node Agent wird der Node Agent-Prozess neu gestartet, wodurch alle laufenden Jobs unterbrochen werden können. Die meisten Jobs werden zwar durch Wiederholungsmechanismen wiederhergestellt, aber um potenzielle Unterbrechungen zu minimieren, führen Sie die folgenden Schritte aus:

  1. Achten Sie darauf, dass kein Cluster-Upgrade oder andere Konfigurationsaktivitäten nach der Installation ausgeführt werden.

  2. Prüfen Sie, ob sich der Cluster im Status „Wird ausgeführt“ befindet.

  3. Starten Sie das Node Agent-Upgrade:

    bmctl nodeagent deploy \
    --pull-binaries=true \
    --generate-ca-creds=false \
    --cluster CLUSTER_NAME \
    --ssh-user USERNAME \
    --ssh-key SSH_KEY_PATH \
    --sa-key SERVICE_ACCOUNT_KEY_PATH

    Ersetzen Sie Folgendes:

    • CLUSTER_NAME: der Name des Clusters, auf dessen Knoten Sie Node Agent bereitstellen möchten.

    • USERNAME: der Nutzername, für den der SSH-Zugriff auf Knoten konfiguriert ist. Standardmäßig ist SSH für root konfiguriert. Wenn Sie jedoch einen Anmeldenutzer festlegen, verwenden Sie diesen Nutzernamen.

    • SSH_KEY_PATH: der Pfad der privaten SSH-Schlüsseldatei.

    • SERVICE_ACCOUNT_KEY_PATH: der Pfad der Dienstkontoschlüsseldatei mit Berechtigungen zum Abrufen von Registrierungs-Images. Standardmäßig ist dies die JSON-Schlüsseldatei für das Dienstkonto anthos-baremetal-gcr.

    Die Befehlsausgabe sieht dann ungefähr so aus:

    Please check the logs at bmctl-workspace/demo-cluster/log/nodeagent_deploy-20250819-180416/nodeagent_deploy.log
[2025-08-19 18:04:16+0000] INFO: Executing 'nodeagent deploy'...
[2025-08-19 18:04:18+0000] -------------------- Deployment Plan --------------------
[2025-08-19 18:04:18+0000]   Target Cluster:            demo-cluster
[2025-08-19 18:04:18+0000]   SSH User:                  root
[2025-08-19 18:04:18+0000]   SSH Key:                   rootSSH
[2025-08-19 18:04:18+0000]   Concurrency:               25
[2025-08-19 18:04:18+0000]   Generate Credentials:      false
[2025-08-19 18:04:18+0000]   Deploy Credentials:        true
[2025-08-19 18:04:18+0000]   Server Cert Validity Days: 1825
[2025-08-19 18:04:18+0000]   Verify SSH Host Keys:      true
[2025-08-19 18:04:18+0000]   Node Agent pull version:   1.33.0-gke.799
[2025-08-19 18:04:18+0000]   Target Nodes Source:       cluster YAML
[2025-08-19 18:04:18+0000]   Nodes Port:                9192
[2025-08-19 18:04:18+0000]   Target Nodes (4):          10.200.0.2, 10.200.0.3, 10.200.0.4, 10.200.0.5
[2025-08-19 18:04:18+0000] ---------------------------------------------------------
Proceed with deployment? [y/N]: y
[2025-08-19 18:04:20+0000] INFO: User confirmed.
[2025-08-19 18:04:20+0000] Downloading Node Agent binary (1.33.0-gke.799)... OK
[2025-08-19 18:04:22+0000] INFO: Node Agent binary pulled and stored at bmctl-workspace/bins/nodeagentd
[2025-08-19 18:04:22+0000] INFO: Attempting to load CAs from: bmctl-workspace/demo-cluster/nodeagent-creds
[2025-08-19 18:04:22+0000] INFO: Server CA loaded successfully. Subject: CN=Node Agent Server CA,O=gcd-SO,L=Sunnyvale,ST=California,C=US, Key Type: *rsa.PrivateKey
[2025-08-19 18:04:22+0000] INFO: Client CA loaded successfully. Subject: CN=Node Agent Client CA,O=gcd-SO,L=Sunnyvale,ST=California,C=US, Key Type: *rsa.PrivateKey
[2025-08-19 18:04:22+0000] ===============================================
[2025-08-19 18:04:22+0000] --- Starting Artifact Preparation ---
[2025-08-19 18:04:22+0000] Starting artifact preparation for 4 nodes (concurrency: 25)...

Auf bestimmten Knoten bereitstellen oder neu bereitstellen

Wenn Sie Clusterknoten hinzufügen oder wiederherstellen, können Sie die Bereitstellung von Node Agent auf bestimmte Knoten ausrichten, anstatt sie auf allen Knoten im Cluster bereitzustellen. Mit dem Flag --nodes geben Sie den Knoten für die Bereitstellung an.

  • Verwenden Sie den folgenden Befehl, um Node Agent auf bestimmten Knoten bereitzustellen:

    bmctl nodeagent deploy \
    --pull-binaries=true \
    --cluster CLUSTER_NAME \
    --ssh-user USERNAME \
    --ssh-key SSH_KEY_PATH \
    --sa-key SERVICE_ACCOUNT_KEY_PATH \
    --nodes NODE_IP_ADDRESS_LIST

    Ersetzen Sie Folgendes:

    • CLUSTER_NAME: der Name des Clusters, auf dessen Knoten Sie Node Agent bereitstellen möchten.

    • USERNAME: der Nutzername, für den der SSH-Zugriff auf Knoten konfiguriert ist. Standardmäßig ist SSH für root konfiguriert. Wenn Sie jedoch einen Anmeldenutzer festlegen, verwenden Sie diesen Nutzernamen.

    • SSH_KEY_PATH: der Pfad der privaten SSH-Schlüsseldatei.

    • SERVICE_ACCOUNT_KEY_PATH: der Pfad der Dienstkontoschlüsseldatei mit Berechtigungen zum Abrufen von Registrierungs-Images. Standardmäßig ist dies die JSON-Schlüsseldatei für das Dienstkonto anthos-baremetal-gcr.

    • NODE_IP_ADDRESS_LIST: eine durch Kommas getrennte Liste der IP-Adressen der Knoten, auf denen Sie Node Agent bereitstellen.

    Die Befehlsausgabe sieht dann ungefähr so aus:

    Please check the logs at bmctl-workspace/demo-cluster/log/nodeagent_deploy-20250819-181751/nodeagent_deploy.log
[2025-08-19 18:17:51+0000] INFO: Executing 'nodeagent deploy'...
[2025-08-19 18:17:54+0000] -------------------- Deployment Plan --------------------
[2025-08-19 18:17:54+0000]   Target Cluster:            demo-cluster
[2025-08-19 18:17:54+0000]   SSH User:                  user
[2025-08-19 18:17:54+0000]   SSH Key:                   SSH_KEY_PATH
[2025-08-19 18:17:54+0000]   Concurrency:               25
[2025-08-19 18:17:54+0000]   Generate Credentials:      false
[2025-08-19 18:17:54+0000]   Deploy Credentials:        true
[2025-08-19 18:17:54+0000]   Server Cert Validity Days: 1825
[2025-08-19 18:17:54+0000]   Verify SSH Host Keys:      true
[2025-08-19 18:17:54+0000]   Node Agent pull version:   1.33.0-gke.799
[2025-08-19 18:17:54+0000]   Target Nodes Source:       nodes flag
[2025-08-19 18:17:54+0000]   Nodes Port:                9192
[2025-08-19 18:17:54+0000]   Target Nodes (3):          10.200.0.2, 10.200.0.3
[2025-08-19 18:17:54+0000] ---------------------------------------------------------
Proceed with deployment? [y/N]:

Eine vollständige Liste der bmctl nodeagent deploy Befehlsoptionen finden Sie unter nodeagent deploy in der bmctl Befehls referenz.

Node Agent aktivieren

Mit dem Befehl enable wird der Node Agent-Modus in einem vorhandenen Cluster aktiviert, nachdem Sie Node Agent auf allen Knoten im Cluster bereitgestellt haben. Mit diesem Befehl werden auch die Node Agent-Anmeldedaten im Cluster erstellt oder aktualisiert.

Node Agent für einen vorhandenen Cluster aktivieren

Sie können Node Agent in vorhandenen Clustern der Version 1.33 und höher aktivieren.

  • Verwenden Sie den folgenden Befehl, um Node Agent in einem vorhandenen Cluster zu aktivieren:

    ./bmctl nodeagent enable \
    --kubeconfig KUBECONFIG \
    --cluster CLUSTER_NAME \
    --namespace CLUSTER_NAMESPACE \
    --ensure-status=true

    Ersetzen Sie Folgendes:

    • KUBECONFIG: der Pfad der kubeconfig-Datei für den Cluster, für den Sie Node Agent aktivieren.

    • CLUSTER_NAME: der Name des Clusters, auf dessen Knoten Sie Node Agent bereitstellen möchten.

    • CLUSTER_NAMESPACE: der Namespace des Clusters, der verwendet werden soll, um den Zielcluster und die Clusteranmeldedaten zu finden und die Clusterressource zu aktualisieren. Standardmäßig ist cluster-<CLUSTER-NAME> festgelegt.

    Die Befehlsausgabe sieht dann ungefähr so aus:

    Please check the logs at bmctl-workspace/demo-cluster/log/nodeagent_enable-20250819-183058/nodeagent_enable.log
[2025-08-19 18:30:58+0000] Enable Node Agent for cluster: demo-cluster
[2025-08-19 18:31:00+0000] Update Node Agent credentials
[2025-08-19 18:31:00+0000] ----------------------------------------------------------
[2025-08-19 18:31:00+0000] Server CA certificate path: bmctl-workspace/demo-cluster/nodeagent-creds/server_ca_cert.pem
[2025-08-19 18:31:00+0000] Server CA private key path: bmctl-workspace/demo-cluster/nodeagent-creds/server_ca_key.pem
[2025-08-19 18:31:00+0000] Client CA certificate path: bmctl-workspace/demo-cluster/nodeagent-creds/client_ca_cert.pem
[2025-08-19 18:31:00+0000] Client CA private key path: bmctl-workspace/demo-cluster/nodeagent-creds/client_ca_key.pem
[2025-08-19 18:31:00+0000] Client certificate path: bmctl-workspace/demo-cluster/nodeagent-creds/client_cert.pem
[2025-08-19 18:31:00+0000] Client private key path: bmctl-workspace/demo-cluster/nodeagent-creds/client_key.pem
[2025-08-19 18:31:00+0000] ----------------------------------------------------------
[2025-08-19 18:31:00+0000] Node Agent client credentials secret has been created/updated
[2025-08-19 18:31:00+0000] Node Agent server CA secret has been created/updated
[2025-08-19 18:31:00+0000] Node Agent client CA secret has been created/updated
[2025-08-19 18:31:00+0000] Successfully created/updated Node Agent credentials secrets in namespace cluster-demo-cluster
[2025-08-19 18:31:00+0000] Annotation 'baremetal.cluster.gke.io/node-agent-port' not found on cluster cluster-demo-cluster/demo-cluster, no removal needed.
[2025-08-19 18:31:00+0000] Successfully enable Node Agent for cluster: demo-cluster
[2025-08-19 18:31:00+0000] ----------------------------------------------------------
[2025-08-19 18:31:00+0000] Verifying Node Agent status on all nodes...
[2025-08-19 18:31:00+0000] --------------------- Total nodes: 3 ----------------------
[2025-08-19 18:31:00+0000] node: control-0--893f0567cb79efc-9b9ec55816170dcf.lab.anthos, version: 1.33.0-gke.799, OS: linux, uptime (seconds): 1577
[2025-08-19 18:31:00+0000] node: control-1--893f0567cb79efc-9b9ec55816170dcf.lab.anthos, version: 1.33.0-gke.799, OS: linux, uptime (seconds): 1578
[2025-08-19 18:31:00+0000] node: control-2--893f0567cb79efc-9b9ec55816170dcf.lab.anthos, version: 1.33.0-gke.799, OS: linux, uptime (seconds): 1581
[2025-08-19 18:31:00+0000] ----------------------------------------------------------
[2025-08-19 18:31:00+0000] Verified Node Agent status on all nodes in cluster

Neuen Cluster installieren

Sie können Node Agent verwenden, wenn Sie Cluster der Version 1.33 und höher erstellen.

So verwenden Sie Node Agent für einen neuen Cluster:

  1. Fügen Sie für einen neuen Administratorcluster die folgenden Pfade zu den Anmeldedatendateien in den oberen Abschnitt der Konfigurationsdatei des Administratorclusters ein:

    nodeAgentServerCACertificatePath: bmctl-workspace/demo-cluster/nodeagent-creds/server_ca_cert.pem
nodeAgentServerCAPrivateKeyPath: bmctl-workspace/demo-cluster/nodeagent-creds/server_ca_key.pem
nodeAgentClientCACertificatePath: bmctl-workspace/demo-cluster/nodeagent-creds/client_ca_cert.pem
nodeAgentClientCAPrivateKeyPath: bmctl-workspace/demo-cluster/nodeagent-creds/client_ca_key.pem
nodeAgentClientCertificatePath: bmctl-workspace/demo-cluster/nodeagent-creds/client_cert.pem
nodeAgentClientPrivateKeyPath: bmctl-workspace/demo-cluster/nodeagent-creds/client_key.pem

  2. Fügen Sie die Annotation zur Aktivierung von Node Agent in den Abschnitt mit den Clustermetadaten der Cluster-Konfigurationsdatei ein:

    kind: Cluster
metadata:
  annotations:
    baremetal.cluster.gke.io/enable-node-agent: ""

  3. Folgen Sie der Standard anleitung zum Erstellen Ihres Clusters.

Eine vollständige Liste der bmctl nodeagent enable Befehlsoptionen finden Sie unter nodeagent enable in der bmctl Befehls referenz.

Anmeldedaten rotieren

Mit dem Befehl rotate-credentials werden die Node Agent-Anmeldedaten sowohl auf den Knoten als auch im Cluster rotiert. Dazu gehört auch die Möglichkeit, die Zertifizierungsstellen (CAs) zu rotieren. Das Flag --generate-ca-creds weist den Befehl an, die CAs neu zu generieren und diese neu generierten CAs zu verwenden, um die Zertifikate für den Server (Knoten) und den Client (Controller) zu signieren.

  • Verwenden Sie den folgenden Befehl, um Anmeldedaten zu rotieren und neue CAs zu generieren und zu verwenden:

    bmctl nodeagent rotate-credentials \
    --kubeconfig KUBECONFIG \
    --generate-ca-creds=true \
    --cluster CLUSTER_NAME \
    --namespace CLUSTER_NAMESPACE \
    --ssh-user USERNAME \
    --ssh-key SSH_KEY_PATH

    Ersetzen Sie Folgendes:

    • KUBECONFIG: der Pfad der kubeconfig-Datei für den Cluster, für den Sie Node Agent aktivieren.

    • CLUSTER_NAME: der Name des Clusters, auf dessen Knoten Sie Node Agent bereitstellen möchten.

    • CLUSTER_NAMESPACE: der Namespace des Clusters, der verwendet werden soll, um den Zielcluster und die Clusteranmeldedaten zu finden und die Clusterressource zu aktualisieren. Standardmäßig ist cluster-<CLUSTER-NAME> festgelegt.

    • USERNAME: der Nutzername, für den der SSH-Zugriff auf Knoten konfiguriert ist. Standardmäßig ist SSH für root konfiguriert. Wenn Sie jedoch einen Anmeldenutzer festlegen, verwenden Sie diesen Nutzernamen.

    • SSH_KEY_PATH: der Pfad der privaten SSH-Schlüsseldatei.

    Die Befehlsausgabe sieht dann ungefähr so aus:

    Please check the logs at bmctl-workspace/demo-cluster/log/nodeagent_rotate_credentials-20250819-184216/nodeagent_rotate_credentials.log
[2025-08-19 18:42:16+0000] INFO: Executing 'nodeagent rotate-credentials'...
[2025-08-19 18:42:18+0000] ------------------- Credentials Rotation  -------------------
[2025-08-19 18:42:18+0000]   Target Cluster:            demo-cluster
[2025-08-19 18:42:18+0000]   SSH User:                  root
[2025-08-19 18:42:18+0000]   SSH Key:                   rootSSH
[2025-08-19 18:42:18+0000]   Concurrency:               25
[2025-08-19 18:42:18+0000]   Generate Credentials:      true
[2025-08-19 18:42:18+0000]   Deploy Credentials:        true
[2025-08-19 18:42:18+0000]   Server Cert Validity Days: 1825
[2025-08-19 18:42:18+0000]   Verify SSH Host Keys:      true
[2025-08-19 18:42:18+0000]   Target Nodes Source:       cluster CR
[2025-08-19 18:42:18+0000]   Nodes Port:                9192
[2025-08-19 18:42:18+0000]   Target Nodes (3):          10.200.0.2, 10.200.0.3, 10.200.0.4
[2025-08-19 18:42:18+0000] ---------------------------------------------------------
Proceed with credentials rotation? [y/N]: [2025-08-19 18:42:18+0000] INFO: Non-interactive mode enabled; automatically confirming.
[2025-08-19 18:42:18+0000] INFO: Starting generate credentials (CAs and client credentials) phase...
[2025-08-19 18:42:18+0000] Generating credentials for the cluster: demo-cluster, 2025-08-19T18:42:18Z
[2025-08-19 18:42:18+0000] ------------ Credentials Options ------------
[2025-08-19 18:42:18+0000] Cluster Name:           demo-cluster
[2025-08-19 18:42:18+0000] Key Algorithm:          rsa
[2025-08-19 18:42:18+0000] Key Length:             4096
[2025-08-19 18:42:18+0000] CA Validity (days):     3650
[2025-08-19 18:42:18+0000] Client Validity (days): 1825
[2025-08-19 18:42:18+0000] Server CA CN:           Node Agent Server CA
[2025-08-19 18:42:18+0000] Client CA CN:           Node Agent Client CA
[2025-08-19 18:42:18+0000] Creds path:             bmctl-workspace/demo-cluster/nodeagent-creds
[2025-08-19 18:42:18+0000] --------------------------------------------
[2025-08-19 18:42:18+0000] Generating credentials... OK
Credential directory 'bmctl-workspace/demo-cluster/nodeagent-creds' already exists. Do you want to back it up and continue? (y/N): y
[2025-08-19 18:42:27+0000] INFO: User confirmed.
[2025-08-19 18:42:27+0000] Credentials backup to bmctl-workspace/demo-cluster/nodeagent-creds_backup_20250819_184227
[2025-08-19 18:42:27+0000] Certificates have been created and stored in bmctl-workspace/demo-cluster/nodeagent-creds
[2025-08-19 18:42:27+0000] INFO: Attempting to load CAs from: bmctl-workspace/demo-cluster/nodeagent-creds
[2025-08-19 18:42:27+0000] INFO: Server CA loaded successfully. Subject: CN=Node Agent Server CA,O=gcd-SO,L=Sunnyvale,ST=California,C=US, Key Type: *rsa.PrivateKey
[2025-08-19 18:42:27+0000] INFO: Client CA loaded successfully. Subject: CN=Node Agent Client CA,O=gcd-SO,L=Sunnyvale,ST=California,C=US, Key Type: *rsa.PrivateKey
[2025-08-19 18:42:27+0000] ===============================================
[2025-08-19 18:42:34+0000] INFO: All host deployments finished.
[2025-08-19 18:42:34+0000] INFO: --- Deployment Phase Completed Successfully ---
[2025-08-19 18:42:34+0000]
===============================================
--- Deployment Summary ---
  Host: 10.200.0.2, Status: SUCCESS
  Host: 10.200.0.3, Status: SUCCESS
  Host: 10.200.0.4, Status: SUCCESS
-----------------------------------------------
Total Nodes Attempted: 3 | SUCCESS: 3 | FAILED: 0
===============================================

Eine vollständige Liste der bmctl nodeagent rotate-credentials Befehlsoptionen finden Sie unter nodeagent rotate-credentials in der bmctl-Befehlsreferenz.

Status prüfen

Der Befehl status enthält Informationen zum Ausführungsstatus von Node Agent auf Knoten. Sie können Zielknoten direkt über das Flag --nodes, über eine Cluster-Konfigurationsdatei mit dem Flag --cluster oder durch Verweis auf die benutzerdefinierte Cluster-Ressource angeben.

Wenn Sie Knoten aus einer Cluster-Konfigurationsdatei oder dem Flag --nodes abrufen, ruft das System Anmeldedaten aus dem lokalen Dateisystem ab. Wenn die Knotenquelle eine benutzerdefinierte Cluster-Ressource ist, ruft das System Anmeldedaten aus dem Cluster ab.

Die folgende Rangfolge bestimmt den Node Agent-Port:

  1. Flag --port
  2. kubeconfig-Datei
  3. Cluster-Konfigurationsdatei

Node Agent-Status prüfen

Mit dem Flag --cluster können Sie den Node Agent-Status anhand der Angaben in der Cluster-Konfigurationsdatei prüfen.

  • Verwenden Sie den folgenden Befehl, um den Node Agent-Status anhand der Cluster-Konfigurationsdatei zu prüfen:

    ./bmctl nodeagent status \
    --cluster CLUSTER_NAME \
    --namespace CLUSTER_NAMESPACE

    Ersetzen Sie Folgendes:

    • CLUSTER_NAME: der Name des Clusters, den Sie prüfen.

    • CLUSTER_NAMESPACE: der Namespace des Clusters, der verwendet werden soll, um den Zielcluster und die Clusteranmeldedaten zu finden und die Clusterressource zu aktualisieren. Standardmäßig ist cluster-<CLUSTER-NAME> festgelegt.

    Die Befehlsausgabe sieht dann ungefähr so aus:

    Please check the logs at bmctl-workspace/demo-cluster/log/nodeagent_status-20250819-205707/nodeagent_status.log
[2025-08-19 20:57:07+0000] Check Node Agent for cluster: demo-cluster
[2025-08-19 20:57:09+0000] ----------------------------------------------------------
[2025-08-19 20:57:09+0000] Verifying Node Agent status on all nodes...
[2025-08-19 20:57:09+0000] Target Nodes Source: cluster YAML
[2025-08-19 20:57:09+0000] --------------------- Total nodes: 4 ----------------------
[2025-08-19 20:57:09+0000] node: control-0--893f0567cb79efc-9b9ec55816170dcf.lab.anthos, version: 1.33.0-gke.799, OS: linux, uptime (seconds): 1175
[2025-08-19 20:57:09+0000] node: control-1--893f0567cb79efc-9b9ec55816170dcf.lab.anthos, version: 1.33.0-gke.799, OS: linux, uptime (seconds): 1174
[2025-08-19 20:57:09+0000] node: control-2--893f0567cb79efc-9b9ec55816170dcf.lab.anthos, version: 1.33.0-gke.799, OS: linux, uptime (seconds): 1176
[2025-08-19 20:57:09+0000] node: worker-0--893f0567cb79efc-9b9ec55816170dcf.lab.anthos, version: 1.33.0-gke.799, OS: linux, uptime (seconds): 1179
[2025-08-19 20:57:09+0000] ----------------------------------------------------------
[2025-08-19 20:57:09+0000] Verified Node Agent status on all nodes in cluster

Node Agent-Status aus dem Cluster prüfen

Mit dem Flag --cluster und dem Flag --kubeconfig können Sie den Node Agent-Status anhand der benutzerdefinierten Cluster-Ressource prüfen.

  • Verwenden Sie den folgenden Befehl, um den Node Agent-Status anhand der benutzerdefinierten Cluster-Ressource zu prüfen:

    ./bmctl nodeagent status \
    --cluster CLUSTER_NAME \
    --kubeconfig KUBECONFIG

    Ersetzen Sie Folgendes:

    • CLUSTER_NAME: der Name des Clusters, auf dessen Knoten Sie Node Agent bereitstellen möchten.

    • KUBECONFIG: der Pfad der kubeconfig-Datei für den Cluster, für den Sie Node Agent aktivieren.

    Die Befehlsausgabe sieht dann ungefähr so aus:

    Please check the logs at bmctl-workspace/demo-cluster/log/nodeagent_status-20250819-205712/nodeagent_status.log
[2025-08-19 20:57:12+0000] Check Node Agent for cluster: demo-cluster
[2025-08-19 20:57:14+0000] ----------------------------------------------------------
[2025-08-19 20:57:14+0000] Verifying Node Agent status on all nodes...
[2025-08-19 20:57:14+0000] Target Nodes Source: cluster CR
[2025-08-19 20:57:14+0000] --------------------- Total nodes: 3 ----------------------
[2025-08-19 20:57:14+0000] node: control-0--893f0567cb79efc-9b9ec55816170dcf.lab.anthos, version: 1.33.0-gke.799, OS: linux, uptime (seconds): 1180
[2025-08-19 20:57:14+0000] node: control-1--893f0567cb79efc-9b9ec55816170dcf.lab.anthos, version: 1.33.0-gke.799, OS: linux, uptime (seconds): 1179
[2025-08-19 20:57:14+0000] node: control-2--893f0567cb79efc-9b9ec55816170dcf.lab.anthos, version: 1.33.0-gke.799, OS: linux, uptime (seconds): 1180
[2025-08-19 20:57:14+0000] ----------------------------------------------------------
[2025-08-19 20:57:14+0000] Verified Node Agent status on all nodes in cluster

Node Agent-Status von Knoten prüfen

Mit dem Flag --cluster und dem Flag --nodes können Sie den Node Agent-Status für bestimmte Clusterknoten prüfen.

  • Verwenden Sie den folgenden Befehl, um den Node Agent-Status für bestimmte Knoten zu prüfen:

    ./bmctl nodeagent status \
    --cluster CLUSTER_NAME \
    --nodes NODE_IP_ADDRESS_LIST

    Ersetzen Sie Folgendes:

    • CLUSTER_NAME: der Name des Clusters, auf dessen Knoten Sie Node Agent bereitstellen möchten.

    • NODE_IP_ADDRESS_LIST: eine durch Kommas getrennte Liste der IP-Adressen der Knoten, auf denen Sie Node Agent bereitstellen.

    Die Befehlsausgabe sieht dann ungefähr so aus:

    Please check the logs at bmctl-workspace/demo-cluster/log/nodeagent_status-20250819-210050/nodeagent_status.log
[2025-08-19 21:00:50+0000] Check Node Agent for cluster: demo-cluster
[2025-08-19 21:00:53+0000] ----------------------------------------------------------
[2025-08-19 21:00:53+0000] Verifying Node Agent status on all nodes...
[2025-08-19 21:00:53+0000] Target Nodes Source: nodes flag
[2025-08-19 21:00:53+0000] --------------------- Total nodes: 1 ----------------------
[2025-08-19 21:00:53+0000] node: control-0--893f0567cb79efc-9b9ec55816170dcf.lab.anthos, version: 1.33.0-gke.799, OS: linux, uptime (seconds): 1399
[2025-08-19 21:00:53+0000] ----------------------------------------------------------
[2025-08-19 21:00:53+0000] Verified Node Agent status on all nodes in cluster

Eine vollständige Liste der bmctl nodeagent status Befehlsoptionen finden Sie unter nodeagent status in der bmctl Befehls referenz.

SSH-Nutzerberechtigungen

Ein Nutzer, der kein Root-Nutzer ist, kann den Befehl bmctl nodeagent ausführen. Dazu muss der Nutzer entweder vollständige sudo-Berechtigungen ohne Passwort oder eine explizite sudo-Zulassungsliste ohne Passwort haben.

Die explizite sudo-Zulassungsliste ohne Passwort für Node Agent hat die folgenden Berechtigungen:

# Permission to create the necessary folders and set permissions.
/bin/mkdir -p /etc/nodeagentd
/bin/chmod 0755 /etc/nodeagentd
/bin/mkdir -p /usr/local/bin
/bin/chmod 0755 /usr/local/bin
/bin/mkdir -p /etc/systemd/system
/bin/chmod 0755 /etc/systemd/system

# Permission to place the main application executable and link it.
/bin/rm -f /usr/local/bin/nodeagentd-*
/bin/touch /usr/local/bin/nodeagentd-*
/bin/cp -f /home/deployer/.deploy_tmp_*/* /usr/local/bin/nodeagentd-*
/bin/chmod 0755 /usr/local/bin/nodeagentd-*
/bin/rm -f /usr/local/bin/nodeagentd
/bin/ln -s /usr/local/bin/nodeagentd-* /usr/local/bin/nodeagentd

# Permission to place configuration files in /etc/nodeagentd and set permissions.
/bin/rm -f /etc/nodeagentd/*
/bin/touch /etc/nodeagentd/*
/bin/cp -f /home/deployer/.deploy_tmp_*/* /etc/nodeagentd/*
/bin/chmod 0600 /etc/nodeagentd/*
/bin/chmod 0644 /etc/nodeagentd/*

# Permission to place the systemd unit file.
/bin/rm -f /etc/systemd/system/nodeagentd.service
/bin/touch /etc/systemd/system/nodeagentd.service
/bin/cp -f /home/deployer/.deploy_tmp_*/* /etc/systemd/system/nodeagentd.service
/bin/chmod 0644 /etc/systemd/system/nodeagentd.service

# Permission to interact with systemd service.
/bin/systemctl daemon-reload
/bin/systemctl stop nodeagentd
/bin/systemctl start nodeagentd
/bin/systemctl enable --now nodeagentd

# Permission to remove the temporary files used for the deployment.
/bin/rm -f /home/deployer/.deploy_tmp_*/*

SSH-Hostschlüsselprüfung

Achten Sie darauf, dass alle Knoten der Datei known_hosts auf der Administrator-Workstation hinzugefügt werden. Andernfalls deaktivieren Sie die Hostschlüsselprüfung während der Bereitstellung (nodeagent deploy) und der Rotation von Anmeldedaten (nodeagent rotate-credentials) mit dem --enforce-host-key-verify=false Flag.

Node Agent-Port anpassen

Node Agent ermöglicht die Anpassung des Ports. Geben Sie diesen benutzerdefinierten Port während der Bereitstellung mit dem Flag --port an. Dadurch wird die Einstellung an die Node Agent-Konfiguration auf jedem Knoten weitergegeben. Der angepasste Port muss mit der clientseitigen Konfiguration übereinstimmen, wie in den folgenden Methoden beschrieben.

Für vorhandene Cluster

Verwenden Sie das Flag --port, um den neuen benutzerdefinierten Port anzugeben und einen vorhandenen Cluster zu aktualisieren. Diese Einstellung wird an die Clients (Controller) weitergegeben.

Für neue Cluster

Fügen Sie beim Erstellen eines neuen Clusters der Clusterkonfiguration die folgende Annotation hinzu, um einen benutzerdefinierten Port für Node Agent anzugeben:

kind: Cluster
metadata:
  annotations:
    baremetal.cluster.gke.io/node-agent-port: "10086"

Lokale Speicherkapazität für Node Agent-Sicherungen erhöhen

Um eine Sicherungsdatei für Node Agent-Knoten zu erstellen, müssen 12 GB freier Speicherplatz im Verzeichnis /tmp auf dem Administrator- und allen Zielknoten verfügbar sein. Wenn Sie die Größe des Verzeichnisses /tmp für Ihre Zielknoten nicht ändern können, lesen Sie die Informationen unter Lokale Speicherkapazität für Zielknoten ändern. Wenn Sie die Größe des Verzeichnisses /tmp für den Administratorknoten nicht ändern können, lesen Sie die Informationen unter Lokale Speicherkapazität für einen Administratorknoten ändern.

Lokale Speicherkapazität für Zielknoten ändern

Wenn Sie die Größe der /tmp-Partition des Zielknotens nicht ändern können, können Sie den temporären Ordner auf eine Partition mit mehr Kapazität umleiten, indem Sie eine systemd-Umgebung überschreiben:

  1. Erstellen Sie eine systemd-Überschreibungsdatei unter /etc/systemd/system/nodeagentd.service.d/override.conf mit folgendem Inhalt:

    [Service]
Environment="TMPDIR=/var/tmp"

  2. Wenden Sie die Konfiguration an und starten Sie den Dienst neu:

    sudo systemctl daemon-reload
sudo systemctl restart nodeagentd

Lokale Speicherkapazität für einen Administratorknoten ändern

Wenn auf der Administrator-Workstation, auf der bmctl ausgeführt wird, nur wenig Speicherplatz für die /tmp-Partition verfügbar ist, legen Sie die Variable TMPDIR lokal fest, wenn Sie eine Sicherung starten:

  TMPDIR=/var/tmp bmctl backup cluster -c CLUSTER_NAME --kubeconfig KUBECONFIG

Ersetzen Sie Folgendes:

  • CLUSTER_NAME: der Name des Clusters, auf dessen Knoten Sie Node Agent bereitstellen möchten.
  • KUBECONFIG: der Pfad der kubeconfig-Datei für den Cluster, für den Sie Node Agent aktivieren.

Leistung

Die Bereitstellung und Aktivierung sind in weniger als einer Minute abgeschlossen. Die Laufzeit der Rotation von Anmeldedaten ist mit einer Standardbereitstellung vergleichbar oder schneller.