יצירת קובץ תצורת build

בדף הזה מוסבר איך ליצור קובץ הגדרות build שאפשר להשתמש בו כדי להתחיל build ב-Cloud Build.

קובץ תצורת build מגדיר את השדות שנדרשים ל-Cloud Build כדי לבצע את המשימות. אם אתם מתחילים תהליכי build באמצעות כלי שורת הפקודה gcloud או טריגרים של build, תצטרכו קובץ תצורת build. אפשר לכתוב את קובץ הגדרות ה-build באמצעות תחביר YAML או JSON.

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

במאמר סקירה כללית על הגדרת build מוסבר על השדות שאפשר לכלול בקובץ הגדרת build.

יצירת תצורת build

בשלבים הבאים מוסבר איך ליצור קובץ תצורה בסיסי של build. כל אחד מהשדות בקובץ הגדרת ה-build מגדיר חלק מהמשימה שרוצים לבצע. השדה היחיד שחובה למלא בקובץ ההגדרות של ה-build הוא השדה name של שלב. כל שאר השדות הם אופציונליים.

הערה: קובץ ההגדרות לדוגמה שמוזכר בדף הזה לא כולל את כל השדות הזמינים. מידע על כל השדות שאפשר לכלול בקובץ הגדרות build זמין במאמר סקירה כללית על הגדרות build.

YAML

1. יוצרים את קובץ התצורה של ה-build. בתיקיית השורש של הפרויקט, יוצרים קובץ בשם cloudbuild.yaml. זהו קובץ התצורה של Cloud Build.

2. מוסיפים את השדה 'שלבים'. הקטע steps בקובץ התצורה של ה-build מכיל את שלבי ה-build שרוצים ש-Cloud Build יבצע.

   steps:
   

3. מוסיפים את השלב הראשון. בקטע steps:, מוסיפים שדה name ומפנים אותו לקובץ אימג' של קונטיינר כדי להריץ את המשימה. ‫Cloud Build והקהילה של המפתחים שלו מספקים כמה קובצי אימג' של קונטיינרים עם כלים ושפות נפוצים שמותקנים בהם. אתם יכולים להשתמש בכל אחת מהתמונות האלה (שנקראות גם Cloud Builders) או בכל תמונה שזמינה לציבור בשלב בנייה. מידע על סוגים שונים של תמונות קונטיינר שאפשר להשתמש בהן בשלב build זמין במאמר Cloud Builders.

   בקטע הקוד הבא מוצג שלב build עם docker builder gcr.io/cloud-builders/docker, שהוא קובץ אימג' של קונטיינר שמריץ Docker.

   steps:
   - name: 'gcr.io/cloud-builders/docker'
   

4. הוספת ארגומנטים לשלב. השדה args של שלב מסוים מקבל רשימה של ארגומנטים ומעביר אותם אל ה-builder שאליו מתייחס השדה name. אם לכלי הבנייה בשדה name יש נקודת כניסה, משתמשים ב-args ברשימה כדי לגשת לנקודת הכניסה הזו. אם לרכיב ה-builder בשדה name אין נקודת כניסה, הרכיב הראשון ב-args משמש כנקודת הכניסה.

   בדוגמה הבאה:

   • ‫build היא נקודת הכניסה ל-Docker cloud builder.
   • ‫-t הוא תג Docker.
   • ‫us-central1-docker.pkg.dev/${PROJECT_ID}/my-docker-repo/my-image הוא השם של קובץ האימג' שייבנה ב-Artifact Registry. שלב ה-build משתמש בהחלפה שמוגדרת כברירת מחדל למזהה הפרויקט, ולכן הערך הזה מוחלף אוטומטית בזמן ה-build.

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

     steps:
     - name: 'gcr.io/cloud-builders/docker'
       args: ['build', '-t', 'us-central1-docker.pkg.dev/${PROJECT_ID}/my-docker-repo/my-image', '.']
     

5. הוספת עוד שלבים. אתם יכולים להוסיף כמה שלבי build שתרצו לקובץ התצורה של ה-build, על ידי הוספה של שדות name נוספים והפניה שלהם אל cloud builders.

   בקטע הקוד הבא מופיעים עוד שני שלבים בקובץ build config:

   • שלב docker build להפעלת הפקודה docker push כדי להעביר בדחיפה את קובץ האימג' שנוצר בשלב הקודם אל Artifact Registry.

   • שלב build לפקודת Google Cloud SDK עם נקודת הכניסה gcloudשצוינה, שיוצרת מכונה וירטואלית ב-Compute Engine מקובץ האימג' של הקונטיינר ב-Artifact Registry. השדה env כלול כדי לציין את האזור והתחום של Compute Engine.

      - name: 'gcr.io/cloud-builders/docker'
        args: ['push', 'us-central1-docker.pkg.dev/${PROJECT_ID}/my-docker-repo/my-image']
      - name: 'gcr.io/google.com/cloudsdktool/cloud-sdk'
        entrypoint: 'gcloud'
        args: ['compute', 'instances', 'create-with-container', 'my-vm-name', '--container-image', 'us-central1-docker.pkg.dev/${PROJECT_ID}/my-docker-repo/my-image']
        env:
        - 'CLOUDSDK_COMPUTE_REGION=us-central1'
        - 'CLOUDSDK_COMPUTE_ZONE=us-central1-a'
     

