Migre clusters para usar o agente de nó

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 a utilização do agente de nó para clusters novos e existentes, de modo a oferecer operações de cluster mais seguras. A partir da versão 1.33, o Google Distributed Cloud para bare metal oferece a capacidade de fazer a transição da utilização do Ansible através de SSH para operações de cluster para um modelo mais seguro baseado em agente que usa o agente de nó. A utilização do agente de nó para gerir as operações do cluster resolve as preocupações de segurança relativas à necessidade de acesso SSH aos nós do cliente em ambientes confidenciais. No novo modelo, é executado um ficheiro binário do agente de nó em cada nó. O agente do nó comunica com os clientes, como os controladores, através de um canal gRPC seguro para gerir todas as atividades de configuração do nó. O Google Distributed Cloud aplica o Transport Layer Security (mTLS) mútuo entre o controlador do cluster e o agente do nó, bem como entre bmctl e o agente do nó para a autenticação e a encriptação das ligações gRPC.

Os comandos bmctl nodeagent tornam o processo de migração dos clusters existentes para usar o agente de nó simples e fiável. Os comandos reduzem o esforço manual, melhoram a consistência entre os nós e automatizam tarefas importantes, como a criação e a rotação de certificados. Os comandos bmctl funcionam principalmente através de SSH. Isto permite que os administradores implementem ou reimplementem agentes mesmo quando o controlador do cluster não está em bom estado ou os respetivos canais de comunicação padrão estão danificados.

O agente de nó e os comandos bmctl nodeagent correspondentes suportam o Google Distributed Cloud para versões bare metal 1.33.0 e posteriores. Pode ativar o agente de nó para clusters existentes com a versão 1.33 ou posterior, ou quando cria clusters com a versão 1.33 ou posterior.

Esta página destina-se a administradores, arquitetos e operadores que gerem o ciclo de vida da infraestrutura tecnológica subjacente. Para saber mais sobre as funções comuns e exemplos de tarefas que referimos no conteúdo, consulte o artigo Funções de utilizador e tarefas comuns do GKE Enterprise. Google Cloud

Antes de começar

Certifique-se de que todos os nós do cluster cumprem os seguintes requisitos antes de migrar um cluster para o modo de agente de nó:

• Cada nó tem uma porta aberta dedicada ao agente do nó. Por predefinição, o agente de nó usa a porta 9192, mas pode configurar esta porta durante a implementação, a ativação ou as instalações de novos clusters. Para mais informações, consulte o artigo Personalize a porta do agente do nó.

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

Migre para o modo de agente de nó

A migração para o modo de agente de nó é um processo de dois passos:

1. Implemente o agente de nó: implemente o componente do agente de nó em todos os nós no cluster.

2. Ative o modo de agente do nó:

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

Implemente o agente de nó

O comando bmctl nodeagent deploy implementa o serviço do agente do nó num ou mais nós de destino num cluster especificado através do SSH. Este comando instala ou reinstala o agente do nó. Liga-se através do SSH e executa os passos necessários, incluindo a transferência de ficheiros binários, a geração e a transferência opcionais de certificados e a configuração do serviço systemd. Requer acesso SSH e privilégios de sudo nos nós de destino.

Pode especificar nós de destino de várias formas: diretamente através da flag --nodes, através de um ficheiro de configuração do cluster com a flag --cluster ou referenciando o recurso personalizado do cluster. Para mais informações sobre os comandos e as opções do agente de nó, consulte a referência de comandos bmctl.

Implemente num ambiente novo

Para implementações iniciais, transfira o ficheiro binário nodeagentd e gere novas autoridades de certificação (CAs). O seguinte comando obtém a lista de nós do ficheiro de configuração do cluster. A flag --sa-key fornece as credenciais necessárias para transferir o ficheiro binário nodeagentd do contentor do Cloud Storage.

