קובץ להתאמה אישית של תמונות

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

סקירה כללית של הסכימה

הגדרת ההתאמה האישית משתמשת בגרסת ה-API‏ imagebuilder.gcp.com/v1 ובסוג המשאב OSImageCustomization.

קובץ מתכון רגיל בנוי כך:

apiVersion: imagebuilder.gcp.com/v1
kind: OSImageCustomization
metadata:
  # Recipe metadata and identifying details
  name: CONFIG_NAME
  description: DESCRIPTION
infrastructureConfig:
  # VM machine type, zone, and network settings
  machineType: MACHINE_TYPE
  zone: ZONE
  network: projects/PROJECT_ID/global/networks/NETWORK_NAME
  subnetwork: projects/PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME
  externalIP: ephemeral
  acceleratorType: ACCELERATOR_TYPE
  acceleratorCount: ACCELERATOR_COUNT
  debug: DEBUG_BOOLEAN
  instanceDurationHours: DURATION_HOURS
  reservations:
    - RESERVATION_NAME
  validationConcurrency: VALIDATION_CONCURRENCY
source:
  # Base source image profile
  imageFamily: projects/IMAGE_PROJECT/global/images/family/IMAGE_FAMILY
  # Alternatively, use a direct image version URI:
  # imagePath: projects/IMAGE_PROJECT/global/images/IMAGE_NAME
destinations:
  # Output OS image release targets
  - diskImage:
      name: IMAGE_NAME
      project: PROJECT_ID
      family: IMAGE_FAMILY
      description: DESCRIPTION
      licenses:
        - projects/PROJECT_ID/global/licenses/LICENSE_NAME
      labels:
        env: production
      signatureDatabaseFile: SIGNATURE_DB_PATH
      storageLocations:
        - STORAGE_LOCATION
spec:
  config:
    # Build options and validation test flags
    skipSystemTests: false
  steps:
    # Customization actions (Shell, FileCopy, UpdateKernelCommandLine, InstallGPU)
    - name: STEP_NAME
      action: ACTION_TYPE
      inputs:
        # Action-specific input parameters

מטא-נתונים

מספק פרטים מזהים של תבנית הבנייה המותאמת אישית הזו:

metadata:
  name: CONFIG_NAME
  description: DESCRIPTION
  • ‫name (מחרוזת, חובה): המזהה של ההגדרה הזו.
  • ‫description (מחרוזת, אופציונלי): תיאור של מטרת הבנייה.

הגדרת התשתית

מציינת את מאפייני החומרה והרשת של מכונות וירטואליות זמניות ש-Image Builder יוצר במהלך משימות בנייה ואימות:

infrastructureConfig:
  machineType: MACHINE_TYPE
  zone: ZONE
  network: projects/PROJECT_ID/global/networks/NETWORK_NAME
  subnetwork: projects/PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME
  externalIP: ephemeral
  acceleratorType: ACCELERATOR_TYPE
  acceleratorCount: ACCELERATOR_COUNT
  debug: DEBUG_BOOLEAN
  instanceDurationHours: DURATION_HOURS
  reservations:
    - RESERVATION_NAME
  validationConcurrency: VALIDATION_CONCURRENCY
  • ‫machineType (מחרוזת, חובה): סוג המכונה ב-Compute Engine שבה יש להשתמש עבור מכונות וירטואליות של worker ומכונות וירטואליות לבדיקה. מוודאים שסוג המכונה תואם לארכיטקטורה של תמונת המקור שצוינה ב-imageFamily או ב-imagePath. לדוגמה, משתמשים ב-e2-standard-4 לתמונות x86 וב-c4a-standard-4 לתמונות Arm. אין תמיכה בסוגי מכונות Bare-metal.
  • ‫zone (מחרוזת, חובה): האזור שבו פועלות מכונות ה-VM של העובד והבדיקה, למשל us-central1-a.
  • ‫network (string, אופציונלי): רשת ה-VPC לצירוף למכונות הווירטואליות של העובד ולבדיקת האימות, כמו projects/<var>PROJECT_ID</var>/global/networks/<var>NETWORK_NAME</var> או default. אם לא מציינים רשת, הכלי Image Builder משתמש ברשת ברירת המחדל.
  • ‫subnetwork (מחרוזת, אופציונלי): רשת המשנה של ה-VPC לצירוף למכונות הווירטואליות של העובד ולמכונות הווירטואליות של בדיקת האימות, למשל projects/<var>PROJECT_ID</var>/regions/<var>REGION</var>/subnetworks/<var>SUBNET_NAME</var>.
  • ‫externalIP (מחרוזת, אופציונלי): מציינת את הקצאת כתובת ה-IP החיצונית למכונות הווירטואליות של העובד ולמכונות הווירטואליות של בדיקת האימות. ערכים מותרים:
    • ‫ephemeral (ברירת מחדל): מקצה כתובת IPv4 ציבורית ארעית ממאגר משותף.
    • ‫none: יוצר מכונות וירטואליות ללא כתובת IP חיצונית, שמשתמשות רק ברשת VPC פרטית. אם הערך הוא none, צריך לוודא שמופעלת גישה פרטית ל-Google או Cloud NAT ברשת המשנה של ה-VPC, כדי שהמכונות הווירטואליות יוכלו לגשת לשירותים הנדרשים Google Cloud ולמאגרי החבילות.
  • ‫acceleratorType (string, אופציונלי): סוג מאיץ ה-GPU לצירוף למכונה הווירטואלית של העובד, כמו nvidia-tesla-t4 או nvidia-l4.
  • ‫acceleratorCount (מספר, אופציונלי): מספר מאיצי ה-GPU שיוצמדו ל-worker VM.
  • ‫debug (boolean, אופציונלי): אם מגדירים את debug ל-true, Image Builder שומר את ה-worker VM, בין אם ההתאמה האישית מסתיימת או נכשלת, כדי שתוכלו לבדוק או לפתור בעיות במופע הפעיל באמצעות SSH. ברירת המחדל היא false.
  • ‫instanceDurationHours (מספר, אופציונלי): מגביל את זמן הריצה של ה-worker VM. הזמן הקצוב לתפוגה מתחיל כשההתאמה האישית מסתיימת או כשמתרחשת שגיאת סקריפט, ומאפשר לכם להתחבר למכונה הווירטואלית הפעילה במהלך סשנים אינטראקטיביים של ניפוי באגים. ההגבלה היא עד 2.0 שעות.
  • ‫reservations (מערך של מחרוזות, אופציונלי): שמות של משאבי הזמנת קיבולת (כמו test-reservation באותו פרויקט) לשימוש כש-Image Builder יוצר מכונות וירטואליות.
  • ‫validationConcurrency (מספר, אופציונלי): מציין את המספר המקסימלי של בדיקות אימות להרצה במקביל במופע המחשוב הזמני של בדיקת האימות. הערכים המותרים כוללים את האפשרויות הבאות:
    • ‫0 או השמטה (ברירת מחדל): Image Builder מזהה אוטומטית את הבו-זמניות על סמך סוג המכונה והגדרות המאיץ, ומגדיר אותה באופן הבא:
      • ‫1 (sequential) לסוגי מכונות Bare Metal או להגדרות עם מאיצי GPU מצורפים, כדי למנוע חריגה ממגבלות המכסה או ניצול יתר של משאבים.
      • ‫4 (מקבילי) לכל שאר סוגי המכונות.
    • ‫1: מריץ בדיקות אימות ברצף. אם לפרויקט שלכם יש מכסת שימוש מוגבלת ב-machineType שצוין, הגדרת מקביליות ל-1 יכולה לעזור כי היא מונעת הפעלה של כמה מופעי מחשוב בו-זמנית.
    • ‫2 ומעלה: מריץ את מספר בדיקות האימות שצוין במקביל. אם יש לכם מספיק קיבולת או הזמנות, הגדלת מספר הבדיקות המקבילות יכולה לקצר את זמן הביצוע הכולל של בדיקות האימות.

תמונת המקור

מזהה את תמונת מערכת ההפעלה הבסיסית ש-Image Builder משתמש בה כדי להפעיל את המכונה הווירטואלית של העובד. צריך לציין אחת מהאפשרויות הבאות:

כדי לציין משפחת תמונות רגילה:

source:
  imageFamily: projects/IMAGE_PROJECT/global/images/family/IMAGE_FAMILY

כדי לציין URI של גרסת תמונה ישירה:

source:
  imagePath: projects/IMAGE_PROJECT/global/images/IMAGE_NAME
  • ‫imageFamily (מחרוזת): הנתיב לקבוצה משפחתית של תמונות רגילות, כמו projects/ubuntu-os-cloud/global/images/family/ubuntu-2204-lts.
  • ‫imagePath (מחרוזת): ה-URI הישיר של משאב לגרסה ספציפית של תמונה ב-Compute Engine, כמו projects/cos-cloud/global/images/cos-105-17412-226-28.

יעדים

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

destinations:
  - diskImage:
      name: IMAGE_NAME
      project: PROJECT_ID
      family: IMAGE_FAMILY
      description: DESCRIPTION
      licenses:
        - projects/PROJECT_ID/global/licenses/LICENSE_NAME
      labels:
        env: production
      signatureDatabaseFile: SIGNATURE_DB_PATH
      storageLocations:
        - STORAGE_LOCATION
  • ‫name (מחרוזת, חובה): התחילית של שם הבסיס שמוקצה למשאב הסופי של קובץ ה-image ב-Compute Engine. ‫Image Builder מוסיף באופן אוטומטי את מזהה ה-build הייחודי לקידומת הזו, וקוצץ את שם התמונה הסופי ל-63 תווים.
  • ‫family (מחרוזת, אופציונלי): משפחת התמונות שרוצים להחיל על התמונה החדשה שנוצרה.
  • ‫project (מחרוזת, חובה): Google Cloud הפרויקט שבו Image Builder כותב את תמונת הפלט.
  • description (מחרוזת, אופציונלי): טקסט תיאור שמצורף למטא-נתונים של התמונה שנוצרה.
  • ‫licenses (מערך של מחרוזות, אופציונלי): נתיבי משאבים של רישיונות תוכנה ספציפיים שחלים על התמונה הזו.
  • ‫labels (map, אופציונלי): תיוג של זוגות מפתח/ערך של מטא-נתונים, כמו env: production.
  • ‫signatureDatabaseFile (מחרוזת, אופציונלי): נתיב משאב לקובץ מסד נתונים של חתימת אתחול מאובטח.
  • ‫storageLocations (מערך של מחרוזות, אופציונלי): אזור היעד או אזור רב-אזורי לאחסון, כמו us-central1 או us, שבו Compute Engine מאחסן את בלוקי הדיסק הסופיים. הערה: למרות שהמאפיין הזה מפורמט כרשימה, אפשר לציין רק מיקום אחד לכל יעד תמונה.

הגדרת המפרט

החלת אפשרויות הרצה כלליות:

spec:
  config:
    skipSystemTests: false
  • ‫skipSystemTests (boolean, Optional): מחליף את המצב של המכונה הווירטואלית לבדיקה כדי להעריך את תנאי האתחול, הרשת ומבני ה-UEFI. ברירת המחדל היא false.

שלבי ההגדרה

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

לכל האובייקטים של שלבי ההתאמה האישית יש את המאפיינים המשותפים הבאים:

spec:
  steps:
    - name: STEP_NAME
      action: ACTION_TYPE
      inputs:
        # Action-specific input parameters
  • ‫name (מחרוזת, חובה): שם מוגדר על ידי המשתמש לשלב ההתאמה האישית הזה.
  • ‫action (string, חובה): פעולת העזר להפעלה. פעולות נתמכות:
    • ‫Shell: הפעלת סקריפטים של מסוף במכונה הווירטואלית.
    • ‫FileCopy: העברת נכסים מקטגוריות של Cloud Storage או מסביבות עבודה.
    • ‫UpdateKernelCommandLine: מעדכן את פרמטרי האתחול.
    • ‫InstallGPU: רישום של דרייברים של NVIDIA GPU.
  • ‫inputs (object, Required): מאפייני המפתח/ערך שנדרשים לפעולה שנבחרה. לעיון בדוגמאות ובהפניות מלאות לפרמטרים, אפשר לעבור אל פעולות ההתאמה האישית הנתמכות.

בקטע הקוד הבא מוצגת דוגמה לשלב שמשתמש בפעולה Shell:

spec:
  steps:
    - name: setup-environment
      action: Shell
      inputs:
        inlineScript: |
          #!/usr/bin/env bash
          echo "Running customization..."

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