Migrar clústeres para usar el agente de nodo

En este documento se describe cómo habilitar el uso de Node Agent en clústeres nuevos y actuales para que las operaciones de los clústeres sean más seguras. A partir de la versión 1.33, Google Distributed Cloud para Bare Metal ofrece la posibilidad de pasar de usar Ansible a través de SSH para las operaciones de clúster a un modelo más seguro basado en agentes que usa Node Agent. Usar el agente de nodo para gestionar las operaciones del clúster resuelve los problemas de seguridad que plantea la necesidad de tener acceso SSH a los nodos de los clientes en entornos sensibles. En el nuevo modelo, se ejecuta un archivo binario de agente de nodo en cada nodo. Node Agent se comunica con los clientes, como los controladores, a través de un canal gRPC seguro para gestionar todas las actividades de configuración de nodos. Google Distributed Cloud aplica la seguridad de la capa de transporte mutua (mTLS) entre el controlador del clúster y el agente de nodo, así como entre bmctl y el agente de nodo para la autenticación y el cifrado de las conexiones gRPC.

Los comandos bmctl nodeagent hacen que el proceso de migración de clústeres a Node Agent sea sencillo y fiable. Los comandos reducen el esfuerzo manual, mejoran la coherencia entre los nodos y automatizan tareas clave, como la creación y la rotación de certificados. Los comandos bmctl funcionan principalmente a través de SSH. De esta forma, los administradores pueden implementar o volver a implementar agentes incluso cuando el controlador del clúster no funciona correctamente o sus canales de comunicación estándar están dañados.

Node Agent y los comandos bmctl nodeagent correspondientes son compatibles con Google Distributed Cloud para versiones de bare metal 1.33.0 y posteriores. Puedes habilitar Node Agent en clústeres con la versión 1.33 o posterior, o bien cuando crees clústeres con la versión 1.33 o posterior.

Esta página está dirigida a administradores, arquitectos y operadores que gestionan el ciclo de vida de la infraestructura tecnológica subyacente. Para obtener más información sobre los roles habituales y las tareas de ejemplo a las que hacemos referencia en el contenido, consulta Roles y tareas habituales de los usuarios de GKE Enterprise. Google Cloud

Antes de empezar

Asegúrate de que todos los nodos del clúster cumplen los siguientes requisitos antes de migrar un clúster al modo de agente de nodo:

  • Cada nodo tiene un puerto abierto dedicado al agente de nodo. De forma predeterminada, Node Agent usa el puerto 9192, pero puedes configurar este puerto durante la implementación, la habilitación o las nuevas instalaciones de clústeres. Para obtener más información, consulta Personalizar el puerto del agente de nodo.

  • Cada nodo tiene instalada la versión 1.7 o una posterior de containerd.

Migrar al modo de agente de nodo

El proceso de migración al modo Node Agent consta de dos pasos:

  1. Implementa el agente de nodo: implementa el componente del agente de nodo en todos los nodos del clúster.

  2. Habilita el modo Agente de nodo:

    • En un clúster ya creado, habilita el modo con el comando bmctl nodeagent.
    • En el caso de un clúster nuevo, añade la anotación de habilitación y las rutas de credenciales correspondientes al archivo de configuración del clúster antes de crearlo.

Desplegar agente de nodo

El comando bmctl nodeagent deploy implementa el servicio Node Agent en uno o varios nodos de destino de un clúster especificado mediante SSH. Este comando instala o reinstala el agente de Node. Se conecta a través de SSH y realiza los pasos necesarios, como transferir archivos binarios, generar y transferir certificados (opcional) y configurar el servicio systemd. Requiere acceso SSH y privilegios de sudo en los nodos de destino.

Puede especificar los nodos de destino de varias formas: directamente a través de la marca --nodes, mediante un archivo de configuración de clúster con la marca --cluster o haciendo referencia al recurso personalizado del clúster. Para obtener más información sobre los comandos y las opciones de Node Agent, consulta la referencia de comandos de bmctl.

