O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Migrar clusters para usar o agente de nós

Este documento descreve como instalar e migrar clusters para o agente de nós para oferecer operações de cluster mais seguras. O agente de nós é um modelo mais seguro e baseado em agente do que o Ansible pelo SSH para operações de cluster, disponível para as versões 1.33 e mais recentes. Ao gerenciar operações de cluster com o agente de nós, é possível acessar nós de clientes em ambientes sensíveis sem SSH.

O 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 Transport Layer Security (mTLS, na sigla em inglês) 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.

Use bmctl nodeagent comandos para reduzir o esforço manual, melhorar a consistência entre os nós, e automatizar a criação e rotação de certificados. Os comandos bmctl operam principalmente pelo SSH para que você possa implantar agentes mesmo quando o controlador de cluster estiver com problemas ou os canais de comunicação padrão estiverem comprometidos.

Antes de começar

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

Uma porta aberta dedicada ao agente de nós. O agente de nós usa a porta 9192 por padrão. Configure essa porta ao implantar, ativar ou instalar um novo cluster. Para mais informações, consulte Personalizar a porta do agente de nós.
Containerd versão 1.7 ou mais recente.
12 GB de espaço livre no diretório /tmp no nó de administrador e em todos os nós de destino. Se não for possível mudar o tamanho do diretório /tmp para os nós de destino, consulte Aumentar a capacidade de armazenamento local para backups do agente de nós.

Migrar para o modo de agente de nós

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

Implantar o agente de nós: implante o componente do agente de nós em todos os nós do cluster.
Ativar o modo de 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 pelo 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 nova tentativa, para minimizar possíveis interrupções, siga estas etapas:

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

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 de 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 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 \
    --namespace CLUSTER_NAMESPACE \
    --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.
CLUSTER_NAMESPACE: o namespace do cluster a ser usado para encontrar o cluster de destino e as credenciais do cluster e atualizar o recurso do cluster. O padrão é cluster-<CLUSTER-NAME>.

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

Instalar um novo cluster

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

Para usar o agente de nós em um novo cluster, faça o seguinte:

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

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: ""
```
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 \
    --namespace CLUSTER_NAMESPACE \
    --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.
CLUSTER_NAMESPACE: o namespace do cluster a ser usado para encontrar o cluster de destino e as credenciais do cluster e atualizar o recurso do cluster. O padrão é cluster-<CLUSTER-NAME>.
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. É 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:

Flag --port
Arquivo kubeconfig
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 \
    --namespace CLUSTER_NAMESPACE

Substitua:

CLUSTER_NAME: o nome do cluster que você está verificando.
CLUSTER_NAMESPACE: o namespace do cluster a ser usado para encontrar o cluster de destino e as credenciais do cluster e atualizar o recurso do cluster. O padrão é cluster-<CLUSTER-NAME>.

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 do 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"

Aumentar a capacidade de armazenamento local para backups do agente de nós

Para criar um arquivo de backup para nós do agente de nós, é necessário ter 12 GB de espaço livre no diretório /tmp no nó de administrador e em todos os nós de destino. Se não for possível mudar o tamanho do diretório /tmp para os nós de destino, consulte Mudar a capacidade de armazenamento local para nós de destino. Se você não conseguir mudar o tamanho do diretório /tmp para o nó de administrador, consulte Mudar a capacidade de armazenamento local para um nó de administrador.

Mudar a capacidade de armazenamento local para nós de destino

Se não for possível mudar o tamanho da partição /tmp do nó de destino, redirecione a pasta temporária para uma partição com mais capacidade aplicando uma substituição de ambiente systemd:

Crie um arquivo de substituição systemd em /etc/systemd/system/nodeagentd.service.d/override.conf que contenha:
```
[Service]
Environment="TMPDIR=/var/tmp"
```

Aplique a configuração e reinicie o serviço:

sudo systemctl daemon-reload
sudo systemctl restart nodeagentd

Mudar a capacidade de armazenamento local para um nó de administrador

Se a estação de trabalho do administrador que executa o bmctl tiver espaço limitado para a partição /tmp, defina a variável TMPDIR localmente ao iniciar um backup:

  TMPDIR=/var/tmp bmctl backup cluster -c 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 para o cluster para o qual você está ativando o agente de nós.

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.

Migrar clusters para usar o agente de nós Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Antes de começar

Migrar para o modo de agente de nós

Implantar o agente de nós

Implantar em um ambiente novo

Fazer upgrade da versão do agente de nós

Implantar ou reimplantar em nós específicos

Ativar o agente de nós

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

Instalar um novo cluster

Alternar credenciais

Verificar status

Verificar o status do agente de nós

Verificar o status do agente de nós no cluster

Verificar o status do agente de nós nos nós

Permissões de usuário SSH

Verificação de chave do host SSH

Personalizar a porta do agente de nós

Para clusters atuais

Para novos clusters

Aumentar a capacidade de armazenamento local para backups do agente de nós

Mudar a capacidade de armazenamento local para nós de destino

Mudar a capacidade de armazenamento local para um nó de administrador

Desempenho

Migrar clusters para usar o agente de nós