Se usó la API de Cloud Translation para traducir esta página.

Migra los clústeres para usar el agente de nodos

En este documento, se describe cómo habilitar el uso del agente de nodo para clústeres nuevos y existentes, de modo que se proporcionen operaciones de clúster más seguras. A partir de la versión 1.33, Google Distributed Cloud para equipos físicos permite la transición del uso de Ansible a través de SSH para las operaciones del clúster a un modelo más seguro basado en agentes que usa Node Agent. El uso de Node Agent para administrar las operaciones del clúster aborda las preocupaciones de seguridad sobre la necesidad de acceso SSH a los nodos del cliente en entornos sensibles. En el nuevo modelo, se ejecuta un archivo binario del agente de nodo en cada nodo. El agente de nodo se comunica con los clientes, como los controladores, a través de un canal gRPC seguro para administrar todas las actividades de configuración del nodo. Google Distributed Cloud aplica la seguridad de la capa de transporte mutua (mTLS) entre el controlador del clúster y el agente de nodo, y entre bmctl y el agente de nodo para la autenticación y la encriptación de las conexiones de gRPC.

Los comandos bmctl nodeagent hacen que el proceso de migración de clústeres existentes para usar el agente de nodo sea sencillo y confiable. Los comandos reducen el esfuerzo manual, mejoran la coherencia en todos los nodos y automatizan tareas clave, como la creación y rotación de certificados. Los comandos de bmctl operan principalmente a través de SSH. Esto permite que los administradores implementen o vuelvan a implementar agentes incluso cuando el controlador del clúster no está en buen estado o sus canales de comunicación estándar están dañados.

El agente de nodo y los comandos bmctl nodeagent correspondientes admiten Google Distributed Cloud para versiones de equipos físicos 1.33.0 y posteriores. Puedes habilitar el agente de nodo para los clústeres existentes de la versión 1.33 o posterior, o cuando creas clústeres de la versión 1.33 o posterior.

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

Antes de comenzar

Antes de migrar un clúster al modo de agente de nodo, asegúrate de que todos los nodos del clúster cumplan con los siguientes requisitos:

Cada nodo tiene un puerto abierto dedicado al agente de nodo. De forma predeterminada, el agente de nodo usa el puerto 9192, pero puedes configurarlo durante la implementación, la habilitación o las instalaciones de clústeres nuevos. Para obtener más información, consulta Cómo personalizar el puerto del agente de nodo.
Cada nodo tiene instalada la versión 1.7 o posterior de containerd.

Migra al modo de agente de nodo

La migración al modo de agente de nodo es un proceso de dos pasos:

Implementa el agente de nodo: Implementa el componente del agente de nodo en todos los nodos del clúster.
Habilita el modo Agente de nodo:
- Para un clúster existente, habilita el modo con el comando bmctl nodeagent.
- En el caso de un clúster nuevo, agrega la anotación de habilitación y las rutas de acceso de credenciales correspondientes al archivo de configuración del clúster antes de la creación.

Implementa el agente de nodo

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

Puedes especificar nodos de destino de varias maneras: directamente a través de la marca --nodes, a través de un archivo de configuración del 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 del agente de nodo, consulta la referencia de comandos de bmctl.

Implementa en un entorno nuevo

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

Para implementar 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

Reemplaza lo siguiente:

CLUSTER_NAME: Es el nombre del clúster en cuyos nodos deseas implementar el agente de nodo.
USERNAME: Es el nombre de usuario para el que se configura el acceso SSH a los nodos. De forma predeterminada, SSH está configurado para root, pero si estableces un usuario de acceso, usa ese nombre de usuario.
SSH_KEY_PATH: Es la ruta de acceso al archivo de clave privada SSH.
SERVICE_ACCOUNT_KEY_PATH: Es la ruta de acceso al archivo de claves de la cuenta de servicio con permisos para extraer imágenes del registro. De forma predeterminada, este es el archivo de claves JSON para 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
===============================================

Actualiza la versión del agente de Node