Desplegar en un entorno nuevo

Para las implementaciones iniciales, descarga el archivo binario nodeagentd y genera nuevas autoridades de certificación (ACs). El siguiente comando obtiene la lista de nodos del archivo de configuración del clúster. La marca --sa-key proporciona las credenciales necesarias para descargar el archivo binario nodeagentd del segmento de Cloud Storage.

  • Para desplegar Node Agent por primera vez en un clúster nuevo, usa el siguiente 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

    Haz los cambios siguientes:

    • CLUSTER_NAME: el nombre del clúster en cuyos nodos quieres implementar el agente de Node.

    • USERNAME: nombre de usuario para el que se ha configurado el acceso SSH a los nodos. De forma predeterminada, SSH está configurado para root, pero si estableces un usuario de inicio de sesión, usa ese nombre de usuario.

    • SSH_KEY_PATH: la ruta del archivo de clave privada SSH.

    • SERVICE_ACCOUNT_KEY_PATH: la ruta del archivo de clave de la cuenta de servicio con permisos para extraer imágenes del registro. De forma predeterminada, se trata del archivo JSON de la clave de la cuenta de servicio anthos-baremetal-gcr.

    El resultado del comando es similar al siguiente ejemplo:

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

Actualizar la versión del agente de nodo

Las actualizaciones del agente de nodo son independientes de las actualizaciones del clúster. Para actualizar Node Agent, usa el comando bmctl nodeagent deploy y asigna el valor true a --pull-binaries. Cuando actualices el agente de Node, asigna el valor --generate-ca-creds a false para usar las autoridades de certificación que ya tengas en lugar de volver a generarlas. Para regenerar las autoridades de certificación, es necesario actualizar las credenciales de clúster correspondientes, un proceso reservado para la rotación de credenciales. El resultado se parece a una implementación nueva, pero sin los registros generados por la CA.

Al actualizar el agente de nodo, se reinicia el proceso del agente de nodo, lo que puede interrumpir cualquier trabajo en curso. Aunque la mayoría de los trabajos se recuperan mediante mecanismos de reintento, para minimizar las posibles interrupciones, sigue estos pasos:

  1. Asegúrate de que no haya ninguna actualización de clúster ni otras actividades de configuración posteriores a la instalación en curso.

  2. Verifica que el clúster esté en estado de ejecución.

  3. Inicia la actualización del agente de 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

    Haz los cambios siguientes:

    • CLUSTER_NAME: el nombre del clúster en cuyos nodos quieres implementar el agente de Node.

    • USERNAME: nombre de usuario para el que se ha configurado el acceso SSH a los nodos. De forma predeterminada, SSH está configurado para root, pero si estableces un usuario de inicio de sesión, usa ese nombre de usuario.

    • SSH_KEY_PATH: la ruta del archivo de clave privada SSH.

    • SERVICE_ACCOUNT_KEY_PATH: la ruta del archivo de clave de la cuenta de servicio con permisos para extraer imágenes del registro. De forma predeterminada, se trata del archivo JSON de la clave de la cuenta de servicio anthos-baremetal-gcr.

    El resultado del comando es similar al siguiente ejemplo:

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

Implementar o volver a implementar en nodos específicos

