העברת אשכולות לשימוש בסוכן הצמתים

במאמר הזה מוסבר איך להתקין את Node Agent ולהעביר אליו אשכולות כדי לספק פעולות אשכול מאובטחות יותר. ‫Node Agent הוא מודל מאובטח יותר שמבוסס על סוכן, בהשוואה ל-Ansible over SSH לפעולות של אשכולות. הוא זמין בגרסאות 1.33 ואילך. כשמנהלים פעולות באשכול באמצעות Node Agent, אפשר לגשת לצמתים של לקוחות בסביבות רגישות בלי SSH.

קובץ הבינארי של Node Agent פועל בכל צומת. סוכן הצומת מתקשר עם לקוחות, כמו בקרים, דרך ערוץ gRPC מאובטח כדי לנהל את כל פעילויות ההגדרה של הצומת. ב-Google Distributed Cloud, אבטחת שכבת התעבורה (TLS) דו-כיוונית (mTLS) נאכפת בין בקר האשכול לבין סוכן הצומת, ובין bmctl לבין סוכן הצומת, לצורך אימות והצפנה של חיבורי gRPC.

אפשר להשתמש בפקודות bmctl nodeagent כדי לצמצם את העבודה הידנית, לשפר את העקביות בין הצמתים ולבצע אוטומציה של יצירת אישורים והחלפתם. הפקודות bmctl פועלות בעיקר באמצעות SSH, כך שאפשר לפרוס סוכנים גם אם הבקר של האשכול לא תקין או אם יש בעיות בערוצי התקשורת הרגילים שלו.

לפני שמתחילים

לפני שמעבירים אשכול למצב Node Agent, צריך לוודא שכל הצמתים באשכול עומדים בדרישות הבאות:

  • יציאה פתוחה שמוקדשת לסוכן הצומת. סוכן Node משתמש ביציאה 9192 כברירת מחדל. צריך להגדיר את הפורט הזה כשפורסים, מפעילים או מתקינים אשכול חדש. מידע נוסף זמין במאמר בנושא התאמה אישית של יציאת Node Agent.

  • גרסה 1.7 ואילך של Containerd.

  • נפח אחסון פנוי של 12GB בספרייה /tmp בצומת האדמין ובכל צומתי היעד. אם אי אפשר לשנות את הגודל של ספריית /tmp עבור צמתי היעד, אפשר לעיין במאמר הגדלת קיבולת האחסון המקומי לגיבויים של Node Agent.

מעבר למצב Node Agent

המעבר למצב Node Agent הוא תהליך דו-שלבי:

  1. פריסת Node Agent: פורסים את רכיב Node Agent בכל הצמתים באשכול.

  2. הפעלת מצב Node Agent:

    • במקרה של אשכול קיים, מפעילים את המצב באמצעות הפקודה bmctl nodeagent.
    • במקרה של אשכול חדש, מוסיפים את הערת ההפעלה ואת הנתיבים המתאימים של פרטי הכניסה לקובץ התצורה של האשכול לפני היצירה.

פריסת סוכן הצומת

הפקודה bmctl nodeagent deploy פורסת את שירות Node Agent בצומת יעד אחד או יותר באשכול שצוין באמצעות SSH. הפקודה הזו מתקינה או מתקינה מחדש את Node Agent. הוא מתחבר באמצעות SSH ומבצע את השלבים הנדרשים, כולל העברת קבצים בינאריים, יצירה והעברה של אישורים (אופציונלי) והגדרת שירות systemd. נדרשת גישת SSH והרשאות sudo בצמתי היעד.

יש כמה דרכים לציין צמתי יעד: ישירות באמצעות הדגל --nodes, באמצעות קובץ הגדרות של אשכול באמצעות הדגל --cluster, או באמצעות הפניה למשאב מותאם אישית של האשכול. מידע נוסף על פקודות ואפשרויות של Node Agent זמין במאמר bmctl command reference.

פריסה בסביבה חדשה

