本文說明如何安裝叢集並遷移至節點代理程式，以提供更安全的叢集作業。Node Agent 是比透過 SSH 使用 Ansible 更安全的代理程式型模型，適用於 1.33 以上版本，可執行叢集作業。使用 Node Agent 管理叢集作業時，您可以在機密環境中存取客戶節點，不需使用 SSH。
Node Agent 二進位檔會在各個節點上執行。節點代理會透過安全的 gRPC 通道與控制器等用戶端通訊，管理所有節點設定活動。Google Distributed Cloud 會在叢集控制器和節點代理程式之間，以及 bmctl 和節點代理程式之間，強制執行相互傳輸層安全標準 (mTLS)，以便驗證及加密 gRPC 連線。
使用 bmctl nodeagent 指令可減少手動作業、提升節點一致性，以及自動建立和輪替憑證。bmctl 指令主要透過 SSH 運作，因此即使叢集控制器運作不正常或標準通訊管道受損，您仍可部署代理程式。
事前準備
將叢集遷移至節點代理程式模式前，請確認所有叢集節點都符合下列規定：
專為節點代理開啟的通訊埠。節點代理程式預設使用通訊埠 9192。部署、啟用或安裝新叢集時，請設定這個通訊埠。詳情請參閱「自訂節點代理程式通訊埠」。
Containerd 1.7 以上版本。
管理員節點和所有目標節點的
/tmp目錄中，有 12 GB 的可用空間。如果無法變更目標節點的/tmp目錄大小，請參閱「增加節點代理程式備份的本機儲存空間容量」。
遷移至 Node Agent 模式
遷移至節點代理程式模式需要兩個步驟：
部署節點代理：將節點代理元件部署至叢集內的所有節點。
啟用節點代理模式：
- 如為現有叢集，請使用
bmctl nodeagent指令啟用模式。 - 如果是新叢集，請在建立前，將啟用註解和對應的憑證路徑新增至叢集設定檔。
- 如為現有叢集，請使用
部署節點代理程式
bmctl nodeagent deploy 指令會使用 SSH，將 Node Agent 服務部署至指定叢集內的一或多個目標節點。這項指令會安裝或重新安裝 Node Agent。這個指令碼會透過 SSH 連線並執行必要步驟，包括傳輸二進位檔、視需要產生及傳輸憑證，以及設定 systemd 服務。您必須具備 SSH 存取權和目標節點的 sudo 權限。
您可以透過多種方式指定目標節點：直接透過 --nodes 標記、透過使用 --cluster 標記的叢集設定檔，或參照叢集自訂資源。如要進一步瞭解節點代理程式指令和選項，請參閱 bmctl 指令參考資料。
在全新環境中部署
如果是初始部署作業，請下載 nodeagentd 二進位檔，並產生新的憑證授權單位 (CA)。下列指令會從叢集設定檔擷取節點清單。--sa-key 旗標會提供必要的憑證，以便從 Cloud Storage bucket 下載 nodeagentd 二進位檔。
如要在新叢集上首次部署 Node Agent，請使用下列指令：
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更改下列內容：
CLUSTER_NAME：要在節點上部署節點代理程式的叢集名稱。USERNAME：已設定節點 SSH 存取權的使用者名稱。根據預設，系統會為root設定 SSH，但如果您設定登入使用者，請使用該使用者名稱。SSH_KEY_PATH：SSH 私密金鑰檔案的路徑。SERVICE_ACCOUNT_KEY_PATH：服務帳戶金鑰檔案的路徑，該檔案具有提取登錄映像檔的權限。根據預設，這是anthos-baremetal-gcr服務帳戶的 JSON 金鑰檔案。
指令輸出內容大致如下：
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 ===============================================
升級節點代理程式版本
節點代理程式升級與叢集升級無關。如要升級 Node Agent，請使用 bmctl nodeagent deploy 指令，並將 --pull-binaries 設為 true。升級節點代理程式時，請將 --generate-ca-creds 設為 false，以便使用現有的 CA，而非重新產生。重新產生 CA 時，必須更新對應的叢集憑證，這個程序僅限憑證輪換使用。輸出內容與全新部署作業類似，但沒有 CA 產生的記錄。
升級節點代理程式會重新啟動節點代理程式程序，這可能會中斷任何執行中的工作。雖然大多數工作都能透過重試機制復原，但為盡可能減少潛在中斷情形，請按照下列步驟操作：
確認叢集升級或其他安裝後設定活動未進行中。
確認叢集處於執行中狀態。
啟動 Node Agent 升級：
bmctl nodeagent deploy \ --pull-binaries=true \ --generate-ca-creds=false \ --cluster CLUSTER_NAME \ --ssh-user USERNAME \ --ssh-key SSH_KEY_PATH \ --sa-key SERVICE_ACCOUNT_KEY_PATH更改下列內容：
CLUSTER_NAME：要在節點上部署節點代理程式的叢集名稱。USERNAME：已設定節點 SSH 存取權的使用者名稱。根據預設，SSH 會設為root，但如果您設定登入使用者，請使用該使用者名稱。SSH_KEY_PATH：SSH 私密金鑰檔案的路徑。SERVICE_ACCOUNT_KEY_PATH：服務帳戶金鑰檔案的路徑，該檔案具有提取登錄映像檔的權限。根據預設，這是anthos-baremetal-gcr服務帳戶的 JSON 金鑰檔案。
指令輸出內容大致如下：
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)...
部署或重新部署至特定節點
如果您新增或復原叢集節點，可以指定要部署 Node Agent 的節點，不必部署至叢集中的所有節點。您可以使用 --nodes 旗標指定要部署的節點。
如要將 Node Agent 部署至特定節點，請使用下列指令：
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更改下列內容：
CLUSTER_NAME：要在節點上部署節點代理程式的叢集名稱。USERNAME：已設定節點 SSH 存取權的使用者名稱。根據預設，SSH 會設為root，但如果您設定登入使用者，請使用該使用者名稱。SSH_KEY_PATH：SSH 私密金鑰檔案的路徑。SERVICE_ACCOUNT_KEY_PATH：服務帳戶金鑰檔案的路徑，該檔案具有提取登錄映像檔的權限。根據預設，這是anthos-baremetal-gcr服務帳戶的 JSON 金鑰檔案。NODE_IP_ADDRESS_LIST：逗號分隔的清單，列出要部署節點代理程式的節點 IP 位址。
指令輸出內容大致如下：
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]:
如需 bmctl nodeagent deploy 指令選項的完整清單，請參閱 bmctl 指令參考資料中的「nodeagent deploy」。
啟用節點代理
將 Node Agent 部署至叢集內的所有節點後，enable 指令會在現有執行中的叢集內啟用 Node Agent 模式。這個指令也會在叢集內建立或更新節點代理程式憑證。
為現有執行中的叢集啟用節點代理
您可以在現有的 1.33 以上版本叢集啟用節點代理。
如要在現有叢集啟用 Node Agent，請按照下列步驟操作：
在叢集上啟用節點代理程式：
./bmctl nodeagent enable \ --kubeconfig KUBECONFIG \ --cluster CLUSTER_NAME \ --namespace CLUSTER_NAMESPACE \ --ensure-status=true更改下列內容：
KUBECONFIG：要啟用節點代理程式的叢集 kubeconfig 檔案路徑。CLUSTER_NAME：要在節點上部署節點代理程式的叢集名稱。CLUSTER_NAMESPACE：叢集的命名空間，用於尋找目標叢集和叢集憑證，並更新叢集資源。預設值為cluster-<CLUSTER-NAME>。
指令輸出內容大致如下：
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在叢集設定檔的叢集中繼資料部分，加入 Node Agent 啟用註解：
kind: Cluster metadata: annotations: baremetal.cluster.gke.io/enable-node-agent: ""
安裝新叢集
建立 1.33 以上版本的叢集時，可以使用節點代理。
如要在新叢集使用節點代理程式，請按照下列步驟操作：
如果是新的管理員叢集，請在管理員叢集設定檔的頂端部分，新增下列憑證檔案路徑：
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在叢集設定檔的叢集中繼資料部分，加入 Node Agent 啟用註解：
kind: Cluster metadata: annotations: baremetal.cluster.gke.io/enable-node-agent: ""按照標準操作說明建立叢集。
如需 bmctl nodeagent enable 指令選項的完整清單，請參閱 bmctl 指令參考資料中的「nodeagent enable」。
輪替憑證
rotate-credentials 指令會輪替節點和叢集中的節點代理程式憑證。包括輪替憑證授權單位 (CA) 的能力。--generate-ca-creds 旗標會指示指令重新產生 CA，並使用這些新產生的 CA 簽署伺服器 (節點) 和用戶端 (控制器) 的憑證。
如要輪換憑證，並重新產生及使用新的 CA，請使用下列指令：
bmctl nodeagent rotate-credentials \ --kubeconfig KUBECONFIG \ --generate-ca-creds=true \ --cluster CLUSTER_NAME \ --namespace CLUSTER_NAMESPACE \ --ssh-user USERNAME \ --ssh-key SSH_KEY_PATH更改下列內容：
KUBECONFIG：要啟用節點代理程式的叢集 kubeconfig 檔案路徑。CLUSTER_NAME：要在節點上部署節點代理程式的叢集名稱。CLUSTER_NAMESPACE：叢集的命名空間，用於尋找目標叢集和叢集憑證，以及更新叢集資源。預設為cluster-<CLUSTER-NAME>。USERNAME：已設定節點 SSH 存取權的使用者名稱。根據預設，SSH 會設為root，但如果您設定登入使用者，請使用該使用者名稱。SSH_KEY_PATH：SSH 私密金鑰檔案的路徑。
指令輸出內容大致如下：
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 ===============================================
如需 bmctl nodeagent rotate-credentials 指令選項的完整清單，請參閱 bmctl 指令參考資料中的「nodeagent rotate-credentials」。
檢查狀態
status 指令會提供節點上 Node Agent 的執行狀態資訊。您可以透過 --nodes 標記直接指定目標節點，也可以透過使用 --cluster 標記的叢集設定檔指定目標節點，或是參照叢集的自訂資源。
從叢集設定檔或 --nodes 旗標取得節點時，系統會從本機檔案系統擷取憑證。如果節點來源是叢集自訂資源，系統會從叢集擷取憑證。
節點代理程式通訊埠取決於下列優先順序：
--port旗標- Kubeconfig 檔案
- 叢集設定檔
驗證節點代理程式狀態
只要使用 --cluster 標記，即可根據叢集設定檔中指定的內容，檢查節點代理程式狀態。
如要根據叢集設定檔檢查節點代理程式狀態，請使用下列指令：
./bmctl nodeagent status \ --cluster CLUSTER_NAME \ --namespace CLUSTER_NAMESPACE更改下列內容：
CLUSTER_NAME：要檢查的叢集名稱。CLUSTER_NAMESPACE：叢集的命名空間，用於尋找目標叢集和叢集憑證，並更新叢集資源。預設值為cluster-<CLUSTER-NAME>。
指令輸出內容大致如下：
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
從叢集驗證節點代理程式狀態
搭配使用 --cluster 和 --kubeconfig 旗標，即可根據叢集自訂資源檢查節點代理程式狀態。
如要根據叢集自訂資源檢查節點代理程式狀態，請使用下列指令：
./bmctl nodeagent status \ --cluster CLUSTER_NAME \ --kubeconfig KUBECONFIG更改下列內容：
CLUSTER_NAME：要部署 Node Agent 的叢集節點名稱。KUBECONFIG：要啟用節點代理程式的叢集 kubeconfig 檔案路徑。
指令輸出內容大致如下：
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
從節點驗證節點代理程式狀態
使用 --cluster 標記和 --nodes 標記，即可檢查特定叢集節點的節點代理程式狀態。
如要檢查特定節點的 Node Agent 狀態，請使用下列指令：
./bmctl nodeagent status \ --cluster CLUSTER_NAME \ --nodes NODE_IP_ADDRESS_LIST更改下列內容：
CLUSTER_NAME：要部署 Node Agent 的叢集節點名稱。NODE_IP_ADDRESS_LIST：逗號分隔的清單，列出要部署節點代理程式的節點 IP 位址。
指令輸出內容大致如下：
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
如需 bmctl nodeagent status 指令選項的完整清單，請參閱 bmctl 指令參考資料中的「nodeagent status」。
SSH 使用者權限
非超級使用者可以執行 bmctl nodeagent 指令。使用者必須具備完整的無密碼 sudo 權限，或明確的無密碼 sudo 許可清單。
Node Agent 的明確無密碼 sudo 允許清單具有下列權限：
# 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_*/*
SSH 主機金鑰驗證
請確認所有節點都已新增至管理員工作站上的 known_hosts 檔案。否則，請在部署 (nodeagent
deploy) 和憑證輪換 (nodeagent
rotate-credentials) 期間，使用 --enforce-host-key-verify=false 旗標停用主機金鑰驗證。
自訂節點代理程式通訊埠
Node Agent 允許自訂通訊埠。部署期間，請使用 --port 旗標指定這個自訂通訊埠。這項設定會套用至每個節點的節點代理設定。自訂的通訊埠必須與用戶端設定一致，詳情請參閱下列方法。
現有叢集
如要更新現有且正在執行的叢集，請使用 --port 旗標指定新的自訂通訊埠。這項設定會傳播至用戶端 (控制器)。
新叢集
建立新叢集時，請在叢集設定中新增下列註解，為節點代理程式指定自訂連接埠：
kind: Cluster
metadata:
annotations:
baremetal.cluster.gke.io/node-agent-port: "10086"
增加節點代理程式備份的本機儲存空間容量
如要為節點代理程式節點建立備份檔案，管理員節點和所有目標節點的 /tmp 目錄中必須有 12 GB 的可用空間。如果無法變更目標節點的 /tmp 目錄大小，請參閱「變更目標節點的本機儲存空間容量」。如果無法變更管理員節點的 /tmp 目錄大小，請參閱「變更管理員節點的本機儲存空間容量」。
變更目標節點的本機儲存空間容量
如果無法變更目標節點的 /tmp 分割區大小，可以套用 systemd 環境覆寫，將暫時資料夾重新導向至容量較大的分割區：
在
/etc/systemd/system/nodeagentd.service.d/override.conf建立 systemd 覆寫檔案，並加入以下內容：[Service] Environment="TMPDIR=/var/tmp"套用設定並重新啟動服務：
sudo systemctl daemon-reload sudo systemctl restart nodeagentd
變更管理員節點的本機儲存空間容量
如果執行 bmctl 的管理員工作站 /tmp 分區空間有限，請在啟動備份時，在本機設定 TMPDIR 變數：
TMPDIR=/var/tmp bmctl backup cluster -c CLUSTER_NAME --kubeconfig KUBECONFIG
更改下列內容：
CLUSTER_NAME：要在其節點上部署 Node Agent 的叢集名稱。KUBECONFIG：要啟用節點代理程式的叢集 kubeconfig 檔案路徑。
效能
部署和啟用作業會在不到一分鐘內完成。憑證輪換執行階段與標準部署相當，甚至更快。