Si añade o recupera nodos de clúster, puede orientar la implementación del agente de nodo a nodos específicos en lugar de implementarlo en todos los nodos del clúster. Usa la marca --nodes para especificar el nodo de la implementación.

  • Para implementar el agente de Node en nodos específicos, usa el siguiente 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

    Haz los cambios siguientes:

    • CLUSTER_NAME: el nombre del clúster en cuyos nodos quieres implementar el agente de Node.

    • USERNAME: nombre de usuario para el que se ha configurado el acceso SSH a los nodos. De forma predeterminada, SSH está configurado para root, pero si estableces un usuario de inicio de sesión, usa ese nombre de usuario.

    • SSH_KEY_PATH: la ruta del archivo de clave privada SSH.

    • SERVICE_ACCOUNT_KEY_PATH: la ruta del archivo de clave de la cuenta de servicio con permisos para extraer imágenes del registro. De forma predeterminada, se trata del archivo JSON de la clave de la cuenta de servicio anthos-baremetal-gcr.

    • NODE_IP_ADDRESS_LIST: lista separada por comas de las direcciones IP de los nodos en los que vas a desplegar el agente de nodo.

    El resultado del comando es similar al siguiente ejemplo:

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

Para ver una lista completa de las opciones del comando bmctl nodeagent deploy, consulta nodeagent deploy en la bmctlreferencia del comandobmctl nodeagent deploy.

Habilitar el agente de nodo

El comando enable activa el modo Agente de nodo en un clúster en ejecución después de implementar el Agente de nodo en todos los nodos del clúster. Este comando también crea o actualiza las credenciales del agente de nodo en el clúster.

Habilitar el agente de nodo en un clúster en ejecución

Puedes habilitar el agente de nodo en clústeres con la versión 1.33 o posterior.

  • Para habilitar Node Agent en un clúster, usa el siguiente comando:

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

    Haz los cambios siguientes:

    • KUBECONFIG: la ruta del archivo kubeconfig del clúster en el que vas a habilitar el agente de nodo.

    • CLUSTER_NAME: el nombre del clúster en cuyos nodos quieres implementar el agente de Node.

    El resultado del comando es similar al siguiente ejemplo:

    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

Instalación de un nuevo clúster

Puedes habilitar el agente de nodo al crear clústeres con la versión 1.33 o posteriores.

Para habilitar el agente de nodo en un clúster nuevo, sigue estos pasos:

  1. En el caso de un clúster de administrador nuevo, añade las siguientes rutas de archivos de credenciales a la sección superior del archivo de configuración del clúster de administrador:

    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. Incluye la anotación para habilitar el agente de nodo en la sección de metadatos del clúster del archivo de configuración del clúster:

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

  3. Sigue las instrucciones estándar para crear el clúster.

Para ver una lista completa de las opciones del comando bmctl nodeagent enable, consulta nodeagent enable en la bmctl referencia de comandos.

Rotar credenciales

El comando rotate-credentials rota las credenciales del agente de nodo tanto en los nodos como en el clúster. Esto incluye la posibilidad de rotar las autoridades de certificación (CAs). La marca --generate-ca-creds indica al comando que regenere las ACs y que use estas ACs recién generadas para firmar los certificados del servidor (nodos) y del cliente (controlador).

  • Para rotar las credenciales, regenerar y usar nuevas autoridades de certificación, usa el siguiente comando:

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

    Haz los cambios siguientes:

    • KUBECONFIG: la ruta del archivo kubeconfig del clúster en el que vas a habilitar el agente de nodo.

    • CLUSTER_NAME: el nombre del clúster en cuyos nodos quieres implementar el agente de Node.

    • USERNAME: nombre de usuario para el que se ha configurado el acceso SSH a los nodos. De forma predeterminada, SSH está configurado para root, pero si estableces un usuario de inicio de sesión, usa ese nombre de usuario.

    • SSH_KEY_PATH: la ruta del archivo de clave privada SSH.

    El resultado del comando es similar al siguiente ejemplo:

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

Para ver una lista completa de las opciones del comando bmctl nodeagent rotate-credentials, consulta nodeagent rotate-credentials en la referencia del comando bmctl.

Comprobar estado

El comando status proporciona información sobre el estado de ejecución del agente de nodo en los nodos. Puedes especificar los nodos de destino directamente con la marca --nodes , mediante un archivo de configuración de clúster con la marca --cluster o haciendo referencia al recurso personalizado del clúster.

