Esegui la migrazione dei cluster per utilizzare Node Agent

Questo documento descrive come abilitare l'utilizzo di Node Agent per i cluster nuovi ed esistenti per fornire operazioni del cluster più sicure. A partire dalla versione 1.33, Google Distributed Cloud per bare metal offre la possibilità di passare dall'utilizzo di Ansible su SSH per le operazioni del cluster a un modello più sicuro basato su agenti che utilizza Node Agent. L'utilizzo di Node Agent per gestire le operazioni del cluster risolve i problemi di sicurezza relativi alla necessità di accesso SSH ai nodi dei clienti in ambienti sensibili. Nel nuovo modello, un file binario di Node Agent viene eseguito su ogni nodo. Node Agent comunica con i client, come i controller, tramite un canale gRPC sicuro per gestire tutte le attività di configurazione dei nodi. Google Distributed Cloud applica Transport Layer Security (mTLS) reciproca tra il controller del cluster e Node Agent e tra bmctl e Node Agent per l'autenticazione e la crittografia delle connessioni gRPC.

I comandi bmctl nodeagent semplificano e rendono affidabile la migrazione dei cluster esistenti all'utilizzo di Node Agent. I comandi riducono il lavoro manuale, migliorano la coerenza tra i nodi e automatizzano le attività chiave come la creazione e la rotazione dei certificati. I comandi bmctl operano principalmente su SSH. Ciò consente agli amministratori di eseguire il deployment o il redeployment degli agenti anche quando il controller del cluster non è integro o i suoi canali di comunicazione standard sono danneggiati.

Node Agent e i comandi bmctl nodeagent corrispondenti supportano Google Distributed Cloud per bare metal versione 1.33.0 e successive. Puoi abilitare Node Agent per i cluster esistenti versione 1.33 o successive o quando crei cluster versione 1.33 o successive.

Questa pagina è rivolta ad amministratori, architetti e operatori che gestiscono il ciclo di vita dell'infrastruttura tecnologica sottostante. Per saperne di più sui ruoli comuni e sulle attività di esempio a cui facciamo riferimento nei Google Cloud contenuti, consulta Ruoli e attività utente GKE comuni.

Prima di iniziare

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

  • Ogni nodo ha una porta aperta dedicata a Node Agent. Per impostazione predefinita, Node Agent utilizza la porta 9192, ma puoi configurarla durante il deployment, l'abilitazione o le nuove installazioni del cluster. Per ulteriori informazioni, consulta Personalizzare la porta di Node Agent.

  • Su ogni nodo è installata la versione 1.7 o successive di containerd.

Eseguire la migrazione alla modalità Node Agent

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

  1. Esegui il deployment di Node Agent: esegui il deployment del componente Node Agent su tutti i nodi all'interno del cluster.

  2. Abilita la modalità Node Agent:

    • Per un cluster esistente, abilita 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.

Eseguire il deployment di Node Agent

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 Node Agent. Si connette tramite SSH ed esegue i passaggi necessari, inclusi 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 il riferimento dei comandi bmctl.

Eseguire il deployment in un ambiente nuovo

Per i deployment iniziali, scarica il file binario nodeagentd e genera nuove autorità di certificazione (CA). Il seguente comando 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 hai impostato 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 dell'account di servizio con le autorizzazioni per eseguire il pull delle immagini del registro. Per impostazione predefinita, questo è il file della chiave JSON per l'account di servizio 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
===============================================

Eseguire l'upgrade della versione di Node Agent

Gli upgrade di Node Agent 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 di Node Agent, 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, una procedura riservata alla rotazione delle credenziali. L'output è simile a un nuovo deployment, ma senza i log generati dalla CA.

L'upgrade di Node Agent riavvia il processo di Node Agent, il che può interrompere eventuali job in esecuzione. Sebbene la maggior parte dei job venga ripristinata tramite meccanismi di nuovi tentativi, 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 di Node Agent:

    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 hai impostato 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 dell'account di servizio con le autorizzazioni per eseguire il pull delle immagini del registro. Per impostazione predefinita, questo è il file della chiave JSON per l'account di servizio 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)...

Eseguire il deployment o il redeployment 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é eseguirne il deployment 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 hai impostato 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 dell'account di servizio con le autorizzazioni per eseguire il pull delle immagini del registro. Per impostazione predefinita, questo è il file della chiave JSON per l'account di servizio 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

Abilitare 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 di Node Agent all'interno del cluster.

Abilitare Node Agent per un cluster in esecuzione esistente

Puoi abilitare Node Agent sui cluster esistenti versione 1.33 e successive.

  • Per abilitare Node Agent su un cluster esistente, utilizza il seguente comando:

    ./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 abilitando 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

Installazione di un nuovo cluster

Puoi abilitare Node Agent quando crei cluster versione 1.33 e successive.

Per abilitare Node Agent 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 abilitazione di Node Agent 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 dei comandi bmctl.

Ruotare le credenziali

Il comando rotate-credentials ruota le credenziali di Node Agent sia sui nodi sia all'interno del cluster. 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 abilitando 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 hai impostato 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.

Verificare 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 recuperi 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 di Node Agent:

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

Verificare lo stato di Node Agent

Utilizzando solo il flag --cluster, puoi controllare lo stato di Node Agent in base a quanto specificato nel file di configurazione del cluster.

  • Per controllare lo stato di Node Agent 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

Verificare lo stato di Node Agent dal cluster

Utilizzando il flag --cluster insieme al flag --kubeconfig, puoi controllare lo stato di Node Agent in base alla risorsa personalizzata del cluster.

  • Per controllare lo stato di Node Agent in base alla risorsa personalizzata del 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 abilitando 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

Verificare lo stato di Node Agent dai nodi

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

  • Per controllare lo stato di Node Agent 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 un elenco di autorizzazioni sudo senza password esplicito.

L'elenco di autorizzazioni sudo senza password esplicito per Node Agent 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.

Personalizzare la porta di Node Agent

Node Agent consente la personalizzazione della porta. Specifica questa porta personalizzata durante il deployment utilizzando il flag --port. Questa impostazione viene propagata alla configurazione di Node Agent su ogni nodo. La porta personalizzata deve essere allineata alla configurazione lato client, come descritto nei seguenti metodi.

Per i cluster esistenti

Per aggiornare un cluster in esecuzione esistente, 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 Node Agent:

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

Prestazioni

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