このドキュメントでは、クラスタをインストールしてノード エージェントに移行し、より安全なクラスタ オペレーションを実現する方法について説明します。ノード エージェントは、クラスタ オペレーションに SSH 経由で Ansible を使用するよりも安全なエージェント ベースのモデルで、バージョン 1.33 以降で使用できます。 ノード エージェントを使用してクラスタ オペレーションを管理すると、SSH を使用せずに機密性の高い環境の顧客ノードにアクセスできます。
各ノードでノード エージェント バイナリが実行されます。ノード エージェントは、安全な gRPC チャネルを介してコントローラなどの
クライアントと通信し、すべてのノード構成アクティビティを管理します。Google Distributed Cloud は、クラスタ コントローラとノード エージェントの間、および bmctl とノード エージェントの間で Mutual Transport Layer Security（mTLS）を適用し、gRPC 接続の認証と暗号化を行います。
bmctl nodeagent コマンドを使用すると、
手作業が減り、ノード間の整合性が向上し、
証明書の作成やローテーションが自動化されます。bmctl コマンドは主に SSH 経由で動作するため、クラスタ コントローラが異常な状態である場合や、標準の通信チャネルが十分に機能していない場合でも、エージェントをデプロイできます。
始める前に
クラスタをノード エージェント モードに移行する前に、すべてのクラスタノードが次の要件を満たしていることを確認します。
ノード エージェント専用のオープンポート。ノード エージェントはデフォルトでポート 9192 を使用します。 このポートは、新しいクラスタをデプロイ、有効化、インストールするときに構成します。 詳細については、ノード エージェントのポートをカスタマイズするをご覧ください。
Containerd バージョン 1.7 以降。
管理ノードとすべてのターゲット ノードの
/tmpディレクトリに 12 GB の空き容量。ターゲット ノードの/tmpディレクトリのサイズを変更できない場合は、ノード エージェントのバックアップ用のローカル ストレージ容量を増やすをご覧ください。
ノード エージェント モードに移行する
ノード エージェント モードへの移行は、次の 2 つの手順で行います。
ノード エージェントをデプロイする:ノード エージェント コンポーネントをクラスタ内のすべてのノードにデプロイします。
ノード エージェント モードを有効にする:
- 既存のクラスタの場合は、
bmctl nodeagentコマンドを使用してモードを有効にします。 - 新しいクラスタの場合は、作成する前に、有効化アノテーションと、対応する認証情報のパスをクラスタ構成ファイルに追加します。
- 既存のクラスタの場合は、
ノード エージェントをデプロイする
bmctl nodeagent deploy コマンドでは、SSH を使用して、指定されたクラスタ内の 1 つ以上のターゲット ノードにノード エージェント サービスをデプロイします。このコマンドでは、ノード エージェントをインストールまたは再インストールします。SSH 経由で接続し、バイナリの転送、証明書の生成と転送（必要に応じて）、systemd サービスのセットアップなどの必要なステップを実行します。このコマンドを実行するには、ターゲット ノードに対する SSH アクセスと sudo 権限が必要です。
ターゲット ノードは、--nodes フラグを使用して直接指定する方法、--cluster フラグを使用してクラスタ構成ファイルで指定する方法、クラスタ カスタム リソースを参照する方法など、いくつかの方法で指定できます。ノード エージェントのコマンドとオプションの詳細については、bmctl コマンド リファレンスをご覧ください。
新しい環境にデプロイする
初回デプロイの場合は、nodeagentd バイナリをダウンロードして、新しい認証局（CA）を生成します。次のコマンドは、クラスタ構成ファイルからノードリストを取得します。--sa-key フラグは、Cloud Storage バケットから nodeagentd バイナリをダウンロードするために必要な認証情報を提供します。
新しいクラスタにノード エージェントを初めてデプロイするには、次のコマンドを使用します。
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 アクセスが構成されているユーザー名。デフォルトでは、SSH はroot用に構成されていますが、ログイン ユーザーを設定した場合は、そのユーザー名を使用します。SSH_KEY_PATH: SSH 秘密鍵ファイルのパス。SERVICE_ACCOUNT_KEY_PATH: レジストリ イメージを pull する権限を持つサービス アカウント キー ファイルのパス。デフォルトでは、これは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 ===============================================
ノード エージェントのバージョンをアップグレードする
ノード エージェントのアップグレードは、クラスタのアップグレードとは別に行われます。ノード エージェントをアップグレードするには、bmctl nodeagent deploy コマンドを使用し、--pull-binaries を true に設定します。ノード エージェントをアップグレードするときに、--generate-ca-creds を false に設定して、CA を再生成するのではなく、既存の CA を使用します。CA を再生成するには、対応するクラスタ認証情報を更新する必要があります。このプロセスは認証情報のローテーション用に予約されています。出力は新規のデプロイに似ていますが、CA によって生成されるログはありません。
ノード エージェントをアップグレードすると、ノード エージェント プロセスが再起動され、実行中のジョブが停止される可能性があります。ほとんどのジョブは再試行メカニズムによって復元されますが、潜在的な停止を最小限に抑えるには、次の手順を行います。
クラスタのアップグレードや、インストール後の他の構成アクティビティが進行中ではないことを確認します。
クラスタが実行状態であることを確認します。
ノード エージェントのアップグレードを開始します。
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: レジストリ イメージを pull する権限を持つサービス アカウント キー ファイルのパス。デフォルトでは、これは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)...
特定のノードにデプロイするか再デプロイする
クラスタノードを追加または復元する場合は、クラスタ内のすべてのノードにデプロイするのではなく、ノード エージェントのデプロイの対象を特定のノードに設定できます。--nodes フラグを使用して、デプロイするノードを指定します。
特定のノードにノード エージェントをデプロイするには、次のコマンドを使用します。
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: レジストリ イメージを pull する権限を持つサービス アカウント キー ファイルのパス。デフォルトでは、これは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 をご覧ください。
ノード エージェントを有効にする
enable コマンドでは、クラスタ内のすべてのノードにノード エージェントをデプロイした後、実行中の既存のクラスタ内でノード エージェント モードを有効にします。このコマンドでは、クラスタ内のノード エージェントの認証情報を作成または更新します。
実行中の既存のクラスタでノード エージェントを有効にする
バージョン 1.33 以降の既存のクラスタでノード エージェントを有効にできます。
既存のクラスタでノード エージェントを有効にするには、次のコマンドを使用します。
./bmctl nodeagent enable \ --kubeconfig KUBECONFIG \ --cluster CLUSTER_NAME \ --namespace CLUSTER_NAMESPACE \ --ensure-status=true次のように置き換えます。
KUBECONFIG:ノード エージェントを有効にするクラスタの kubeconfig ファイルのパス。CLUSTER_NAME: ノード エージェントをデプロイするノードがあるクラスタの名前。CLUSTER_NAMESPACE: ターゲット クラスタとクラスタ認証情報の検索、クラスタ リソースの更新に使用するクラスタの 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
新しいクラスタをインストールする
ノード エージェントは、バージョン 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クラスタ構成ファイルのクラスタ メタデータ セクションに、ノード エージェントの有効化アノテーションを含めます。
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: ターゲット クラスタとクラスタ認証情報の検索、クラスタ リソースの更新に使用するクラスタの 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 コマンドでは、ノード上のノード エージェントの実行ステータスに関する情報を提供します。ターゲット ノードは、--nodes フラグを使用して直接指定する方法、--cluster フラグを使用してクラスタ構成ファイルで指定する方法、クラスタ カスタム リソースを参照する方法で指定できます。
クラスタ構成ファイルまたは --nodes フラグからノードを取得すると、システムはローカル ファイル システムから認証情報を取得します。ノードソースがクラスタ カスタム リソースの場合、システムはクラスタから認証情報を取得します。
次の優先順位でノード エージェントのポートが決定されます。
--portフラグ- Kubeconfig ファイル
- クラスタ構成ファイル
ノード エージェントのステータスを確認する
--cluster フラグのみを使用すると、クラスタ構成ファイルで指定された内容に基づいて、ノード エージェントのステータスを確認できます。
クラスタ構成ファイルに基づいてノード エージェントのステータスを確認するには、次のコマンドを使用します。
./bmctl nodeagent status \ --cluster CLUSTER_NAME \ --namespace CLUSTER_NAMESPACE次のように置き換えます。
CLUSTER_NAME: 確認するクラスタの名前。CLUSTER_NAMESPACE: ターゲット クラスタとクラスタ認証情報の検索、クラスタ リソースの更新に使用するクラスタの 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: ノード エージェントをデプロイするノードがあるクラスタの名前。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 フラグを組み合わせて使用すると、特定のクラスタノードのノード エージェントのステータスを確認できます。
特定のノードのノード エージェントのステータスを確認するには、次のコマンドを使用します。
./bmctl nodeagent status \ --cluster CLUSTER_NAME \ --nodes NODE_IP_ADDRESS_LIST次のように置き換えます。
CLUSTER_NAME: ノード エージェントをデプロイするノードがあるクラスタの名前。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 ユーザー権限
root 以外のユーザーは bmctl nodeagent コマンドを実行できます。これには、ユーザーがパスワードなしの sudo フルアクセス権限を持っているか、パスワードなしの sudo 明示的許可リストを持っている必要があります。
ノード エージェントのパスワードなしの 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 ファイルに追加されていることを確認します。それ以外の場合は、--enforce-host-key-verify=false フラグを使用して、デプロイ中のホストキーの検証（nodeagent
deploy）と認証情報のローテーション（nodeagent
rotate-credentials）を無効にします。
ノード エージェント ポートをカスタマイズする
ノード エージェントでは、ポートをカスタマイズできます。このカスタムポートは、デプロイ時に --port フラグを使用して指定します。これにより、設定が各ノードのノード エージェント構成に伝播されます。カスタマイズされたポートは、次の方法で説明するように、クライアントサイドの構成と一致している必要があります。
既存のクラスタの場合
実行中の既存のクラスタを更新するには、--port フラグを使用して新しいカスタムポートを指定します。この設定はクライアント（コントローラ）に伝播されます。
新しいクラスタの場合
新しいクラスタを作成するときに、次のアノテーションをクラスタ構成に追加して、ノード エージェントのカスタムポートを指定します。
kind: Cluster
metadata:
annotations:
baremetal.cluster.gke.io/node-agent-port: "10086"
ノード エージェントのバックアップ用のローカル ストレージ容量を増やす
ノード エージェント ノードのバックアップ ファイルを作成するには、管理ノードとすべてのターゲット ノードの /tmp ディレクトリに 12 GB の空き容量が必要です。ターゲット ノードの /tmp ディレクトリのサイズを変更できない場合は、ターゲット ノードのローカル ストレージ容量を変更するをご覧ください。管理ノードの /tmp ディレクトリのサイズを変更できない場合は、管理ノードのローカル ストレージ容量を変更するをご覧ください。
ターゲット ノードのローカル ストレージ容量を変更する
ターゲット ノードの /tmp パーティション サイズを変更できない場合は、systemd 環境のオーバーライドを適用して、一時フォルダを容量の大きいパーティションにリダイレクトできます。
次の内容を含む systemd オーバーライド ファイルを
/etc/systemd/system/nodeagentd.service.d/override.confに作成します。[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: ノード エージェントをデプロイするノードがあるクラスタの名前。KUBECONFIG: ノード エージェントを有効にするクラスタの kubeconfig ファイルのパス。
パフォーマンス
デプロイと有効化は 1 分以内に完了します。認証情報のローテーションのランタイムは、標準のデプロイと同程度か、それよりも高速です。