Esegui la migrazione dei cluster per utilizzare Node Agent

Node Agent ti consente di eseguire operazioni sicure sui cluster sui nodi Google Distributed Cloud senza fare affidamento su Ansible tramite SSH. Disponibile per le versioni 1.33 e successive, questo agente viene eseguito su ogni nodo e gestisce le configurazioni dei nodi tramite un canale gRPC autenticato e criptato.

Puoi eseguire la migrazione dei cluster esistenti all'agente del nodo o eseguire il deployment dell'agente quando crei nuovi cluster. Per gestire il ciclo di vita degli agenti, i comandi bmctl nodeagent automatizzano la creazione dei certificati e la rotazione delle credenziali tra i nodi, operando tramite SSH in modo da poter eseguire il deployment degli agenti anche quando i controller del cluster non sono integri.

Prima di iniziare

Prima di eseguire la migrazione di un cluster alla modalità Node Agent, assicurati che tutti i nodi del cluster soddisfino i seguenti requisiti:

  • Una porta aperta dedicata all'agente del nodo. Per impostazione predefinita, l'agente del nodo utilizza la porta 9192. Configura questa porta quando esegui il deployment, l'attivazione o l'installazione di un nuovo cluster. Per saperne di più, consulta Personalizza la porta dell'agente del nodo.

  • Containerd versione 1.7 o successive.

  • 12 GB di spazio libero nella directory /tmp sul nodo di amministrazione e su tutti i nodi di destinazione. Se non riesci a modificare le dimensioni della directory /tmp per i nodi di destinazione, consulta Aumenta la capacità di archiviazione locale per i backup di Node Agent.

Esegui la migrazione alla modalità Node Agent

La migrazione alla modalità Node Agent è una procedura in due passaggi:

  1. Esegui il deployment dell'agente nodo: esegui il deployment del componente agente nodo su tutti i nodi all'interno del cluster.

  2. Attiva la modalità Node Agent:

    • Per un cluster esistente, attiva la modalità utilizzando il comando bmctl nodeagent.
    • Per un nuovo cluster, aggiungi l'annotazione di abilitazione e i percorsi delle credenziali corrispondenti al file di configurazione del cluster prima della creazione.

Esegui il deployment dell'agente del nodo

Il comando bmctl nodeagent deploy esegue il deployment del servizio Node Agent su uno o più nodi di destinazione all'interno di un cluster specificato utilizzando SSH. Questo comando installa o reinstalla l'agente nodo. Si connette tramite SSH ed esegue i passaggi necessari, tra cui il trasferimento dei file binari, la generazione e il trasferimento facoltativi dei certificati e la configurazione del servizio systemd. Richiede l'accesso SSH e i privilegi sudo sui nodi di destinazione.

Puoi specificare i nodi di destinazione in diversi modi: direttamente tramite il flag --nodes, tramite un file di configurazione del cluster utilizzando il flag --cluster o facendo riferimento alla risorsa personalizzata del cluster. Per ulteriori informazioni sui comandi e sulle opzioni di Node Agent, consulta la documentazione di riferimento dei comandi bmctl.

Esegui il deployment in un nuovo ambiente

Per i deployment iniziali, scarica il file binario nodeagentd e genera nuove autorità di certificazione (CA). Il comando seguente recupera l'elenco dei nodi dal file di configurazione del cluster. Il flag --sa-key fornisce le credenziali necessarie per scaricare il file binario nodeagentd dal bucket Cloud Storage.

  • Per eseguire il deployment di Node Agent per la prima volta su un nuovo cluster, utilizza il seguente comando:

    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

    Sostituisci quanto segue:

    • CLUSTER_NAME: il nome del cluster sui cui nodi vuoi eseguire il deployment di Node Agent.

    • USERNAME: il nome utente per cui è configurato l'accesso SSH ai nodi. Per impostazione predefinita, SSH è configurato per root, ma se imposti un utente di accesso, utilizza quel nome utente.

    • SSH_KEY_PATH: il percorso del file della chiave privata SSH.

    • SERVICE_ACCOUNT_KEY_PATH: il percorso del file della chiave del service account con le autorizzazioni per eseguire il pull delle immagini del registry. Per impostazione predefinita, questo è il file della chiave JSON per il service account anthos-baremetal-gcr.

    L'output comando è simile al seguente esempio:

    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
===============================================

