חיבור ל-Cloud Build

בדף הזה מוסבר איך להגדיר את Cloud Build לאחסון ארטיפקטים שנבנו במאגר של Artifact Registry.

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

1. אם מאגר היעד לא קיים ב-Artifact Registry, צריך ליצור מאגר חדש.

2. אם Cloud Build והמאגר נמצאים בפרויקטים שונים, או אם אתם משתמשים בחשבון שירות שצוין על ידי המשתמש כדי להריץ בנייה, צריך להעניק את התפקיד Artifact Registry Writer לחשבון השירות של הבנייה בפרויקט עם המאגרים.

   לחשבון השירות שמוגדר כברירת מחדל ב-Cloud Build יש גישה לביצוע הפעולות הבאות במאגר באותו פרויקט Google Cloud :

   • העלאה והורדה של פריטי מידע שנוצרים בתהליך פיתוח (Artifact)
   • יצירת מאגרי gcr.io ב-Artifact Registry

הגדרת Docker build

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

כדי להגדיר את הבנייה:

1. בקובץ התצורה של ה-build, מוסיפים את השלב ליצירה ולתיוג של קובץ האימג'.

   steps:
   - name: 'gcr.io/cloud-builders/docker'
     args: [ 'build', '-t', '${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/${_IMAGE}', '.' ]
   images:
   - '${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/${_IMAGE}'
   

   בקטע הקוד הזה נעשה שימוש בהחלפות של Cloud Build. הגישה הזו שימושית אם רוצים להשתמש באותו קובץ הגדרות build כדי לדחוף תמונות למאגרי תמונות עבור סביבות שונות, כמו בדיקה, staging או ייצור.

   • ‫${_LOCATION}, ${_REPOSITORY} ו-${_IMAGE} הם משתנים שמוגדרים על ידי המשתמש למיקום המאגר, לשם המאגר ולתמונה. מציינים את הערכים של המשתנים האלה בזמן הבנייה.

   • ‫$PROJECT_ID הוא החלפה שמוגדרת כברירת מחדל ש-Cloud Build פותרת באמצעות Google Cloud מזהה הפרויקט$PROJECT_ID של הבנייה.

     • אם מריצים את הפקודה gcloud builds submit, ‏ Cloud Build משתמש במזהה הפרויקט הפעיל בסשן gcloud.
     • אם משתמשים בטריגר לפיתוח גרסת Build, ‏ Cloud Build משתמש במזהה של הפרויקט שבו Cloud Build פועל.

     לחלופין, אפשר להשתמש בהחלפה שהוגדרה על ידי המשתמש במקום ב-$PROJECT_ID כדי לציין מזהה פרויקט בזמן הבנייה.

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

   • ‫us-east1 למיקום המאגר
   • ‫my-repo בשם המאגר
   • ‫my-image בשם התמונה

   gcloud builds submit --config=cloudbuild.yaml \
     --substitutions=_LOCATION="us-east1",_REPOSITORY="my-repo",_IMAGE="my-image" .
   

הגדרת build של Go

אחרי שמעניקים הרשאות למאגר היעד, אפשר להגדיר את הבנייה. בהוראות הבאות מוסבר איך להגדיר את ה-build להעלאת מודול Go למאגר Go.

כדי להגדיר את הבנייה:

1. כדי להעלות מודול Go למאגר Go ב-build, מוסיפים את השלבים הבאים לקובץ התצורה של ה-build:

   steps:
   - name: gcr.io/cloud-builders/gcloud
   args:
   - 'artifacts'
   - 'go'
   - 'upload'
   - '--project=$PROJECT_ID'
   - '--location=${_LOCATION}'
   - '--repository=${_REPOSITORY}'
   - '--module-path=${_MODULE_PATH}'
   - '--version=$TAG_NAME'
   

   קובץ התצורה של ה-build כולל החלפות של Cloud Build. הגישה הזו שימושית אם רוצים להשתמש באותו קובץ הגדרות של build כדי להעלות חבילות למאגרי מידע עבור סביבות שונות, כמו בדיקה, Staging או ייצור.

   • ‫${_LOCATION},‏ ${_REPOSITORY} ו-${_MODULE_PATH} הם תחליפים שמוגדרים על ידי המשתמש למיקום המאגר, לשם המאגר ולנתיב המודול. אתם מציינים את הערכים של המשתנים האלה בזמן הבנייה.

   • ‫$PROJECT_ID ו-$TAG_NAME הם תחליפים שמוגדרים כברירת מחדל ש-Cloud Build מחליף בערכים הבאים:

     • ‫$PROJECT_ID מוחלף במזהה הפרויקט של הגרסה. Google Cloud

       • אם מריצים את הפקודה gcloud builds submit, ‏ Cloud Build משתמש במזהה הפרויקט הפעיל בסשן gcloud.
       • אם משתמשים בטריגר לפיתוח גרסת Build, ‏ Cloud Build משתמש במזהה של הפרויקט שבו Cloud Build פועל.

       לחלופין, אפשר להשתמש בהחלפה שהוגדרה על ידי המשתמש במקום ב-$PROJECT_ID כדי לציין מזהה פרויקט בזמן הבנייה.

     • ‫$TAG_NAME מוחלף בשם התג כדי לתמוך במוסכמה של Go להשתמש בתגי Git כמספרי גרסאות.

