פריסת חבילות לכלל המכשירים בארגון

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

FleetPackage הוא API הצהרתי לפריסת מניפסטים גולמיים של Kubernetes למערך של אשכולות. כל משאבי Kubernetes שרוצים לפרוס באמצעות חבילת Fleet צריכים להיות כבר מוכנים (WET).

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

  1. צריך ליצור מאגר Git או לוודא שיש לכם גישה למאגר Git עם משאבי Kubernetes שרוצים לפרוס בצי.

  2. מתקינים ומפעילים את Google Cloud CLI, שמספק את הפקודות gcloud ו-nomos. אם אתם משתמשים ב-Cloud Shell, ‏ Google Cloud CLI מותקן מראש. אם התקנתם בעבר את Google Cloud CLI, תוכלו להריץ את הפקודה gcloud components update כדי לקבל את הגרסה העדכנית.

  3. מפעילים את סנכרון תצורות (anthosconfigmanagement) API ואת ConfigDelivery API:

    gcloud services enable anthosconfigmanagement.googleapis.com configdelivery.googleapis.com
    
  4. הגדרת מיקום ברירת מחדל:

    gcloud config set config_delivery/location us-central1
    
  5. כדי להגדיר פרויקט ברירת מחדל:

    gcloud config set project PROJECT_ID
    

    מחליפים את PROJECT_ID במזהה הפרויקט המארח של הצי.

  6. מוודאים שהאשכולות רשומים ב-Fleet.

  7. משתמשים במאגרי Cloud Build כדי ליצור חיבור לספק נתמך כמו GitHub או GitLab. כשמשתמשים בחבילת Fleet, צריך להגדיר את Cloud Build רק פעם אחת לכל מאגר שרוצים לסנכרן.

בדיקת הדרישות לאשכול

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

הכנת הסביבה

כדי להכין את הסביבה לחבילות של סנכרון תצורות fleet, צריך לתת את תפקידי ה-IAM הנדרשים למשתמש שרושם את האשכול.

התקנת סנכרון תצורות

אפשר להתקין את סנכרון תצורות באמצעות מסוף Cloud de Confiance או Google Cloud CLI.

המסוף

כדי להתקין את סנכרון תצורות, צריך לרשום את כל האשכולות בצי. כשמתקינים את סנכרון תצורות במסוף Cloud de Confiance , בחירה של אשכולות בודדים גורמת לרישום אוטומטי של האשכולות האלה בצי.

  1. נכנסים לדף Config במסוף Cloud de Confiance , בקטע Features.

    מעבר אל Config

  2. לוחצים על Install Config Sync (התקנת סנכרון תצורות).

  3. בקטע Installation options (אפשרויות התקנה), בוחרים באפשרות Install Config Sync on entire fleet (recommended) (התקנת סנכרון תצורות בכל הצי (מומלץ)).

  4. לוחצים על Install Config Sync (התקנת סנכרון תצורות). בכרטיסייה הגדרות, אחרי כמה דקות, אמור להופיע הסטטוס מופעל בעמודה סטטוס עבור האשכולות בצי.

gcloud

  1. הפעלת התכונה ConfigManagement לצי הרכבים:

    gcloud beta container fleet config-management enable
    
  2. כדי להפעיל את סנכרון תצורות, יוצרים קובץ בשם apply-spec.yaml עם התוכן הבא:

    applySpecVersion: 1
    spec:
      configSync:
        enabled: true
    
  3. מחילים את הקובץ apply-spec.yaml:

    gcloud beta container fleet config-management apply \
        --membership=MEMBERSHIP_NAME \
        --config=apply-spec.yaml
    

    מחליפים את MEMBERSHIP_NAME בשם החברות ב-Fleet שבחרתם כשנרשמתם לאשכול. כדי למצוא את שם החברות, מריצים את הפקודה gcloud container fleet memberships list.

יצירת חשבון שירות ל-Cloud Build