בפריסות ראשוניות, מורידים את הקובץ הבינארי nodeagentd ויוצרים רשויות אישורים (CA) חדשות. הפקודה הבאה מאחזרת את רשימת הצמתים מקובץ התצורה של האשכול. הדגל --sa-key מספק את פרטי הכניסה הנדרשים להורדת הקובץ הבינארי nodeagentd מקטגוריית Cloud Storage.

  • כדי לפרוס את 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: שם האשכול שרוצים לפרוס את Node Agent בצמתים שלו.

    • ‫USERNAME: שם המשתמש שעבורו מוגדרת גישת SSH לצמתים. כברירת מחדל, פרוטוקול SSH מוגדר ל-root, אבל אם הגדרתם משתמש לכניסה, צריך להשתמש בשם המשתמש הזה.

    • ‫SSH_KEY_PATH: הנתיב של קובץ המפתח הפרטי של SSH.

    • ‫SERVICE_ACCOUNT_KEY_PATH: הנתיב של קובץ המפתח של חשבון השירות עם הרשאות לשליפת תמונות ממאגר. כברירת מחדל, זהו קובץ מפתח JSON של חשבון השירות anthos-baremetal-gcr.

    פלט הפקודה אמור להיראות כך:

    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

שדרוגים של Node Agent לא תלויים בשדרוגים של אשכולות. כדי לשדרג את Node Agent, משתמשים בפקודה bmctl nodeagent deploy ומגדירים את --pull-binaries לערך true. כשמשדרגים את Node Agent, מגדירים את --generate-ca-creds ל-false כדי להשתמש ב-CA קיימים במקום ליצור אותם מחדש. כדי ליצור מחדש רשויות אישורים, צריך לעדכן את פרטי הכניסה המתאימים של האשכול. התהליך הזה שמור לרוטציה של פרטי הכניסה. הפלט דומה לפריסה חדשה, אבל בלי היומנים שנוצרו על ידי רשות האישורים.

שדרוג של Node Agent מפעיל מחדש את התהליך של Node Agent, מה שיכול לשבש משימות שפועלות. למרות שרוב העבודות משוחזרות באמצעות מנגנוני ניסיון חוזר, כדי לצמצם את הסיכוי להפרעות, כדאי לפעול לפי השלבים הבאים:

  1. מוודאים שלא מתבצע שדרוג של אשכול או פעילויות אחרות של הגדרה אחרי ההתקנה.

  2. מוודאים שהאשכול במצב פעיל.

  3. מפעילים את השדרוג של 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: שם האשכול שרוצים לפרוס את Node Agent בצמתים שלו.

    • ‫USERNAME: שם המשתמש שעבורו מוגדרת גישת SSH לצמתים. כברירת מחדל, פרוטוקול SSH מוגדר ל-root, אבל אם הגדרתם משתמש לכניסה, צריך להשתמש בשם המשתמש הזה.

    • ‫SSH_KEY_PATH: הנתיב של קובץ המפתח הפרטי של SSH.

    • ‫SERVICE_ACCOUNT_KEY_PATH: הנתיב של קובץ המפתח של חשבון השירות עם הרשאות לשליפת תמונות ממאגר. כברירת מחדל, זהו קובץ מפתח JSON של חשבון השירות anthos-baremetal-gcr.

    פלט הפקודה אמור להיראות כך:

    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: שם האשכול שרוצים לפרוס את Node Agent בצמתים שלו.

    • ‫USERNAME: שם המשתמש שעבורו מוגדרת גישת SSH לצמתים. כברירת מחדל, פרוטוקול SSH מוגדר ל-root, אבל אם הגדרתם משתמש לכניסה, צריך להשתמש בשם המשתמש הזה.

    • ‫SSH_KEY_PATH: הנתיב של קובץ המפתח הפרטי של SSH.

    • ‫SERVICE_ACCOUNT_KEY_PATH: הנתיב של קובץ המפתח של חשבון השירות עם הרשאות לשליפת תמונות ממאגר. כברירת מחדל, זהו קובץ מפתח JSON של חשבון השירות anthos-baremetal-gcr.

    • ‫NODE_IP_ADDRESS_LIST: רשימה מופרדת בפסיקים של כתובות ה-IP של הצמתים שבהם אתם פורסים את Node Agent.

    פלט הפקודה אמור להיראות כך:

    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 מופיעה במאמר nodeagent deploy בחומר העזר בנושא הפקודה bmctl.

