במאמר הזה מוסבר איך להגדיר את ה-builds כך שישתמשו בחשבון שירות בניהול המשתמש.
אם לא תציינו חשבון שירות בניהול המשתמש בשביל ה-builds, המערכת של Cloud Build תשתמש באופן אוטומטי בחשבון השירות שמוגדר כברירת מחדל ב-Cloud Build. יכול להיות שלחשבון השירות הזה, שמוגדר כברירת מחדל, יש הרשאות רחבות מדי, כמו גישה למאגרים שלכם ב-Cloud Source Repositories ולכל קטגוריה של Cloud Storage בפרויקט.
מומלץ לפעול לפי העיקרון של הרשאות מינימליות, ולהקצות לחשבונות השירות הרשאות ותפקידים שמוגבלים למשימה שהם מבצעים. לדוגמה, אתם יכולים להשתמש בחשבון שירות אחד כדי ליצור תמונות ולשלוח אותן ל-Artifact Registry, כמו שמוצג בבלוג שלGoogle Cloud .
לפני שמתחילים
-
מפעילים את Cloud Build API ואת IAM API, אם הם עדיין לא מופעלים.
התפקידים שנדרשים כדי להפעיל ממשקי API
כדי להפעיל ממשקי API, צריך את ההרשאה
serviceusage.services.enable. אם אתם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד "בעלים" (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד "אדמין בממשק 'שימוש בשירות'" (roles/serviceusage.serviceUsageAdmin). כך מקצים תפקידים. אם אתם מתכננים להשתמש בחשבון הזה כדי ליצור ולנהל פרטי כניסה לחשבון, לדוגמה כדי ליצור פרטי כניסה לטווח קצר, הפעילו את IAM Service Account Credentials API.
התפקידים שנדרשים כדי להפעיל ממשקי API
כדי להפעיל ממשקי API, צריך את ההרשאה
serviceusage.services.enable. אם אתם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד "בעלים" (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד "אדמין בממשק 'שימוש בשירות'" (roles/serviceusage.serviceUsageAdmin). כך מקצים תפקידים.אם עדיין לא עשיתם זאת, צרו חשבון שירות.
הגדרת חשבון השירות
כדי שלחשבון השירות שמנוהל על ידי המשתמש יהיו ההרשאות הנדרשות להרצת ה-builds, צריך להקצות לו תפקידי IAM. אפשר גם להגדיר את Cloud Build כך שיבחר באופן אוטומטי את חשבון השירות הזה לטריגרים חדשים.
-
במסוף Google Cloud , נכנסים לדף Permissions של settings Cloud Build:
בתפריט Service account, בוחרים את חשבון השירות. כדי לבחור חשבון שירות בפרויקט אחר, לוחצים על Switch project.
כדי להשתמש בחשבון השירות שנבחר כחשבון השירות לטריגרים חדשים, מפעילים את האפשרות Set as pre-selected for new triggers.
ברשימת השירותים של Google Cloud , מפעילים את תפקידי ה-IAM שרוצים להקצות לחשבון השירות.
אם התפקיד שאתם צריכים לצינור עיבוד הנתונים של ה-build לא מופיע כאן, אתם יכולים להקצות תפקידים נוספים בדף ההגדרות של IAM.
אם בחרתם חשבון שירות בפרויקט אחר, בצעו את השלבים שמפורטים בקטע הגדרה בפרויקטים שונים.
זיהוי חשבון השירות שצריך להגדיר
לפני שנותנים תפקידים, צריך לבדוק איזה חשבון שירות מוגדר ל-builds:
טריגרים קיימים לפיתוח גרסת build: בודקים את חשבון השירות שמוגדר בטריגר:
gcloud builds triggers describe TRIGGER_NAME \ --region=REGION \ --format="value(serviceAccount)"מחליפים את מה שכתוב בשדות הבאים:
-
TRIGGER_NAME: השם של הטריגר לפיתוח גרסת ה-Build. -
REGION: האזור של הטריגר לפיתוח גרסת ה-Build.
כך מפרשים את הפלט:
- אם פלט הפקודה הוא שם משאב של חשבון שירות בפורמט
projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL, צריך להקצות את התפקידים הנדרשים לחשבון הזה. הפלט הזה יכול לזהות חשבון שירות שמנוהל על ידי משתמש או את חשבון השירות שמוגדר כברירת מחדל ב-Compute Engine. - אם השדה
serviceAccountריק, הטריגר משתמש בחשבון השירות הקודם של Cloud Build. אפשר להשמיט אתserviceAccountכשיוצרים טריגר רק בפרויקטים שמשתמשים בחשבון השירות הקודם שמוגדר כברירת מחדל. בפרויקטים שבהם משתמשים בחשבון השירות שמוגדר כברירת מחדל ב-Compute Engine או מגבילים את חשבון השירות שמוגדר כברירת מחדל באמצעות מדיניות הארגון, יצירת הטריגר נכשלת עם שגיאתINVALID_ARGUMENTשמציינת שצריך לציין חשבון שירות (BYOSA is required when creating triggers). אם מדיניות הארגון מגבילה את חשבון השירות שמוגדר כברירת מחדל בזמן ה-build, ה-build נכשל עם השגיאהbuild.service_account must be specified due to the evaluation of the following org policies.
-
קבצי תצורה של build: אם אתם מריצים גרסאות build באופן ידני באמצעות
gcloud builds submit, בדקו את השדהserviceAccountבקובץcloudbuild.yaml. אם לא מציינים חשבון שירות, Cloud Build משתמש בחשבון השירות שמוגדר כברירת מחדל ל-build, או נכשל עם השגיאהbuild.service_account must be specified due to the evaluation of the following org policiesאם מדיניות הארגון מגבילה את חשבון השירות שמוגדר כברירת מחדל.
התפקידים הנדרשים
כדי לוודא שלחשבון השירות בניהול המשתמש יש את ההרשאות הנדרשות להרצת גרסאות build באמצעות חשבון שירות בניהול המשתמש, צריך לבקש מהאדמין להקצות לחשבון השירות בניהול המשתמש את תפקידי ה-IAM הבאים בפרויקט שבו מריצים את גרסאות ה-build:
-
כתיבה והעברה בסטרימינג של יומני build ל-Cloud Logging:
כותב יומנים (
roles/logging.logWriter) -
הורדת ארכיונים של מקורות או יחסי תלות מקטגוריות של Cloud Storage:
צפייה באובייקטים באחסון (
roles/storage.objectViewer)
להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.
יכול להיות שהאדמין גם יוכל לתת לחשבון השירות בניהול המשתמש את ההרשאות הנדרשות באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש אחרים.
התחזות לחשבון שירות
כדי לאפשר ל-Cloud Build ולטריגרים להריץ גרסאות build באמצעות חשבון שירות בניהול המשתמש, ודאו שההרשאות הבאות ניתנו בחשבון השירות בניהול המשתמש:
- למשתמש או לזהות האוטומציה שיוצרים, מעדכנים או מריצים באופן ידני את הטריגר לפיתוח גרסת ה-Build (או שולחים גרסאות Build באמצעות
gcloud builds submit), מקצים את התפקיד "משתמש בחשבון שירות" (roles/iam.serviceAccountUser), שכולל את ההרשאהiam.serviceAccounts.actAs. - לסוכן השירות של Cloud Build (
service-PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com), נדרשת ההרשאהiam.serviceAccounts.getAccessToken. באותו פרויקט, ההרשאה הזו כלולה כברירת מחדל בתפקיד "סוכן שירות של Cloud Build" (roles/cloudbuild.serviceAgent). אם התפקיד הזה הוסר, או אם חשבון השירות בניהול המשתמש נמצא בפרויקט אחר, צריך להקצות את התפקיד "יצירת אסימונים בחשבון שירות" (roles/iam.serviceAccountTokenCreator).
למידע נוסף על תפקידי IAM שבדרך כלל נדרשים ל-build, קראו את המידע הבא:
- חשבון השירות שמוגדר כברירת מחדל ב-Cloud Build.
- הגדרת הגישה למשאבים של Cloud Build.
- תפקידים והרשאות של IAM ב-Cloud Build.
הגדרת יומני build
כשמציינים חשבון שירות משלכם ל-builds, צריך לאחסן את יומני ה-build באחד מסוגי הקטגוריות הבאים:
קטגוריות של Cloud Storage בפרויקט של המשתמש. אלה יכולים להיות קטגוריות שנוצרו על ידי משתמשים או קטגוריות שנוצרו על ידיGoogle Cloudובבעלות משתמשים.
אם אתם יוצרים קטגוריית יומנים, ודאו שאין לה מדיניות שמירת נתונים, כי המדיניות עשויה למנוע מ-Cloud Build לכתוב יומני build לקטגוריה.
אי אפשר לאחסן את היומנים בקטגוריית יומנים שבבעלות Google Cloud.
מידע נוסף על המקומות שבהם אפשר לאחסן את יומני ה-build זמין במאמר אפשרויות לאחסון יומני build.
הרצת build באמצעות קובץ תצורה
כדי להריץ build באופן ידני באמצעות קובץ תצורה:
בתיקיית השורש של הפרויקט, יוצרים קובץ תצורה של Cloud Build בשם
cloudbuild.yamlאוcloudbuild.json.מוסיפים את השדה
serviceAccountואת הגדרת הרישום ביומן המועדפת.אם אתם שומרים את יומני ה-build ב-Cloud Logging, הוסיפו שדה
loggingוהגדירו את הערך של השדה ל-CLOUD_LOGGING_ONLY.אם אתם מאחסנים את יומני ה-build בקטגוריה של Cloud Storage שנוצרה על ידי משתמש:
- מוסיפים שדה
loggingומגדירים את הערך שלו כ-GCS_ONLY. - מוסיפים שדה
logsBucketומגדירים את הערך שלו למיקום של הקטגוריה של Cloud Storage.
- מוסיפים שדה
בדוגמה הבאה, Cloud Build מוגדר להריץ גרסאות build באמצעות חשבון שירות בניהול המשתמש, ויומני ה-build מוגדרים לאחסון בקטגוריה של Cloud Storage שנוצרה על ידי המשתמש:
YAML
steps: - name: 'bash' args: ['echo', 'Hello world!'] logsBucket: 'LOGS_BUCKET_LOCATION' serviceAccount: 'projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT' options: logging: GCS_ONLYJSON
{ "steps": [ { "name": "bash", "args": [ "echo", "Hello world!" ] } ], "logsBucket": "LOGS_BUCKET_LOCATION", "serviceAccount": "projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT", "options": { "logging": "GCS_ONLY" } }מחליפים את המשתנים בקובץ התצורה של ה-build בערכים הבאים:
-
LOGS_BUCKET_LOCATIONהיא הקטגוריה של Cloud Storage שבה מאוחסנים יומני ה-build. לדוגמה,gs://mylogsbucket. -
PROJECT_IDהוא מזהה הפרויקט ב- Google Cloud שבו מריצים את ה-build. -
SERVICE_ACCOUNTהיא כתובת האימייל או המזהה הייחודי של חשבון השירות שרוצים לציין ל-builds. לדוגמה, כתובת אימייל של חשבון שירות נראית כך:service-account-name@project-id.iam.gserviceaccount.com.
מפעילים את ה-build באמצעות קובץ תצורת ה-build:
gcloud builds submit --config CONFIG_FILE_PATH SOURCE_DIRECTORYמחליפים את המשתנים בפקודות בערכים הבאים:
-
CONFIG_FILE_PATHהוא הנתיב לקובץ תצורת ה-build. -
SOURCE_DIRECTORYהוא הנתיב או כתובת ה-URL לקוד המקור.
אם לא מציינים CONFIG_FILE_PATH ו-SOURCE_DIRECTORY בפקודה
gcloud builds submit, המערכת של Cloud Build מניחה שקובץ תצורת ה-build וקוד המקור נמצאים בספריית העבודה הנוכחית.-
הרצת גרסאות build באמצעות טריגרים
כדי להריץ גרסת build עם טריגרים לפיתוח גרסת Build של Cloud Build באמצעות חשבון שירות משלכם, צריך להגדיר את אפשרות הרישום ביומן המועדפת ולבחור את חשבון השירות המועדף כשיוצרים את הטריגר.
אם אתם רוצים להשתמש באותו חשבון שירות לכל הטריגרים החדשים, אתם יכולים להגדיר את Cloud Build כך שיבחר אוטומטית את חשבון השירות.
בקובץ תצורת ה-build:
אם אתם שומרים את יומני ה-build ב-Cloud Logging, הוסיפו שדה
loggingוהגדירו את הערך של השדה ל-CLOUD_LOGGING_ONLY.אם אתם מאחסנים את יומני ה-build בקטגוריה של Cloud Storage שנוצרה על ידי משתמש:
- מוסיפים שדה
loggingומגדירים את הערך שלו כ-GCS_ONLY. - מוסיפים שדה
logsBucketומגדירים את הערך שלו למיקום של הקטגוריה של Cloud Storage.
- מוסיפים שדה
בדוגמה הבאה, יומני ה-build מוגדרים לאחסון בקטגוריה של Cloud Storage שנוצרה על ידי המשתמש:
YAML
steps: - name: 'bash' args: ['echo', 'Hello world!'] logsBucket: 'LOGS_BUCKET_LOCATION' options: logging: GCS_ONLYJSON
{ "steps": [ { "name": "bash", "args": [ "echo", "Hello world!" ] } ], "logsBucket": "LOGS_BUCKET_LOCATION", "options": { "logging": "GCS_ONLY" } }מחליפים את
LOGS_BUCKET_LOCATIONבקטגוריה של Cloud Storage שבה רוצים לאחסן את יומני ה-build. לדוגמה,gs://mylogsbucket.מציינים חשבון שירות לשימוש עם הטריגר לפיתוח גרסת ה-Build:
המסוף
בשדה Service account, מציינים את חשבון השירות. כדי לבחור חשבון שירות בפרויקט אחר, לוחצים על Switch project.
בפרויקטים שמשתמשים בחשבון השירות הקודם של Cloud Build, אם משמיטים את השדה הזה, ברירת המחדל היא חשבון השירות הקודם. בפרויקטים שמשתמשים בחשבון השירות שמוגדר כברירת מחדל ב-Compute Engine, או מגבילים את חשבון השירות שמוגדר כברירת מחדל באמצעות מדיניות הארגון, צריך לבחור חשבון שירות. אחרת, יצירת הטריגר תיכשל ותופיע השגיאה
INVALID_ARGUMENT, שמציינת שצריך לציין חשבון שירות.לוחצים על Create כדי לשמור את הטריגר לפיתוח גרסת ה-Build.
gcloud
כשיוצרים טריגר לפיתוח גרסת build, מציינים את חשבון השירות באמצעות הדגל
--service-account. בפרויקטים שלא משתמשים בחשבון השירות הקודם שמוגדר כברירת מחדל, צריך להשתמש בדגל--service-account. אחרת, יצירת הטריגר תיכשל ותופיע השגיאהINVALID_ARGUMENT, שמציינת שצריך לציין חשבון שירות. בדוגמה הבאה, הפקודהgcloudיוצרת טריגר לפיתוח גרסת build שמושך קוד ממאגר Git:gcloud builds triggers create github \ --name=TRIGGER_NAME \ --repo-name=REPO_NAME \ --repo-owner=REPO_OWNER \ --branch-pattern=BRANCH_PATTERN --build-config=BUILD_CONFIG_FILE --service-account=SERVICE_ACCOUNT --project=BUILD_PROJECTמחליפים את המשתנים בקובץ התצורה של ה-build בערכים הבאים:
-
TRIGGER_NAMEהוא השם של הטריגר לפיתוח גרסת ה-Build. -
REPO_NAMEהוא שם המאגר. -
REPO_OWNERהוא שם המשתמש של בעלי המאגר. -
BRANCH_PATTERNהוא שם ההסתעפות במאגר שבו רוצים להפעיל את ה-build. -
TAG_PATTERNהוא שם התג במאגר שבו רוצים להפעיל את ה-build. -
BUILD_CONFIG_FILEהוא הנתיב לקובץ תצורת ה-build. -
SERVICE_ACCOUNTהוא חשבון השירות בפורמט/projects/PROJECT_ID/serviceAccounts/ACCOUNT_ID_OR_EMAIL. -
BUILD_PROJECTהוא הפרויקט שבו מתחילים את ה-builds.
הגדרה בכמה פרויקטים
אתם יכולים להשתמש בחשבון שירות בניהול המשתמשים כדי להריץ גרסאות build בפרויקט שונה מהפרויקט שבו יצרתם את חשבון השירות, רק אם לא נאכף אילוץ מדיניות הארגון iam.disableCrossProjectServiceAccountUsage. האילוץ הזה נאכף כברירת מחדל.
מידע נוסף
הפקודה הבאה משביתה את האכיפה של האילוץ הזה ומעניקה את הגישה הנדרשת. לפני שמגדירים את האילוץ במדיניות הארגון, חשוב להבין את ההשלכות של האילוץ על האבטחה:
gcloud resource-manager org-policies disable-enforce \ iam.disableCrossProjectServiceAccountUsage \ --project=SERVICE_ACCOUNT_PROJECT_IDבפקודה הזו, SERVICE_ACCOUNT_PROJECT_ID הוא הפרויקט שמכיל את חשבון השירות בניהול המשתמשים.
בפרויקט שבו נמצא חשבון השירות בניהול המשתמשים, מקצים את התפקיד
roles/iam.serviceAccountTokenCreatorלסוכן השירות של Cloud Build בפרויקט שבו מריצים את ה-builds:gcloud projects add-iam-policy-binding SERVICE_ACCOUNT_PROJECT_ID \ --member="serviceAccount:BUILD_SERVICE_AGENT" \ --role="roles/iam.serviceAccountTokenCreator"מחליפים את המשתנים בפקודה בערכים הבאים:
-
SERVICE_ACCOUNT_PROJECT_ID: מזהה הפרויקט שמכיל את חשבון השירות שמנוהל על ידי המשתמש. -
BUILD_SERVICE_AGENT: מזהה האימייל של סוכן השירות בפורמטservice-BUILD_PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com, כאשרBUILD_PROJECT_NUMBERהוא מספר הפרויקט שבו מריצים את ה-builds. אפשר למצוא את מספר הפרויקט בדף הגדרות הפרויקט.
-
מגבלות:
הפרויקט ב- Google Cloud חייב להיות בארגון ב- Google Cloud .
צריך להתחיל את ה-builds בשורת הפקודה באמצעות
gcloud builds submitאוgcloud builds triggers create.אם קיבלתם את השגיאה
service account not foundכשניסיתם להקצות את תפקיד ה-IAM, יכול להיות שתצטרכו ליצור את סוכן השירות באופן ידני.