חבילות Fleet משתמשות ב-Cloud Build כדי לאחזר את משאבי Kubernetes ממאגר Git שלכם ולפרוס אותם באשכולות. ב-Cloud Build נדרש חשבון שירות עם הרשאות להפעלת המשימה הזו. כדי ליצור את חשבון השירות ולהעניק את ההרשאות הנדרשות, מבצעים את הפעולות הבאות:

  1. יוצרים את חשבון השירות:

    gcloud iam service-accounts create "SERVICE_ACCOUNT_NAME"
    

    מחליפים את הערך SERVICE_ACCOUNT_NAME בשם שרוצים לתת לחשבון השירות. השם צריך להיות מזהה אלפאנומרי באורך של 6 עד 30 תווים, למשל my-service-account. אחרי שיוצרים חשבון שירות, אי אפשר לשנות את השם שלו.

  2. מוסיפים קישור למדיניות IAM עבור התפקיד Resource Bundle Publisher (פרסום חבילות משאבים):

    gcloud projects add-iam-policy-binding PROJECT_ID \
       --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.s3ns.iam.gserviceaccount.com" \
       --role='roles/configdelivery.resourceBundlePublisher'
    

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

  3. מוסיפים קישור למדיניות IAM לתפקיד Logs Writer:

    gcloud projects add-iam-policy-binding PROJECT_ID \
       --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.s3ns.iam.gserviceaccount.com" \
       --role='roles/logging.logWriter'
    

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

  4. מוסיפים קישור למדיניות IAM לתפקיד Artifact Registry Writer:

    gcloud projects add-iam-policy-binding PROJECT_ID \
       --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.s3ns.iam.gserviceaccount.com" \
       --role='roles/artifactregistry.writer'
    

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

יצירת חבילת מכשירים

כדי ליצור חבילת צי, מגדירים מפרט FleetPackage שמפנה למאגר עם משאבי Kubernetes שמקושרים ל-Cloud Build. לאחר מכן מריצים את הפקודה FleetPackage כדי לאחזר את המשאבים מ-Git ולפרוס אותם בכל הצי.

  1. יוצרים קובץ בשם fleetpackage-spec.yaml עם התוכן הבא:

    resourceBundleSelector:
      cloudBuildRepository:
        name: projects/PROJECT_ID/locations/us-central1/connections/CONNECTION_NAME/repositories/REPOSITORY_NAME
        tag: TAG
        serviceAccount: projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_NAME@PROJECT_ID.s3ns.iam.gserviceaccount.com
        path: CONFIG_FILE_PATH
        # Match all files and directories to generate variants
        variantsPattern: "*"
    target:
      fleet:
        project: projects/PROJECT_ID
    rolloutStrategy:
      rolling:
        maxConcurrent: MAX_CLUSTERS
    variantSelector:
      variantNameTemplate: "VARIANT_NAME"
    # set the state to SUSPENDED to pause new rollouts
    # set the state back to ACTIVE to resume rollouts
    # state: SUSPENDED
    

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

    • CONNECTION_NAME: השם שבחרתם כשחיברתם את מארח Git ל-Cloud Build. כדי לראות את כל החיבורים של Cloud Build בפרויקט, מריצים את הפקודה gcloud builds connections list או פותחים את הדף Repositories במסוף Cloud de Confiance :

      פתיחת הדף Repositories

    • REPOSITORY_NAME: שם המאגר. הערך הזה צריך להיות זהה לערך שהוזן כשמגדירים את החיבור ל-Cloud Build.

    • TAG: תג Git של המאגר. הפורמט צריך להיות הגרסה הסמנטית המלאה עם מספר הגרסה הראשית, המשנית ומספר תיקון הבאגים. לדוגמה, v1.0.0 הוא תג תקין, אבל v1 או v1.0 הם תגים לא תקינים.

    • CONFIG_FILE_PATH: הנתיב למשאבי Kubernetes במאגר. אם הקבצים נמצאים בבסיס המאגר, אפשר להשמיט את השדה הזה.

    • MAX_CLUSTERS: המספר המקסימלי של אשכולות לפריסת משאבי Kubernetes בו-זמנית. לדוגמה, אם מגדירים את הערך הזה ל-1, חבילות של משאבים נפרסות לאשכול אחד בכל פעם.

    • VARIANT_NAME: הווריאנט לפריסה באשכולות. השם צריך להיות זהה לגרסה במאגר (שם הקובץ ללא הסיומת או שם הספרייה). לדוגמה, אם יש לכם קובץ בשם prod.yaml, צריך להגדיר את השדה הזה לערך prod. כדי להשתמש בהתנהגות ברירת המחדל (לדוגמה, כדי לפרוס את אותה הגדרה לכל האשכולות בצי), מגדירים את השדה הזה ל-default ומוודאים שהמאגר מכיל קובץ בשם default.yaml.

      רשימה מלאה של כל השדות שאפשר להגדיר מופיעה FleetPackage במאמרי העזרה.

  2. יוצרים את חבילת הצי:

    gcloud container fleet packages create FLEET_PACKAGE_NAME \
        --source=fleetpackage-spec.yaml
    

    מחליפים את FLEET_PACKAGE_NAME בשם של השקת חבילת הצי.

  3. מוודאים שחבילת Fleet נוצרה:

    gcloud container fleet packages list
    

    בפלט מופיע הסטטוס של טריגר לפיתוח גרסת Build. אחרי כמה שניות, השדה MESSAGE מתעדכן עם פלט שדומה לזה:

    MESSAGES: Build status: WORKING. The release is still being built; see the build status on the following page:
    

    אפשר ללחוץ על הקישור שמופיע כדי לראות את יומני הסטרימינג של משימת Cloud Build. יכול להיות שיחלפו כמה דקות עד ש-Cloud Build יעבד את טריגר לפיתוח גרסת Build.

    אם טריגר הבנייה מצליח, חבילת הצי מתחילה להפיץ את משאבי Kubernetes בצי.

  4. כשטריגר לפיתוח גרסת Build מסתיים בהצלחה, הפלט של gcloud container fleet packages list דומה לזה:

    NAME               STATE   CREATE_TIME           ACTIVE_ROLLOUT            LAST_COMPLETED_ROLLOUT  MESSAGES
    my-fleet-package   ACTIVE  2024-07-09T15:15:56   rollout-20240709-153621
    

    חבילת הצי מתחילה להפיץ את משאבי Kubernetes בצי.