2. כדי להתקין את החבילה ממאגר Go, מוסיפים את השלבים הבאים לקובץ התצורה של ה-build:

   • מוסיפים נקודת קצה אזורית של Artifact Registry למיקום המאגר בקובץ .netrc.
   • מריצים את כלי העזר לפרטי הכניסה כדי לרענן את אסימוני OAuth.
   • מריצים את הפקודה go run. אפשר גם לשנות את הפקודה ל-go build כדי לקמפל את המודול, ל-go test כדי להריץ בדיקות או ל-go mod tidy כדי להוריד את התלות.

   בשלב הפקודה go, הערך של GOPROXY מוגדר למאגר Artifact Registry שמארח יחסי תלות פרטיים. אם למודול יש תלויות ציבוריות, אפשר להוסיף את ה-proxy הציבורי לרשימה GOPROXY המופרדת בפסיקים.

   steps:
   - name: golang
     entrypoint: go
     args: ['run', 'github.com/GoogleCloudPlatform/artifact-registry-go-tools/cmd/auth@v0.1.0', 'add-locations', '--locations=${_LOCATION}']
     env:
     # Set GOPROXY to the public proxy to pull the credential helper tool
     - 'GOPROXY=https://proxy.golang.org'
   - name: golang
     entrypoint: go
     args: ['run', 'github.com/GoogleCloudPlatform/artifact-registry-go-tools/cmd/auth@v0.1.0', 'refresh']
     env:
     # Set GOPROXY to the public proxy to pull the credential helper tool
     - 'GOPROXY=https://proxy.golang.org'
   - name: golang
     entrypoint: go
     args: ['run', '.']
     env:
     - 'GOPROXY=https://${_LOCATION}-go.pkg.dev/${_PROJECT_ID}/${_REPOSITORY}'
   options:
     env:
     # Disable GO sumdb checks for private modules.
     - 'GONOSUMDB=${_MODULE_PATH}'
   

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

   • ‫us-east1 למיקום המאגר
   • ‫my-project למזהה הפרויקט
   • ‫my-repo בשם המאגר
   • example.com/greetings עבור נתיב המודול

   gcloud builds submit --config=cloudbuild.yaml \
     --substitutions=_LOCATION="us-east1",_PROJECT_ID="my-project",_REPOSITORY="my-repo",_MODULE_PATH="example.com/greetings" .
   

הגדרת build של Java

אחרי שמעניקים הרשאות למאגר היעד, אפשר להגדיר את הבנייה. בהוראות הבאות מוסבר איך להגדיר את הגרסה כדי להעלות חבילת Java למאגר Maven.

כדי להגדיר את הבנייה:

1. מגדירים אימות ל-Maven. חשוב לוודא שציינתם את פרויקט היעד ואת המאגר הנכונים בקובץ pom.xml.

2. בקובץ התצורה של ה-build ב-Cloud Build, מוסיפים את השלב להעלאת החבילה באמצעות Maven:

   steps:
   - name: gcr.io/cloud-builders/mvn
     args: ['deploy']
   

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

   gcloud builds submit
   

הגדרת תצורה של build ב-Node.js

אחרי שמעניקים הרשאות למאגר היעד, אפשר להגדיר את הבנייה. בהוראות הבאות מוסבר איך להגדיר את ה-build כדי להעלות חבילת Node.js למאגר npm.

כדי להגדיר את הבנייה:

1. מוסיפים את מאגר Artifact Registry לקובץ .npmrc בפרויקט Node.js. הקובץ נמצא בספרייה עם קובץ package.json.

   @SCOPE:registry=https://LOCATION-npm.pkg.dev/PROJECT_ID/REPOSITORY
   //LOCATION-npm.pkg.dev/PROJECT_ID/REPOSITORY/:always-auth=true
   

   • ‫SCOPE-NAME הוא שם ההיקף של npm שאותו רוצים לשייך למאגר. שימוש בהיקפים מבטיח שתמיד תפרסמו ותתקינו חבילות מהמאגר הנכון.
   • ‫PROJECT_ID הוא מזהה הפרויקט. Google Cloud
   • ‫LOCATION הוא המיקום האזורי או המיקום במספר אזורים של המאגר.
   • ‫REPOSITORY הוא שם המאגר.

2. מוסיפים סקריפט לקובץ package.json בפרויקט כדי לרענן את אסימון הגישה לאימות מול המאגר.

   "scripts": {
    "artifactregistry-login": "npx google-artifactregistry-auth"
   }
   

3. בקובץ התצורה של ה-build, מוסיפים את השלב להעלאת החבילה למאגר.

   steps:
   - name: gcr.io/cloud-builders/npm
     args: ['run', 'artifactregistry-login']
   - name: gcr.io/cloud-builders/npm
     args: ['publish', '${_PACKAGE}']
   

   ‫${_PACKAGE} הוא תחליף של Cloud Build שמייצג את ספריית הפרויקט של Node.js. אפשר לציין את הספרייה כשמריצים את הפקודה להרצת הבנייה.

   לדוגמה, הפקודה הזו מעלה את החבילה מספרייה בשם src:

   gcloud builds submit --config=cloudbuild.yaml \
       --substitutions=_PACKAGE="src" .
   

