הפעלת בנייה באמצעות חשבון שירות שמנוהל על ידי משתמש

במאמר הזה מוסבר איך להגדיר את ה-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). כך מקצים תפקידים.

    הפעלת ממשקי ה-API

  • אם אתם מתכננים להשתמש בחשבון הזה כדי ליצור ולנהל פרטי כניסה לחשבון, לדוגמה כדי ליצור פרטי כניסה לטווח קצר, הפעילו את IAM Service Account Credentials API.

    התפקידים שנדרשים כדי להפעיל ממשקי API

    כדי להפעיל ממשקי API, צריך את ההרשאה serviceusage.services.enable. אם אתם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד "בעלים" (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד "אדמין בממשק 'שימוש בשירות'" (roles/serviceusage.serviceUsageAdmin). כך מקצים תפקידים.

    להפעלת ה-API

  • אם עדיין לא עשיתם זאת, צרו חשבון שירות.

הגדרת חשבון השירות

כדי שלחשבון השירות שמנוהל על ידי המשתמש יהיו ההרשאות הנדרשות להרצת ה-builds, צריך להקצות לו תפקידי IAM. אפשר גם להגדיר את Cloud Build כך שיבחר באופן אוטומטי את חשבון השירות הזה לטריגרים חדשים.

  1. במסוף Google Cloud , נכנסים לדף Permissions של Cloud Build:

    עוברים אל הרשאות.

  2. בתפריט Service account, בוחרים את חשבון השירות. כדי לבחור חשבון שירות בפרויקט אחר, לוחצים על Switch project.

  3. כדי להשתמש בחשבון השירות שנבחר כחשבון השירות לטריגרים חדשים, מפעילים את האפשרות Set as pre-selected for new triggers.

  4. ברשימת השירותים של Google Cloud , מפעילים את תפקידי ה-IAM שרוצים להקצות לחשבון השירות.

  5. אם התפקיד שאתם צריכים לצינור עיבוד הנתונים של ה-build לא מופיע כאן, אתם יכולים להקצות תפקידים נוספים בדף ההגדרות של IAM.

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

זיהוי חשבון השירות שצריך להגדיר

לפני שנותנים תפקידים, צריך לבדוק איזה חשבון שירות מוגדר ל-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:

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

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

התחזות לחשבון שירות

כדי לאפשר ל-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, קראו את המידע הבא:

הגדרת יומני build

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

אם אתם יוצרים קטגוריית יומנים, ודאו שאין לה מדיניות שמירת נתונים, כי המדיניות עשויה למנוע מ-Cloud Build לכתוב יומני build לקטגוריה.

אי אפשר לאחסן את היומנים בקטגוריית יומנים שבבעלות Google Cloud.

מידע נוסף על המקומות שבהם אפשר לאחסן את יומני ה-build זמין במאמר אפשרויות לאחסון יומני build.

הרצת build באמצעות קובץ תצורה

כדי להריץ build באופן ידני באמצעות קובץ תצורה:

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

  2. מוסיפים את השדה 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_ONLY
    

    JSON

    {
      "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.
  3. מפעילים את ה-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 כך שיבחר אוטומטית את חשבון השירות.

  1. בקובץ תצורת ה-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_ONLY
    

    JSON

    {
      "steps": [
      {
        "name": "bash",
        "args": [
          "echo",
          "Hello world!"
        ]
      }
      ],
      "logsBucket": "LOGS_BUCKET_LOCATION",
      "options": {
        "logging": "GCS_ONLY"
      }
    }
    

    מחליפים את LOGS_BUCKET_LOCATION בקטגוריה של Cloud Storage שבה רוצים לאחסן את יומני ה-build. לדוגמה, gs://mylogsbucket.

  2. מציינים חשבון שירות לשימוש עם הטריגר לפיתוח גרסת ה-Build:

    המסוף

    1. יוצרים או עורכים את הטריגר לפיתוח גרסת ה-Build.

    2. בשדה Service account, מציינים את חשבון השירות. כדי לבחור חשבון שירות בפרויקט אחר, לוחצים על Switch project.

      בפרויקטים שמשתמשים בחשבון השירות הקודם של Cloud Build, אם משמיטים את השדה הזה, ברירת המחדל היא חשבון השירות הקודם. בפרויקטים שמשתמשים בחשבון השירות שמוגדר כברירת מחדל ב-Compute Engine, או מגבילים את חשבון השירות שמוגדר כברירת מחדל באמצעות מדיניות הארגון, צריך לבחור חשבון שירות. אחרת, יצירת הטריגר תיכשל ותופיע השגיאה INVALID_ARGUMENT, שמציינת שצריך לציין חשבון שירות.

    3. לוחצים על 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, יכול להיות שתצטרכו ליצור את סוכן השירות באופן ידני.

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