Esegui l'upgrade della versione dell'agente del nodo

Gli upgrade dell'agente del nodo sono indipendenti dagli upgrade del cluster. Per eseguire l'upgrade di Node Agent, utilizza il comando bmctl nodeagent deploy e imposta --pull-binaries su true. Quando esegui l'upgrade dell'agente nodo, imposta --generate-ca-creds su false per utilizzare le CA esistenti anziché rigenerarle. La rigenerazione delle CA richiede l'aggiornamento delle credenziali del cluster corrispondenti, un processo riservato alla rotazione delle credenziali. L'output è simile a un nuovo deployment, ma senza i log generati dalla CA.

L'upgrade dell'agente del nodo riavvia il processo dell'agente del nodo, il che può interrompere i job in esecuzione. Sebbene la maggior parte dei job venga recuperata tramite meccanismi di ripetizione, per ridurre al minimo le potenziali interruzioni, segui questi passaggi:

  1. Assicurati che non siano in corso upgrade del cluster o altre attività di configurazione post-installazione.

  2. Verifica che il cluster sia in esecuzione.

  3. Avvia l'upgrade dell'agente del nodo:

    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

    Sostituisci quanto segue:

    • CLUSTER_NAME: il nome del cluster sui cui nodi vuoi eseguire il deployment di Node Agent.

    • USERNAME: il nome utente per cui è configurato l'accesso SSH ai nodi. Per impostazione predefinita, SSH è configurato per root, ma se imposti un utente di accesso, utilizza quel nome utente.

    • SSH_KEY_PATH: il percorso del file della chiave privata SSH.

    • SERVICE_ACCOUNT_KEY_PATH: il percorso del file della chiave del service account con le autorizzazioni per eseguire il pull delle immagini del registry. Per impostazione predefinita, questo è il file della chiave JSON per il service account anthos-baremetal-gcr.

    L'output comando è simile al seguente esempio:

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

Esegui o rifai il deployment su nodi specifici

Se aggiungi o recuperi i nodi del cluster, puoi scegliere come target i nodi specifici per il deployment di Node Agent, anziché eseguirlo su tutti i nodi del cluster. Utilizza il flag --nodes per specificare il nodo per il deployment.

  • Per eseguire il deployment di Node Agent su nodi specifici, utilizza il seguente comando:

    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

    Sostituisci quanto segue:

    • CLUSTER_NAME: il nome del cluster sui cui nodi vuoi eseguire il deployment di Node Agent.

    • USERNAME: il nome utente per cui è configurato l'accesso SSH ai nodi. Per impostazione predefinita, SSH è configurato per root, ma se imposti un utente di accesso, utilizza quel nome utente.

    • SSH_KEY_PATH: il percorso del file della chiave privata SSH.

    • SERVICE_ACCOUNT_KEY_PATH: il percorso del file della chiave del service account con le autorizzazioni per eseguire il pull delle immagini del registry. Per impostazione predefinita, questo è il file della chiave JSON per il service account anthos-baremetal-gcr.

    • NODE_IP_ADDRESS_LIST: un elenco separato da virgole degli indirizzi IP dei nodi su cui stai eseguendo il deployment di Node Agent.

    L'output comando è simile al seguente esempio:

    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]:

Per un elenco completo delle opzioni del comando bmctl nodeagent deploy, consulta nodeagent deploy nel riferimento dei comandi bmctl.

Abilita Node Agent

Il comando enable attiva la modalità Node Agent all'interno di un cluster in esecuzione esistente dopo aver eseguito il deployment di Node Agent su tutti i nodi del cluster. Questo comando crea o aggiorna anche le credenziali dell'agente del nodo all'interno del cluster.

Abilita Node Agent per un cluster in esecuzione esistente

Puoi attivare l'agente del nodo sui cluster esistenti con versione 1.33 e successive.

Per attivare l'agente del nodo su un cluster esistente, segui questi passaggi:

  1. Abilita l'agente del nodo sul cluster:

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

    Sostituisci quanto segue:

    • KUBECONFIG: il percorso del file kubeconfig per il cluster per cui stai attivando Node Agent.

    • CLUSTER_NAME: il nome del cluster sui cui nodi vuoi eseguire il deployment di Node Agent.

    • CLUSTER_NAMESPACE: lo spazio dei nomi del cluster da utilizzare per trovare il cluster di destinazione e le credenziali del cluster e aggiornare la risorsa del cluster. Il valore predefinito è cluster-<CLUSTER-NAME>.

    L'output comando è simile al seguente esempio:

    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

  2. Includi l'annotazione di attivazione dell'agente del nodo nella sezione dei metadati del cluster del file di configurazione del cluster:

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

