Migrar clusters para usar o agente de nós

Este documento descreve como ativar o uso do agente de nós para clusters novos e atuais, a fim de fornecer 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 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ós. O uso do agente de nós para gerenciar operações de cluster resolve problemas de segurança sobre a necessidade de acesso SSH a nós do cliente em ambientes sensíveis. No novo modelo, um binário do agente de nós é executado em cada nó. O agente de nós 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 aplica o TLS mútuo (mTLS) entre o controlador de cluster e o agente de nós e entre o bmctl e o agente de nós para a autenticação e criptografia das conexões gRPC.

Os comandos bmctl nodeagent facilitam e tornam confiável o processo de migração de clusters atuais para usar o agente de nós. 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 operam principalmente por SSH. Isso permite que os administradores implantem ou reimplantem agentes mesmo quando o controlador de cluster está com problemas ou os canais de comunicação padrão estão comprometidos.

O agente de nós e os comandos bmctl nodeagent correspondentes são compatíveis com o Google Distributed Cloud para bare metal versões 1.33.0 e mais recentes. É possível ativar o agente de nós para clusters atuais 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 Google Cloud conteúdo, consulte Funções e tarefas de usuário comuns do GKE.

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ós:

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

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

Migrar para o modo do agente de nós

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

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

  2. Ativar o modo do agente de nós:

    • 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 de nós

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

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

Implantar em um ambiente novo

Para implantações iniciais, faça o download do binário nodeagentd e gere novas autoridades certificadoras (ACs). O comando a seguir recupera 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ós 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 que você quer implantar o agente de nós.

    • 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 de 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 de nós

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

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

  1. Verifique se não há 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ós:

    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 que você quer implantar o agente de nós.

    • 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 de 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 a implantação do agente de nós, em vez de implantá-lo em todos os nós do cluster. Use a flag --nodes para especificar o nó para implantação.

  • Para implantar o agente de nós 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 que você quer implantar o agente de nós.

    • 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 de 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 de nós.

    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 comandos bmctl.

Ativar o agente de nós

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

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

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

  • Para ativar o agente de nós 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 para o qual você está ativando o agente de nós.

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

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

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

Para ativar o agente de nós para 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ós 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 o cluster.

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

Alternar credenciais

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

  • Para alternar credenciais e 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:

    • KUBECONFIG: o caminho do arquivo kubeconfig do cluster para o qual você está ativando o agente de nós.

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

    • 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 comandos bmctl.

Verificar status

O comando status fornece informações sobre o status de execução do agente de nós nos nós. É possível especificar nós de destino diretamente pela flag --nodes, por um arquivo de configuração de 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 de cluster, o sistema vai recuperar as credenciais do cluster.

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

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

Verificar o status do agente de nós

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

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

    ./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ós no cluster

Usando a flag --cluster com a flag --kubeconfig, é possível verificar o status do agente de nós 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 que você quer implantar o agente de nós.

    • KUBECONFIG: o caminho do arquivo kubeconfig do cluster para o qual você está ativando o agente de nós.

    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ós nos nós

Usando a flag --cluster com a flag --nodes, é possível verificar o status do agente de nós para nós de cluster específicos.

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

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

    Substitua:

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

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

    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 de comandos bmctl.

Permissões de usuário 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 explícita sem senha.

A lista de permissões sudo explícita sem senha para o agente de nós 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 de 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 de 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ós

O agente de nós permite a personalização da porta. 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ós em cada nó. A porta personalizada precisa estar alinhada à 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 novo cluster, adicione a seguinte anotação à configuração do cluster para especificar uma porta personalizada para o agente de nós:

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. O tempo de execução da rotação de credenciais é comparável ou mais rápido do que uma implantação padrão.