התחברות למארח של GitLab Enterprise Edition

בדף הזה מוסבר איך להתחבר למארח GitLab Enterprise Edition ל-Cloud Build.

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

• מפעילים את Cloud Build API ואת Secret Manager API, אם הם עדיין לא מופעלים.

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

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

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

דרישות מהמארחים

• אם לא התקנתם מופע של GitLab Enterprise Edition Server, תוכלו לקרוא את ההוראות במדריך ההתקנה של GitLab Enterprise Edition.

  כשפועלים לפי ההוראות להתקנת מופע של GitLab Enterprise Edition Server, חשוב לשים לב לנקודות הבאות:

  • חובה להגדיר את המארח לטיפול בפרוטוקול HTTPS. אין תמיכה במארחים שהוגדרו עם פרוטוקול HTTP.

  • חובה להגדיר את המארח עם אותה כתובת URL שמשמשת להגעה למארח מ- Google Cloud. למידע נוסף, אפשר לעיין במסמכי התיעוד של GitLab בנושא הגדרת כתובת URL חיצונית.

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

כדי לקשר את המארח שלכם ב-GitLab Enterprise Edition, צריך להקצות לחשבון המשתמש שלכם את התפקיד 'אדמין של חיבור Cloud Build' (roles/cloudbuild.connectionAdmin).

במאמר הגדרת גישה למשאבי Cloud Build מוסבר איך להוסיף את התפקידים הנדרשים לחשבון המשתמש. במאמר תפקידים והרשאות ב-IAM מוסבר בהרחבה על תפקידי IAM שמשויכים ל-Cloud Build.

אם מופע GitLab Enterprise Edition מתארח ברשת פרטית, כדאי לעיין במאמר יצירת מאגרים מ-GitLab Enterprise Edition ברשת פרטית כדי לקבל מידע על תפקידי IAM נוספים שנדרשים לפני חיבור המארח.

התחברות למארח של GitLab Enterprise Edition

לפני שיוצרים חיבור מארח למופע של GitLab Enterprise Edition, צריך ליצור אסימוני גישה אישיים ב-GitLab Enterprise Edition. לשם כך, מבצעים את השלבים הבאים:

1. מתחברים לחשבון שלכם במהדורת GitLab Enterprise.

2. בדף GitLab Enterprise Edition של המופע שלכם, לוחצים על האווטאר בפינה השמאלית העליונה.

3. לוחצים על עריכת הפרופיל.

4. בסרגל הצד שמימין, לוחצים על Access tokens (אסימוני גישה).

   מוצג הדף Personal Access Tokens (אסימוני גישה אישיים).

5. כדי להתחבר למאגרי מידע ולנתק אותם, צריך ליצור אסימון גישה עם היקף api.

6. יוצרים אסימון גישה עם ההיקף read_api כדי לוודא שמאגרי Cloud Build יוכלו לגשת לקוד המקור במאגרים.

   הערה: בנוסף לאסימוני גישה אישיים, אפשר להשתמש גם באסימוני גישה לפרויקט. אם גרסת GitLab שלכם היא 14.2 או גרסה חדשה יותר, אתם יכולים להשתמש גם באסימוני גישה לקבוצות. אם אתם משתמשים באסימוני גישה לפרויקט או לקבוצה, צריך לבחור את התפקיד Maintainer כדי להבטיח שהחיבור יתבצע בהצלחה.

המסוף

כדי לחבר את המארח שלכם ב-GitLab Enterprise Edition ל-Cloud Build:

1. פותחים את הדף Repositories במסוף Google Cloud .

   פתיחת הדף Repositories

   מוצג הדף Repositories (מאגרי מידע).

2. בחלק העליון של הדף, לוחצים על הכרטיסייה דור שני.

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

4. לוחצים על יצירת חיבור למארח כדי לחבר מארח חדש ל-Cloud Build.

5. בחלונית הימנית, בוחרים באפשרות GitLab כספק המקור.

6. בקטע Configure Connection (הגדרת החיבור), מזינים את הפרטים הבאים:

   • אזור: בוחרים אזור לקישור.

     הערה: חובה לציין אזור. החיבור לא יכול להתקיים באופן גלובלי.

   • שם: מזינים שם לחיבור.

7. בקטע פרטי המארח, בוחרים או מזינים את הפרטים הבאים:

   • GitLab host (מארח GitLab): בוחרים באפשרות Self-managed GitLab Enterprise Edition (מהדורת GitLab Enterprise בניהול עצמי).

   • כתובת ה-URL של המארח: מזינים את כתובת ה-URL של המארח לחיבור. לדוגמה, https://my-gle-server.net.