הגדרת build של Python

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

במאמר פיתוח אפליקציות ב-Python בחומרי העזר של Cloud Build מוסבר איך לפתח אפליקציית Python, להוסיף אותה לקונטיינר ואז להעביר אותה בדחיפה למאגר Docker.

כדי להגדיר את הבנייה:

1. בתיקייה שבה נמצא קובץ ההגדרות של ה-build ב-Cloud Build, יוצרים קובץ בשם requirements.txt עם התלות הבאה:

   twine
   keyrings.google-artifactregistry-auth
   

   • ‫Twine משמש להעלאת חבילות ל-Artifact Registry.
   • ‫keyrings.google-artifactregistry-auth הוא קצה העורפי של אוסף המפתחות של Artifact Registry שמטפל באימות באמצעות Artifact Registry עבור pip ו-Twine.

2. כדי להעלות חבילת Python למאגר Python ב-build, מוסיפים את השלבים הבאים לקובץ ההגדרות של ה-build:

   steps:
   - name: python
     entrypoint: pip
     args: ["install", "-r", "requirements.txt", "--user"]
   - name: python
     entrypoint: python
     args:
     - '-m'
     - 'twine'
     - 'upload'
     - '--repository-url'
     - 'https://${_LOCATION}-python.pkg.dev/$PROJECT_ID/${_REPOSITORY}/'
     - 'dist/*'
   

   בקטע הקוד הזה, בשלב הראשון מותקנים Twine והקצה העורפי של מחזיק המפתחות של Artifact Registry. בשלב השני, הקבצים של Python שנוצרו מועלים לספריית המשנה dist. אם הנתיבים לא תואמים לקטע הקוד, צריך להתאים את הנתיבים ל-requirements.txt ולקובצי Python שנוצרו.

   נתיב המאגר כולל החלפות של Cloud Build. הגישה הזו שימושית אם רוצים להשתמש באותו קובץ הגדרות של build כדי להעלות חבילות למאגרי מידע עבור סביבות שונות, כמו בדיקה, Staging או ייצור.

   • ‫${_LOCATION} ו-${_REPOSITORY} הם תחליפים שהמשתמש מגדיר למיקום המאגר, לשם המאגר ולשם החבילה. מציינים את הערכים של המשתנים האלה בזמן הבנייה.

   • ‫$PROJECT_ID הוא החלפה שמוגדרת כברירת מחדל ש-Cloud Build פותרת באמצעות Google Cloud מזהה הפרויקט$PROJECT_ID של הבנייה.

     • אם מריצים את הפקודה gcloud builds submit, ‏ Cloud Build משתמש במזהה הפרויקט הפעיל בסשן gcloud.
     • אם משתמשים בטריגר לפיתוח גרסת Build, ‏ Cloud Build משתמש במזהה של הפרויקט שבו Cloud Build פועל.

     לחלופין, אפשר להשתמש בהחלפה שהוגדרה על ידי המשתמש במקום ב-$PROJECT_ID כדי לציין מזהה פרויקט בזמן הבנייה.

3. כדי להתקין את החבילה ממאגר Python, מוסיפים שלב לקובץ הגדרות ה-build שמריץ את הפקודה pip install.

     steps:
     - name: python
       entrypoint: pip
       args:
       - 'install'
       - '--index-url'
       - 'https://${_LOCATION}-python.pkg.dev/$PROJECT_ID/${_REPOSITORY}/simple/'
       - '${_PACKAGE}'
       - '--verbose'
   

   קטע הקוד הזה כולל החלפה נוספת של ${_PACKAGE} לשם החבילה.

   הערה: החל מ-pip 21.2, אפשר להשתמש בדגל --verbose או בדגל -v עד שלוש פעמים כדי לקבל פלט נוסף לניפוי באגים. לדוגמה, כדי לקבל את רמת הפירוט הבאה של ניפוי הבאגים, משתמשים ב---verbose --verbose או ב--vv.

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

   • ‫us-east1 למיקום המאגר
   • ‫my-repo בשם המאגר
   • ‫my-package שם החבילה

   gcloud builds submit --config=cloudbuild.yaml \
     --substitutions=_LOCATION="us-east1",_REPOSITORY="my-repo",_PACKAGE="my-package" .
   

אחסון ארטיפקטים במאגר פרטי באמצעות אישורים עם חתימה עצמית

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

- name: gcr.io/cloud-builders/docker
  args:
    - run
    - --rm
    - --volume=/etc/docker/certs.d/:/etc/docker/certs.d/
    - --volume=certificates:/certificates
    - ubuntu
    - bash
    - -c
    - |
      cp /certificates/ca.crt /etc/docker/certs.d/quay.apps.cloud.inter
  volumes:
    - name: certificates
      path: /certificates