Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

Migra los clústeres para usar el agente de nodos

En este documento, se describe cómo instalar clústeres y migrarlos a Node Agent para proporcionar operaciones de clúster más seguras. Node Agent es un modelo más seguro basado en agentes que Ansible a través de SSH para las operaciones de clúster, disponible para las versiones 1.33 y posteriores. Cuando administras las operaciones del clúster con Node Agent, puedes acceder a los nodos del cliente en entornos sensibles sin SSH.

El objeto binario de Node Agent se ejecuta en cada nodo. Node Agent se comunica con los clientes, como los controladores, a través de un canal gRPC seguro para administrar 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 Node Agent, y entre bmctl y Node Agent para la autenticación y el encriptado de las conexiones gRPC.

Usa los comandos bmctl nodeagent para reducir el esfuerzo manual, mejorar la coherencia entre los nodos y automatizar la creación y rotación de certificados. Los comandos bmctl operan principalmente a través de SSH, por lo que puedes 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.

Antes de comenzar

Asegúrate de que todos los nodos del clúster cumplan con los siguientes requisitos antes de migrar un clúster al modo Node Agent:

Un puerto abierto dedicado a Node Agent. Node Agent usa el puerto 9192 de forma predeterminada. Configura este puerto cuando implementes, habilites o instales un clúster nuevo. Para obtener más información, consulta Personaliza el puerto de Node Agent.
Containerd versión 1.7 o posterior.
12 GB de espacio libre en el directorio /tmp del nodo de administrador y todos los nodos de destino. Si no puedes cambiar el tamaño del directorio /tmp para tus nodos de destino, consulta Aumenta la capacidad de almacenamiento local para las copias de seguridad de Node Agent.

Migra al modo Node Agent

La migración al modo Node Agent es un proceso de dos pasos:

Implementa Node Agent: Implementa el componente Node Agent en todos los nodos del clúster.
Habilita el modo Node Agent:
- Para un clúster existente, habilita el modo con el comando bmctl nodeagent.
- Para 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 Node Agent

El comando bmctl nodeagent deploy implementa el servicio Node Agent en uno o más nodos de destino dentro de un clúster especificado con SSH. Este comando instala o reinstala Node Agent. Se conecta a través de SSH y realiza los pasos necesarios, incluida la transferencia de objetos binarios, la generación y transferencia opcionales de certificados y la configuración del servicio systemd. Requiere acceso SSH y privilegios de sudo en los nodos de destino.

Puedes especificar los 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 de Node Agent, consulta la referencia del comando bmctl.

Implementa en un entorno nuevo

Para las implementaciones iniciales, descarga el objeto 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 Node Agent.
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 de Node Agent

Las actualizaciones de Node Agent son independientes de las actualizaciones del clúster. Para actualizar Node Agent, usa el comando bmctl nodeagent deploy y configura --pull-binaries como true. Cuando actualices Node Agent, configura --generate-ca-creds como false para usar las CA 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 es similar a una implementación nueva, pero sin los registros generados por la CA.

La actualización de Node Agent reinicia el proceso de Node Agent, 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 una 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 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

Reemplaza lo siguiente:

CLUSTER_NAME: Es el nombre del clúster en cuyos nodos deseas implementar Node Agent.
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 orientar los nodos específicos para la implementación de Node Agent, en lugar de implementarlo en todos los nodos del clúster. Usa la marca --nodes para especificar el nodo para la implementación.

Para implementar Node Agent 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 Node Agent.
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 Node Agent

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

Habilita Node Agent para un clúster en ejecución existente

Puedes habilitar Node Agent en clústeres existentes de la versión 1.33 y posteriores.

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

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

Reemplaza lo siguiente:

KUBECONFIG: Es la ruta de acceso al archivo kubeconfig del clúster para el que habilitas Node Agent.
CLUSTER_NAME: Es el nombre del clúster en cuyos nodos deseas implementar Node Agent.
CLUSTER_NAMESPACE: Es el espacio de nombres del clúster que se usará para encontrar el clúster de destino y las credenciales del clúster, y actualizar el recurso del clúster. El valor predeterminado es cluster-<CLUSTER-NAME>.

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

Instala un clúster nuevo

Puedes usar Node Agent cuando creas clústeres de la versión 1.33 y posteriores.

Para usar Node Agent en un clúster nuevo, haz lo siguiente:

Para un clúster de administrador nuevo, agrega las siguientes rutas de acceso a 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 de Node Agent 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 de Node Agent 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 del servidor (nodos) y el cliente (controlador).

Para rotar las credenciales y regenerar y usar CA nuevas, usa el siguiente comando:

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

