Migrar clusters para usar o agente de nós

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

Este documento descreve como ativar o uso do agente de nó para clusters novos e atuais para oferecer operações de cluster mais seguras. A partir da versão 1.33, o Google Distributed Cloud para bare metal permite fazer a transição do uso do Ansible por SSH para operações de cluster para um modelo mais seguro, baseado em agente, que usa o agente de nó. O uso do agente de nó para gerenciar operações de cluster aborda questões de segurança sobre a necessidade de acesso SSH aos nós do cliente em ambientes sensíveis. No novo modelo, um binário do agente de nó é executado em cada nó. O agente de nó se comunica com clientes, como controladores, por um canal gRPC seguro para gerenciar todas as atividades de configuração de nós. O Google Distributed Cloud impõe o Transport Layer Security (mTLS) mútuo entre o controlador de cluster e o agente de nó e entre bmctl e o agente de nó para a autenticação e criptografia das conexões gRPC.

Os comandos bmctl nodeagent tornam o processo de migração de clusters atuais para usar o agente de nós simples e confiável. Os comandos reduzem o esforço manual, melhoram a consistência entre os nós e automatizam tarefas importantes, como criação e rotação de certificados. Os comandos bmctl operam principalmente por SSH. Isso permite que os administradores implantem ou reimplantem agentes mesmo quando o controlador do cluster está com problemas ou os canais de comunicação padrão estão comprometidos.

O agente de nó e os comandos bmctl nodeagent correspondentes são compatíveis com o Google Distributed Cloud para bare metal nas versões 1.33.0 e mais recentes. É possível ativar o agente de nó para clusters da versão 1.33 ou mais recente ou ao criar clusters da versão 1.33 ou mais recente.

Esta página é destinada a administradores, arquitetos e operadores que gerenciam o ciclo de vida da infraestrutura de tecnologia subjacente. Para saber mais sobre papéis comuns e tarefas de exemplo referenciados no conteúdo do Google Cloud , consulte Funções e tarefas de usuário comuns do GKE Enterprise.

Antes de começar

Verifique se todos os nós do cluster atendem aos seguintes requisitos antes de migrar um cluster para o modo do agente de nó:

• Cada nó tem uma porta aberta dedicada ao agente de nó. Por padrão, o agente de nó usa a porta 9192, mas é possível configurar essa porta durante a implantação, ativação ou instalações de novos clusters. Para mais informações, consulte Personalizar a porta do agente de nó.

• Cada nó tem a versão 1.7 ou mais recente do containerd instalada.

Migrar para o modo Agente de nó

A migração para o modo de agente do Node é um processo de duas etapas:

1. Implante o agente de nó: implante o componente do agente de nó em todos os nós do cluster.

2. Ativar o modo de agente do nó:

   • Para um cluster atual, ative o modo usando o comando bmctl nodeagent.
   • Para um novo cluster, adicione a anotação de ativação e os caminhos de credenciais correspondentes ao arquivo de configuração do cluster antes da criação.

Implantar o agente do nó

O comando bmctl nodeagent deploy implanta o serviço do agente de nó em um ou mais nós de destino em um cluster especificado usando SSH. Esse comando instala ou reinstala o agente de nó. Ele se conecta por SSH e realiza as etapas necessárias, incluindo a transferência de binários, a geração e transferência opcionais de certificados e a configuração do serviço systemd. Ele exige acesso SSH e privilégios de sudo nos nós de destino.

É possível especificar nós de destino de várias maneiras: diretamente com a flag --nodes, com um arquivo de configuração do cluster usando a flag --cluster ou referenciando o recurso personalizado do cluster. Para mais informações sobre comandos e opções do agente do nó, consulte a referência de comando bmctl.

Implantar em um ambiente novo

Para implantações iniciais, faça o download do binário nodeagentd e gere novas autoridades certificadoras (CAs). O comando a seguir extrai a lista de nós do arquivo de configuração do cluster. A flag --sa-key fornece as credenciais necessárias para fazer o download do binário nodeagentd do bucket do Cloud Storage.

• Para implantar o agente de nó pela primeira vez em um novo cluster, use o seguinte 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
  

  Substitua:

  • CLUSTER_NAME: o nome do cluster em cujos nós você quer implantar o agente de nó.

  • USERNAME: o nome de usuário para o qual o acesso SSH aos nós está configurado. Por padrão, o SSH é configurado para root, mas se você definir um usuário de login, use esse nome de usuário.

  • SSH_KEY_PATH: o caminho do arquivo de chave privada SSH.

  • SERVICE_ACCOUNT_KEY_PATH: o caminho do arquivo de chave da conta de serviço com permissões para extrair imagens do registro. Por padrão, esse é o arquivo de chave JSON da conta de serviço anthos-baremetal-gcr.

  A resposta ao comando é semelhante ao exemplo a seguir:

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

Fazer upgrade da versão do agente do Node

