連結至 Bitbucket Data Center 主機

本頁說明如何將 Bitbucket Data Center 主機連線至 Cloud Build。連線至 Bitbucket Data Center 主機後，即可將 Bitbucket Data Center 存放區與 Cloud Build 整合。這樣一來，您就能設定建構觸發程序，從 Bitbucket 資料中心建構存放區，以及從私人網路中的 Bitbucket 資料中心建構存放區。

事前準備

  • Enable the Cloud Build and Secret Manager APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

  • 在 Bitbucket 資料中心存放區中準備好原始碼。
  • 在 Bitbucket Data Center 來源存放區中，擁有 Dockerfile 或 Cloud Build 設定檔。
  • 如果尚未安裝 Bitbucket Data Center 執行個體，請參閱 Bitbucket Data Center 安裝指南瞭解操作說明。

必要 IAM 權限

如要取得連線至 Bitbucket Data Center 主機所需的權限，請要求管理員在您的使用者帳戶中，授予 Cloud Build 連線管理員 (roles/cloudbuild.connectionAdmin) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

如果 Bitbucket 資料中心執行個體託管於私人網路，請參閱「在私人網路中從 Bitbucket 資料中心建構存放區」，瞭解設定主機連線所需的其他 IAM 角色。

建立個人存取權杖

為 Bitbucket Data Center 執行個體建立主機連線前，請在 Bitbucket Data Center 中建立個人存取權杖，方法如下：

  1. 登入 Bitbucket Data Center 執行個體。

  2. 按照操作說明為使用者帳戶建立 HTTP 存取權杖。

    1. 建立具備存放區管理員範圍的存取權杖，用於連結及取消連結存放區。

    2. 建立具備「repository read」範圍的存取權杖，確保 Cloud Build 存放區可以存取存放區中的原始碼。

  3. 請妥善保存符記值。您會使用這些密鑰連線至 Bitbucket Data Center 存放區。

連線至 Bitbucket Data Center 主機

控制台

如要將 Bitbucket Data Center 主機連結至 Cloud Build，請按照下列步驟操作：

  1. 在 Google Cloud 控制台中開啟「Repositories」(存放區) 頁面。

    開啟「Repositories」(存放區) 頁面

  2. 選取頁面頂端的「第 2 代」分頁標籤。

  3. 在頂端列的專案選取器中，選取 Google Cloud 專案。

  4. 按一下「建立主機連線」，將新主機連結至 Cloud Build。

  5. 在左側面板中，選取「Bitbucket」做為來源供應商。

  6. 在「設定連線」部分，輸入下列資訊：

    1. 「Region」(區域)：選取連線的區域。您必須指定區域。連結無法在全球通用。

    2. 名稱：輸入連線名稱。

  7. 在「主機詳細資料」部分，選取或輸入下列資訊：

    1. Bitbucket 主機：選取「Bitbucket Data Center」做為主機。

    2. 主機網址：輸入 Bitbucket Data Center 主機的網址。

  8. 在「網路」部分，選取下列其中一個選項：

    1. 公開網際網路：如果執行個體可透過公開網際網路存取，請選取這個選項。

    2. 私人網路：如果執行個體是託管在私人網路上，請選取這個選項。

      1. CA 憑證：自行簽署的憑證。按一下「瀏覽」，從本機開啟憑證。

        憑證大小不得超過 10 KB，且應為 PEM 格式 (.pem、.cer 或 .crt)。如果將這個欄位留空，Cloud Build 會使用預設憑證集中的憑證。

      2. 在「Service Directory service」(服務目錄服務) 部分，選取服務位置。您可以接受預先填入的專案 ID，或指定其他專案。

        1. 選取服務專案。您可以接受預先填入的專案，選擇「In another project」(位在其他專案)來瀏覽，或選擇「Enter manually」(手動輸入)。

          如果選擇「手動輸入」，請輸入下列資訊：

          • 專案：輸入或從下拉式選單中選取專案 ID。 Google Cloud

          • 區域：這個欄位會預先選取連線的區域。服務指定的區域必須與連線關聯的區域相符。

        2. 命名空間：選取服務的命名空間。

        3. 服務：選取命名空間中的服務名稱。

  9. 在「HTTP access tokens」部分，輸入下列資訊：

    1. 管理員存取權杖：輸入範圍為 repository admin 的權杖。這個權杖用於連結及取消連結存放區。

    2. 讀取存取權杖：輸入範圍為「repository read」的權杖。Cloud Build 觸發條件會使用這個權杖存取存放區中的原始碼。

  10. 按一下「連線」。

    按一下「連線」按鈕後，系統會將個人存取權杖安全地儲存在 Secret Manager。連線至 Bitbucket Data Center 主機後，Cloud Build 會代您建立 Webhook 密鑰。您可以在「Secret Manager」頁面查看及管理密鑰。

