Memigrasikan cluster untuk menggunakan Agen Node

Dokumen ini menjelaskan cara menginstal dan memigrasikan cluster ke Agen Node untuk menyediakan operasi cluster yang lebih aman. Agen Node adalah model berbasis agen yang lebih aman daripada Ansible melalui SSH untuk operasi cluster, yang tersedia untuk versi 1.33 dan yang lebih baru. Saat mengelola operasi cluster dengan Agen Node, Anda dapat mengakses node pelanggan di lingkungan sensitif tanpa SSH.

Biner Agen Node berjalan di setiap node. Agen Node berkomunikasi dengan klien, seperti pengontrol, melalui saluran gRPC yang aman untuk mengelola semua aktivitas konfigurasi node. Google Distributed Cloud menerapkan mutual Transport Layer Security (mTLS) antara pengontrol cluster dan Node Agent serta antara bmctl dan Node Agent untuk autentikasi dan enkripsi koneksi gRPC.

Gunakan perintah bmctl nodeagent untuk mengurangi upaya manual, meningkatkan konsistensi di seluruh node, dan mengotomatiskan pembuatan dan rotasi sertifikat. Perintah bmctl beroperasi terutama melalui SSH sehingga Anda dapat men-deploy agen meskipun pengontrol cluster tidak berfungsi atau saluran komunikasi standarnya terganggu.

Sebelum memulai

Pastikan semua node cluster memenuhi persyaratan berikut sebelum memigrasikan cluster ke mode Agen Node:

  • Port terbuka yang dikhususkan untuk Agen Node. Node Agent menggunakan port 9192 secara default. Konfigurasi port ini saat Anda men-deploy, mengaktifkan, atau menginstal cluster baru. Untuk mengetahui informasi selengkapnya, lihat Menyesuaikan port Agen Node.

  • Containerd versi 1.7 atau yang lebih tinggi.

  • Ruang kosong sebesar 12 GB di direktori /tmp pada node admin dan semua node target. Jika Anda tidak dapat mengubah ukuran direktori /tmp untuk node target, lihat Meningkatkan kapasitas penyimpanan lokal untuk cadangan Agen Node.

Bermigrasi ke mode Agen Node

Migrasi ke mode Agen Node adalah proses dua langkah:

  1. Deploy Agen Node: Deploy komponen Agen Node ke semua node dalam cluster.

  2. Mengaktifkan mode Agen Node:

    • Untuk cluster yang sudah ada, aktifkan mode menggunakan perintah bmctl nodeagent.
    • Untuk cluster baru, tambahkan anotasi pengaktifan dan jalur kredensial yang sesuai ke file konfigurasi cluster sebelum pembuatan.

Men-deploy Agen Node

Perintah bmctl nodeagent deploy men-deploy layanan Agen Node ke satu atau beberapa node target dalam cluster yang ditentukan menggunakan SSH. Perintah ini menginstal atau menginstal ulang Agen Node. Skrip ini terhubung melalui SSH dan melakukan langkah-langkah yang diperlukan, termasuk mentransfer biner, membuat dan mentransfer sertifikat (opsional), serta menyiapkan layanan systemd. Alat ini memerlukan akses SSH dan hak istimewa sudo pada node target.

Anda dapat menentukan node target dengan beberapa cara: langsung melalui flag --nodes, melalui file konfigurasi cluster menggunakan flag --cluster, atau dengan mereferensikan resource kustom cluster. Untuk mengetahui informasi selengkapnya tentang perintah dan opsi Agen Node, lihat referensi perintah bmctl.

Men-deploy di lingkungan baru

