Cluster zur Verwendung von Node Agent migrieren

In diesem Dokument wird beschrieben, wie Sie die Verwendung von Node Agent für neue und vorhandene Cluster aktivieren, um sicherere Clusteroperationen zu ermöglichen. Ab Version 1.33 bietet Google Distributed Cloud for Bare Metal die Möglichkeit, für Clusteroperationen von Ansible über SSH zu einem sichereren, agentbasierten Modell zu wechseln, das Node Agent verwendet. Durch die Verwendung von Node Agent zur Verwaltung von Clusteroperationen werden Sicherheitsbedenken hinsichtlich des erforderlichen SSH-Zugriffs auf Kundennodes in sensiblen Umgebungen ausgeräumt. Im neuen Modell wird auf jedem Knoten eine Node Agent-Binärdatei ausgeführt. Der Node-Agent kommuniziert über einen sicheren gRPC-Kanal mit Clients wie Controllern, um alle Konfigurationsaktivitäten des Knotens zu verwalten. In Google Distributed Cloud wird Mutual Transport Layer Security (mTLS) zwischen dem Cluster-Controller und dem Node Agent sowie zwischen bmctl und dem Node Agent für die Authentifizierung und Verschlüsselung der gRPC-Verbindungen erzwungen.

Die Befehle bmctl nodeagent machen die Migration vorhandener Cluster zur Verwendung von Node Agent einfach und zuverlässig. Die Befehle reduzieren den manuellen Aufwand, verbessern die Konsistenz zwischen den Knoten und automatisieren wichtige Aufgaben wie das Erstellen und Rotieren von Zertifikaten. Die bmctl-Befehle werden hauptsächlich über SSH ausgeführt. So können Administratoren Agents auch dann bereitstellen oder neu bereitstellen, wenn der Cluster-Controller fehlerhaft ist oder seine Standardkommunikationskanäle beeinträchtigt sind.

Der Node-Agent und die entsprechenden bmctl nodeagent-Befehle unterstützen Google Distributed Cloud für Bare Metal-Versionen ab 1.33.0. Sie können den Node Agent für vorhandene Cluster der Version 1.33 oder höher oder beim Erstellen von Clustern der Version 1.33 oder höher aktivieren.

Diese Seite richtet sich an Administratoren, Architekten und Betreiber, die den Lebenszyklus der zugrunde liegenden technischen Infrastruktur verwalten. Weitere Informationen zu gängigen Rollen und Beispielaufgaben, auf die wir in Google Cloud -Inhalten verweisen, finden Sie unter Häufig verwendete GKE Enterprise-Nutzerrollen und -Aufgaben.

Hinweise

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

  • Jeder Knoten hat einen offenen Port, der für den Node Agent vorgesehen ist. Standardmäßig verwendet der Node Agent Port 9192. Sie können diesen Port jedoch während der Bereitstellung, Aktivierung oder Installation neuer Cluster konfigurieren. Weitere Informationen finden Sie unter Node-Agent-Port anpassen.

  • Auf jedem Knoten ist containerd-Version 1.7 oder höher installiert.

Zum Knoten-Agent-Modus migrieren

Die Migration zum Node Agent-Modus erfolgt in zwei Schritten:

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

  2. Knoten-Agent-Modus aktivieren:

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

Knoten-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 der Node Agent installiert oder neu installiert. Es 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 Clusterkonfigurationsdatei mit dem Flag --cluster oder durch Verweisen auf die benutzerdefinierte Clusterressource. 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 (Certificate Authorities, CAs). Mit dem folgenden Befehl wird die Knotenliste aus der Clusterkonfigurationsdatei abgerufen. Das Flag --sa-key stellt die erforderlichen Anmeldedaten zum Herunterladen der Binärdatei nodeagentd aus dem Cloud Storage-Bucket bereit.

  • Verwenden Sie den folgenden Befehl, um den Node Agent zum ersten Mal in 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 den 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 Datei mit dem privaten SSH-Schlüssel.

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

    Die Befehlsausgabe sieht in etwa 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 zum Aktualisieren von Node Agent den Befehl bmctl nodeagent deploy und legen Sie --pull-binaries auf true fest. Wenn Sie den Node Agent aktualisieren, setzen Sie --generate-ca-creds auf false, um vorhandene Zertifizierungsstellen zu verwenden, anstatt sie neu zu generieren. Wenn Sie Zertifizierungsstellen neu generieren, müssen Sie die entsprechenden Clusteranmeldedaten aktualisieren. Dieser Vorgang ist für die Rotation von Anmeldedaten reserviert. Die Ausgabe ähnelt einer neuen Bereitstellung, jedoch ohne die von der Zertifizierungsstelle generierten Logs.