• Para implementar o agente de nó pela primeira vez num 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 o seguinte:

  • CLUSTER_NAME: o nome do cluster cujos nós quer implementar o agente de nó.

  • USERNAME: o nome de utilizador para o qual o acesso SSH aos nós está configurado. Por predefinição, o SSH está configurado para root, mas se definir um utilizador de início de sessão, use esse nome de utilizador.

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

  • SERVICE_ACCOUNT_KEY_PATH: o caminho do ficheiro de chave da conta de serviço com autorizações para extrair imagens de registo. Por predefinição, este é o ficheiro de chave JSON da conta de serviço anthos-baremetal-gcr.

  O resultado do comando é semelhante ao seguinte exemplo:

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

Atualize a versão do agente do nó

As atualizações do agente de nó são independentes das atualizações do cluster. Para atualizar o agente do nó, use o comando bmctl nodeagent deploy e defina --pull-binaries como true. Quando atualizar o agente do nó, defina --generate-ca-creds como false para usar as ACs existentes em vez de as regenerar. A regeneração de ACs requer a atualização das credenciais do cluster correspondentes, um processo reservado para a rotação de credenciais. O resultado assemelha-se a uma implementação recente, mas sem os registos gerados pela AC.

A atualização do agente do nó reinicia o processo do agente do nó, o que pode interromper quaisquer tarefas em execução. Embora a maioria das tarefas seja recuperada através de mecanismos de repetição, para minimizar potenciais interrupções, siga os passos abaixo:

1. Certifique-se de que não existe nenhuma atualização do cluster nem outras atividades de configuração pós-instalação em curso.

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

3. Inicie a atualização 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 o seguinte:

   • CLUSTER_NAME: o nome do cluster cujos nós quer implementar o agente de nó.

   • USERNAME: o nome de utilizador para o qual o acesso SSH aos nós está configurado. Por predefinição, o SSH está configurado para root, mas se definir um utilizador de início de sessão, use esse nome de utilizador.

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

   • SERVICE_ACCOUNT_KEY_PATH: o caminho do ficheiro de chave da conta de serviço com autorizações para extrair imagens de registo. Por predefinição, este é o ficheiro de chave JSON da conta de serviço anthos-baremetal-gcr.

   O resultado do comando é semelhante ao seguinte exemplo:

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

Implemente ou reimplemente em nós específicos

Se adicionar ou recuperar nós do cluster, pode segmentar os nós específicos para a implementação do agente do nó, em vez de o implementar em todos os nós do cluster. Use a flag --nodes para especificar o nó para implementação.

• Para implementar 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 o seguinte:

  • CLUSTER_NAME: o nome do cluster cujos nós quer implementar o agente de nó.

  • USERNAME: o nome de utilizador para o qual o acesso SSH aos nós está configurado. Por predefinição, o SSH está configurado para root, mas se definir um utilizador de início de sessão, use esse nome de utilizador.

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

  • SERVICE_ACCOUNT_KEY_PATH: o caminho do ficheiro de chave da conta de serviço com autorizações para extrair imagens de registo. Por predefinição, este é o ficheiro 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 nos quais está a implementar o agente de nó.

  O resultado do comando é semelhante ao seguinte exemplo:

  Please check the logs at bmctl-workspace/demo-cluster/log/nodeagent_deploy-20250819-181751/nodeagent_deploy.log
  [2025-08-19 18:17:51+0000] INFO: Executing 'nodeagent deploy'...
  [2025-08-19 18:17:54+0000] -------------------- Deployment Plan --------------------
  [2025-08-19 18:17:54+0000]   Target Cluster:            demo-cluster
  [2025-08-19 18:17:54+0000]   SSH User:                  user
  [2025-08-19 18:17:54+0000]   SSH Key:                   SSH_KEY_PATH
  [2025-08-19 18:17:54+0000]   Concurrency:               25
  [2025-08-19 18:17:54+0000]   Generate Credentials:      false
  [2025-08-19 18:17:54+0000]   Deploy Credentials:        true
  [2025-08-19 18:17:54+0000]   Server Cert Validity Days: 1825
  [2025-08-19 18:17:54+0000]   Verify SSH Host Keys:      true
  [2025-08-19 18:17:54+0000]   Node Agent pull version:   1.33.0-gke.799
  [2025-08-19 18:17:54+0000]   Target Nodes Source:       nodes flag
  [2025-08-19 18:17:54+0000]   Nodes Port:                9192
  [2025-08-19 18:17:54+0000]   Target Nodes (3):          10.200.0.2, 10.200.0.3
  [2025-08-19 18:17:54+0000] ---------------------------------------------------------
  Proceed with deployment? [y/N]:
  