עכשיו, אחרי שפרסתם חבילת Fleet, כשתוסיפו אשכול חדש ל-Fleet, משאבי ה-Kubernetes שמוגדרים בחבילת ה-Fleet ייפרסו אוטומטית באשכול החדש.

עדכון חבילה של צי

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

  • כדי לשנות את אסטרטגיית ההשקה, משנים את הערך של השדה maxConcurrent.
  • כדי להשהות חבילת צי באופן זמני, מגדירים את state: SUSPENDED. כשחבילת עדכון לצי מכשירים מושהית, כל ההשקות שמתבצעות ממשיכות. לא ייווצרו או יתוזמנו השקות חדשות עד שתשנו את המצב בחזרה לACTIVE.
  • כדי לעדכן את משאבי Kubernetes שחבילת הצי מפריסה, צריך לעדכן את השדה tag כדי למשוך מתג Git אחר.

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

  1. מעדכנים את המפרט של FleetPackage בהתאם לשינויים.

  2. מעדכנים את חבילת הצי:

    gcloud container fleet packages update FLEET_PACKAGE_NAME \
        --source=fleetpackage-spec.yaml
    

    יכול להיות שיעברו כמה דקות עד שהשינוי יזוהה ויתחיל להתעדכן באשכולות.

בדיקת חבילות משאבים ופריטי תוכן

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

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

  • כדי לראות מידע מפורט על חבילת משאבים ספציפית:

    gcloud container fleet packages resource-bundles describe flpkg-rb-FLEET_PACKAGE_NAME
    
  • הצגת רשימה של כל הגרסאות שמשויכות לחבילת משאבים:

    gcloud container fleet packages resource-bundles releases list \
        --resource-bundle flpkg-rb-FLEET_PACKAGE_NAME
    
  • הצגת מידע מפורט על גרסה ספציפית, כולל חבילת המשאבים שבה נעשה שימוש. הפקודה הזו שימושית במיוחד לניפוי באגים שקשורים לגרסאות שונות, כי היא מאפשרת לבדוק בדיוק אילו גרסאות נכללו במהדורה ספציפית:

    gcloud container fleet packages resource-bundles releases describe RELEASE_NAME\
        --resource-bundle flpkg-rb-FLEET_PACKAGE_NAME
    

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

  • FLEET_PACKAGE_NAME: השם של חבילת הצי. השם של חבילת המשאבים מתחיל אוטומטית בקידומת flpkg-rb-.
  • RELEASE_NAME: השם של הגרסה מפלט הפקודה list.