Beim Aktualisieren des Node Agent wird der Node Agent-Prozess neu gestartet, was laufende Jobs unterbrechen kann. Die meisten Jobs werden zwar durch Wiederholungsmechanismen wiederhergestellt, aber um potenzielle Unterbrechungen zu minimieren, sollten Sie die folgenden Schritte ausführen:

  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 den 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 Datei mit dem privaten SSH-Schlüssel.

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

    Die Befehlsausgabe sieht in etwa 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 des Node Agent auf bestimmte Knoten ausrichten, anstatt ihn 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 den 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 den 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 Datei mit dem privaten SSH-Schlüssel.

    • SERVICE_ACCOUNT_KEY_PATH: Der Pfad der Dienstkonto-Schlüsseldatei mit Berechtigungen zum Abrufen von Registry-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 den Node Agent bereitstellen.

    Die Befehlsausgabe sieht in etwa 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 in der bmctl-Befehlsreferenz unter nodeagent deploy.

Node-Agent aktivieren

Mit dem Befehl enable wird der Node-Agent-Modus in einem vorhandenen laufenden Cluster aktiviert, nachdem Sie den 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 laufenden Cluster aktivieren

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

  • Verwenden Sie den folgenden Befehl, um den Knoten-Agent auf einem vorhandenen Cluster zu aktivieren:

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

    Ersetzen Sie Folgendes:

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

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

    Die Befehlsausgabe sieht in etwa 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 den Node Agent aktivieren, wenn Sie Cluster der Version 1.33 und höher erstellen.

So aktivieren Sie den Knoten-Agent für einen neuen Cluster:

  1. Fügen Sie für einen neuen Administratorcluster die folgenden Pfade zu Anmeldedateien in den oberen Abschnitt der Konfigurationsdatei für den Administratorcluster 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 zum Aktivieren des Knoten-Agents in den Abschnitt „clusterMetadata“ der Clusterkonfigurationsdatei ein:

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

  3. Folgen Sie der Standardanleitung zum Erstellen Ihres Clusters.

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

Anmeldedaten rotieren

Mit dem Befehl rotate-credentials werden die Anmeldedaten des Node-Agents 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 zum Signieren der Zertifikate für den Server (Knoten) und den Client (Controller) zu verwenden.

  • 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 \
    --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 den Node-Agent aktivieren.

    • CLUSTER_NAME: der Name des Clusters, auf dessen Knoten Sie den 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 Datei mit dem privaten SSH-Schlüssel.

    Die Befehlsausgabe sieht in etwa 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 in der bmctl-Befehlsreferenz unter nodeagent rotate-credentials.

Status prüfen

Der Befehl status liefert Informationen zum Ausführungsstatus des Node Agent auf Knoten. Sie können Zielknoten direkt über das Flag --nodes, über eine Clusterkonfigurationsdatei mit dem Flag --cluster oder durch Verweisen auf die benutzerdefinierte Ressource des Clusters angeben.

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

Der Node Agent-Port wird in der folgenden Reihenfolge bestimmt:

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

Node Agent-Status prüfen

Mit dem Flag --cluster können Sie den Status des Knoten-Agents anhand der Angaben in der Clusterkonfigurationsdatei prüfen.

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

    ./bmctl nodeagent status \
    --cluster CLUSTER_NAME

    Ersetzen Sie CLUSTER_NAME durch den Namen des Clusters, den Sie prüfen.

    Die Befehlsausgabe sieht in etwa 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 über den Cluster prüfen

Wenn Sie das Flag --cluster zusammen mit dem Flag --kubeconfig verwenden, können Sie den Node Agent-Status basierend auf der benutzerdefinierten Clusterressource prüfen.

  • Verwenden Sie den folgenden Befehl, um den Status des Node-Agents anhand der benutzerdefinierten Clusterressource zu prüfen:

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

    Ersetzen Sie Folgendes:

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

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

    Die Befehlsausgabe sieht in etwa 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 über Knoten prüfen

Mit dem Flag --cluster in Kombination mit 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 den Node Agent bereitstellen möchten.

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

    Die Befehlsausgabe sieht in etwa 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 in der bmctl-Befehlsreferenz unter nodeagent status.

SSH-Nutzerberechtigungen

Ein Nutzer ohne Rootberechtigung 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 den 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üsselbestätigung

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 die Anmeldedatenrotation (nodeagent rotate-credentials) mit dem Flag --enforce-host-key-verify=false.

Node Agent-Port anpassen

Der Node-Agent ermöglicht die Anpassung von 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 benutzerdefinierte Port muss mit der clientseitigen Konfiguration übereinstimmen, wie in den folgenden Methoden beschrieben.

Für vorhandene Cluster

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

Für neue Cluster

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

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

Leistung

Die Bereitstellung und Aktivierung sind in weniger als einer Minute abgeschlossen. Die Laufzeit für die Anmeldedatenrotation ist vergleichbar mit oder schneller als bei einer Standardbereitstellung.