שליחת גרסת build באמצעות CLI ו-API

בדף הזה מוסבר איך להתחיל בנייה ב-Cloud Build באופן ידני באמצעות Google Cloud CLI ו-Cloud Build API.

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

• כדי לבצע build באמצעות קובץ תצורת build של Cloud Build, צריך ליצור קובץ תצורת build.
• חשוב להכין את קוד המקור של האפליקציה ואת Dockerfile.
• צריך שיהיה לכם מאגר Docker לאחסון תמונות ב-Artifact Registry, או ליצור מאגר.

הרשאות IAM נדרשות

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

• אחסון יומני בנייה בקטגוריית היומנים שמוגדרת כברירת מחדל: עריכה ב-Cloud Build (roles/cloudbuild.builds.editor)
• אחסון יומני בנייה בקטגוריית היומנים שנוצרה על ידי המשתמש: עריכה ב-Cloud Build (roles/cloudbuild.builds.editor)
• שימוש במאגרים פרטיים: Cloud Build WorkerPool User (roles/cloudbuild.workerPoolUser)

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

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

הרצת בנייה

אפשר לציין את המקור של ה-build באמצעות השדה מקור ה-build. השדה 'מקור הבנייה' יכול להיות אחד מהערכים הבאים: storage_source, ‏ repo_source, ‏ git_source ו-connected_repository.

שליחת גרסאות Build באמצעות storage_source

gcloud

שימוש בקובץ Dockerfile:

קובץ ה-Dockerfile מכיל את כל המידע שנדרש כדי ליצור קובץ אימג' של Docker באמצעות Cloud Build.

כדי לבצע Build באמצעות Dockerfile, מריצים את הפקודה הבאה מהספרייה שמכילה את קוד המקור ואת Dockerfile:

gcloud builds submit --tag LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME

כאשר:

• ‫LOCATION: המיקום האזורי או הרב-אזורי של מאגר Docker ב-Artifact Registry.
• ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
• ‫REPOSITORY: השם של מאגר Artifact Registry.
• ‫IMAGE_NAME: השם של קובץ אימג' של קונטיינר שרוצים לבנות.

השם המלא של קובץ האימג' שייבנה הוא LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME. קובצי אימג' שמועברים בדחיפה ל-Artifact Registry פועלים לפי מוסכמת מתן השמות של Artifact Registry.

הפקודה gcloud builds submit:

• דוחס את קוד האפליקציה, Dockerfile, ואת כל הנכסים האחרים בספרייה הנוכחית, כפי שמצוין על ידי ..
• מתחילים לבצע build במיקום LOCATION באמצעות הקבצים שהועלו כקלט.
• מתייג את התמונה באמצעות השם שצוין.
• מעבירה בדחיפה את קובץ האימג' שנוצר אל Artifact Registry.

במהלך ה-build, הפלט שלו מוצג בחלון של ה-shell או הטרמינל. בסיום ה-build, הפלט אמור להיראות כך:

    DONE
    ---------------------------------------------------------------------------------
    ID                                    CREATE_TIME                DURATION STATUS
    $BUILD_ID                             2023-10-28T15:21:18+00:00  12S      SUCCESS

כאשר $BUILD_ID הוא המזהה הייחודי של הגרסה.

באמצעות קובץ התצורה של Cloud Build:

כדי לשלוח build באמצעות קובץ התצורה של ה-build, מריצים את הפקודה הבאה:

    gcloud builds submit --config BUILD_CONFIG SOURCE

כאשר:

• ‫BUILD_CONFIG הוא הנתיב לקובץ התצורה של ה-build.
• ‫SOURCE הוא הנתיב או קוד המקור של כתובת ה-URL.

כשמריצים את gcloud builds submit בפעם הראשונה בפרויקט Google Cloud ,‏ Cloud Build יוצר קטגוריה של Cloud Storage בשם [YOUR_PROJECT_NAME]_cloudbuild באותו פרויקט. ‫Cloud Build משתמש בקטגוריה הזו כדי לאחסן קוד מקור שבו אתם עשויים להשתמש ב-builds. ‫Cloud Build לא מוחק באופן אוטומטי את התוכן בדלי הזה. כדי למחוק אובייקטים שכבר לא משמשים אתכם לבנייה, אתם יכולים להגדיר את מחזור החיים בקטגוריה או למחוק את האובייקטים באופן ידני.

הפקודה הבאה מדגימה איך לשלוח cloudbuild.yaml בקשת build באמצעות קוד מקור שמאוחסן בקטגוריה של Cloud Storage.

    gcloud builds submit --config cloudbuild.yaml \
        gs://BUCKET/SOURCE.tar.gz

כאשר:

• ‫BUCKET הוא השם של הקטגוריה ב-Cloud Storage שמכילה את קוד המקור שרוצים לבנות.
• ‫SOURCE הוא השם של קובץ קוד המקור הדחוס.

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

    gcloud builds submit --config=cloudbuild.yaml .