6. הוספת שדות נוספים של תצורת build. אפשר להגדיר את הבנייה עוד יותר על ידי הוספת שדות כמו machineType,‏ tags או timeout. רשימה מלאה של השדות שאפשר לכלול בקובץ התצורה של ה-build מופיעה במאמר סקירה כללית על תצורת ה-build.

   בדוגמה הבאה, פסק הזמן של שלב ה-build‏ gcr.io/google.com/cloudsdktool/cloud-sdk הוא 240 שניות.

     - name: 'gcr.io/google.com/cloudsdktool/cloud-sdk'
       entrypoint: 'gcloud'
       timeout: 240s
       args: ['compute', 'instances', 'create-with-container', 'my-vm-name', '--container-image', 'us-central1-docker.pkg.dev/${PROJECT_ID}/my-docker-repo/my-image']
       env:
       - 'CLOUDSDK_COMPUTE_REGION=us-central1'
       - 'CLOUDSDK_COMPUTE_ZONE=us-central1-a'
   

   בקטע הקוד הבא אפשר לראות דוגמה מלאה של קובץ תצורה בסיסי:

   steps:
     # Docker Build
     - name: 'gcr.io/cloud-builders/docker'
       args: ['build', '-t', 
              'us-central1-docker.pkg.dev/${PROJECT_ID}/my-docker-repo/myimage', 
              '.']
   
     # Docker Push
     - name: 'gcr.io/cloud-builders/docker'
       args: ['push', 
              'us-central1-docker.pkg.dev/${PROJECT_ID}/my-docker-repo/myimage']
   
     # Entrypoint, timeout and environment variables
     - name: 'gcr.io/google.com/cloudsdktool/cloud-sdk'
       entrypoint: 'gcloud'
       timeout: 240s
       args: ['compute', 'instances', 
              'create-with-container', 'my-vm-name',
              '--container-image', 
              'us-central1-docker.pkg.dev/${PROJECT_ID}/my-docker-repo/myimage']
       env:
         - 'CLOUDSDK_COMPUTE_REGION=us-central1'
         - 'CLOUDSDK_COMPUTE_ZONE=us-central1-a'

   בדוגמה, תמונות של קונטיינרים מאוחסנות ב-Artifact Registry. אם תהליך הבנייה יוצר ארטיפקטים שאינם קונטיינרים, אפשר לאחסן אותם ב-Cloud Storage באמצעות השדה artifacts. הוראות מפורטות מופיעות במאמר אחסון תמונות וארטיפקטים.

JSON

1. יוצרים את קובץ התצורה של ה-build. בתיקיית השורש של הפרויקט, יוצרים קובץ בשם cloudbuild.json. זהו קובץ התצורה של Cloud Build.

2. מוסיפים את השדה 'שלבים'. הקטע steps בקובץ התצורה של ה-build מכיל את שלבי ה-build שרוצים ש-Cloud Build יבצע.

   {
      "steps":
   }
   

3. מוסיפים את השלב הראשון. בקטע steps:, מוסיפים שדה name ומפנים אותו לקובץ אימג' של קונטיינר כדי להריץ את המשימה. ‫Cloud Build וקהילת המפתחים שלו מספקים כמה קובצי אימג' של קונטיינרים עם כלים ושפות נפוצים שמותקנים בהם. אתם יכולים להשתמש בכל אחת מהתמונות האלה (שנקראות גם Cloud Builders) או בכל תמונה שזמינה לציבור בשלב בנייה. מידע על סוגים שונים של תמונות קונטיינר שאפשר להשתמש בהן בשלב build זמין במאמר Cloud Builders.

   בקטע הקוד הבא מוצג שלב build עם docker builder gcr.io/cloud-builders/docker, שהוא קובץ אימג' של קונטיינר שמריץ Docker.

   {
      "steps": [
         {
            "name": "gcr.io/cloud-builders/docker"
         }
      ]
   }
   