Las actualizaciones del agente de nodo son independientes de las actualizaciones del clúster. Para actualizar el agente de nodo, usa el comando bmctl nodeagent deploy y configura --pull-binaries como true. Cuando actualices el agente de nodo, configura --generate-ca-creds como false para usar las entidades de certificación existentes en lugar de volver a generarlas. La regeneración de las CA requiere la actualización de las credenciales del clúster correspondientes, un proceso reservado para la rotación de credenciales. El resultado se asemeja a una implementación nueva, pero sin los registros generados por la CA.

La actualización del agente de nodo reinicia el proceso del agente de nodo, lo que puede interrumpir cualquier trabajo en ejecución. Aunque la mayoría de los trabajos se recuperan a través de mecanismos de reintento, para minimizar las posibles interrupciones, sigue estos pasos:

Asegúrate de que no haya ninguna actualización del clúster ni otras actividades de configuración posteriores a la instalación en curso.
Verifica que el clúster esté en estado de ejecución.

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

Reemplaza lo siguiente:

CLUSTER_NAME: Es el nombre del clúster en cuyos nodos deseas implementar el agente de nodo.
USERNAME: Es el nombre de usuario para el que se configura el acceso SSH a los nodos. De forma predeterminada, SSH está configurado para root, pero si estableces un usuario de acceso, usa ese nombre de usuario.
SSH_KEY_PATH: Es la ruta de acceso al archivo de clave privada SSH.
SERVICE_ACCOUNT_KEY_PATH: Es la ruta de acceso al archivo de claves de la cuenta de servicio con permisos para extraer imágenes del registro. De forma predeterminada, este es el archivo de claves JSON para 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)...

Implementa o vuelve a implementar en nodos específicos

Si agregas o recuperas nodos del clúster, puedes segmentar los nodos específicos para la implementación del agente de nodos, en lugar de implementarlo en todos los nodos del clúster. Usas la marca --nodes para especificar el nodo de implementación.

Para implementar el agente de nodo 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

Reemplaza lo siguiente:

CLUSTER_NAME: Es el nombre del clúster en cuyos nodos deseas implementar el agente de nodo.
USERNAME: Es el nombre de usuario para el que se configura el acceso SSH a los nodos. De forma predeterminada, SSH está configurado para root, pero si estableces un usuario de acceso, usa ese nombre de usuario.
SSH_KEY_PATH: Es la ruta de acceso al archivo de clave privada SSH.
SERVICE_ACCOUNT_KEY_PATH: Es la ruta de acceso al archivo de claves de la cuenta de servicio con permisos para extraer imágenes del registro. De forma predeterminada, este es el archivo de claves JSON para la cuenta de servicio anthos-baremetal-gcr.
NODE_IP_ADDRESS_LIST: Es una lista separada por comas de las direcciones IP de los nodos en los que implementas Node Agent.

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 obtener una lista completa de las opciones del comando bmctl nodeagent deploy, consulta nodeagent deploy en la referencia del comando bmctl.

Habilita el agente de nodo

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

Habilita el agente de nodo para un clúster en ejecución existente

Puedes habilitar el agente de nodo en clústeres existentes de la versión 1.33 y versiones posteriores.

Para habilitar el agente de nodo en un clúster existente, usa el siguiente comando:

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

Reemplaza lo siguiente:

KUBECONFIG: Es la ruta de acceso del archivo kubeconfig del clúster para el que habilitas el agente de nodo.
CLUSTER_NAME: Es el nombre del clúster en cuyos nodos deseas implementar el agente de nodo.

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 clúster nuevo

Puedes habilitar el agente de nodo cuando creas clústeres de la versión 1.33 y versiones posteriores.

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

Para un clúster de administrador nuevo, agrega las siguientes rutas de acceso 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