הפעלת סוכן הצמתים

הפקודה enable מפעילה את מצב Node Agent באשכול קיים שפועל אחרי שפורסים את Node Agent בכל הצמתים באשכול. הפקודה הזו גם יוצרת או מעדכנת את פרטי הכניסה של Node Agent באשכול.

הפעלת Node Agent באשכול קיים שפועל

אפשר להפעיל את Node Agent באשכולות קיימים בגרסה 1.33 ואילך.

  • כדי להפעיל את Node Agent באשכול קיים, משתמשים בפקודה הבאה:

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

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫KUBECONFIG: הנתיב של קובץ ה-kubeconfig של האשכול שבו מפעילים את Node Agent.

    • ‫CLUSTER_NAME: שם האשכול שרוצים לפרוס את Node Agent בצמתים שלו.

    • ‫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 כשיוצרים אשכולות מגרסה 1.33 ואילך.

כדי להשתמש ב-Node Agent עבור אשכול חדש:

  1. במקרה של אשכול אדמין חדש, מוסיפים את נתיבי הקבצים של פרטי הכניסה לחלק העליון של קובץ ההגדרות של אשכול האדמין:

    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. כוללים את הערת ההפעלה של Node Agent בקטע המטא-נתונים של האשכול בקובץ התצורה של האשכול:

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

  3. פועלים לפי ההוראות הרגילות ליצירת אשכול.

רשימה מלאה של אפשרויות הפקודה bmctl nodeagent enable מופיעה במאמר nodeagent enable בחומר העזר של הפקודה bmctl.

עדכון של פרטי הכניסה

הפקודה rotate-credentials מבצעת רוטציה של פרטי הכניסה של Node Agent בצמתים ובאשכול. האפשרות הזו כוללת את היכולת לבצע רוטציה של רשויות האישורים (CA). הדגל --generate-ca-creds מכוון את הפקודה ליצור מחדש את ה-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 של האשכול שבו מפעילים את Node Agent.

    • ‫CLUSTER_NAME: שם האשכול שרוצים לפרוס את Node Agent בצמתים שלו.

    • ‫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 מופיעה במאמר nodeagent rotate-credentials בקטע בנושא הפקודה bmctl.

בדיקת הסטטוס

הפקודה status מספקת מידע על סטטוס הפעולה של Node Agent בצמתים. אפשר לציין צמתי יעד ישירות באמצעות הדגל --nodes, באמצעות קובץ הגדרות של אשכול באמצעות הדגל --cluster, או באמצעות הפניה למשאב המותאם אישית של האשכול.

כשמקבלים צמתים מקובץ תצורה של אשכול או מהדגל --nodes, המערכת מאחזרת פרטי כניסה ממערכת הקבצים המקומית. אם מקור הצומת הוא משאב מותאם אישית של אשכול, המערכת מאחזרת את פרטי הכניסה מהאשכול.

סדר העדיפויות הבא קובע את היציאה של Node Agent:

  1. --port דגל
  2. קובץ Kubeconfig
  3. קובץ תצורה של אשכול

אימות הסטטוס של Node Agent

אם משתמשים רק בדגל --cluster, אפשר לבדוק את הסטטוס של Node Agent על סמך מה שצוין בקובץ ההגדרות של האשכול.

  • כדי לבדוק את הסטטוס של Node Agent על סמך קובץ התצורה של האשכול, משתמשים בפקודה הבאה:

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

אימות הסטטוס של Node Agent מהאשכול

אפשר להשתמש בדגל --cluster יחד עם הדגל --kubeconfig כדי לבדוק את הסטטוס של Node Agent על סמך משאב מותאם אישית של אשכול.

  • כדי לבדוק את הסטטוס של Node Agent על סמך המשאב המותאם אישית של Cluster, משתמשים בפקודה הבאה:

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

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫CLUSTER_NAME: שם האשכול שרוצים לפרוס את Node Agent בצמתים שלו.

    • ‫KUBECONFIG: הנתיב של קובץ ה-kubeconfig של האשכול שבו מפעילים את Node Agent.

    פלט הפקודה אמור להיראות כך:

    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

