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

Ce document explique comment installer des clusters et les migrer vers Node Agent pour sécuriser davantage les opérations de cluster. Node Agent est un modèle plus sécurisé basé sur un agent qu'Ansible sur SSH pour les opérations de cluster. Il est disponible pour les versions 1.33 et ultérieures. Lorsque vous gérez des opérations de cluster avec Node Agent, vous pouvez accéder aux nœuds client dans des environnements sensibles sans SSH.

Le binaire Node Agent s'exécute sur chaque nœud. Node Agent 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 la sécurité mutuelle de la couche de transport (mTLS) entre le contrôleur de cluster et Node Agent, ainsi qu'entre bmctl et Node Agent pour l'authentification et le chiffrement des connexions gRPC.

Utilisez les commandes bmctl nodeagent pour réduire les efforts manuels, améliorer la cohérence entre les nœuds et automatiser la création et la rotation des certificats. Les commandes bmctl fonctionnent principalement sur SSH. Vous pouvez donc dé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.

Avant de commencer

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

  • Un port ouvert dédié à Node Agent. Node Agent utilise le port 9192 par défaut. Configurez ce port lorsque vous déployez, activez ou installez un nouveau cluster. Pour en savoir plus, consultez Personnaliser le port Node Agent.

  • Containerd version 1.7 ou ultérieure.

  • 12 Go d'espace libre dans le répertoire /tmp sur le nœud d'administration et tous les nœuds cibles. Si vous ne pouvez pas modifier la taille du répertoire /tmp pour vos nœuds cibles, consultez Augmenter la capacité de stockage local pour les sauvegardes Node Agent.

Migrer vers le mode Node Agent

La migration vers le mode Node Agent s'effectue en deux étapes :

  1. Déployer Node Agent : déployez le composant Node Agent sur tous les nœuds du cluster.

  2. Activer le mode Node Agent :

    • 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 la création.

Déployer Node Agent

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 Node Agent. Elle se connecte via SSH et effectue les étapes nécessaires, y compris le transfert de binaires, la génération et le transfert facultatifs de certificats, et la configuration du service systemd. Elle 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 via l'option --nodes, via un fichier de configuration de cluster à l'aide de l'option --cluster ou en référençant la ressource personnalisée du cluster. Pour en savoir plus sur les commandes et les options Node Agent, 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'option --sa-key fournit les identifiants nécessaires pour télécharger le binaire nodeagentd à partir du 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 Node Agent.

    • 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é de compte de service disposant des autorisations nécessaires pour extraire des images de 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 Node Agent

Les mises à niveau de Node Agent sont indépendantes des mises à niveau de cluster. Pour mettre à niveau Node Agent, utilisez la commande bmctl nodeagent deploy et définissez --pull-binaries sur true. Lors de la mise à niveau de Node Agent, définissez --generate-ca-creds sur false pour utiliser les autorités de certification existantes plutôt que 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. La sortie ressemble à un nouveau déploiement, mais sans les journaux générés par l'autorité de certification.

La mise à niveau de Node Agent redémarre le processus Node Agent, ce qui peut perturber les tâches en cours d'exécution. Bien que la plupart des tâches soient récupérées via des mécanismes de nouvelle tentative, procédez comme suit pour minimiser les perturbations potentielles :

  1. Assurez-vous qu'aucune mise à niveau de cluster ni aucune 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 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

    Remplacez les éléments suivants :

    • CLUSTER_NAME: nom du cluster sur les nœuds duquel vous souhaitez déployer Node Agent.

    • 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é de compte de service disposant des autorisations nécessaires pour extraire des images de 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 les nœuds spécifiques pour le déploiement de Node Agent au lieu de le déployer sur tous les nœuds du cluster. Vous utilisez l'option --nodes pour spécifier le nœud à déployer.

  • Pour déployer Node Agent 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 Node Agent.

    • 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é de compte de service disposant des autorisations nécessaires pour extraire des images de 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 d'adresses IP des nœuds sur lesquels vous déployez Node Agent, 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 sur les commandes bmctl.

Activer Node Agent

La commande enable active le mode Node Agent dans un cluster en cours d'exécution existant après avoir déployé 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 Node Agent pour un cluster en cours d'exécution existant

Vous pouvez activer Node Agent sur les clusters existants de la version 1.33 et ultérieures.

  • Pour activer Node Agent sur un cluster existant, utilisez la commande suivante :

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

    • CLUSTER_NAMESPACE : espace de noms du cluster à utiliser pour trouver le cluster cible et les identifiants du cluster, et mettre à jour la ressource de cluster. La valeur par défaut est cluster-<CLUSTER-NAME>.

    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

Installer un nouveau cluster

Vous pouvez utiliser Node Agent lorsque vous créez des clusters de la version 1.33 et ultérieures.

Pour utiliser Node Agent 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 Node Agent 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 sur les commandes bmctl.