Os upgrades do agente de nó são independentes dos upgrades do cluster. Para fazer upgrade do agente de nó, use o comando bmctl nodeagent deploy e defina --pull-binaries como true. Ao fazer upgrade do agente de nó, defina --generate-ca-creds como false para usar as CAs existentes em vez de regenerá-las. A regeneração de CAs exige a atualização das credenciais do cluster correspondente, um processo reservado para a rotação de credenciais. A saída parece uma implantação nova, mas sem os registros gerados pela CA.

O upgrade do agente de nó reinicia o processo do agente de nó, o que pode interromper qualquer job em execução. Embora a maioria dos jobs seja recuperada por mecanismos de nova tentativa, para minimizar possíveis interrupções, siga estas etapas:

1. Verifique se não há um upgrade de cluster ou outras atividades de configuração pós-instalação em andamento.

2. Verifique se o cluster está em execução.

3. Inicie o upgrade do agente de nó:

   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
   

   Substitua:

   • CLUSTER_NAME: o nome do cluster em cujos nós você quer implantar o agente de nó.

   • USERNAME: o nome de usuário para o qual o acesso SSH aos nós está configurado. Por padrão, o SSH é configurado para root, mas se você definir um usuário de login, use esse nome de usuário.

   • SSH_KEY_PATH: o caminho do arquivo de chave privada SSH.

   • SERVICE_ACCOUNT_KEY_PATH: o caminho do arquivo de chave da conta de serviço com permissões para extrair imagens do registro. Por padrão, esse é o arquivo de chave JSON da conta de serviço anthos-baremetal-gcr.

   A resposta ao comando é semelhante ao exemplo a seguir:

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

Implantar ou reimplantar em nós específicos

Se você adicionar ou recuperar nós de cluster, poderá segmentar os nós específicos para implantação do agente de nó, em vez de implantá-lo em todos os nós do cluster. Use a flag --nodes para especificar o nó da implantação.

• Para implantar o agente do Node em nós específicos, use o seguinte 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
  

  Substitua:

  • CLUSTER_NAME: o nome do cluster em cujos nós você quer implantar o agente de nó.

  • USERNAME: o nome de usuário para o qual o acesso SSH aos nós está configurado. Por padrão, o SSH é configurado para root, mas se você definir um usuário de login, use esse nome de usuário.

  • SSH_KEY_PATH: o caminho do arquivo de chave privada SSH.

  • SERVICE_ACCOUNT_KEY_PATH: o caminho do arquivo de chave da conta de serviço com permissões para extrair imagens do registro. Por padrão, esse é o arquivo de chave JSON da conta de serviço anthos-baremetal-gcr.

  • NODE_IP_ADDRESS_LIST: uma lista separada por vírgulas dos endereços IP dos nós em que você está implantando o agente do Node.

  A resposta ao comando é semelhante ao exemplo a seguir:

  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 uma lista completa de opções de comando bmctl nodeagent deploy, consulte nodeagent deploy na referência de comando bmctl.

Ativar o agente de nó

O comando enable ativa o modo de agente de nó em um cluster em execução depois que você implanta o agente de nó em todos os nós do cluster. Esse comando também cria ou atualiza as credenciais do agente de nó no cluster.

Importante: a ativação do modo de agente de nó é uma operação unidirecional. Não é possível reverter o cluster para o modo SSH.

Ativar o agente de nó para um cluster em execução

É possível ativar o agente de nó em clusters atuais da versão 1.33 e posteriores.

• Para ativar o agente de nó em um cluster atual, use o seguinte comando:

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

  Substitua:

  • KUBECONFIG: o caminho do arquivo kubeconfig do cluster em que você está ativando o Node Agent.

  • CLUSTER_NAME: o nome do cluster em cujos nós você quer implantar o agente de nó.

  A resposta ao comando é semelhante ao exemplo a seguir:

  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ção de um novo cluster

É possível ativar o agente de nó ao criar clusters da versão 1.33 e mais recentes.

Para ativar o agente de nó em um novo cluster, siga estas etapas:

1. Para um novo cluster de administrador, adicione os seguintes caminhos de arquivo de credenciais à seção superior do arquivo de configuração do cluster 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. Inclua a anotação de ativação do agente de nó na seção de metadados do cluster do arquivo de configuração do cluster:

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

3. Siga as instruções padrão para criar seu cluster.

Para uma lista completa de opções de comando bmctl nodeagent enable, consulte nodeagent enable na referência do comando bmctl.

Alternar credenciais

O comando rotate-credentials gira as credenciais do agente de nó nos nós e no cluster. Isso inclui a capacidade de rotacionar as autoridades de certificação (CAs). A flag --generate-ca-creds direciona o comando para regenerar as CAs e usar as CAs recém-geradas para assinar os certificados do servidor (nós) e do cliente (controlador).

Observação: a rotação das credenciais do agente de nó reinicia o processo do agente de nó. Semelhante a um upgrade, inicie a rotação de credenciais do agente de nó somente quando o cluster estiver em um estado de execução e nenhuma outra configuração for aplicada simultaneamente.

