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

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

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

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

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

    כדי להפעיל ממשקי API, נדרשת ההרשאה serviceusage.services.enable. אם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד 'בעלים' (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד 'אדמין בממשק 'שימוש בשירות'' (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, צריך להקצות לחשבון המשתמש שלכם את התפקיד 'אדמין של חיבור' (roles/cloudbuild.connectionAdmin) ב-Cloud Build.

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

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

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

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

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

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

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

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

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

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

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

המסוף

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

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

    פתיחת הדף Repositories

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

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

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

  4. לוחצים על Create host connection (יצירת חיבור למארח) כדי לחבר מארח חדש ל-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: לוחצים על 'עיון' כדי להעלות את האישור בחתימה עצמית.

      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:service-PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com"]
    }
}

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

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

  • כשמנסים לקשר מאגר GitLab Enterprise Edition לחיבור Cloud Build, מופיעה ההודעה Failed to fetch repositories to link. Check that Cloud Build is still authorized to access data from the selected connection.

  • בדף Triggers (טריגרים), כשלוחצים על Run (הפעלה), נפתח הדף Run trigger (הפעלת טריגר) ומוצגת הודעה Failed to list branches. You can still enter one manually.

כדי לבצע רוטציה של טוקן ישן או שפג תוקפו לחיבור שלכם:

  1. מאתרים את הסודות שמשויכים לחיבור המארח:

    1. מריצים את הפקודה הבאה:

      gcloud builds connections describe CONNECTION_PATH --region=REGION

      כאשר:

      • ‫CONNECTION_PATH הוא הנתיב של חיבור המארח שלכם ב-GitLab Enterprise Edition ב-Cloud Build, בפורמט projects/PROJECT_ID/locations/REGION/connections/CONNECTION_NAME.
      • ‫REGION הוא האזור של החיבור שלך.

    2. בפלט של הפקודה, מחפשים את הערכים של השדות של אסימון המשתמש. ‫readAuthorizerCredential.userTokenSecretVersion shows the Secret Manager name of the read_api token, and authorizerCredential.userTokenSecretVersion shows the Secret Manager name of the api token. השמות האלה מאוחסנים כסודות ב-Secret Manager.

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

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

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

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

  3. יוצרים גרסה חדשה של סוד לכל טוקן:

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

      פתיחת הדף Secret Manager

    2. לכל טוקן שביצעתם לו רוטציה, מחפשים את שם הסוד שזיהיתם בשלב 1, לוחצים על פעולות ואז על הוספת גרסה חדשה.

    3. בחלון Add new version (הוספת גרסה חדשה), מזינים את המזהה של האסימון שהוחלף ולוחצים על Add new version (הוספת גרסה חדשה).

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

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