Migrer des clusters pour utiliser l'agent de nœud

Ce document explique comment activer l'utilisation de l'agent de nœud pour les clusters nouveaux et existants afin de sécuriser davantage les opérations de cluster. À partir de la version 1.33, Google Distributed Cloud pour Bare Metal permet de passer d'un modèle basé sur Ansible via SSH pour les opérations de cluster à un modèle plus sécurisé basé sur un agent qui utilise Node Agent. L'utilisation de Node Agent pour gérer les opérations de cluster permet de résoudre les problèmes de sécurité liés à l'accès SSH aux nœuds client dans les environnements sensibles. Dans le nouveau modèle, un binaire Node Agent s'exécute sur chaque nœud. L'agent de nœud communique avec les clients, tels que les contrôleurs, via un canal gRPC sécurisé pour gérer toutes les activités de configuration des nœuds. Google Distributed Cloud applique le protocole mTLS (mutual Transport Layer Security) entre le contrôleur de cluster et l'agent de nœud, ainsi qu'entre bmctl et l'agent de nœud pour l'authentification et le chiffrement des connexions gRPC.

Les commandes bmctl nodeagent simplifient et fiabilisent la migration des clusters existants pour qu'ils utilisent l'agent de nœud. Les commandes réduisent les efforts manuels, améliorent la cohérence entre les nœuds et automatisent les tâches clés telles que la création et la rotation des certificats. Les commandes bmctl fonctionnent principalement sur SSH. Cela permet aux administrateurs de déployer ou de redéployer des agents même lorsque le contrôleur de cluster est défectueux ou que ses canaux de communication standards sont altérés.

L'agent de nœud et les commandes bmctl nodeagent correspondantes sont compatibles avec Google Distributed Cloud pour Bare Metal versions 1.33.0 et ultérieures. Vous pouvez activer l'agent de nœud pour les clusters existants de version 1.33 ou ultérieure, ou lorsque vous créez des clusters de version 1.33 ou ultérieure.

Cette page est destinée aux administrateurs, aux architectes et aux opérateurs qui gèrent le cycle de vie de l'infrastructure technologique sous-jacente. Pour en savoir plus sur les rôles courants et les exemples de tâches que nous citons dans le contenu Google Cloud , consultez Rôles utilisateur et tâches courantes de GKE Enterprise.

Avant de commencer

Avant de migrer un cluster vers le mode Node Agent, assurez-vous que tous les nœuds du cluster répondent aux exigences suivantes :

  • Chaque nœud dispose d'un port ouvert dédié à l'agent de nœud. Par défaut, l'agent de nœud utilise le port 9192, mais vous pouvez le configurer lors du déploiement, de l'activation ou de l'installation de nouveaux clusters. Pour en savoir plus, consultez Personnaliser le port de l'agent de nœud.

  • La version 1.7 ou ultérieure de containerd est installée sur chaque nœud.

Migrer vers le mode Agent de nœud

La migration vers le mode Agent de nœud s'effectue en deux étapes :

  1. Déployez l'agent de nœud : déployez le composant de l'agent de nœud sur tous les nœuds du cluster.

  2. Activer le mode Agent de nœuds :

    • Pour un cluster existant, activez le mode à l'aide de la commande bmctl nodeagent.
    • Pour un nouveau cluster, ajoutez l'annotation d'activation et les chemins d'accès aux identifiants correspondants au fichier de configuration du cluster avant de le créer.

Déployer l'agent de nœud

La commande bmctl nodeagent deploy déploie le service Node Agent sur un ou plusieurs nœuds cibles d'un cluster spécifié à l'aide de SSH. Cette commande installe ou réinstalle l'agent de nœud. Il se connecte via SSH et effectue les étapes nécessaires, y compris le transfert des binaires, la génération et le transfert facultatifs des certificats, et la configuration du service systemd. Il nécessite un accès SSH et des droits sudo sur les nœuds cibles.

Vous pouvez spécifier des nœuds cibles de plusieurs manières : directement à l'aide de l'indicateur --nodes, via un fichier de configuration de cluster à l'aide de l'indicateur --cluster ou en référençant la ressource personnalisée du cluster. Pour en savoir plus sur les commandes et les options de l'agent Node, consultez la documentation de référence sur les commandes bmctl.