• Para fazer a rotação de credenciais e regenerar e usar novas CAs, use o seguinte comando:

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

  Substitua:

  • KUBECONFIG: o caminho do arquivo kubeconfig do cluster em que você está ativando o Node Agent.

  • CLUSTER_NAME: o nome do cluster em cujos nós você quer implantar o agente de nó.

  • USERNAME: o nome de usuário para o qual o acesso SSH aos nós está configurado. Por padrão, o SSH é configurado para root, mas se você definir um usuário de login, use esse nome de usuário.

  • SSH_KEY_PATH: o caminho do arquivo de chave privada SSH.

  A resposta ao comando é semelhante ao exemplo a seguir:

  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 uma lista completa de opções de comando bmctl nodeagent rotate-credentials, consulte nodeagent rotate-credentials na referência de comando bmctl.

Verificar status

O comando status fornece informações sobre o status de execução do Node Agent em nós. É possível especificar os nós de destino diretamente com a flag --nodes, com um arquivo de configuração do cluster usando a flag --cluster ou referenciando o recurso personalizado do cluster.

Quando você recebe nós de um arquivo de configuração de cluster ou da flag --nodes, o sistema recupera as credenciais do sistema de arquivos local. Se a origem do nó for um recurso personalizado do cluster, o sistema vai recuperar as credenciais dele.

A seguinte ordem de precedência determina a porta do agente de nó:

1. Sinalização --port
2. Arquivo kubeconfig
3. Arquivo de configuração do cluster

Verificar o status do agente de nó

Usando apenas a flag --cluster, é possível verificar o status do agente de nó com base no que está especificado no arquivo de configuração do cluster.

• Para verificar o status do agente de nó com base no arquivo de configuração do cluster, use o comando a seguir:

  ./bmctl nodeagent status \
      --cluster CLUSTER_NAME
  

  Substitua CLUSTER_NAME pelo nome do cluster que você está verificando.

  A resposta ao comando é semelhante ao exemplo a seguir:

  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 o status do agente de nó no cluster

Usando as flags --cluster e --kubeconfig juntas, é possível verificar o status do agente de nó com base no recurso personalizado do cluster.

• Para verificar o status do agente de nós com base no recurso personalizado do cluster, use o seguinte comando:

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

  Substitua:

  • CLUSTER_NAME: o nome do cluster em cujos nós você quer implantar o agente de nó.

  • KUBECONFIG: o caminho do arquivo kubeconfig do cluster em que você está ativando o Node Agent.

  A resposta ao comando é semelhante ao exemplo a seguir:

  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 o status do agente de nó nos nós

Usando as flags --cluster e --nodes juntas, é possível verificar o status do agente de nó para nós de cluster específicos.

• Para verificar o status do agente de nó em nós específicos, use o comando a seguir:

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

  Substitua:

  • CLUSTER_NAME: o nome do cluster em cujos nós você quer implantar o agente de nó.

  • NODE_IP_ADDRESS_LIST: uma lista separada por vírgulas dos endereços IP dos nós em que você está implantando o agente do Node.

  A resposta ao comando é semelhante ao exemplo a seguir:

  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 uma lista completa de opções de comando bmctl nodeagent status, consulte nodeagent status na referência do comando bmctl.

Permissões de usuário do SSH

Um usuário não raiz pode executar o comando bmctl nodeagent. Isso exige que o usuário tenha permissões sudo completas sem senha ou uma lista de permissões sudo sem senha explícita.

A lista de permissões explícita do sudo sem senha para o agente de nó tem as seguintes permissões:

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

Verificação da chave do host SSH

Verifique se todos os nós foram adicionados ao arquivo known_hosts na estação de trabalho de administrador. Caso contrário, desative a verificação da chave do host durante a implantação (nodeagent deploy) e a rotação de credenciais (nodeagent rotate-credentials) usando a flag --enforce-host-key-verify=false.

Personalizar a porta do agente de nó

O agente de nó permite a personalização de portas. Especifique essa porta personalizada durante a implantação usando a flag --port. Isso propaga a configuração para a configuração do agente de nó em cada nó. A porta personalizada precisa estar alinhada com a configuração do lado do cliente, conforme detalhado nos métodos a seguir.

Para clusters atuais

Para atualizar um cluster em execução, use a flag --port para especificar a nova porta personalizada. Essa configuração é propagada para os clientes (controladores).

Para novos clusters

Ao criar um cluster, adicione a seguinte anotação à configuração do cluster para especificar uma porta personalizada para o agente de nó:

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

Desempenho

A implantação e a ativação são concluídas em menos de um minuto. A rotação de credenciais em tempo de execução é comparável ou mais rápida que uma implantação padrão.

Observação: as métricas de desempenho variam de acordo com os recursos da máquina de bootstrap (CPU, memória), a largura de banda da rede e a carga operacional do nó. Os números são derivados de testes locais em um cluster inativo de 50 nós usando uma máquina de bootstrap configurada com 4 núcleos de CPU e 16 GB de memória.