Reemplaza lo siguiente:

KUBECONFIG: Es la ruta de acceso al archivo kubeconfig del clúster para el que habilitas Node Agent.
CLUSTER_NAME: Es el nombre del clúster en cuyos nodos deseas implementar Node Agent.
CLUSTER_NAMESPACE: Es el espacio de nombres del clúster que se usará para encontrar el clúster de destino y las credenciales del clúster, y actualizar el recurso del clúster. El valor predeterminado es cluster-<CLUSTER-NAME>.
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 de Node Agent en los nodos. Puedes especificar los 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 de Node Agent:

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

Verifica el estado de Node Agent

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

Para verificar el estado de Node Agent en función del archivo de configuración del clúster, usa el siguiente comando:

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

Reemplaza lo siguiente:

CLUSTER_NAME: Es el nombre del clúster que verificas.
CLUSTER_NAMESPACE: Es el espacio de nombres del clúster que se usará para encontrar el clúster de destino y las credenciales del clúster, y actualizar el recurso del clúster. El valor predeterminado es cluster-<CLUSTER-NAME>.

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 de Node Agent desde el clúster

Con la marca --cluster junto con la marca --kubeconfig, puedes verificar el estado de Node Agent en función del recurso personalizado del clúster.

Para verificar el estado de Node Agent en función del 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 Node Agent.
KUBECONFIG: Es la ruta de acceso al archivo kubeconfig del clúster para el que habilitas Node Agent.

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 de Node Agent desde los nodos

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

Para verificar el estado de Node Agent para 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 Node Agent.
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 que no es raíz puede ejecutar el comando bmctl nodeagent. Esto requiere que el usuario tenga permisos sudo completos sin contraseña o una lista de entidades permitidas sudo explícita sin contraseña.

La lista de entidades permitidas sudo explícita sin contraseña para Node Agent 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 agreguen 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) con la marca --enforce-host-key-verify=false.

Personaliza el puerto de Node Agent

Node Agent permite la personalización de puertos. Especifica este puerto personalizado durante la implementación con la marca --port. Esto propaga la configuración a la configuración de Node Agent 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 en ejecución existente, 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 Node Agent:

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

Aumenta la capacidad de almacenamiento local para las copias de seguridad de Node Agent

Para crear un archivo de copia de seguridad para los nodos de Node Agent, debes tener 12 GB de espacio libre en el directorio /tmp del nodo de administrador y todos los nodos de destino. Si no puedes cambiar el tamaño del directorio /tmp para tus nodos de destino, consulta Cambia la capacidad de almacenamiento local para los nodos de destino. Si no puedes cambiar el tamaño del directorio /tmp para el nodo de administrador, consulta Cambia la capacidad de almacenamiento local para un nodo de administrador.

Cambia la capacidad de almacenamiento local para los nodos de destino

Si no puedes cambiar el tamaño de la partición /tmp del nodo de destino, puedes redireccionar la carpeta temporal a una partición con más capacidad si aplicas una anulación del entorno de systemd:

Crea un archivo de anulación de systemd en /etc/systemd/system/nodeagentd.service.d/override.conf que contenga lo siguiente:
```
[Service]
Environment="TMPDIR=/var/tmp"
```

Aplica la configuración y reinicia el servicio:

sudo systemctl daemon-reload
sudo systemctl restart nodeagentd

Cambia la capacidad de almacenamiento local para un nodo de administrador

Si la estación de trabajo del administrador que ejecuta bmctl tiene espacio limitado para la partición /tmp, establece la variable TMPDIR de forma local cuando inicies una copia de seguridad:

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

Reemplaza lo siguiente:

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

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 o más rápido que una implementación estándar.

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 Node Agent

Implementa Node Agent

Implementa en un entorno nuevo

Actualiza la versión de Node Agent

Implementa o vuelve a implementar en nodos específicos

Habilita Node Agent

Habilita Node Agent para un clúster en ejecución existente

Instala un clúster nuevo

Rota las credenciales

Verificar el estado

Verifica el estado de Node Agent

Verifica el estado de Node Agent desde el clúster

Verifica el estado de Node Agent desde los nodos

Permisos de usuario de SSH

Verificación de la clave de host SSH

Personaliza el puerto de Node Agent

Para clústeres existentes

Para clústeres nuevos

Aumenta la capacidad de almacenamiento local para las copias de seguridad de Node Agent

Cambia la capacidad de almacenamiento local para los nodos de destino

Cambia la capacidad de almacenamiento local para un nodo de administrador

Rendimiento

Migra los clústeres para usar el agente de nodos