Effectuer une rotation des identifiants

La commande rotate-credentials fait pivoter les identifiants Node Agent à la fois sur les nœuds et dans le cluster. Cela inclut la possibilité de faire pivoter les autorités de certification. L'option --generate-ca-creds demande à 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 pivoter 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 \
    --namespace CLUSTER_NAMESPACE \
    --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 Node Agent.

    • CLUSTER_NAMESPACE : espace de noms du cluster à utiliser pour trouver le cluster cible et les identifiants du cluster, et mettre à jour la ressource de cluster. La valeur par défaut est cluster-<CLUSTER-NAME>.

    • 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 sur les commandes bmctl.

Vérifier l'état

La commande status fournit des informations sur l'état d'exécution de Node Agent sur les nœuds. Vous pouvez spécifier des nœuds cibles directement via l'option --nodes, via un fichier de configuration de cluster à l'aide de l'option --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'option --nodes, le système récupère les identifiants à partir du système de fichiers local. Si la source du nœud est une ressource personnalisée de cluster, le système récupère les identifiants à partir du cluster.

L'ordre de priorité suivant détermine le port Node Agent :

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

Vérifier l'état de Node Agent

En utilisant uniquement l'option --cluster, vous pouvez vérifier l'état de Node Agent en fonction de ce qui est spécifié dans le fichier de configuration du cluster.

  • Pour vérifier l'état de Node Agent en fonction du fichier de configuration du cluster, utilisez la commande suivante :

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

    Remplacez les éléments suivants :

    • CLUSTER_NAME : nom du cluster que vous vérifiez.

    • CLUSTER_NAMESPACE : espace de noms du cluster à utiliser pour trouver le cluster cible et les identifiants du cluster, et mettre à jour la ressource de cluster. La valeur par défaut est cluster-<CLUSTER-NAME>.

    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 Node Agent à partir du cluster

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

  • Pour vérifier l'état de Node Agent 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 Node Agent.

    • 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 Node Agent à partir des nœuds

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

  • Pour vérifier l'état de Node Agent 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 Node Agent.

    • NODE_IP_ADDRESS_LIST: liste d'adresses IP des nœuds sur lesquels vous déployez Node Agent, 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 sur les commandes bmctl

Autorisations utilisateur SSH

Un utilisateur non root 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 explicite sans mot de passe pour Node Agent 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_*/*

Vérification 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é d'hôte lors du déploiement (nodeagent deploy) et de la rotation des identifiants (nodeagent rotate-credentials) à l'aide de l'option --enforce-host-key-verify=false.

Personnaliser le port Node Agent

Node Agent permet de personnaliser le port. Spécifiez ce port personnalisé lors du déploiement à l'aide de l'option --port. Ce paramètre est propagé à la configuration Node Agent 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 existant, utilisez l'option --port pour spécifier le nouveau port personnalisé. Ce paramètre est propagé aux clients (contrôleurs).

Pour les nouveaux clusters

Lors de la création d'un cluster, ajoutez l'annotation suivante à la configuration du cluster pour spécifier un port personnalisé pour Node Agent :

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

Augmenter la capacité de stockage local pour les sauvegardes Node Agent

Pour créer un fichier de sauvegarde pour les nœuds Node Agent, vous devez disposer de 12 Go d'espace libre dans le répertoire /tmp sur le nœud d'administration et tous les nœuds cibles. Si vous ne pouvez pas modifier la taille du répertoire /tmp pour vos nœuds cibles, consultez Modifier la capacité de stockage local pour les nœuds cibles. Si vous ne pouvez pas modifier la taille du répertoire /tmp pour le nœud d'administration, consultez Modifier la capacité de stockage local pour un nœud d'administration.

Modifier la capacité de stockage local pour les nœuds cibles

Si vous ne pouvez pas modifier la taille de la partition /tmp du nœud cible, vous pouvez rediriger le dossier temporaire vers une partition ayant plus de capacité en appliquant un remplacement d'environnement systemd :

  1. Créez un fichier de remplacement systemd dans /etc/systemd/system/nodeagentd.service.d/override.conf contenant :

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

  2. Appliquez la configuration et redémarrez le service :

    sudo systemctl daemon-reload
sudo systemctl restart nodeagentd

Modifier la capacité de stockage local pour un nœud d'administration

Si le poste de travail administrateur exécutant bmctl dispose d'un espace limité pour la partition /tmp, définissez la variable TMPDIR localement lorsque vous démarrez une sauvegarde :

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

Remplacez les éléments suivants :

  • CLUSTER_NAME : nom du cluster sur les nœuds duquel vous souhaitez déployer Node Agent.
  • KUBECONFIG : chemin d'accès au fichier kubeconfig pour le cluster pour lequel vous activez Node Agent.

Performances

Le déploiement et l'activation sont terminés en 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.