8. אופציונלי: אם רוצים לנהל את מפתחות ההצפנה שמשמשים להצפנת טוקני הגישה למאגרי GitLab Enterprise Edition, עוברים לקטע הצפנה ובוחרים מפתח של Cloud Key Management Service. מידע נוסף זמין במאמר בנושא הפעלת מפתחות הצפנה בניהול הלקוח ב-Secret Manager.

9. בקטע Networking, באפשרות Connection type, בוחרים באחת מהאפשרויות הבאות:

   • אינטרנט ציבורי: בוחרים באפשרות הזו אם אפשר לגשת למכונה באמצעות האינטרנט הציבורי.

   • רשת פרטית: בוחרים באפשרות הזו אם המופע מתארח ברשת פרטית. לאחר מכן, מגדירים את האפשרויות הבאות:

     1. אישור CA: לוחצים על 'עיון' כדי להעלות את האישור בחתימה עצמית.

        הערה: גודל האישור לא יכול לחרוג מ-10KB והוא צריך להיות בפורמט PEM ‏ (.pem, .cer או .crt). אם לא ממלאים את הקטע הזה, המערכת תשתמש בקבוצת אישורים שמוגדרת כברירת מחדל במקום זאת.

     2. בקטע Service Directory service, בוחרים את המיקום של השירות:

        • בפרויקט CURRENT_PROJECT
        • בפרויקט אחר
        • הזנה ידנית

     3. הזן את פריטי המידע הבאים:

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

        • אזור: בשדה הזה האזור של החיבור שלכם נבחר מראש. האזור שצוין לשירות חייב להיות זהה לאזור שמשויך לחיבור.

        • מרחב שמות: בוחרים את מרחב השמות של השירות.

        • שירות: בוחרים את שם השירות במרחב השמות.

10. בקטע Personal access tokens (אסימוני גישה אישיים), מזינים את הפרטים הבאים:

    • טוקן גישה ל-API: מזינים את הטוקן עם גישת ההיקף api. הטוקן הזה משמש לחיבור מאגרי מידע ולניתוק שלהם.

    • קריאת טוקן גישה ל-API: מזינים את הטוקן עם גישה בהיקף read_api. טריגרים של Cloud Build משתמשים באסימון הזה כדי לגשת לקוד המקור במאגרי מידע.

11. לוחצים על Connect.

    אחרי שלוחצים על הלחצן Connect (חיבור), טוקני הגישה האישיים מאוחסנים בצורה מאובטחת ב-Secret Manager. אחרי חיבור המארח, Cloud Build יוצר גם סוד של webhook בשמכם. אפשר לראות ולנהל סודות בדף Secret Manager. אפשר לראות ולנהל את הסודות בדף Secret Manager.

gcloud

לפני שמקשרים את המארח של GitLab Enterprise Edition ל-Cloud Build, צריך לבצע את השלבים הבאים כדי לאחסן את פרטי הכניסה:

1. מאחסנים את האסימון ב-Secret Manager.

2. יוצרים סוד של webhook ב-Secret Manager על ידי הפעלת הפקודה הבאה:

    cat /proc/sys/kernel/random/uuid | tr -d '\n' | gcloud secrets create my-gle-webhook-secret --data-file=-
   

3. אם אתם מאחסנים את הסודות בפרויקט אחר Google Cloud מזה שבו אתם מתכננים להשתמש כדי ליצור חיבור למארח, מזינים את הפקודה הבאה כדי להעניק לפרויקט גישה לסוכן השירות של Cloud Build:

   PN=$(gcloud projects describe PROJECT_ID --format="value(projectNumber)")
   CLOUD_BUILD_SERVICE_AGENT="service-${PN}@gcp-sa-cloudbuild.iam.gserviceaccount.com"
   gcloud projects add-iam-policy-binding PROJECT_ID \
     --member="serviceAccount:${CLOUD_BUILD_SERVICE_AGENT} \
     --role="roles/secretmanager.admin"
   

   כאשר:

   • ‫PROJECT_ID הוא Google Cloud מזהה הפרויקט.

עכשיו אפשר להמשיך ולחבר את המארח שלכם ב-GitLab Enterprise Edition אל Cloud Build.

כך עושים את זה:

1. מזינים את הפקודה הבאה כדי ליצור חיבור ל-GitLab Enterprise Edition:

   gcloud builds connections create gitlab CONNECTION_NAME \
     --host-uri=HOST_URI \
     --project=PROJECT_ID \
     --region=REGION \
     --authorizer-token-secret-version=projects/PROJECT_ID/secrets/API_TOKEN/versions/SECRET_VERSION \
     --read-authorizer-token-secret-version=projects/PROJECT_ID/secrets/READ_TOKEN/versions/SECRET_VERSION \
     --webhook-secret-secret-version=projects/PROJECT_ID/secrets/WEBHOOK_SECRET/versions/SECRET_VERSION
   

   כאשר:

   • ‫CONNECTION_NAME הוא שם החיבור ב-Cloud Build.
   • ‫HOST_URI הוא ה-URI של מופע GitLab Enterprise Edition. לדוגמה, https://my-gle-server.net.
   • ‫PROJECT_ID הוא Google Cloud מזהה הפרויקט.
   • ‫REGION הוא האזור של החיבור.
   • ‫API_TOKEN הוא שם האסימון עם apiההיקף.
   • ‫READ_TOKEN הוא שם האסימון עם read_apiההיקף.
   • ‫SECRET_VERSION היא הגרסה של הסוד.
   • ‫WEBHOOK_SECRET הוא הסוד של ה-webhook.

