קובץ תצורת build של Cloud Build

במאמר הזה מתוארים המבנה והפרמטרים של קובץ התצורה של Cloud Build ‏ (cloudbuild.yaml) שמשמש לתיאום השלבים של צינור העיבוד של Image Builder: ניתוח, בנייה, אימות ופרסום של גרסת הפצה.

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

קובץ cloudbuild.yaml רגיל של Image Builder פועל לפי המבנה הרגיל של קובץ התצורה של Cloud Build ומבצע שלוש פעולות build של קונטיינרים ברצף: /build, /validate ו-/publish.

substitutions:
  _GCS_WORKDIR: 'gs://BUCKET_NAME/workdir/'
  _IMAGE_BUILDER_CONFIG_PATH: 'imagebuilder.yaml'
  _SERVICE_ACCOUNT: 'projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL'
  _IMAGE_OUTPUT_PATH: 'image-builder/binaryOut'
  _ARTIFACT_REGISTRY_RESOURCE_URI: 'projects/PROJECT_ID/locations/REGION/repositories/REPOSITORY_NAME/packages/PACKAGE_NAME/versions/v${BUILD_ID}'

steps:
  # Step 1: Parse configs and run OS customization on the worker VM
  - name: 'REGION-docker.pkg.dev/image-builder-official/release/builder:stable'
    script: |
      #!/usr/bin/env bash
      /build
    id: 'imagebuilder-customize'
    results:
      - name: image_builder_telemetry_metrics
      - name: base_image
        attestationType: "https://cloudbuild.googleapis.com/attestations/build_content_restrictions"
        attestationContent: base_image

  # Step 2: Validate by running system boot checks on the test VM
  - name: 'REGION-docker.pkg.dev/image-builder-official/release/validator:stable'
    script: |
      #!/usr/bin/env bash
      /validate
    id: 'imagebuilder-validate'
    results:
      - name: image_builder_telemetry_metrics

  # Step 3: Register OS image and publish tar file to Artifact Registry
  - name: 'REGION-docker.pkg.dev/image-builder-official/release/builder:stable'
    script: |
      #!/usr/bin/env bash
      /publish
    id: 'imagebuilder-publish'
    results:
      - name: image_builder_telemetry_metrics

options:
  automapSubstitutions: true
  requestedVerifyOption: VERIFIED
  substitutionOption: ALLOW_LOOSE
  dynamicSubstitutions: true
  logging: CLOUD_LOGGING_ONLY

artifacts:
  generic_artifacts:
    - folder: '${_IMAGE_OUTPUT_PATH}'
      registry_path: '${_ARTIFACT_REGISTRY_RESOURCE_URI}'

timeout: '3600s'

משתני החלפה

קובץ cloudbuild.yaml משתמש במשתני ההחלפה הבאים כדי למפות ישירות למשתני סביבה לצורך ביצוע:

substitutions:
  _GCS_WORKDIR: 'gs://BUCKET_NAME/workdir/'
  _IMAGE_BUILDER_CONFIG_PATH: 'imagebuilder.yaml'
  _SERVICE_ACCOUNT: 'projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL'
  _IMAGE_OUTPUT_PATH: 'image-builder/binaryOut'
  _ARTIFACT_REGISTRY_RESOURCE_URI: 'projects/PROJECT_ID/locations/REGION/repositories/REPOSITORY_NAME/packages/PACKAGE_NAME/versions/v${BUILD_ID}'

• ‫_GCS_WORKDIR: הנתיב האזורי של Cloud Storage שמשמש כמיקום זמני להעברת נתונים של ארטיפקטים כמו יומני פעילות טורית, ארכיונים זמניים של תמונות והיסטוריית ביצוע של אורחים. הבאקט חייב להיות קיים.