Incluye la anotación de habilitación del 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: ""
```
Sigue las instrucciones estándar para crear tu clúster.

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

Rota las credenciales

El comando rotate-credentials rota las credenciales del agente de nodo en los nodos y dentro del clúster. Esto incluye la capacidad de rotar las autoridades certificadoras (CA). La marca --generate-ca-creds dirige el comando para regenerar las CA y usar estas CA recién generadas para firmar los certificados tanto del servidor (nodos) como del cliente (controlador).

Para rotar las credenciales, regenerar y usar nuevas CAs, 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

Reemplaza lo siguiente:

KUBECONFIG: Es la ruta de acceso del archivo kubeconfig del clúster para el que habilitas el agente de nodo.
CLUSTER_NAME: Es el nombre del clúster en cuyos nodos deseas implementar el agente de nodo.
USERNAME: Es el nombre de usuario para el que se configura el acceso SSH a los nodos. De forma predeterminada, SSH está configurado para root, pero si estableces un usuario de acceso, usa ese nombre de usuario.
SSH_KEY_PATH: Es la ruta de acceso al 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 obtener una lista completa de las opciones del comando bmctl nodeagent rotate-credentials, consulta nodeagent rotate-credentials en la referencia del comando bmctl.

Verificar el estado

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

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

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

Marca --port
Archivo kubeconfig
Archivo de configuración de clúster

Verifica el estado del agente de nodo

Con solo la marca --cluster, puedes verificar el estado del agente de nodo según lo que se especifica en el archivo de configuración del clúster.

Para verificar el estado del agente de nodo según el archivo de configuración del clúster, usa el siguiente comando:

./bmctl nodeagent status \
    --cluster CLUSTER_NAME

Reemplaza CLUSTER_NAME por el nombre del clúster que deseas verificar.

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

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

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

Para verificar el estado del agente de nodo según el recurso personalizado del clúster, usa el siguiente comando:

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

Reemplaza lo siguiente:

CLUSTER_NAME: Es el nombre del clúster en cuyos nodos deseas implementar el agente de nodo.
KUBECONFIG: Es la ruta de acceso del archivo kubeconfig del clúster para el que habilitas 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

Verifica el estado del agente de nodos desde los nodos

Con la marca --cluster junto con la marca --nodes, puedes verificar el estado del agente de nodo para nodos de clúster específicos.

Para verificar el estado del agente de nodo en nodos específicos, usa el siguiente comando:

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

Reemplaza lo siguiente:

CLUSTER_NAME: Es el nombre del clúster en cuyos nodos deseas implementar el agente de nodo.
NODE_IP_ADDRESS_LIST: Es una lista separada por comas de las direcciones IP de los nodos en los que implementas Node Agent.

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 obtener una lista completa de las opciones del comando bmctl nodeagent status, consulta nodeagent status en la referencia del comando bmctl.

Permisos de usuario de SSH

Un usuario no raíz puede ejecutar el comando bmctl nodeagent. Esto requiere que el usuario tenga permisos sudo completos sin contraseña o una lista de permisos sudo explícita sin contraseña.

La lista de usuarios permitidos de sudo sin contraseña explícita para el agente de nodos 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 de SSH

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

Personaliza el puerto del agente de nodo

El agente de nodo permite la personalización de puertos. Especifica este puerto personalizado durante la implementación con la marca --port. Esto propaga el parámetro de configuración a la configuración del agente de nodo en cada nodo. El puerto personalizado debe alinearse con la configuración del cliente, como se detalla en los siguientes métodos.

Para clústeres existentes

Para actualizar un clúster existente en ejecución, usa la marca --port para especificar el nuevo puerto personalizado. Este parámetro de configuración se propaga a los clientes (controladores).

Para clústeres nuevos

Cuando crees un clúster nuevo, agrega 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

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

Migra los clústeres para usar el agente de nodos Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Antes de comenzar

Migra al modo de agente de nodo

Implementa el agente de nodo

Implementa en un entorno nuevo

Actualiza la versión del agente de Node

Implementa o vuelve a implementar en nodos específicos

Habilita el agente de nodo

Habilita el agente de nodo para un clúster en ejecución existente

Instalación de un clúster nuevo

Rota las credenciales

Verificar el estado

Verifica el estado del agente de nodo

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

Verifica el estado del agente de nodos desde los nodos

Permisos de usuario de SSH

Verificación de la clave de host de SSH

Personaliza el puerto del agente de nodo

Para clústeres existentes

Para clústeres nuevos

Rendimiento

Migra los clústeres para usar el agente de nodos