סיימתם ליצור חיבור ל-GitLab Enterprise Edition.

Terraform

אפשר לחבר את המארח שלכם ב-GitLab Enterprise Edition ל-Cloud Build באמצעות Terraform. מידע נוסף על Terraform ב- Google Cloud

בדוגמה הבאה, קטע הקוד מבצע את הפעולות הבאות:

• הגדרת ספק Terraform למשאבים של Google Cloud
• יצירת סוד לשמירת אסימון הגישה האישי שלכם ל-GitLab Enterprise Edition
• נותן לסוכן השירות של Cloud Build את ההרשאות הנדרשות כדי לגשת לסודות

• יצירת חיבור ל-GitLab Enterprise Edition

  // Configure the Terraform Google provider
  terraform {
    required_providers {
      google = {}
    }
  }
  
  // Create secrets and grant permissions to the Cloud Build service agent
  resource "google_secret_manager_secret" "api-pat-secret" {
      project = "PROJECT_ID"
      secret_id = "GITLAB_PAT_API"
  
      replication {
          auto {}
       }
   }
  
   resource "google_secret_manager_secret_version" "api-pat-secret-version" {
       secret = google_secret_manager_secret.api-pat-secret.id
       secret_data = "GITLAB_API_TOKEN"
   }
  
   resource "google_secret_manager_secret" "read-pat-secret" {
       project = "PROJECT_ID"
       secret_id = "GITLAB_PAT_READ"
  
       replication {
           auto {}
       }
  }
  
  resource "google_secret_manager_secret_version" "read-pat-secret-version" {
      secret = google_secret_manager_secret.read-pat-secret.id
      secret_data = "GITLAB_API_TOKEN"
  }
  
  resource "google_secret_manager_secret" "webhook-secret-secret" {
      project = "PROJECT_ID"
      secret_id = "WEBHOOK_SECRET"
  
      replication {
          auto {}
      }
  }
  
  resource "google_secret_manager_secret_version" "webhook-secret-secret-version" {
      secret = google_secret_manager_secret.webhook-secret-secret.id
      secret_data = "WEBHOOK_SECRET_VALUE"
  }
  
  data "google_iam_policy" "serviceagent-secretAccessor" {
      binding {
          role = "roles/secretmanager.secretAccessor"
          members = ["serviceAccount:[e-mail]"]
      }
  }
  
  resource "google_secret_manager_secret_iam_policy" "policy-pak" {
    project = google_secret_manager_secret.api-pat-secret.project
    secret_id = google_secret_manager_secret.api-pat-secret.secret_id
    policy_data = data.google_iam_policy.serviceagent-secretAccessor.policy_data
  }
  
  resource "google_secret_manager_secret_iam_policy" "policy-rpak" {
    project = google_secret_manager_secret.read-pat-secret.project
    secret_id = google_secret_manager_secret.read-pat-secret.secret_id
    policy_data = data.google_iam_policy.serviceagent-secretAccessor.policy_data
  }
  
  resource "google_secret_manager_secret_iam_policy" "policy-whs" {
    project = google_secret_manager_secret.webhook-secret-secret.project
    secret_id = google_secret_manager_secret.webhook-secret-secret.secret_id
    policy_data = data.google_iam_policy.serviceagent-secretAccessor.policy_data
  }
  
  // Create the connection and add the repository resource
  resource "google_cloudbuildv2_connection" "my-connection" {
      project = "PROJECT_ID"
      location = "REGION"
      name = "CONNECTION_NAME"
  
      gitlab_config {
          host_uri = "URI"
          authorizer_credential {
              user_token_secret_version = google_secret_manager_secret_version.api-pat-secret-version.id
          }
          read_authorizer_credential {
               user_token_secret_version = google_secret_manager_secret_version.read-pat-secret-version.id
          }
          webhook_secret_secret_version = google_secret_manager_secret_version.webhook-secret-secret-version.id
      }
  
      depends_on = [
          google_secret_manager_secret_iam_policy.policy-pak,
          google_secret_manager_secret_iam_policy.policy-rpak,
          google_secret_manager_secret_iam_policy.policy-whs
      ]
  }
  