ניהול השקות של חבילות בצי

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

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

    gcloud container fleet packages rollouts list --fleet-package FLEET_PACKAGE_NAME
    

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

    ROLLOUT                   RELEASE  START_TIME              END_TIME                STATE     MESSAGE
    rollout-20250515-132857   v2-0-0   2025-05-15T13:28:58Z                            STALLED
    rollout-20250418-165528   v1-0-0   2025-04-18T16:55:29Z    2025-04-18T16:57:47Z    COMPLETED
    
  2. תיאור של השקה מספק מידע מפורט על השקה ספציפית, כולל הסטטוס של כל אשכול יעד ושגיאות ספציפיות לאשכול. כדי לתאר השקה, מריצים את הפקודה הבאה:

    gcloud container fleet packages rollouts describe ROLLOUT_NAME --fleet-package FLEET_PACKAGE_NAME
    

    מחליפים את ROLLOUT_NAME בשם של ההשקה. אפשר לקבל את השם המלא של ההשקה מהפקודה list בשלב הקודם.

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

    CLUSTER    CURRENT_VERSION  SYNC_STATE  DESIRED_VERSION  START_TIME              END_TIME                STATE      MESSAGES
    cluster1   v2.0.0           SYNCED      v2.0.0           2025-05-15T13:28:58Z    2025-05-15T13:30:27Z    COMPLETED
    cluster2   v1.0.0           SYNCED      v2.0.0           2025-05-15T13:30:27Z                            ERROR      Membership no longer exists
    
  3. כדי לנהל את ההשקות הפעילות, מריצים את הפקודות הבאות:

    • השהיית ההשקה מעבירה את ההשקה למצב SUSPENDED. עדכוני חבילות שנמצאים בתהליך ימשיכו, ולא יתוזמנו עדכוני חבילות נוספים. כדי להשהות את ההשקה, מריצים את הפקודה הבאה:

      gcloud container fleet packages rollouts suspend ROLLOUT_NAME --fleet-package FLEET_PACKAGE_NAME
      
    • כשממשיכים השקה, היא משתנה ממצב SUSPENDED למצב IN_PROGRESS. עדכוני החבילות נפרסים באשכולות היעד כמתוכנן. כדי להפעיל מחדש את ההשקה, מריצים את הפקודה הבאה:

      gcloud container fleet packages rollouts resume ROLLOUT_NAME --fleet-package FLEET_PACKAGE_NAME
      
    • ביטול של השקה מתמשכת יפסיק אותה באופן מיידי ויעביר אותה למצב ABORTED. כל עדכוני החבילות שבהמתנה שמתוכננים כחלק מההשקה מבוטלים. כדי לבטל השקה, מריצים את הפקודה הבאה:

      gcloud container fleet packages rollouts abort ROLLOUT_NAME --fleet-package FLEET_PACKAGE_NAME
      

שיטות פריסה

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

פריסה לקבוצת משנה של אשכולות

אפשר להטמיע את אותו משאב בקבוצת משנה של אשכולות באמצעות תוויות, ולציין את השדה target.fleet.selector.matchLabels עם התוויות (צמד של מפתח וערך). לדוגמה, אם מגדירים את matchLabels כ-country: "us", שירות חבילת ה-Fleet פורס את המשאבים רק באשכולות עם התווית country שתואמת ל-"us".