gcloud

  1. 將權杖儲存在 Secret Manager。

  2. 執行下列指令，在 Secret Manager 中建立 Webhook 密鑰，其中 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 專案 ID。

現在可以繼續將 Bitbucket Data Center 主機連結至 Cloud Build。

  1. 執行下列指令，建立 Bitbucket Data Center 連線：

    gcloud builds connections create bitbucket-data-center 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 是 Cloud Build 中 Bitbucket Data Center 主機連線的名稱。
    • HOST_URI 是 Bitbucket Data Center 執行個體的 URI。
    • PROJECT_ID 是您的 Google Cloud 專案 ID。
    • REGION 是連線的地區。
    • ADMIN_TOKEN 是範圍為「repository admin」的權杖名稱。
    • READ_TOKEN 是範圍為「repository read」的權杖名稱。
    • SECRET_VERSION 是密鑰的版本。
    • WEBHOOK_SECRET 是您的 Webhook 密鑰。

Terraform

您可以使用 Terraform 將 Bitbucket Data Center 主機連至 Cloud Build。

在以下範例中，程式碼片段會執行下列操作：

  • 設定 Terraform Google 供應商。
  • 建立 Secret Manager 密鑰，用於儲存 Bitbucket 權杖。
  • 將存取密鑰的必要權限授予 Cloud Build 服務代理。

  • 建立 Bitbucket Data Center 連線。

    // 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_data_center_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 專案 ID。
  • 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 是 Cloud Build 中 Bitbucket Data Center 主機連線的名稱。
  • BITBUCKET_URI 是 Bitbucket Data Center 執行個體的 URI。

輪替舊的或過期的 Bitbucket Data Center 存取權杖

如果 Bitbucket Data Center 存取權杖過期，Cloud Build 主機連線就會與 Bitbucket Data Center 存放區中斷連線。因此，在下列情況下，您會看到錯誤訊息：

  • 嘗試連結 Bitbucket Data Center 存放區 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 是 Cloud Build 中 Bitbucket Data Center 主機連線的路徑，格式為 projects/PROJECT_ID/locations/REGION/connections/CONNECTION_NAME。
      • REGION 是連線的區域。

    2. 在指令輸出中，找出使用者權杖欄位的值。readAuthorizerCredential.userTokenSecretVersion 顯示權杖的 Secret Manager 名稱，Read 並顯示權杖的 Secret Manager 名稱。authorizerCredential.userTokenSecretVersion Admin 這些名稱會以 Secret 形式儲存在 Secret Manager 中。

  2. 在 Bitbucket Data Center 中輪替每個存取權杖：

    1. 前往連結至 Cloud Build 主機連線的 Bitbucket Data Center 存放區。

    2. 請按照 Bitbucket 說明文件中的操作說明輪替存取權杖。 輪替權杖時，Bitbucket Data Center 會使用新憑證建立新權杖，並使舊版權杖失效。輪替後的權杖與原始權杖的權限和範圍相同。

    3. 複製輪替後權杖的 ID。

  3. 為每個權杖建立新的密鑰版本：

    1. 在 Google Cloud 控制台中開啟「Secret Manager」頁面：

      開啟 Secret Manager 頁面

    2. 針對您輪替的每個符記，找出您在步驟 1 中識別的密碼名稱，然後按一下「動作」，再按一下「新增版本」。

    3. 在「新增版本」視窗中，輸入輪替權杖的 ID，然後按一下「新增版本」。

詳情請參閱 Bitbucket Data Center 說明文件中的「存取權杖」和「提升 Bitbucket 安全性：推出存取權杖到期功能」。

後續步驟