Installa un nuovo cluster

Puoi utilizzare l'agente del nodo quando crei cluster della versione 1.33 e successive.

Per utilizzare l'agente del nodo per un nuovo cluster, segui questi passaggi:

  1. Per un nuovo cluster di amministrazione, aggiungi i seguenti percorsi dei file delle credenziali alla sezione superiore del file di configurazione del cluster di amministrazione:

    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. Includi l'annotazione di attivazione dell'agente del nodo nella sezione dei metadati del cluster del file di configurazione del cluster:

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

  3. Segui le istruzioni standard per creare il cluster.

Per un elenco completo delle opzioni del comando bmctl nodeagent enable, consulta nodeagent enable nel riferimento ai comandi bmctl.

Ruota le credenziali

Il comando rotate-credentials ruota le credenziali dell'agente del nodo sia sui nodi sia all'interno del cluster. Ciò include la possibilità di ruotare le autorità di certificazione (CA). Il flag --generate-ca-creds indica al comando di rigenerare le CA e di utilizzare queste CA appena generate per firmare i certificati sia per il server (nodi) sia per il client (controller).

  • Per ruotare le credenziali e rigenerare e utilizzare nuove CA, utilizza il seguente comando:

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

    Sostituisci quanto segue:

    • KUBECONFIG: il percorso del file kubeconfig per il cluster per cui stai attivando Node Agent.

    • CLUSTER_NAME: il nome del cluster sui cui nodi vuoi eseguire il deployment di Node Agent.

    • CLUSTER_NAMESPACE: lo spazio dei nomi del cluster da utilizzare per trovare il cluster di destinazione e le credenziali del cluster e aggiornare la risorsa del cluster. Il valore predefinito è cluster-<CLUSTER-NAME>.

    • USERNAME: il nome utente per cui è configurato l'accesso SSH ai nodi. Per impostazione predefinita, SSH è configurato per root, ma se imposti un utente di accesso, utilizza quel nome utente.

    • SSH_KEY_PATH: il percorso del file della chiave privata SSH.

    L'output comando è simile al seguente esempio:

    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
===============================================

Per un elenco completo delle opzioni del comando bmctl nodeagent rotate-credentials, consulta nodeagent rotate-credentials nel riferimento dei comandi bmctl.

Verifica lo stato

Il comando status fornisce informazioni sullo stato di esecuzione di Node Agent sui nodi. Puoi specificare i nodi di destinazione direttamente tramite il flag --nodes, tramite un file di configurazione del cluster utilizzando il flag --cluster o facendo riferimento alla risorsa personalizzata del cluster.

Quando ottieni i nodi da un file di configurazione del cluster o dal flag --nodes, il sistema recupera le credenziali dal file system locale. Se l'origine del nodo è una risorsa personalizzata del cluster, il sistema recupera le credenziali dal cluster.

Il seguente ordine di precedenza determina la porta dell'agente del nodo:

  1. --port flag
  2. File kubeconfig
  3. File di configurazione del cluster

Verifica lo stato dell'agente del nodo

Utilizzando solo il flag --cluster, puoi controllare lo stato dell'agente del nodo in base a quanto specificato nel file di configurazione del cluster.

  • Per controllare lo stato dell'agente del nodo in base al file di configurazione del cluster, utilizza il seguente comando:

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

    Sostituisci quanto segue:

    • CLUSTER_NAME: il nome del cluster che stai controllando.

    • CLUSTER_NAMESPACE: lo spazio dei nomi del cluster da utilizzare per trovare il cluster di destinazione e le credenziali del cluster e aggiornare la risorsa del cluster. Il valore predefinito è cluster-<CLUSTER-NAME>.

    L'output comando è simile al seguente esempio:

    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

Verifica lo stato di Node Agent dal cluster