Para ver uma lista completa das opções de comando bmctl nodeagent deploy, consulte nodeagent deploy na bmctlreferência de comandos.

Ative o agente de nó

O comando enable ativa o modo de agente de nó num cluster em execução existente depois de implementar o agente de nó em todos os nós no cluster. Este comando também cria ou atualiza as credenciais do agente do nó no cluster.

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

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

Pode ativar o agente de nó em clusters existentes da versão 1.33 e posteriores.

• Para ativar o agente de nó num cluster existente, use o seguinte comando:

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

  Substitua o seguinte:

  • KUBECONFIG: o caminho do ficheiro kubeconfig para o cluster para o qual está a ativar o agente de nó.

  • CLUSTER_NAME: o nome do cluster cujos nós quer implementar o agente de nó.

  O resultado do comando é semelhante ao seguinte exemplo:

  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 novo cluster

Pode ativar o agente de nó quando cria clusters da versão 1.33 e posteriores.

Para ativar o agente de nó para um novo cluster, siga estes passos:

1. Para um novo cluster de administrador, adicione os caminhos dos ficheiros de credenciais seguintes à secção superior do ficheiro 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 secção de metadados do cluster do ficheiro 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 o cluster.

Para ver uma lista completa das opções de comando bmctl nodeagent enable, consulte nodeagent enable na bmctlreferência de comandos.

Rote as credenciais

O comando rotate-credentials roda as credenciais do agente do nó nos nós e no cluster. Isto inclui a capacidade de rodar as autoridades de certificação (ACs). A flag --generate-ca-creds direciona o comando para regenerar as ACs e usar estas ACs geradas recentemente para assinar os certificados para o servidor (nós) e o cliente (controlador).

Nota: a rotação das credenciais do agente do nó reinicia o processo do agente do nó. Semelhante a uma atualização, inicie a rotação das credenciais do agente do nó apenas quando o cluster estiver em estado de execução e não forem aplicadas outras configurações em simultâneo.

• Para alternar as credenciais, regenerar e usar novas ACs, 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 o seguinte:

  • KUBECONFIG: o caminho do ficheiro kubeconfig para o cluster para o qual está a ativar o agente de nó.

  • CLUSTER_NAME: o nome do cluster cujos nós quer implementar o agente de nó.

  • USERNAME: o nome de utilizador para o qual o acesso SSH aos nós está configurado. Por predefinição, o SSH está configurado para root, mas se definir um utilizador de início de sessão, use esse nome de utilizador.

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

  O resultado do comando é semelhante ao seguinte exemplo:

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

Verificar estado

O comando status fornece informações sobre o estado de execução do agente de nó nos nós. Pode especificar nós de destino diretamente através da flag --nodes, através de um ficheiro de configuração do cluster com a flag --cluster ou referenciando o recurso personalizado do cluster.

Quando obtém nós a partir de um ficheiro de configuração do cluster ou da flag --nodes, o sistema obtém credenciais do sistema de ficheiros local. Se a origem do nó for um recurso personalizado do cluster, o sistema obtém as credenciais do cluster.

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

1. --port bandeira
2. Ficheiro Kubeconfig
3. Ficheiro de configuração do cluster

Valide o estado do agente do nó

Se usar apenas a flag --cluster, pode verificar o estado do agente do nó com base no que está especificado no ficheiro de configuração do cluster.