Untuk deployment awal, download biner nodeagentd dan buat Certificate Authority (CA) baru. Perintah berikut mengambil daftar node dari file konfigurasi cluster. Flag --sa-key memberikan kredensial yang diperlukan untuk mendownload biner nodeagentd dari bucket Cloud Storage.

  • Untuk men-deploy Node Agent pertama kali di cluster baru, gunakan perintah berikut:

    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

    Ganti kode berikut:

    • CLUSTER_NAME: nama cluster tempat Anda ingin men-deploy Agen Node.

    • USERNAME: nama pengguna yang akses SSH-nya ke node dikonfigurasi. Secara default, SSH dikonfigurasi untuk root, tetapi jika Anda menetapkan pengguna login, gunakan nama pengguna tersebut.

    • SSH_KEY_PATH: jalur file kunci pribadi SSH.

    • SERVICE_ACCOUNT_KEY_PATH: jalur file kunci akun layanan dengan izin untuk menarik image registry. Secara default, ini adalah file kunci JSON untuk akun layanan anthos-baremetal-gcr.

    Output perintah akan terlihat seperti contoh berikut:

    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
===============================================

Mengupgrade versi Agen Node

Upgrade Node Agent terpisah dari upgrade cluster. Untuk mengupgrade Node Agent, gunakan perintah bmctl nodeagent deploy dan tetapkan --pull-binaries ke true. Saat mengupgrade Agen Node, tetapkan --generate-ca-creds ke false untuk menggunakan CA yang ada, bukan membuatnya ulang. Membuat ulang CA memerlukan pembaruan kredensial cluster yang sesuai, sebuah proses yang disediakan untuk rotasi kredensial. Output-nya menyerupai deployment baru, tetapi tanpa log yang dihasilkan CA.

Mengupgrade Agen Node akan memulai ulang proses Agen Node, yang dapat mengganggu tugas yang sedang berjalan. Meskipun sebagian besar tugas dipulihkan melalui mekanisme percobaan ulang, untuk meminimalkan potensi gangguan, gunakan langkah-langkah berikut:

  1. Pastikan tidak ada upgrade cluster atau aktivitas konfigurasi pasca-penginstalan lainnya yang sedang berlangsung.

  2. Verifikasi bahwa cluster dalam status berjalan.

  3. Mulai upgrade Agen Node:

    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

    Ganti kode berikut:

    • CLUSTER_NAME: nama cluster tempat Anda ingin men-deploy Agen Node.

    • USERNAME: nama pengguna yang akses SSH-nya ke node dikonfigurasi. Secara default, SSH dikonfigurasi untuk root, tetapi jika Anda menetapkan pengguna login, gunakan nama pengguna tersebut.

    • SSH_KEY_PATH: jalur file kunci pribadi SSH.

    • SERVICE_ACCOUNT_KEY_PATH: jalur file kunci akun layanan dengan izin untuk menarik image registry. Secara default, ini adalah file kunci JSON untuk akun layanan anthos-baremetal-gcr.

    Output perintah akan terlihat seperti contoh berikut:

    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)...

Men-deploy atau men-deploy ulang ke node tertentu

Jika Anda menambahkan atau memulihkan node cluster, Anda dapat menargetkan node tertentu untuk deployment Agen Node, alih-alih men-deploy-nya ke semua node dalam cluster. Anda menggunakan flag --nodes untuk menentukan node yang akan di-deploy.

  • Untuk men-deploy Agen Node ke node tertentu, gunakan perintah berikut:

    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

    Ganti kode berikut:

    • CLUSTER_NAME: nama cluster tempat Anda ingin men-deploy Agen Node.

    • USERNAME: nama pengguna yang dikonfigurasi akses SSH-nya ke node. Secara default, SSH dikonfigurasi untuk root, tetapi jika Anda menetapkan pengguna login, gunakan nama pengguna tersebut.

    • SSH_KEY_PATH: jalur file kunci pribadi SSH.

    • SERVICE_ACCOUNT_KEY_PATH: jalur file kunci akun layanan dengan izin untuk menarik image registry. Secara default, ini adalah file kunci JSON untuk akun layanan anthos-baremetal-gcr.

    • NODE_IP_ADDRESS_LIST: daftar alamat IP yang dipisahkan koma dari node tempat Anda men-deploy Agen Node.

    Output perintah akan terlihat seperti contoh berikut:

    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]:

Untuk mengetahui daftar lengkap opsi perintah bmctl nodeagent deploy, lihat nodeagent deploy di referensi perintah bmctl.

Aktifkan Agen Node

Perintah enable mengaktifkan mode Agen Node dalam cluster yang sedang berjalan setelah Anda men-deploy Agen Node ke semua node dalam cluster. Perintah ini juga membuat atau memperbarui kredensial Agen Node dalam cluster.

Mengaktifkan Agen Node untuk cluster yang sudah berjalan

Anda dapat mengaktifkan Agen Node di cluster versi 1.33 dan yang lebih baru yang sudah ada.

Untuk mengaktifkan Node Agent di cluster yang ada, lakukan langkah berikut:

  1. Aktifkan Agen Node di cluster:

    ./bmctl nodeagent enable \
    --kubeconfig KUBECONFIG \
    --cluster CLUSTER_NAME \
    --namespace CLUSTER_NAMESPACE \
    --ensure-status=true

    Ganti kode berikut:

    • KUBECONFIG: jalur file kubeconfig untuk cluster yang Anda aktifkan Node Agent-nya.

    • CLUSTER_NAME: nama cluster tempat Anda ingin men-deploy Agen Node.

    • CLUSTER_NAMESPACE: namespace cluster yang akan digunakan untuk menemukan cluster target dan kredensial cluster serta memperbarui resource cluster. Nilai defaultnya adalah cluster-<CLUSTER-NAME>.

    Output perintah akan terlihat seperti contoh berikut:

    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

  2. Sertakan anotasi pengaktifan Agen Node di bagian metadata cluster pada file konfigurasi cluster:

    kind: Cluster
metadata:
  annotations:
    baremetal.cluster.gke.io/enable-node-agent: ""

Menginstal cluster baru

Anda dapat menggunakan Node Agent saat membuat cluster versi 1.33 dan yang lebih baru.

Untuk menggunakan Node Agent di cluster baru, lakukan hal berikut:

  1. Untuk cluster admin baru, tambahkan jalur file kredensial berikut ke bagian atas file konfigurasi cluster admin:

    nodeAgentServerCACertificatePath: bmctl-workspace/demo-cluster/nodeagent-creds/server_ca_cert.pem
nodeAgentServerCAPrivateKeyPath: bmctl-workspace/demo-cluster/nodeagent-creds/server_ca_key.pem
nodeAgentClientCACertificatePath: bmctl-workspace/demo-cluster/nodeagent-creds/client_ca_cert.pem
nodeAgentClientCAPrivateKeyPath: bmctl-workspace/demo-cluster/nodeagent-creds/client_ca_key.pem
nodeAgentClientCertificatePath: bmctl-workspace/demo-cluster/nodeagent-creds/client_cert.pem
nodeAgentClientPrivateKeyPath: bmctl-workspace/demo-cluster/nodeagent-creds/client_key.pem

  2. Sertakan anotasi pengaktifan Agen Node di bagian metadata cluster pada file konfigurasi cluster:

    kind: Cluster
metadata:
  annotations:
    baremetal.cluster.gke.io/enable-node-agent: ""

  3. Ikuti petunjuk standar untuk membuat cluster.

Untuk mengetahui daftar lengkap opsi perintah bmctl nodeagent enable, lihat nodeagent enable dalam referensi perintah bmctl.

Merotasi kredensial