API

כדי לשלוח את בקשת ה-Build באמצעות curl:

1. יוצרים קובץ בשם request.json עם התוכן הבא:

   {
       "source": {
           "storageSource": {
               "bucket": "BUCKET",
               "object": "SOURCE.tar.gz"
           }
       },
       "steps": [{
           "name": "gcr.io/cloud-builders/docker",
           "args": [
               "build",
               "-t",
               "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME",
               "."
           ]
       }],
       "images": [
           "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME"
       ]
   }
   

   כאשר:

   • ‫BUCKET הוא השם של קטגוריה של Cloud Storage שמכילה את קוד המקור שרוצים לבנות.
   • ‫SOURCE הוא השם של קובץ קוד המקור הדחוס.
   • ‫IMAGE_NAME הוא שם האימג' שרוצים ליצור.
   • ‫LOCATION: המיקום האזורי או הרב-אזורי של מאגר Docker ב-Artifact Registry.
   • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
   • ‫REPOSITORY: השם של מאגר Docker ב-Artifact Registry.
   הערה: בזמן ה-build, מערכת Cloud Build מחליפה באופן אוטומטי את $PROJECT_ID במזהה הפרויקט.

   בבקשת ה-build הזו, ‏ Cloud Build קורא לשלב ה-build‏ docker עם הארגומנטים build -t LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY ..

   השם המלא של קובץ האימג' שייבנה הוא LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY.

   קובצי אימג' שמועברים בדחיפה ל-Artifact Registry פועלים לפי מוסכמת מתן השמות של Artifact Registry.

2. מריצים את הפקודה הבאה, כאשר PROJECT_ID הוא מזהה הפרויקטGoogle Cloud ו-REGION הוא אחד מהאזורים הנתמכים:

   curl -X POST -T request.json -H "Authorization: Bearer $(gcloud config config-helper \
       --format='value(credential.access_token)')" \
       https://cloudbuild.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/builds
   

   בפקודה הזו, curl שולח את request.json בקריאת POST לנקודת הקצה builds של ה-method projects.builds.create ב-API.

   הפקודה מציגה פרטים על ה-build בחלון של מעטפת הפקודות או הטרמינל. הפלט הוא תגובת JSON שדומה לזו:

       {
           "name": "operations/build/$PROJECT-ID/NmZhZW...",
           "metadata": {
               "@type": "type.googleapis.com/google.devtools.cloudbuild.v1.BuildOperationMetadata",
               "build": {
                   "id": $BUILD-ID,
                   "status": "QUEUED",
                   "source": {
                       "storageSource": {
                           "bucket": "BUCKET",
                           "object": "SOURCE.tar.gz"
                       }
                   },
                   "createTime": "2017-05-12T18:58:07.341526Z",
                   "steps": [
                   {
                       "name": "gcr.io/cloud-builders/docker",
                       "args": [
                           "build",
                           "-t",
                           "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME",
                           "."
                       ]
                   }
                   ],
                   "timeout": "600s",
                   "images": [
                       "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME"
                   ],
                   "projectId": $PROJECT-ID,
                   "logsBucket": "gs://...",
                   "sourceProvenance": {
                       "resolvedStorageSource": {
                           "bucket": "BUCKET",
                           "object": "SOURCE.tar.gz"
                           "generation": "..."
                       }
                   },
                   "logUrl": "https://console.cloud.google.com/cloud-build/builds/...?project=$PROJECT_ID"
               }
           }
       }
   

   התגובה בפורמט JSON מבוססת על משאב Operation ב-Cloud Build API. השדה metadata מבוסס על המשאב Build. הסטטוס QUEUED מציין שה-build ממתין להרצה.

שליחת גרסאות Build באמצעות connected_repository

gcloud

כדי להריץ בקשת build עם מקור build ממאגר משאבים מדור שני, מריצים את הפקודה הבאה:

gcloud builds submit REPOSITORY --revision=REVISION --config=BUILD_CONFIG LOCATION

כאשר:

• ‫LOCATION הוא המיקום האזורי או המיקום של מספר אזורים של מאגר Docker ב-Artifact Registry.
• ‫REPOSITORY: השם של מאגר Cloud Build מהדור השני, בפורמט projects/*/locations/*/connections/*/repositories/*.
• ‫REVISION הוא השינוי שיש לאחזר ממאגר Git, כמו הסתעפות, תג, SHA של קומיט או כל הפניה של Git.
• ‫BUILD_CONFIG הוא הנתיב לקובץ התצורה של ה-build.

במהלך תהליך ה-build, הפלט שלו מוצג בחלון של ה-shell או הטרמינל. בסיום ה-build, הפלט אמור להיראות כך:

    DONE
    ---------------------------------------------------------------------------------
    ID                                    CREATE_TIME                DURATION STATUS
    $BUILD_ID                             2023-10-28T15:21:18+00:00  12S      SUCCESS

כאשר $BUILD_ID הוא המזהה הייחודי של הגרסה.

‫gcloudignore: כשכוללים קוד מקור לבנייה, הפקודה הקודמת מעלה את כל הקבצים בספרייה שצוינה אל Google Cloudכדי לבנות. אם רוצים להחריג קבצים מסוימים בספרייה, אפשר לכלול קובץ בשם .gcloudignore בספריית ההעלאה ברמה העליונה. המערכת תתעלם מהקבצים שצוינו בו. אם הקובץ .gcloudignore לא נמצא בספריית ההעלאה ברמה העליונה, אבל יש קובץ .gitignore, ה-CLI של gcloud יוצר קובץ .gcloudignore שתואם ל-Git, שמכבד את הקבצים שצוינו ב-.gitignore. מידע נוסף זמין במאמרי העזרה בנושא gcloudignore.

אם אין לכם קוד מקור להעברה אל ה-build, משתמשים בדגל --no-source, כאשר BUILD_CONFIG הוא הנתיב לקובץ ההגדרות של ה-build:

    gcloud builds submit --config CONFIG_FILE_PATH SOURCE_DIRECTORY

API

כדי לשלוח את בקשת ה-Build באמצעות curl:

1. יוצרים קובץ בשם request.json עם התוכן הבא:

   {
       "source": {
           "connectedRepository": {
               "repository": "REPOSITORY",
               "revision": "REVISION"
           }
       },
       "steps": [{
           "name": "gcr.io/cloud-builders/docker",
           "args": [
               "build",
               "-t",
               "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME",
               "."
           ]
       }],
       "images": [
           "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME"
       ]
   }
   

   כאשר:

   • ‫REPOSITORY: השם של מאגר Cloud Build מהדור השני, בפורמט projects/*/locations/*/connections/*repositories/*.
   • ‫REVISION הוא השינוי שיש לאחזר ממאגר Git, כמו הסתעפות, תג, SHA של קומיט או כל הפניה של Git.
   • ‫IMAGE_NAME הוא שם האימג' שרוצים ליצור.
   • ‫LOCATION: המיקום האזורי או הרב-אזורי של מאגר Docker ב-Artifact Registry.
   • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
   הערה: בזמן ה-build, מערכת Cloud Build מחליפה באופן אוטומטי את $PROJECT_ID במזהה הפרויקט.

   בבקשת ה-build הזו, ‏ Cloud Build קורא לשלב ה-build‏ docker עם הארגומנטים build -t LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME ..

   השם המלא של קובץ האימג' שייבנה הוא LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME. קובצי אימג' שמועברים בדחיפה ל-Artifact Registry פועלים לפי מוסכמת מתן השמות של Artifact Registry.

2. מריצים את הפקודה הבאה, כאשר PROJECT_ID הוא מזהה הפרויקט שלכם ו-REGION הוא אחד מהאזורים הנתמכים:Google Cloud

   curl -X POST -T request.json -H "Authorization: Bearer $(gcloud config config-helper \
       --format='value(credential.access_token)')" \
       https://cloudbuild.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/builds
   

   בפקודה הזו, curl שולח את request.json בקריאת POST לנקודת הקצה builds של ה-method projects.builds.create ב-API.

   הפקודה מציגה פרטים על ה-build בחלון של מעטפת הפקודות או הטרמינל. הפלט הוא תגובת JSON שדומה לזו:

       {
           "name": "operations/build/$PROJECT-ID/NmZhZW...",
           "metadata": {
               "@type": "type.googleapis.com/google.devtools.cloudbuild.v1.BuildOperationMetadata",
               "build": {
                   "id": $BUILD-ID,
                   "status": "QUEUED",
                   "source": {
                       "connectedRepository": {
                           "repository": "REPOSITORY",
                           "revision": "REVISION"
                       }
                   },
                   "createTime": "2017-05-12T18:58:07.341526Z",
                   "steps": [
                   {
                       "name": "gcr.io/cloud-builders/docker",
                       "args": [
                           "build",
                           "-t",
                           "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME",
                           "."
                       ]
                   }
                   ],
                   "timeout": "600s",
                   "images": [
                       "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME"
                   ],
                   "projectId": PROJECT_ID,
                   "logsBucket": "gs://...",
                   "sourceProvenance": {
                       "resolvedConnectedRepository": {
                           "repository": "REPOSITORY",
                           "revision": "REVISION.tar.gz"
                           "generation": "..."
                       }
                   },
                   "logUrl": "https://console.cloud.google.com/cloud-build/builds/...?project=PROJECT_ID"
               }
           }
       }
   

   התגובה בפורמט JSON מבוססת על משאב Operation ב-Cloud Build API. השדה metadata מבוסס על המשאב Build. הסטטוס QUEUED מציין שה-build ממתין להרצה.

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

• איך יוצרים טריגרים ידניים
• איך צופים בתוצאות של בניית האפליקציה
• איך פותרים בעיות שקשורות לבנייה