• Para verificar o estado do agente de nó com base no ficheiro de configuração do cluster, use o seguinte comando:

  ./bmctl nodeagent status \
      --cluster CLUSTER_NAME
  

  Substitua CLUSTER_NAME pelo nome do cluster que está a verificar.

  O resultado do comando é semelhante ao seguinte exemplo:

  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
  

Valide o estado do agente do nó a partir do cluster

Usando o sinalizador --cluster juntamente com o sinalizador --kubeconfig, pode verificar o estado do agente do nó com base no recurso personalizado do cluster.

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

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

  Substitua o seguinte:

  • CLUSTER_NAME: o nome do cluster cujos nós quer implementar o agente de nó.

  • KUBECONFIG: o caminho do ficheiro kubeconfig para o cluster para o qual está a ativar o agente de nó.

  O resultado do comando é semelhante ao seguinte exemplo:

  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
  

Valide o estado do agente do nó a partir dos nós

Usando o sinalizador --cluster juntamente com o sinalizador --nodes, pode verificar o estado do agente do nó para nós do cluster específicos.

• Para verificar o estado do agente do nó para nós específicos, use o seguinte comando:

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

  Substitua o seguinte:

  • CLUSTER_NAME: o nome do cluster cujos nós quer implementar o agente de nó.

  • NODE_IP_ADDRESS_LIST: uma lista separada por vírgulas dos endereços IP dos nós nos quais está a implementar o agente de nó.

  O resultado do comando é semelhante ao seguinte exemplo:

  Please check the logs at bmctl-workspace/demo-cluster/log/nodeagent_status-20250819-210050/nodeagent_status.log
  [2025-08-19 21:00:50+0000] Check Node Agent for cluster: demo-cluster
  [2025-08-19 21:00:53+0000] ----------------------------------------------------------
  [2025-08-19 21:00:53+0000] Verifying Node Agent status on all nodes...
  [2025-08-19 21:00:53+0000] Target Nodes Source: nodes flag
  [2025-08-19 21:00:53+0000] --------------------- Total nodes: 1 ----------------------
  [2025-08-19 21:00:53+0000] node: control-0--893f0567cb79efc-9b9ec55816170dcf.lab.anthos, version: 1.33.0-gke.799, OS: linux, uptime (seconds): 1399
  [2025-08-19 21:00:53+0000] ----------------------------------------------------------
  [2025-08-19 21:00:53+0000] Verified Node Agent status on all nodes in cluster
  

Para ver uma lista completa das opções de comando bmctl nodeagent status, consulte nodeagent status na bmctlreferência de comandos.

Autorizações do utilizador SSH

Um utilizador não root pode executar o comando bmctl nodeagent. Isto requer que o utilizador tenha autorizações sudo completas sem palavra-passe ou uma lista de autorizações sudo explícita sem palavra-passe.

A lista de autorizações sudo sem palavra-passe explícita para o agente do nó tem as seguintes autorizaçõ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_*/*

Validação da chave do anfitrião SSH

Certifique-se de que todos os nós são adicionados ao ficheiro known_hosts na estação de trabalho do administrador. Caso contrário, desative a validação da chave do anfitrião durante a implementação (nodeagent deploy) e a rotação de credenciais (nodeagent rotate-credentials) com a flag --enforce-host-key-verify=false.

Personalize a porta do agente do nó

O agente de nó permite a personalização da porta. Especifique esta porta personalizada durante a implementação com a flag --port. Isto propaga a definição para a configuração do agente do nó em cada nó. A porta personalizada tem de estar alinhada com a configuração do lado do cliente, conforme detalhado nos métodos seguintes.

Para clusters existentes

Para atualizar um cluster existente em execução, use a flag --port para especificar a nova porta personalizada. Esta definição propaga-se aos clientes (controladores).

Para novos clusters

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

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

Desempenho

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

Nota: as métricas de desempenho variam com base nos recursos da máquina de arranque (CPU, memória), na largura de banda da rede e na carga operacional do nó. Os números derivam de testes locais num cluster de 50 nós inativo com uma máquina de arranque configurada com 4 núcleos de CPU e 16 GB de memória.