Utilizzando il flag --cluster insieme al flag --kubeconfig, puoi controllare lo stato dell'agente del nodo in base alla risorsa personalizzata del cluster.

  • Per controllare lo stato dell'agente del nodo in base alla risorsa personalizzata Cluster, utilizza il seguente comando:

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

    Sostituisci quanto segue:

    • CLUSTER_NAME: il nome del cluster sui cui nodi vuoi eseguire il deployment di Node Agent.

    • KUBECONFIG: il percorso del file kubeconfig per il cluster per cui stai attivando Node Agent.

    L'output comando è simile al seguente esempio:

    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

Verifica lo stato di Node Agent dai nodi

Utilizzando il flag --cluster insieme al flag --nodes, puoi controllare lo stato di Node Agent per nodi cluster specifici.

  • Per controllare lo stato dell'agente del nodo per nodi specifici, utilizza il seguente comando:

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

    Sostituisci quanto segue:

    • CLUSTER_NAME: il nome del cluster sui cui nodi vuoi eseguire il deployment di Node Agent.

    • NODE_IP_ADDRESS_LIST: un elenco separato da virgole degli indirizzi IP dei nodi su cui stai eseguendo il deployment di Node Agent.

    L'output comando è simile al seguente esempio:

    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

Per un elenco completo delle opzioni del comando bmctl nodeagent status, consulta nodeagent status nel riferimento dei comandi bmctl.

Autorizzazioni utente SSH

Un utente non root può eseguire il comando bmctl nodeagent. Ciò richiede che l'utente disponga di autorizzazioni sudo complete senza password o di una lista consentita sudo esplicita senza password.

La lista consentita esplicita di sudo senza password per l'agente nodo ha le seguenti autorizzazioni:

# 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_*/*

Verifica della chiave host SSH

Assicurati che tutti i nodi siano aggiunti al file known_hosts sulla workstation di amministrazione. In caso contrario, disattiva la verifica della chiave host durante il deployment (nodeagent deploy) e la rotazione delle credenziali (nodeagent rotate-credentials) utilizzando il flag --enforce-host-key-verify=false.

Personalizza la porta dell'agente del nodo

L'agente del nodo consente la personalizzazione delle porte. Specifica questa porta personalizzata durante il deployment utilizzando il flag --port. In questo modo, l'impostazione viene propagata alla configurazione dell'agente del nodo su ciascun nodo. La porta personalizzata deve essere in linea con la configurazione lato client, come descritto nei metodi seguenti.

Per i cluster esistenti

Per aggiornare un cluster esistente in esecuzione, utilizza il flag --port per specificare la nuova porta personalizzata. Questa impostazione viene propagata ai client (controller).

Per i nuovi cluster

Quando crei un nuovo cluster, aggiungi la seguente annotazione alla configurazione del cluster per specificare una porta personalizzata per l'agente del nodo:

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

Aumenta la capacità di archiviazione locale per i backup di Node Agent

Per creare un file di backup per i nodi dell'agente nodo, devi disporre di 12 GB di spazio libero nella directory /tmp sul nodo di amministrazione e su tutti i nodi di destinazione. Se non puoi modificare le dimensioni della directory /tmp per i nodi di destinazione, consulta Modifica la capacità di archiviazione locale per i nodi di destinazione. Se non riesci a modificare le dimensioni della directory /tmp per il nodo di amministrazione, consulta Modifica la capacità di archiviazione locale per un nodo di amministrazione.

Modifica la capacità di archiviazione locale per i nodi di destinazione

Se non riesci a modificare le dimensioni della partizione /tmp del nodo di destinazione, puoi reindirizzare la cartella temporanea a una partizione con maggiore capacità applicando un override dell'ambiente systemd:

  1. Crea un file di override systemd in /etc/systemd/system/nodeagentd.service.d/override.conf contenente:

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

  2. Applica la configurazione e riavvia il servizio:

    sudo systemctl daemon-reload
sudo systemctl restart nodeagentd

Modifica la capacità di archiviazione locale per un nodo di amministrazione

Se la workstation di amministrazione che esegue bmctl ha spazio limitato per la partizione /tmp, imposta la variabile TMPDIR localmente quando avvii un backup:

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

Sostituisci quanto segue:

  • CLUSTER_NAME: il nome del cluster sui cui nodi vuoi eseguire il deployment di Node Agent.
  • KUBECONFIG: il percorso del file kubeconfig per il cluster su cui stai abilitando Node Agent.

Prestazioni

Il deployment e l'abilitazione vengono completati in meno di un minuto. Il runtime della rotazione delle credenziali è paragonabile o più veloce di un deployment standard.