Perintah rotate-credentials merotasi kredensial Agen Node di kedua node dan dalam cluster. Hal ini mencakup kemampuan untuk mengganti Certificate Authority (CA). Flag --generate-ca-creds mengarahkan perintah untuk membuat ulang CA dan menggunakan CA yang baru dibuat ini untuk menandatangani sertifikat bagi server (node) dan klien (pengontrol).

  • Untuk merotasi kredensial serta membuat ulang dan menggunakan CA baru, gunakan perintah berikut:

    bmctl nodeagent rotate-credentials \
    --kubeconfig KUBECONFIG \
    --generate-ca-creds=true \
    --cluster CLUSTER_NAME \
    --namespace CLUSTER_NAMESPACE \
    --ssh-user USERNAME \
    --ssh-key SSH_KEY_PATH

    Ganti kode berikut:

    • KUBECONFIG: jalur file kubeconfig untuk cluster yang Anda aktifkan Node Agent-nya.

    • CLUSTER_NAME: nama cluster tempat Anda ingin men-deploy Agen Node.

    • CLUSTER_NAMESPACE: namespace cluster yang akan digunakan untuk menemukan cluster target dan kredensial cluster serta memperbarui resource cluster. Nilai defaultnya adalah cluster-<CLUSTER-NAME>.

    • USERNAME: nama pengguna yang akses SSH-nya ke node dikonfigurasi. Secara default, SSH dikonfigurasi untuk root, tetapi jika Anda menetapkan pengguna login, gunakan nama pengguna tersebut.

    • SSH_KEY_PATH: jalur file kunci pribadi SSH.

    Output perintah akan terlihat seperti contoh berikut:

    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
===============================================

Untuk mengetahui daftar lengkap opsi perintah bmctl nodeagent rotate-credentials, lihat nodeagent rotate-credentials dalam referensi perintah bmctl.

Periksa status

Perintah status memberikan informasi tentang status berjalan Agen Node di node. Anda dapat menentukan node target secara langsung melalui flag --nodes, melalui file konfigurasi cluster menggunakan flag --cluster, atau dengan mereferensikan resource kustom cluster.

Saat Anda mendapatkan node dari file konfigurasi cluster atau flag --nodes, sistem akan mengambil kredensial dari sistem file lokal. Jika sumber node adalah resource kustom cluster, sistem akan mengambil kredensial dari cluster.

Urutan prioritas berikut menentukan port Agen Node:

  1. Flag --port
  2. File kubeconfig
  3. File konfigurasi cluster

Memverifikasi status Agen Node

Hanya dengan menggunakan tanda --cluster, Anda dapat memeriksa status Agen Node berdasarkan apa yang ditentukan dalam file konfigurasi cluster.

  • Untuk memeriksa status Agen Node berdasarkan file konfigurasi cluster, gunakan perintah berikut:

    ./bmctl nodeagent status \
    --cluster CLUSTER_NAME \
    --namespace CLUSTER_NAMESPACE

    Ganti kode berikut:

    • CLUSTER_NAME: nama cluster yang Anda periksa.

    • CLUSTER_NAMESPACE: namespace cluster yang akan digunakan untuk menemukan cluster target dan kredensial cluster serta memperbarui resource cluster. Nilai defaultnya adalah cluster-<CLUSTER-NAME>.

    Output perintah akan terlihat seperti contoh berikut:

    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

Memverifikasi status Agen Node dari cluster

Dengan menggunakan flag --cluster bersama dengan flag --kubeconfig, Anda dapat memeriksa status Node Agent berdasarkan resource kustom Cluster.

  • Untuk memeriksa status Agen Node berdasarkan resource kustom Cluster, gunakan perintah berikut:

    ./bmctl nodeagent status \
    --cluster CLUSTER_NAME \
    --kubeconfig KUBECONFIG

    Ganti kode berikut:

    • CLUSTER_NAME: nama cluster tempat Anda ingin men-deploy Agen Node.

    • KUBECONFIG: jalur file kubeconfig untuk cluster tempat Anda mengaktifkan Agen Node.

    Output perintah akan terlihat seperti contoh berikut:

    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

Memverifikasi status Agen Node dari node

Dengan menggunakan flag --cluster bersama dengan flag --nodes, Anda dapat memeriksa status Agen Node untuk node cluster tertentu.

  • Untuk memeriksa status Agen Node untuk node tertentu, gunakan perintah berikut:

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

    Ganti kode berikut:

    • CLUSTER_NAME: nama cluster tempat Anda ingin men-deploy Agen Node.

    • NODE_IP_ADDRESS_LIST: daftar alamat IP node yang dipisahkan koma tempat Anda men-deploy Agen Node.

    Output perintah akan terlihat seperti contoh berikut:

    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