Déployer dans un nouvel environnement

Pour les déploiements initiaux, téléchargez le binaire nodeagentd et générez de nouvelles autorités de certification. La commande suivante récupère la liste des nœuds à partir du fichier de configuration du cluster. L'indicateur --sa-key fournit les identifiants nécessaires pour télécharger le fichier binaire nodeagentd depuis le bucket Cloud Storage.

  • Pour déployer Node Agent pour la première fois sur un nouveau cluster, utilisez la commande suivante :

    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

    Remplacez les éléments suivants :

    • CLUSTER_NAME : nom du cluster sur les nœuds duquel vous souhaitez déployer l'agent de nœud.

    • USERNAME : nom d'utilisateur pour lequel l'accès SSH aux nœuds est configuré. Par défaut, SSH est configuré pour root, mais si vous définissez un utilisateur de connexion, utilisez ce nom d'utilisateur.

    • SSH_KEY_PATH : chemin d'accès au fichier de clé privée SSH.

    • SERVICE_ACCOUNT_KEY_PATH : chemin d'accès au fichier de clé du compte de service avec les autorisations nécessaires pour extraire les images du registre. Par défaut, il s'agit du fichier de clé JSON pour le compte de service anthos-baremetal-gcr.

    Le résultat de la commande ressemble à l'exemple suivant :

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

Mettre à niveau la version de l'agent Node

Les mises à niveau de l'agent de nœud sont indépendantes de celles du cluster. Pour mettre à niveau l'agent de nœud, utilisez la commande bmctl nodeagent deploy et définissez --pull-binaries sur true. Lorsque vous mettez à niveau l'agent de nœud, définissez --generate-ca-creds sur false pour utiliser les CA existantes au lieu de les régénérer. La régénération des autorités de certification nécessite la mise à jour des identifiants de cluster correspondants, un processus réservé à la rotation des identifiants. Le résultat ressemble à un nouveau déploiement, mais sans les journaux générés par l'autorité de certification.

La mise à niveau de l'agent de nœud redémarre le processus de l'agent de nœud, ce qui peut perturber les jobs en cours d'exécution. Bien que la plupart des tâches soient récupérées grâce à des mécanismes de réessai, pour minimiser les perturbations potentielles, procédez comme suit :

  1. Assurez-vous qu'aucune mise à niveau de cluster ni autre activité de configuration post-installation n'est en cours.

  2. Vérifiez que le cluster est en cours d'exécution.

  3. Lancez la mise à niveau de l'agent de nœud :

    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

    Remplacez les éléments suivants :

    • CLUSTER_NAME : nom du cluster sur les nœuds duquel vous souhaitez déployer l'agent de nœud.

    • USERNAME : nom d'utilisateur pour lequel l'accès SSH aux nœuds est configuré. Par défaut, SSH est configuré pour root, mais si vous définissez un utilisateur de connexion, utilisez ce nom d'utilisateur.

    • SSH_KEY_PATH : chemin d'accès au fichier de clé privée SSH.

    • SERVICE_ACCOUNT_KEY_PATH : chemin d'accès au fichier de clé du compte de service avec les autorisations nécessaires pour extraire les images du registre. Par défaut, il s'agit du fichier de clé JSON pour le compte de service anthos-baremetal-gcr.

    Le résultat de la commande ressemble à l'exemple suivant :

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

Déployer ou redéployer sur des nœuds spécifiques

Si vous ajoutez ou récupérez des nœuds de cluster, vous pouvez cibler des nœuds spécifiques pour le déploiement de l'agent de nœud, au lieu de le déployer sur tous les nœuds du cluster. Vous utilisez l'indicateur --nodes pour spécifier le nœud de déploiement.

  • Pour déployer l'agent de nœud sur des nœuds spécifiques, utilisez la commande suivante :

    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

    Remplacez les éléments suivants :

    • CLUSTER_NAME : nom du cluster sur les nœuds duquel vous souhaitez déployer l'agent de nœud.

    • USERNAME : nom d'utilisateur pour lequel l'accès SSH aux nœuds est configuré. Par défaut, SSH est configuré pour root, mais si vous définissez un utilisateur de connexion, utilisez ce nom d'utilisateur.

    • SSH_KEY_PATH : chemin d'accès au fichier de clé privée SSH.

    • SERVICE_ACCOUNT_KEY_PATH : chemin d'accès au fichier de clé du compte de service avec les autorisations nécessaires pour extraire les images du registre. Par défaut, il s'agit du fichier de clé JSON pour le compte de service anthos-baremetal-gcr.

    • NODE_IP_ADDRESS_LIST : liste des adresses IP des nœuds sur lesquels vous déployez l'agent Node, séparées par une virgule.

    Le résultat de la commande ressemble à l'exemple suivant :

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

