Esegui la migrazione dei cluster per utilizzare Node Agent

Questo documento descrive come attivare 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 accedere tramite SSH ai nodi dei clienti in ambienti sensibili. Nel nuovo modello, su ogni nodo viene eseguito un binario Node Agent. 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 l'agente nodo e tra bmctl e l'agente nodo per l'autenticazione e la crittografia delle connessioni gRPC.

I comandi bmctl nodeagent rendono il processo di migrazione dei cluster esistenti per l'utilizzo di Node Agent semplice e affidabile. I comandi riducono l'impegno manuale, migliorano la coerenza tra i nodi e automatizzano le attività chiave come la creazione e la rotazione dei certificati. I comandi bmctl funzionano principalmente tramite 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 compromessi.

Node Agent e i relativi comandi bmctl nodeagent supportano Google Distributed Cloud per le versioni bare metal 1.33.0 e successive. Puoi abilitare Node Agent per i cluster esistenti versione 1.33 o successive oppure 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 scoprire di più sui ruoli comuni e sulle attività di esempio a cui facciamo riferimento nei contenuti, consulta Ruoli e attività comuni degli utenti di GKE Enterprise. Google Cloud

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 all'agente del nodo. Per impostazione predefinita, Node Agent utilizza la porta 9192, ma puoi configurarla durante il deployment, l'attivazione o le nuove installazioni del cluster. Per saperne di più, consulta Personalizzare la porta dell'agente nodo.

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

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. Abilita la modalità Agente nodo:

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

Esegui 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, 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 per il comando bmctl.

Deployment in un ambiente nuovo

Per i deployment iniziali, scarica il 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 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 il quale è configurato l'accesso SSH ai nodi. Per impostazione predefinita, SSH è configurato per root, ma se imposti un utente di accesso, utilizza questo 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 registro. Per impostazione predefinita, questo è il file della chiave JSON per l'account di servizio anthos-baremetal-gcr.

    L'output del 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 Node

Gli upgrade dell'agente 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, una procedura riservata alla rotazione delle credenziali. L'output assomiglia 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 qualsiasi 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 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 il quale è configurato l'accesso SSH ai nodi. Per impostazione predefinita, SSH è configurato per root, ma se imposti un utente di accesso, utilizza questo 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 registro. Per impostazione predefinita, questo è il file della chiave JSON per l'account di servizio anthos-baremetal-gcr.

    L'output del 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 nodi del cluster, puoi scegliere come target i nodi specifici per il deployment dell'agente del nodo, 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 il quale è configurato l'accesso SSH ai nodi. Per impostazione predefinita, SSH è configurato per root, ma se imposti un utente di accesso, utilizza questo 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 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 del 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 nella documentazione di riferimento del comando bmctl.

Abilita l'agente del nodo

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 nodo all'interno del cluster.

Abilitare Node Agent per un cluster in esecuzione esistente

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

  • Per abilitare Node Agent in un cluster esistente, utilizza questo comando:

    ./bmctl nodeagent enable \
    --kubeconfig KUBECONFIG \
    --cluster CLUSTER_NAME \
    --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.

    L'output del 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 attivazione dell'agente 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 nella documentazione di riferimento del comando 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 \
    --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.

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

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

    L'output del 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 nella documentazione di riferimento del comando 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 nodo:

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

Verificare lo stato dell'agente del nodo

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

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

    ./bmctl nodeagent status \
    --cluster CLUSTER_NAME

    Sostituisci CLUSTER_NAME con il nome del cluster che stai controllando.

    L'output del 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 dell'agente del nodo dal cluster

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

  • Per controllare lo stato dell'agente 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 del 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 dell'agente nodo per nodi del cluster specifici.

  • Per controllare lo stato dell'agente 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 del 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 nella documentazione di riferimento del comando 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 consentito sudo senza password esplicito.

L'elenco consentito sudo senza password esplicito per Node Agent dispone delle 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 vengano aggiunti al file known_hosts sulla workstation amministrativa. 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 nodo

L'agente nodo consente la personalizzazione della porta. Specifica questa porta personalizzata durante il deployment utilizzando il flag --port. In questo modo, l'impostazione viene propagata alla configurazione dell'agente nodo su ogni 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 Node Agent:

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

Prestazioni

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