התחברות למארח של Bitbucket Server

בדף הזה מוסבר איך לחבר מארח של Bitbucket Server ל-Cloud Build. חיבור למארח של Bitbucket Server מאפשר לשלב את מאגרי Bitbucket Server עם Cloud Build. כך תוכלו להגדיר טריגרים לבנייה כדי לבנות מאגרי מידע מ-Bitbucket Server וגם לבנות מאגרי מידע מ-Bitbucket Server ברשת פרטית.

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

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

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

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

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

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

כדי לקבל את ההרשאות שדרושות לחיבור למארח של Bitbucket Server, צריך לבקש מהאדמין להקצות לחשבון המשתמש שלכם את תפקיד ה-IAM‏ Cloud Build Connection Admin (roles/cloudbuild.connectionAdmin). כדי לקרוא הסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

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

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

יצירת טוקנים אישיים של גישה

לפני שיוצרים חיבור מארח למופע של Bitbucket Server, צריך ליצור אסימוני גישה אישיים ב-Bitbucket Server. לשם כך:

  1. נכנסים למופע של Bitbucket Server.

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

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

    2. כדי לוודא שלמאגרי Cloud Build יש גישה לקוד המקור במאגרים, צריך ליצור אסימון גישה עם ההיקף repository read.

  3. שומרים את ערכי האסימון באופן מאובטח. תשתמשו בהם כדי להתחבר למאגר Bitbucket Server.

התחברות למארח של Bitbucket Server

המסוף

כדי לקשר את המארח של Bitbucket Server ל-Cloud Build:

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

    פתיחת הדף Repositories

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

gcloud

  1. אחסון טוקנים ב-Secret Manager

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

      cat /proc/sys/kernel/random/uuid | tr -d '\n' | gcloud secrets create 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 מזהה הפרויקט.

עכשיו אפשר להמשיך ולחבר את המארח של Bitbucket Server ל-Cloud Build.

  1. מריצים את הפקודה הבאה כדי ליצור חיבור ל-Bitbucket Server:

    gcloud builds connections create bitbucketserver CONNECTION_NAME \
    --host-uri=HOST_URI \
    --project=PROJECT_ID \
    --region=REGION \
    --authorizer-token-secret-version=projects/PROJECT_ID/secrets/ADMIN_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
 ```

Where:
    • ‫CONNECTION_NAME הוא שם לחיבור המארח של Bitbucket Server ב-Cloud Build.
    • ‫HOST_URI הוא ה-URI של המכונה של Bitbucket Server.
    • ‫PROJECT_ID הוא Google Cloud מזהה הפרויקט.
    • ‫REGION הוא האזור של החיבור.
    • ‫ADMIN_TOKEN הוא שם האסימון עם ההיקף repository admin.
    • ‫READ_TOKEN הוא שם האסימון עם ההיקף repository read.
    • ‫SECRET_VERSION היא הגרסה של הסוד.
    • ‫WEBHOOK_SECRET הוא הסוד של ה-webhook.

Terraform

אפשר לחבר את המארח של Bitbucket Server ל-Cloud Build באמצעות Terraform.

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

  • מגדיר את ספק Google של Terraform.
  • יוצר סוד ב-Secret Manager לאחסון האסימונים של Bitbucket.
  • נותן לסוכן השירות של Cloud Build את ההרשאות הנדרשות לגישה לסודות.

  • יוצר חיבור ל-Bitbucket Server.

    // Configure the Terraform Google provider
terraform {
  required_providers {
    google = {}
  }
}

provider "google" {
  project = "PROJECT_ID"
  region = "REGION"
}

// Create secrets and grant permissions to the Cloud Build service agent
resource "google_secret_manager_secret" "admin-token-secret" {
    project = "PROJECT_ID"
    secret_id = "ADMIN_TOKEN_NAME"

    replication {
        auto {}
    }
}

resource "google_secret_manager_secret_version" "admin-token-secret-version" {
    secret = google_secret_manager_secret.admin-token-secret.id
    secret_data = "ADMIN_TOKEN_VALUE"
}

resource "google_secret_manager_secret" "read-token-secret" {
    project = "PROJECT_ID"
    secret_id = "READ_TOKEN_NAME"

    replication {
        auto {}
    }
}

resource "google_secret_manager_secret_version" "read-token-secret-version" {
    secret = google_secret_manager_secret.read-token-secret.id
    secret_data = "READ_TOKEN_VALUE"
}

resource "google_secret_manager_secret" "webhook-secret-secret" {
    project = "PROJECT_ID"
    secret_id = "WEBHOOK_SECRET_NAME"

    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" "p4sa-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.admin-token-secret.project
  secret_id = google_secret_manager_secret.admin-token-secret.secret_id
  policy_data = data.google_iam_policy.p4sa-secretAccessor.policy_data
}

resource "google_secret_manager_secret_iam_policy" "policy-rpak" {
  project = google_secret_manager_secret.read-token-secret.project
  secret_id = google_secret_manager_secret.read-token-secret.secret_id
  policy_data = data.google_iam_policy.p4sa-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.p4sa-secretAccessor.policy_data
}

// Create the connection resource
resource "google_cloudbuildv2_connection" "my-connection" {
    project = "PROJECT_ID"
    location = "REGION"
    name = "CONNECTION_NAME"

    bitbucket_server_config {
        host_uri = "BITBUCKET_URI"
        authorizer_credential {
            user_token_secret_version = google_secret_manager_secret_version.admin-token-secret-version.id
        }
        read_authorizer_credential {
            user_token_secret_version = google_secret_manager_secret_version.read-token-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 מזהה הפרויקט.
  • ‫PROJECT_NUMBER הוא מספר הפרויקט שלכם ב- Google Cloud .
  • ‫ADMIN_TOKEN_NAME הוא השם של האסימון עם ההיקף repository:admin.
  • ‫ADMIN_TOKEN_VALUE הוא הערך של ADMIN_TOKEN_NAME.
  • ‫READ_TOKEN_NAME הוא השם של האסימון עם ההיקף repository:read.
  • ‫READ_TOKEN_VALUE הוא הערך של READ_TOKEN_NAME.
  • ‫WEBHOOK_SECRET_NAME הוא השם של הסוד של ה-webhook.
  • ‫WEBHOOK_SECRET_VALUE הוא הערך של WEBHOOK_SECRET_NAME.
  • ‫REGION הוא האזור של החיבור.
  • ‫CONNECTION_NAME הוא שם לחיבור המארח של Bitbucket Server ב-Cloud Build.
  • ‫BITBUCKET_URI הוא ה-URI של מופע Bitbucket Data Center.

החלפה של טוקנים ישנים או שפג תוקפם ב-Bitbucket Server

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

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

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

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

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

    1. עוברים למאגר Bitbucket Server שמחובר לחיבור המארח של Cloud Build.

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

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

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

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

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

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

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

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

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

מידע נוסף זמין במאמרים Access tokens (אסימוני גישה) ו-Enhancing security in Bitbucket: Introducing expiry for access tokens (שיפור האבטחה ב-Bitbucket: הצגת תפוגה לאסימוני גישה) במסמכי Bitbucket Server.

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