מחליפים את מה שכתוב בשדות הבאים:

• ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
• ‫GITLAB_PAT_API: אסימון הגישה האישי עם גישת api.
• ‫GITLAB_API_TOKEN: אסימון הגישה האישי שלכם.
• ‫GITLAB_PAT_READ: אסימון הגישה האישי שלכם עם גישה ל-read_api.
• ‫WEBHOOK_SECRET: השם של הסוד שמכיל את הערך הסודי של ה-webhook.
• ‫WEBHOOK_SECRET_VALUE: הערך של הסוד של ה-webhook.

• ‫PROJECT_NUMBER: מספר הפרויקט ב- Google Cloud . אפשר לראות את מספר הפרויקט בדף Welcome במסוף Google Cloud או על ידי הרצת הפקודה הבאה:

  gcloud projects describe PROJECT_ID --format='value(projectNumber)'
  

• ‫REGION: האזור של החיבור.

• ‫CONNECTION_NAME: שם לחיבור של מארח GitLab Enterprise Edition ב-Cloud Build.

• ‫URI: ה-URI של החיבור, לדוגמה: https://my-gitlab-enterprise-server.net.

סיימתם ליצור חיבור ל-GitLab Enterprise Edition.

החלפה של טוקנים ישנים או לא תקפים של גישה ל-GitLab Enterprise Edition

מבצעים רוטציה של אסימוני הגישה כדי שחיבור המארח של Cloud Build יוכל לשמור על החיבור למאגר של GitLab Enterprise Edition. אם תוקף טוקן הגישה שלכם ל-GitLab Enterprise Edition יפוג, החיבור של מארח Cloud Build למאגר GitLab Enterprise Edition ינותק. במקרה כזה, לא תוכלו להשבית את החיבור או לקשר מאגר עד שתחליפו את האסימון שפג תוקפו. בנוסף, השגיאות יופיעו במקרים הבאים:

• בדף פרטי החיבורים של החיבור מופיעה הודעת שגיאה שבה מצוין Connection is disconnected due to an invalid or expired access token.

• אם תנסו לקשר מאגר לחיבור עם טוקן גישה שתוקפו פג, תופיע ההודעה Invalid access token. כשלוחצים על View connection (הצגת החיבור), מגיעים לדף Connection details (פרטי החיבור) של החיבור עם האסימון שתוקפו פג.

ב-Cloud Build אפשר להחליף את טוקני הגישה על ידי הזנת ערכי טוקנים חדשים ושמירתם ב-Secret Manager בגרסה העדכנית ביותר של הסודות האלה. כדי לבצע רוטציה של טוקנים לגישה:

1. מבצעים רוטציה של כל אסימון גישה ב-GitLab Enterprise Edition:

   1. עוברים למאגר GitLab Enterprise Edition שמקושר לחיבור המארח של Cloud Build.

   2. פועלים לפי ההוראות במסמכי התיעוד של GitLab כדי להחליף אסימון גישה. כשמבצעים רוטציה של אסימון, GitLab Enterprise Edition יוצר אסימון חדש עם פרטי כניסה חדשים ומבטל את התוקף של הגרסה הקודמת של האסימון. לאסימון המעודכן יש את אותן הרשאות ואותו היקף כמו לאסימון המקורי.

   3. מעתיקים את המזהים של הטוקנים שהוחלפו.

2. מעדכנים את טוקן הגישה ב-Cloud Build:

   1. עוברים לדף פרטי החיבור של החיבור.

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

   3. בתפריט Token rotation (רוטציה של טוקנים), מזינים את הטוקנים החדשים בשדות API access token (טוקן גישה ל-API) ו-Read access token (טוקן גישת קריאה).

   4. (אופציונלי): אם רוצים שהחיבור ישתמש תמיד בגרסה העדכנית ביותר של הסוד עבור האסימונים, בוחרים באפשרות עדכון החיבור כך שתמיד תהיה בשימוש הגרסה העדכנית ביותר. יכול להיות שיהיה לכם שימושי להשאיר את האפשרות הזו לא מסומנת אם החיבור שלכם משתמש במספר גרסה סודי ספציפי.

   5. כדי לשמור את השינויים, לוחצים על עדכון.

      ‫Cloud Build שומר את אסימוני הגישה החדשים כגרסה האחרונה של הסוד ב-Secret Manager.

מידע נוסף זמין במאמר תפוגה של אסימון גישה במסמכי התיעוד של GitLab Enterprise Edition.

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

• איך מחברים מאגר GitLab Enterprise Edition
• במאמר הזה מוסבר איך ליצור ולפרוס את עומסי העבודה שלכם ב- Google Cloud באמצעות רכיבי CI/CD מנוהלים על ידי Google בצינור העיבוד של GitLab. מידע נוסף זמין במאמר GitLab ב- Google Cloud.