Untuk mengetahui daftar lengkap opsi perintah bmctl nodeagent status, lihat nodeagent status dalam referensi perintah bmctl.

Izin pengguna SSH

Pengguna non-root dapat menjalankan perintah bmctl nodeagent. Hal ini mengharuskan pengguna memiliki izin sudo tanpa sandi penuh atau daftar yang diizinkan sudo tanpa sandi eksplisit.

Daftar izin sudo eksplisit tanpa sandi untuk Agen Node memiliki izin berikut:

# 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_*/*

Verifikasi kunci host SSH

Pastikan semua node ditambahkan ke file known_hosts di workstation admin. Atau, nonaktifkan verifikasi kunci host selama deployment (nodeagent deploy) dan rotasi kredensial (nodeagent rotate-credentials) menggunakan flag --enforce-host-key-verify=false.

Menyesuaikan port Agen Node

Agen Node memungkinkan penyesuaian port. Tentukan port kustom ini selama deployment menggunakan flag --port. Tindakan ini akan menerapkan setelan ke konfigurasi Agen Node di setiap node. Port yang disesuaikan harus sesuai dengan konfigurasi sisi klien, seperti yang dijelaskan dalam metode berikut.

Untuk cluster yang sudah ada

Untuk mengupdate cluster yang sudah ada dan sedang berjalan, gunakan flag --port untuk menentukan port kustom baru. Setelan ini disebarkan ke klien (pengontrol).

Untuk cluster baru

Saat membuat cluster baru, tambahkan anotasi berikut ke konfigurasi cluster untuk menentukan port kustom bagi Node Agent:

kind: Cluster
metadata:
  annotations:
    baremetal.cluster.gke.io/node-agent-port: "10086"

Meningkatkan kapasitas penyimpanan lokal untuk pencadangan Agen Node

Untuk membuat file cadangan untuk node Agen Node, Anda harus memiliki ruang kosong sebesar 12 GB di direktori /tmp pada node admin dan semua node target. Jika Anda tidak dapat mengubah ukuran direktori /tmp untuk node target, lihat Mengubah kapasitas penyimpanan lokal untuk node target. Jika Anda tidak dapat mengubah ukuran direktori /tmp untuk node admin, lihat Mengubah kapasitas penyimpanan lokal untuk node admin.

Mengubah kapasitas penyimpanan lokal untuk node target

Jika Anda tidak dapat mengubah ukuran partisi /tmp node target, Anda dapat mengalihkan folder sementara ke partisi dengan kapasitas lebih besar dengan menerapkan penggantian lingkungan systemd:

  1. Buat file penggantian systemd di /etc/systemd/system/nodeagentd.service.d/override.conf yang berisi:

    [Service]
Environment="TMPDIR=/var/tmp"

  2. Terapkan konfigurasi dan mulai ulang layanan:

    sudo systemctl daemon-reload
sudo systemctl restart nodeagentd

Mengubah kapasitas penyimpanan lokal untuk node admin

Jika workstation admin yang menjalankan bmctl memiliki ruang terbatas untuk partisi /tmp, tetapkan variabel TMPDIR secara lokal saat Anda memulai pencadangan:

  TMPDIR=/var/tmp bmctl backup cluster -c CLUSTER_NAME --kubeconfig KUBECONFIG

Ganti kode berikut:

  • CLUSTER_NAME: nama cluster yang nodenya ingin Anda gunakan untuk men-deploy Node Agent.
  • KUBECONFIG: jalur file kubeconfig untuk cluster tempat Anda mengaktifkan Agen Node.

Performa

Deployment dan pengaktifan selesai dalam waktu kurang dari satu menit. Waktu proses rotasi kredensial sebanding dengan, atau lebih cepat daripada, deployment standar.