Pour obtenir la liste complète des options de la commande bmctl nodeagent deploy, consultez nodeagent deploy dans la documentation de référence de la commande bmctl.

Activer l'agent de nœud

La commande enable active le mode Node Agent dans un cluster en cours d'exécution existant après le déploiement de Node Agent sur tous les nœuds du cluster. Cette commande crée ou met également à jour les identifiants Node Agent dans le cluster.

Activer l'agent de nœud pour un cluster en cours d'exécution

Vous pouvez activer l'agent de nœud sur les clusters existants de version 1.33 et ultérieures.

  • Pour activer l'agent de nœud sur un cluster existant, utilisez la commande suivante :

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

    Remplacez les éléments suivants :

    • KUBECONFIG : chemin d'accès au fichier kubeconfig du cluster pour lequel vous activez Node Agent.

    • CLUSTER_NAME : nom du cluster sur les nœuds duquel vous souhaitez déployer l'agent de nœud.

    Le résultat de la commande ressemble à l'exemple suivant :

    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

Installation d'un nouveau cluster

Vous pouvez activer l'agent de nœud lorsque vous créez des clusters version 1.33 et ultérieures.

Pour activer l'agent de nœud pour un nouveau cluster, procédez comme suit :

  1. Pour un nouveau cluster d'administrateur, ajoutez les chemins d'accès aux fichiers d'identifiants suivants à la section supérieure du fichier de configuration du cluster d'administrateur :

    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. Incluez l'annotation d'activation de l'agent de nœud dans la section des métadonnées du cluster du fichier de configuration du cluster :

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

  3. Suivez les instructions standards pour créer votre cluster.

Pour obtenir la liste complète des options de la commande bmctl nodeagent enable, consultez nodeagent enable dans la documentation de référence de la commande bmctl.

Effectuer une rotation des identifiants

La commande rotate-credentials fait pivoter les identifiants de l'agent de nœud sur les nœuds et dans le cluster. Cela inclut la possibilité d'alterner les autorités de certification. L'indicateur --generate-ca-creds indique à la commande de régénérer les autorités de certification et d'utiliser ces autorités de certification nouvellement générées pour signer les certificats du serveur (nœuds) et du client (contrôleur).

  • Pour faire tourner les identifiants, régénérer et utiliser de nouvelles autorités de certification, utilisez la commande suivante :

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

    Remplacez les éléments suivants :

    • KUBECONFIG : chemin d'accès au fichier kubeconfig du cluster pour lequel vous activez Node Agent.

    • CLUSTER_NAME : nom du cluster sur les nœuds duquel vous souhaitez déployer l'agent de nœud.

    • USERNAME : nom d'utilisateur pour lequel l'accès SSH aux nœuds est configuré. Par défaut, SSH est configuré pour root, mais si vous définissez un utilisateur de connexion, utilisez ce nom d'utilisateur.

    • SSH_KEY_PATH : chemin d'accès au fichier de clé privée SSH.

    Le résultat de la commande ressemble à l'exemple suivant :

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

Pour obtenir la liste complète des options de la commande bmctl nodeagent rotate-credentials, consultez nodeagent rotate-credentials dans la documentation de référence de la commande bmctl.

Vérifier l'état

La commande status fournit des informations sur l'état d'exécution de l'agent de nœud sur les nœuds. Vous pouvez spécifier des nœuds cibles directement à l'aide de l'indicateur --nodes, via un fichier de configuration de cluster à l'aide de l'indicateur --cluster ou en référençant la ressource personnalisée du cluster.