חבילות לצי רכבים תומכות רק בתוויות של חברות בצי רכבים. אין תמיכה בתוויות של אשכולות GKE.

  1. (אופציונלי) אם אין לכם תוויות שאתם רוצים להשתמש בהן, תוכלו להוסיף אותן כך:

    1. כדי לקבל רשימה של חברויות במועדון בצי:

      gcloud container fleet memberships list
      
    2. מוסיפים תווית למינוי:

      gcloud container fleet memberships update MEMBERSHIP_NAME \
          --update-labels=KEY=VALUE
      

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

      • MEMBERSHIP_NAME: השם של האשכול שרשום ב-Fleet.
      • KEY ו-VALUE: התווית שרוצים להוסיף למינוי. אם התווית קיימת, הערך שלה ישתנה. אחרת, נוצר תווית חדשה. המפתחות צריכים להתחיל באות קטנה. אפשר להשתמש רק באותיות קטנות, וגם בספרות, במקף (-) ובקו תחתון (_). הערכים חייבים להכיל רק מקפים (-), קווים תחתונים (_), אותיות קטנות ומספרים.

      חוזרים על הפקודה הזו לכל חברות שרוצים להוסיף לה תווית.

  2. יוצרים או מעדכנים את המפרט FleetPackage באמצעות הכלי לבחירת תוויות:

    resourceBundleSelector:
      cloudBuildRepository:
        name: projects/PROJECT_ID/locations/us-central1/connections/CONNECTION_NAME/repositories/REPOSITORY_NAME
        tag: TAG
        serviceAccount: projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_NAME@PROJECT_ID.s3ns.iam.gserviceaccount.com
        path: CONFIG_FILE_PATH
    target:
      fleet:
        project: projects/PROJECT_ID
        selector:
          matchLabels:
            KEY: "VALUE"
    rolloutStrategy:
      rolling:
        maxConcurrent: MAX_CLUSTERS
    
  3. יוצרים או מעדכנים את חבילת הצי:

    יצירת חבילת מכשירים

    gcloud container fleet packages create FLEET_PACKAGE_NAME \
        --source=fleetpackage-spec.yaml
    

    עדכון חבילה של צי

    gcloud container fleet packages update FLEET_PACKAGE_NAME \
        --source=fleetpackage-spec.yaml
    

פריסת משאבי וריאנטים באשכולות

אתם יכולים לפרוס הגדרות ייחודיות לאשכולות שונים (לדוגמה, dev לעומת prod) על ידי הוספת הגדרות של וריאציות לחבילת הצי.

במאמר איך נוצרים וריאנטים מוסבר איך נוצרים וריאנטים ממבנה המאגר.

כדי לפרוס חבילת צי עם וריאציות:

  1. יוצרים או מעדכנים את המפרט FleetPackage כך שיכלול את השדות variantsPattern ו-variantNameTemplate:

    resourceBundleSelector:
      cloudBuildRepository:
        name: projects/PROJECT_ID/locations/us-central1/connections/CONNECTION_NAME/repositories/REPOSITORY_NAME
        tag: TAG
        serviceAccount: projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_NAME@PROJECT_ID.s3ns.iam.gserviceaccount.com
        path: CONFIG_FILE_PATH
        variantsPattern: VARIANT_PATTERN
    target:
      fleet:
        project: projects/PROJECT_ID
    rolloutStrategy:
      rolling:
        maxConcurrent: MAX_CLUSTERS
    target:
      fleet:
        project: projects/PROJECT_ID
     variantSelector:
      variantNameTemplate: VARIANT_NAME_TEMPLATE
    

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

    • VARIANT_PATTERN: תבנית glob ליצירת וריאציות מהמאגר, כמו * (התאמה לכל הקבצים והספריות) או *.yaml (התאמה רק לקבצים). מידע נוסף על הדפוסים הנתמכים זמין במאמר בנושא variantsPatternהתאמה.
    • VARIANT_NAME_TEMPLATE : מחרוזת או תבנית לבחירת וריאציה לכל אשכול. אפשר להשתמש במשתני מטא-נתונים כמו ${membership.labels['env']} או ${membership.location}.
  2. יוצרים או מעדכנים את חבילת הצי:

    יצירת חבילת מכשירים

    gcloud container fleet packages create FLEET_PACKAGE_NAME \
        --source=fleetpackage-spec.yaml
    

    עדכון חבילה של צי

    gcloud container fleet packages update FLEET_PACKAGE_NAME \
        --source=fleetpackage-spec.yaml
    

מחיקת חבילה של צי רכבים

מחיקת חבילת צי תמחק גם את המשאבים הבאים:

  • משאבי Kubernetes שנפרסו באשכולות
  • היסטוריית ההשקה של חבילת הצי

כדי למחוק חבילת צי, מריצים את הפקודה הבאה:

gcloud container fleet packages delete FLEET_PACKAGE_NAME --force

פתרון בעיות

כדי למצוא שיטות לאבחון ולפתרון שגיאות שקשורות ל-Cloud Build, אפשר לעיין במאמר בנושא פתרון שגיאות ב-build.

המאמרים הבאים