אימות הסטטוס של Node Agent מהצמתים

אפשר להשתמש בדגל --cluster יחד עם הדגל --nodes כדי לבדוק את הסטטוס של Node Agent בצמתים ספציפיים של אשכול.

  • כדי לבדוק את הסטטוס של Node Agent עבור צמתים ספציפיים, משתמשים בפקודה הבאה:

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

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫CLUSTER_NAME: שם האשכול שרוצים לפרוס את Node Agent בצמתים שלו.

    • ‫NODE_IP_ADDRESS_LIST: רשימה מופרדת בפסיקים של כתובות ה-IP של הצמתים שבהם אתם פורסים את Node Agent.

    פלט הפקודה אמור להיראות כך:

    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 מופיעה במאמר nodeagent status בחומר העזר של הפקודה bmctl.

הרשאות משתמש SSH

משתמשים שהם לא משתמשים מסוג root יכולים להריץ את הפקודה bmctl nodeagent. כדי לעשות את זה, המשתמש צריך הרשאות sudo מלאות ללא סיסמה או רשימת הרשאות sudo מפורשת ללא סיסמה.

הרשימה המפורשת של הרשאות sudo ללא סיסמה עבור Node Agent כוללת את ההרשאות הבאות:

# 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

הסוכן של Node מאפשר התאמה אישית של היציאה. מציינים את היציאה המותאמת אישית הזו במהלך הפריסה באמצעות הדגל --port. ההגדרה הזו מועברת להגדרות של NodeAgent בכל צומת. היציאה המותאמת אישית צריכה להיות זהה להגדרה בצד הלקוח, כמו שמתואר בשיטות הבאות.

לגבי אשכולות קיימים

כדי לעדכן אשכול קיים שפועל, משתמשים בדגל --port כדי לציין את היציאה המותאמת אישית החדשה. ההגדרה הזו מועברת ללקוחות (בקרים).

לצבי אשכולות חדשים

כשיוצרים אשכול חדש, מוסיפים את ההערה הבאה להגדרת האשכול כדי לציין יציאה מותאמת אישית לסוכן הצומת:

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

הגדלת נפח האחסון המקומי לגיבויים של Node Agent

כדי ליצור קובץ גיבוי לצמתי Node Agent, צריך לפנות 12 GB בספרייה /tmp בצומת האדמין ובכל צמתי היעד. אם אי אפשר לשנות את הגודל של ספריית /tmp עבור צמתי היעד, אפשר לעיין במאמר בנושא שינוי קיבולת האחסון המקומי של צמתי היעד. אם אי אפשר לשנות את הגודל של ספריית /tmp בצומת האדמין, אפשר לעיין במאמר שינוי קיבולת האחסון המקומי בצומת אדמין.

שינוי קיבולת האחסון המקומי של צמתי היעד

אם אי אפשר לשנות את /tmp גודל המחיצה של צומת היעד, אפשר להפנות מחדש את התיקייה הזמנית למחיצה עם קיבולת גדולה יותר על ידי החלת שינוי בסביבת systemd:

  1. יוצרים קובץ systemd override בנתיב /etc/systemd/system/nodeagentd.service.d/override.conf שמכיל את השורות הבאות:

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

  2. מחילים את ההגדרה ומפעילים מחדש את השירות:

    sudo systemctl daemon-reload
sudo systemctl restart nodeagentd

שינוי קיבולת האחסון המקומי בצומת אדמין

אם למחשב האדמין שבו פועל bmctl יש מקום מוגבל במחיצה /tmp partition, צריך להגדיר את המשתנה TMPDIR באופן מקומי כשמתחילים גיבוי:

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

מחליפים את מה שכתוב בשדות הבאים:

  • ‫CLUSTER_NAME: שם האשכול שרוצים לפרוס את Node Agent בצמתים שלו.
  • ‫KUBECONFIG: הנתיב של קובץ ה-kubeconfig של האשכול שבו מפעילים את Node Agent.

ביצועים

הפריסה וההפעלה מסתיימות תוך פחות מדקה. הזמן שנדרש לרוטציה של פרטי הכניסה בזמן הריצה דומה לזמן שנדרש לפריסה רגילה, או מהיר יותר.