Lorsque vous obtenez des nœuds à partir d'un fichier de configuration de cluster ou de l'indicateur --nodes, le système récupère les identifiants à partir du système de fichiers local. Si la source de nœud est une ressource personnalisée de cluster, le système récupère les identifiants du cluster.

L'ordre de priorité suivant détermine le port de l'agent de nœud :

  1. Option --port
  2. Fichier kubeconfig
  3. Fichier de configuration du cluster

Vérifier l'état de l'agent de nœud

En utilisant uniquement l'indicateur --cluster, vous pouvez vérifier l'état de l'agent de nœud en fonction de ce qui est spécifié dans le fichier de configuration du cluster.

  • Pour vérifier l'état de l'agent de nœud en fonction du fichier de configuration du cluster, utilisez la commande suivante :

    ./bmctl nodeagent status \
    --cluster CLUSTER_NAME

    Remplacez CLUSTER_NAME par le nom du cluster que vous vérifiez.

    Le résultat de la commande ressemble à l'exemple suivant :

    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

Vérifier l'état de l'agent de nœud à partir du cluster

En utilisant l'option --cluster avec l'option --kubeconfig, vous pouvez vérifier l'état de l'agent de nœud en fonction de la ressource personnalisée du cluster.

  • Pour vérifier l'état de l'agent de nœud en fonction de la ressource personnalisée du cluster, utilisez la commande suivante :

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

    Remplacez les éléments suivants :

    • CLUSTER_NAME : nom du cluster sur les nœuds duquel vous souhaitez déployer l'agent de nœud.

    • KUBECONFIG : chemin d'accès au fichier kubeconfig du cluster pour lequel vous activez Node Agent.

    Le résultat de la commande ressemble à l'exemple suivant :

    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

Vérifier l'état de l'agent de nœud à partir des nœuds

En utilisant l'option --cluster avec l'option --nodes, vous pouvez vérifier l'état de l'agent de nœud pour des nœuds de cluster spécifiques.

  • Pour vérifier l'état de l'agent de nœud pour des nœuds spécifiques, utilisez la commande suivante :

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

    Remplacez les éléments suivants :

    • CLUSTER_NAME : nom du cluster sur les nœuds duquel vous souhaitez déployer l'agent de nœud.

    • NODE_IP_ADDRESS_LIST : liste des adresses IP des nœuds sur lesquels vous déployez l'agent Node, séparées par une virgule.

    Le résultat de la commande ressemble à l'exemple suivant :

    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

Pour obtenir la liste complète des options de la commande bmctl nodeagent status, consultez nodeagent status dans la documentation de référence de la commande bmctl.

Autorisations utilisateur SSH

Un utilisateur non racine peut exécuter la commande bmctl nodeagent. Pour cela, l'utilisateur doit disposer d'autorisations sudo complètes sans mot de passe ou d'une liste d'autorisation sudo explicite sans mot de passe.

La liste d'autorisation sudo sans mot de passe explicite pour l'agent Node dispose des autorisations suivantes :

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

Validation de la clé d'hôte SSH

Assurez-vous que tous les nœuds sont ajoutés au fichier known_hosts sur le poste de travail administrateur. Sinon, désactivez la vérification de la clé hôte lors du déploiement (nodeagent deploy) et la rotation des identifiants (nodeagent rotate-credentials) à l'aide du flag --enforce-host-key-verify=false.

Personnaliser le port de l'agent de nœud

L'agent de nœud permet de personnaliser les ports. Spécifiez ce port personnalisé lors du déploiement à l'aide de l'indicateur --port. Ce paramètre est propagé à la configuration de l'agent de nœud sur chaque nœud. Le port personnalisé doit correspondre à la configuration côté client, comme indiqué dans les méthodes suivantes.

Pour les clusters existants

Pour mettre à jour un cluster en cours d'exécution, utilisez l'option --port pour spécifier le nouveau port personnalisé. Ce paramètre est propagé aux clients (contrôleurs).

Pour les nouveaux clusters

Lorsque vous créez un cluster, ajoutez l'annotation suivante à la configuration du cluster pour spécifier un port personnalisé pour l'agent de nœud :

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

Performances

Le déploiement et l'activation prennent moins d'une minute. La durée d'exécution de la rotation des identifiants est comparable à celle d'un déploiement standard, voire plus rapide.