• ‫_IMAGE_BUILDER_CONFIG_PATH: הנתיב לimagebuilder.yamlמתכון ההתאמה האישית. זה יכול להיות נתיב מרוחק ב-Cloud Storage (לדוגמה, gs://BUCKET_NAME/imagebuilder.yaml), או נתיב יחסי בסביבת העבודה או במאגר GitHub, בהתאם למקור.

• ‫_SERVICE_ACCOUNT: שם המשאב המלא של ניהול הזהויות והרשאות הגישה (IAM) של חשבון השירות שהוגדר להפעלת הבנייה ולאישור שלבי התיזמור.

• ‫_IMAGE_OUTPUT_PATH: נתיב הפלט של קובץ ה-tar המיוצא בספרייה /workspace/ של Cloud Build.

• ‫_ARTIFACT_REGISTRY_RESOURCE_URI (אופציונלי): ה-URI של המשאב עבור המאגר הכללי ב-Artifact Registry. אם מספקים את קובץ ה-tar של התמונה הבלתי ניתנת לשינוי שנוצר, צינור הנתונים דוחף אותו ומפיק אישורים במיקום הזה.

שלבים

כדי לתזמן את יצירת קובץ האימג' של מערכת ההפעלה, Image Builder מריץ שלושה שלבים נפרדים של קונטיינרים ברצף. מחליפים את REGION בנתיב של קובץ האימג' של הקונטיינר באזור היעד Cloud de Confiance שבו הגדרתם את צינורות עיבוד הנתונים, כמו us-central1,‏ europe-west1 או asia-east1:

steps:
  - name: 'REGION-docker.pkg.dev/image-builder-official/release/builder:stable'
    script: |
      #!/usr/bin/env bash
      /build
    id: 'imagebuilder-customize'

  - name: 'REGION-docker.pkg.dev/image-builder-official/release/validator:stable'
    script: |
      #!/usr/bin/env bash
      /validate
    id: 'imagebuilder-validate'

  - name: 'REGION-docker.pkg.dev/image-builder-official/release/builder:stable'
    script: |
      #!/usr/bin/env bash
      /publish
    id: 'imagebuilder-publish'

דרישות לגבי טלמטריה ומזהה שלב

קונטיינר התיזמור מזהה את ההתקדמות של כל שלב ב-build – התאמה אישית, אימות ופרסום – ועוקב אחריה על ידי קריאת השדה id של כל שלב בקובץ cloudbuild.yaml.

מזהי השלבים צריכים להתחיל בקידומת imagebuilder-, כמו imagebuilder-customize,‏ imagebuilder-validate ו-imagebuilder-publish, כדי לאפשר ל-Image Builder לאסוף מדדי טלמטריה ספציפיים לשירות.

כשכוללים את image_builder_telemetry_metrics בבלוק results של כל שלב, Image Builder אוסף באופן מאובטח מדדים ברמה גבוהה של ביצוע צינור עיבוד הנתונים כדי לעקוב אחרי מהימנות השירות ולנטר אותה, באופן הבא:

• ביצוע וסטטוס של בנייה: סטטוס הצלחה או כישלון ומשך הזמן של כל שלב בנייה ופעולת התאמה אישית.
• פרטי הסביבה: סוג המכונה, האזור ותג גרסת הקונטיינר ב-Compute Engine שבהם נעשה שימוש במהלך ההפעלה.
• מטא-נתונים של קובץ האימג': הפצה של מערכת ההפעלה הבסיסית, גרסה ותכונות מוגדרות של מערכת ההפעלה של האורח.
• תוצאות בדיקת האימות: סטטוס של בדיקות אימות אוטומטיות של המערכת, כמו אתחול מכונה וירטואלית, אתחול מאובטח, תקינות של אחסון בלוקים, סטטוס של סוכן אורח וקישור של מנהל התקן לרשת. הסטטוס יכול להיות 'עבר', 'נכשל' או 'דילוג'.

שלב התאמה אישית

בשלב ההתאמה האישית, המערכת מאמתת את הסכימה של imagebuilder.yaml, בודקת את הרשאות ה-IAM, מפעילה את מופע ה-worker VM, מטעינה את דיסק הבינארי של ההתאמה האישית, מפעילה את כלי ההקצאה של ההתאמה האישית ומייצאת בצורה מאובטחת את המחיצה של דיסק האתחול.

• קובץ אימג' של קונטיינר: us-central1-docker.pkg.dev/image-builder-official/release/builder:stable
• פקודת סקריפט: /build
• בלוק המשנה של התוצאות:
  • ‫image_builder_telemetry_metrics: איסוף מדדים של ביצוע בניית התאמה אישית.
  • ‫base_image (אופציונלי): מתעד פרטים של תמונת המקור הבסיסית במטא-נתונים של אישור הבנייה כשמציינים יעד של מאגר כללי ב-Artifact Registry. הגדרת attestationType: "https://cloudbuild.googleapis.com/attestations/build_content_restrictions" כדי ליצור רשומה שניתן לאמת של מקור התמונה.

שלב האימות

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

• קובץ אימג' של קונטיינר: us-central1-docker.pkg.dev/image-builder-official/release/validator:stable
• פקודת סקריפט: /validate
• בלוק המשנה Results: image_builder_telemetry_metrics אוסף מדדים של הרצת בדיקות אימות.

שלב הפרסום

בשלב הפרסום, מתבצעת הרשמה של תמונת מערכת ההפעלה הסופית, נמחקים דיסקים זמניים, מטען ה-tar מועלה ל-Artifact Registry אם הוא מוגדר, ונכתבות רשומות של מקורות מידע (provenance) של Supply Chain Levels for Software Artifacts‏ (SLSA).

• קובץ אימג' של קונטיינר: us-central1-docker.pkg.dev/image-builder-official/release/builder:stable
• פקודת סקריפט: /publish
• בלוק המשנה Results: image_builder_telemetry_metrics אוסף מדדים של הרצת פרסום.

אפשרויות

אפשרויות הדגלים מגדירות את הגדרות ההרצה בשרת Cloud Build. צריך להגדיר את האפשרויות הבאות:

options:
  automapSubstitutions: true
  requestedVerifyOption: VERIFIED
  substitutionOption: ALLOW_LOOSE
  dynamicSubstitutions: true
  logging: CLOUD_LOGGING_ONLY

מידע נוסף על ההגדרות האלה זמין במאמר אפשרויות בקובץ תצורת ה-build של Cloud.

• ‫automapSubstitutions: צריך להגדיר את הערך true כדי לוודא שמשתני החלפה ממופים לסביבת הקונטיינר.
• ‫requestedVerifyOption: מוגדר ל-VERIFIED. ההגדרה הזו מורה ל-Cloud Build ליצור באופן אוטומטי אישורי המקור של Build לפי SLSA. מקורות המידע האלה מספקים אימות קריפטוגרפי לכך שהתמונה נוצרה בדיוק כמו שהוגדר בצינור העיבוד, ועוזרים למנוע שינויים לא רצויים ולשמור על התקינות של שרשרת אספקת התוכנה.
• ‫substitutionOption: מוגדר ל-ALLOW_LOOSE. ההגדרה הזו נדרשת כדי לאלץ את Cloud Build להתעלם מפרמטרים דינמיים או מארגומנטים של סקריפט שלא נעשה בהם שימוש.
• ‫dynamicSubstitutions: צריך להגדיר את הערך true כדי לאפשר למשתני הערכה של המערכת, כמו ${BUILD_ID}, לפעול בצורה תקינה.
• ‫logging: אם מגדירים את הערך CLOUD_LOGGING_ONLY, יומני ה-build מוגבלים ל-Cloud Logging.

ממצא

הגדרת הבלוק artifacts כשמייצאים ארכיונים של תמונות ואישורים ל-Artifact Registry:

artifacts:
  generic_artifacts:
    - folder: '${_IMAGE_OUTPUT_PATH}'
      registry_path: '${_ARTIFACT_REGISTRY_RESOURCE_URI}'