Cuando obtienes nodos de un archivo de configuración de clúster o de la marca --nodes, el sistema recupera las credenciales del sistema de archivos local. Si el origen del nodo es un recurso personalizado de clúster, el sistema obtiene las credenciales del clúster.

El siguiente orden de precedencia determina el puerto del agente de nodo:

  1. Marca --port
  2. Archivo Kubeconfig
  3. Archivo de configuración del clúster

Verificar el estado del agente de nodo

Si solo usas la marca --cluster, puedes consultar el estado del agente de nodo en función de lo que se haya especificado en el archivo de configuración del clúster.

  • Para comprobar el estado del agente de nodo en función del archivo de configuración del clúster, utiliza el siguiente comando:

    ./bmctl nodeagent status \
    --cluster CLUSTER_NAME

    Sustituye CLUSTER_NAME por el nombre del clúster que quieras comprobar.

    El resultado del comando es similar al siguiente ejemplo:

    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

Verificar el estado del agente de nodo desde el clúster

Si usas la marca --cluster junto con la marca --kubeconfig, puedes consultar el estado del agente de nodo en función del recurso personalizado del clúster.

  • Para comprobar el estado del agente de nodo en función del recurso personalizado de clúster, usa el siguiente comando:

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

    Haz los cambios siguientes:

    • CLUSTER_NAME: el nombre del clúster en cuyos nodos quieres implementar el agente de Node.

    • KUBECONFIG: la ruta del archivo kubeconfig del clúster en el que vas a habilitar el agente de nodo.

    El resultado del comando es similar al siguiente ejemplo:

    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

Verificar el estado del agente de nodo desde los nodos

Si usas la marca --cluster junto con la marca --nodes, puedes consultar el estado del agente de nodo de nodos de clúster específicos.

  • Para comprobar el estado del agente de nodo de nodos específicos, utiliza el siguiente comando:

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

    Haz los cambios siguientes:

    • CLUSTER_NAME: el nombre del clúster en cuyos nodos quieres implementar el agente de Node.

    • NODE_IP_ADDRESS_LIST: lista separada por comas de las direcciones IP de los nodos en los que vas a desplegar el agente de nodo.

    El resultado del comando es similar al siguiente ejemplo:

    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

Para ver una lista completa de las opciones del comando bmctl nodeagent status, consulta nodeagent status en la bmctl referencia de comandos.

Permisos de usuario de SSH

Un usuario que no sea root puede ejecutar el comando bmctl nodeagent. Para ello, el usuario debe tener permisos sudo completos sin contraseña o una lista de elementos permitidos sudo sin contraseña explícita.

La lista de elementos permitidos de sudo sin contraseña explícita para el agente de Node tiene los siguientes permisos:

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

Verificación de la clave de host SSH

Asegúrate de que todos los nodos se añaden al archivo known_hosts en la estación de trabajo del administrador. De lo contrario, inhabilita la verificación de la clave de host durante la implementación (nodeagent deploy) y la rotación de credenciales (nodeagent rotate-credentials) mediante la marca --enforce-host-key-verify=false.

Personalizar el puerto del agente de nodo

El agente de nodo permite personalizar el puerto. Especifica este puerto personalizado durante la implementación con la marca --port. De esta forma, la configuración se propaga a la configuración de Node Agent en cada nodo. El puerto personalizado debe coincidir con la configuración del lado del cliente, tal como se detalla en los siguientes métodos.

Para clústeres actuales

Para actualizar un clúster que ya está en ejecución, usa la marca --port para especificar el nuevo puerto personalizado. Este ajuste se propaga a los clientes (controladores).

Para clústeres nuevos

Cuando crees un clúster, añade la siguiente anotación a la configuración del clúster para especificar un puerto personalizado para el agente de nodo:

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

Rendimiento

El despliegue y la habilitación se completan en menos de un minuto. El tiempo de ejecución de la rotación de credenciales es comparable o más rápido que el de una implementación estándar.