このドキュメントでは、新しいクラスタと既存のクラスタでノード エージェントの使用を有効にして、より安全なクラスタ オペレーションを実現する方法について説明します。バージョン 1.33 以降、ベアメタル用 Google Distributed Cloud では、クラスタ オペレーションに SSH 経由で Ansible を使用する方法から、ノード エージェントを使用するより安全なエージェント ベースのモデルに移行できます。ノード エージェントを使用してクラスタ オペレーションを管理することで、機密性の高い環境で顧客ノードへの SSH アクセスが必要になるというセキュリティ上の懸念に対処できます。新しいモデルでは、各ノードでノード エージェント バイナリが実行されます。ノード エージェントは、安全な gRPC チャネルを介してコントローラなどのクライアントと通信し、すべてのノード構成アクティビティを管理します。Google Distributed Cloud は、クラスタ コントローラとノード エージェントの間、および bmctl とノード エージェントの間で Mutual Transport Layer Security（mTLS）を適用し、gRPC 接続の認証と暗号化を行います。
bmctl nodeagent コマンドを使用すると、既存のクラスタを移行してノード エージェントを使用するプロセスが簡単かつ確実になります。このコマンドを使用すると、手作業が減り、ノード間の整合性が向上し、証明書の作成やローテーションなどの重要なタスクが自動化されます。bmctl コマンドは主に SSH 経由で動作します。これにより、クラスタ コントローラが異常な状態である場合や、標準の通信チャネルが十分に機能していない場合でも、管理者はエージェントをデプロイまたは再デプロイできます。
ノード エージェントと対応する bmctl nodeagent コマンドは、ベアメタル用 Google Distributed Cloud バージョン 1.33.0 以降をサポートしています。ノード エージェントは、バージョン 1.33 以降の既存のクラスタで有効にするか、バージョン 1.33 以降のクラスタの作成時に有効にできます。
このページは、基盤となる技術インフラストラクチャのライフサイクルを管理する管理者、アーキテクト、オペレーターを対象としています。 Google Cloud のコンテンツで使用されている一般的なロールとタスクの例の詳細については、一般的な GKE Enterprise ユーザーロールとタスクをご覧ください。
始める前に
クラスタをノード エージェント モードに移行する前に、すべてのクラスタノードが次の要件を満たしていることを確認します。
各ノードには、ノード エージェント専用のオープンポートがあります。デフォルトでは、ノード エージェントはポート 9192 を使用しますが、デプロイ時、有効化時、新しいクラスタのインストール時にこのポートを構成できます。詳細については、ノード エージェントのポートをカスタマイズするをご覧ください。
各ノードに containerd バージョン 1.7 以降がインストールされています。
ノード エージェント モードに移行する
ノード エージェント モードへの移行は、次の 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 \ --ensure-status=true次のように置き換えます。
KUBECONFIG:ノード エージェントを有効にするクラスタの kubeconfig ファイルのパス。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 \ --ssh-user USERNAME \ --ssh-key SSH_KEY_PATH次のように置き換えます。
KUBECONFIG:ノード エージェントを有効にするクラスタの kubeconfig ファイルのパス。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_NAMECLUSTER_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"
パフォーマンス
デプロイと有効化は 1 分以内に完了します。認証情報のローテーションのランタイムは、標準のデプロイと同程度か、それよりも高速です。