4. הוספת ארגומנטים לשלב. השדה args של שלב מסוים מקבל רשימה של ארגומנטים ומעביר אותם אל ה-builder שאליו מתייחס השדה name. אם לכלי הבנייה בשדה name יש נקודת כניסה, משתמשים ב-args ברשימה כדי לגשת לנקודת הכניסה הזו. אם לרכיב ה-builder בשדה name אין נקודת כניסה, הרכיב הראשון ב-args משמש כנקודת הכניסה.

   בדוגמה הבאה:

   • ‫build היא נקודת הכניסה ל-Docker cloud builder.
   • ‫-t הוא תג Docker.
   • ‫us-central1-docker.pkg.dev/${PROJECT_ID}/my-docker-repo/my-image הוא השם של קובץ האימג' שייבנה ב-Artifact Registry. שלב ה-build משתמש בהחלפה שמוגדרת כברירת מחדל למזהה הפרויקט, ולכן הערך הזה מוחלף אוטומטית בזמן ה-build.

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

     {
        "steps": [
           {
              "name": "gcr.io/cloud-builders/docker",
              "args": [
                 "build",
                 "-t",
                 "us-central1-docker.pkg.dev/${PROJECT_ID}/my-docker-repo/myimage",
                 "."
              ]
           }
        ]
     }
     

5. הוספת עוד שלבים. אתם יכולים להוסיף כמה שלבי build שתרצו לקובץ התצורה של ה-build, על ידי הוספה של שדות name נוספים והפניה שלהם אל cloud builders.

   בקטע הקוד הבא מופיעים עוד שני שלבים בקובץ build config:

   • שלב docker build להפעלת הפקודה docker push כדי להעביר בדחיפה את קובץ האימג' שנוצר בשלב הקודם אל Artifact Registry.

   • שלב build לפקודת Google Cloud SDK עם נקודת הכניסה gcloudשצוינה, שיוצרת מכונה וירטואלית ב-Compute Engine מקובץ האימג' של הקונטיינר ב-Artifact Registry. השדה env כלול כדי לציין את האזור והתחום של Compute Engine.

           {
              "name": "gcr.io/cloud-builders/docker",
              "args": [
                 "push",
                 "us-central1-docker.pkg.dev/${PROJECT_ID}/my-docker-repo/myimage"
              ]
           },
           {
              "name": "gcr.io/google.com/cloudsdktool/cloud-sdk",
              "entrypoint": "gcloud",
              "args": [
                 "compute",
                 "instances",
                 "create-with-container",
                 "my-vm-name",
                 "--container-image",
                 "us-central1-docker.pkg.dev/${PROJECT_ID}/my-docker-repo/myimage"
              ],
              "env": [
                 "CLOUDSDK_COMPUTE_REGION=us-central1",
                 "CLOUDSDK_COMPUTE_ZONE=us-central1-a"
              ]
           }
     

6. הוספת שדות נוספים של תצורת build. אפשר להגדיר את הבנייה עוד יותר על ידי הוספת שדות כמו machineType,‏ tags או timeout. רשימה מלאה של השדות שאפשר לכלול בקובץ התצורה של ה-build מופיעה במאמר סקירה כללית על תצורת ה-build.

   בדוגמה הבאה, פסק הזמן של שלב ה-build‏ gcr.io/google.com/cloudsdktool/cloud-sdk הוא 240 שניות.

         {
            "name": "gcr.io/google.com/cloudsdktool/cloud-sdk",
            "entrypoint": "gcloud",
            "timeout": "240s",
            "args": [
               "compute",
               "instances",
               "create-with-container",
               "my-vm-name",
               "--container-image",
               "us-central1-docker.pkg.dev/${PROJECT_ID}/my-docker-repo/myimage"
            ],
            "env": [
               "CLOUDSDK_COMPUTE_REGION=us-central1",
               "CLOUDSDK_COMPUTE_ZONE=us-central1-a"
            ]
         }
   

   בקטע הקוד הבא אפשר לראות דוגמה מלאה של קובץ תצורה בסיסי:

   {
      "steps": [
         {
            "name": "gcr.io/cloud-builders/docker",
            "args": [
               "build",
               "-t",
               "us-central1-docker.pkg.dev/${PROJECT_ID}/my-docker-repo/myimage",
               "."
            ]
         },
         {
            "name": "gcr.io/cloud-builders/docker",
            "args": [
               "push",
               "us-central1-docker.pkg.dev/${PROJECT_ID}/my-docker-repo/myimage"
            ]
         },
         {
            "name": "gcr.io/google.com/cloudsdktool/cloud-sdk",
            "entrypoint": "gcloud",
            "timeout": "240s",
            "args": [
               "compute",
               "instances",
               "create-with-container",
               "my-vm-name",
               "--container-image",
               "us-central1-docker.pkg.dev/${PROJECT_ID}/my-docker-repo/myimage"
            ],
            "env": [
               "CLOUDSDK_COMPUTE_REGION=us-central1",
               "CLOUDSDK_COMPUTE_ZONE=us-central1-a"
            ]
         }
      ]
   }
   

   בדוגמה, תמונות של קונטיינרים מאוחסנות ב-Artifact Registry. אם תהליך הבנייה יוצר ארטיפקטים שאינם קונטיינרים, אפשר לאחסן אותם ב-Cloud Storage באמצעות השדה artifacts. הוראות מפורטות מופיעות במאמר אחסון תמונות וארטיפקטים.

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

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