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

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

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

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

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

apiVersion: imagebuilder.gcp.com/v1
kind: OSImageCustomization
metadata:
  # Recipe metadata and identifying details
infrastructureConfig:
  # VM machine type, zone, and network settings
source:
  # Base source image profile
destinations:
  # Output OS image release targets
spec:
  config:
    # Build options and validation test flags
  steps:
    # Customization actions (Shell, FileCopy, UpdateKernelCommandLine, InstallGPU)

מטא-נתונים

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

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: nvidia-l4
  acceleratorCount: 1
  debug: false
  instanceDurationHours: 2.0
  reservations:
    - RESERVATION_NAME
  • ‫machineType (מחרוזת, חובה): סוג המכונה ב-Compute Engine שבה יש להשתמש עבור מכונות וירטואליות של worker ומכונות וירטואליות לבדיקה. מוודאים שסוג המכונה תואם לארכיטקטורה של תמונת המקור שצוינה ב-imageFamily או ב-imagePath. לדוגמה, משתמשים ב-e2-standard-4 לתמונות x86 וב-c4a-standard-4 לתמונות Arm. אין תמיכה בסוגי מכונות Bare-metal.
  • ‫zone (מחרוזת, חובה): האזור שבו פועלות מכונות ה-VM של העובד והבדיקה, למשל us-central1-a.
  • ‫network (מחרוזת, אופציונלי): רשת ה-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 יוצר מכונות וירטואליות.

תמונת המקור

מזהה את תמונת מערכת ההפעלה הבסיסית ש-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:
        - us-central1
  • ‫name (מחרוזת, חובה): תחילית שם הבסיס שמוקצית למשאב התמונה הסופי של 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): Toggles whether the test VM evaluates boot conditions, networking, and UEFI structures. ברירת המחדל היא 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..."

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