建立 Private Service Connect 執行個體

本頁說明如何為 Secure Source Manager 建立 Private Service Connect 執行個體。

Private Service Connect 執行個體不會向公開網際網路公開任何端點。建立 Private Service Connect 執行個體時，系統會建立端點，提供執行個體的 SSH (Git) 和 HTTPS (Git、網頁介面、API) 存取權。端點必須在私有網路上指派 IP 位址。Private Service Connect 執行個體的所有進出流量都會通過 Private Service Connect 端點。

如要進一步瞭解如何使用 Private Service Connect，從虛擬私有雲網路內部私下存取受管理服務，請參閱 Private Service Connect。

Secure Source Manager 是單一租戶服務。單一 Secure Source Manager 執行個體應只包含來自一個Google Cloud 客戶的使用者，除非多間有合約關係的公司需要使用單一執行個體進行協作。

如果您與多家公司合作，並想與他們共同處理原始碼，建議為每家公司建立個別的執行個體。

事前準備

登入 Google 帳戶。

如果沒有帳戶，請 申請新帳戶。

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Enable the Secure Source Manager API.

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 API

安裝 Google Cloud CLI。

注意：如果您先前已安裝 gcloud CLI，請執行 gcloud components update，確認您使用的是最新版本。

若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

執行下列指令，初始化 gcloud CLI：

gcloud init

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Enable the Secure Source Manager API.

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 API

安裝 Google Cloud CLI。

注意：如果您先前已安裝 gcloud CLI，請執行 gcloud components update，確認您使用的是最新版本。

若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

執行下列指令，初始化 gcloud CLI：

gcloud init

必要的角色

如要取得建立 Private Service Connect Secure Source Manager 執行個體所需的權限，請要求管理員授予您下列 IAM 角色：

• 機構的 Access Context Manager 管理員角色 (roles/accesscontextmanager.policyAdmin)
• 執行個體擁有者角色 (roles/securesourcemanager.instanceOwner) 執行個體
• 如要建立服務身分和憑證授權單位集區，請執行下列步驟： CA 服務作業管理員 (roles/privateca.caManager) 在機構上

建立服務身分和憑證授權單位集區

本節說明如何使用自己的 CA 憑證。如要在私人執行個體中使用自訂網域，請務必使用自己的 CA 憑證。如要使用 Google管理的憑證，而不使用自訂網域，您只需執行 gcloud source-manager instances create 指令，不必建立服務身分和 CA 集區。詳情請參閱「建立 Private Service Connect Secure Source Manager 執行個體」。

如果您使用自己的 CA 憑證，建立私有 Secure Source Manager 執行個體時，必須指定憑證授權單位 (CA) 集區名稱。系統會將簽署執行個體 HTTPS SSL 憑證的要求傳送至 CA 集區。

1. 執行下列指令，在專案中為 Secure Source Manager API 建立服務身分：

   gcloud beta services identity create \
       --service=securesourcemanager.googleapis.com \
       --project=PROJECT_ID
   

   其中 PROJECT_ID 是您的專案 ID。

   輸出結果會與下列內容相似：

   Service identity created: [e-mail]

   其中 [e-mail] 是 Secure Source Manager 服務代理程式，PROJECT_NUM 則是專案編號。

2. 建立憑證授權單位 (CA) 集區，並啟用以 CSR 為基礎的憑證要求。

3. 建立 CA。您可以根據需求建立根或從屬 CA。

   注意： 使用自己的憑證授權單位時，必須使用 2048 位元的金鑰大小。
   • 如要建立根 CA，請按照「建立根 CA」一文的說明操作。
   • 如要從 Google Cloud中的父項 CA 建立從屬 CA，請按照「建立從屬 CA」一文中的操作說明進行。
   • 如要從外部 CA 建立從屬 CA，請按照「從外部 CA 建立從屬 CA」一節的說明操作。

   如要進一步瞭解根 CA 和下層 CA 的差異，請參閱「判斷憑證授權單位設定」。

4. 授予 Secure Source Manager API 服務身分權限，在 CA 集區中要求新憑證：

   gcloud privateca pools add-iam-policy-binding CA_POOL_NAME \
       --location=CA_LOCATION \
       --member='serviceAccount:[e-mail]' \
       --role='roles/privateca.certificateRequester' \
       --project=CA_PROJECT_ID
   

   更改下列內容：

   • CA_POOL_NAME 替換成您為 CA 集區提供的名稱。
   • CA_LOCATION 替換為 CA 集區的區域或可用區。
   • PROJECT_NUMBER，其中 Secure Source Manager 已啟用。如要找出專案編號，請參閱「識別專案」。
   • CA_PROJECT_ID，並將其替換為您建立 CA 集區的專案 ID。

建立 Private Service Connect Secure Source Manager 執行個體

您可以為 HTML、API、Git HTTP 和 Git SSH 端點指派私人執行個體的自訂網域。自訂網域需要您自己的 CA 憑證。因此，使用自訂網域建立執行個體時，您必須提供 CA 集區。您只能在建立執行個體時，使用 API 設定自訂網域。執行個體建立後即無法修改。

gcloud

使用下列指令建立 Private Service Connect 執行個體：

gcloud source-manager instances create INSTANCE_ID \
  --region=LOCATION \
  --project=PROJECT_ID \
  --is-private \
  --ca-pool=projects/CA_PROJECT/locations/CA_LOCATION/caPools/CA_POOL_NAME

更改下列內容：

• INSTANCE_ID 替換為您要為執行個體取的名稱。
• LOCATION 替換為您要建立執行個體的地區。如要查看支援的地區，請參閱「地點」。
• PROJECT_ID 改為您要在其中建立執行個體的專案名稱。
• CA_PROJECT，並將其替換為 CA 集區專案的名稱。如果您使用自己的 CA 憑證，則必須提供這個屬性。
• CA_LOCATION，並替換為您建立 CA 集區的區域。 如果您使用自己的 CA 憑證，就必須提供這項資訊。
• CA_POOL_NAME 替換成 CA 集區的名稱。如果您使用自己的 CA 憑證，則必須提供這個屬性。

注意： 如果您使用Google管理的憑證，且未使用自訂網域，可以省略 --ca-pool 旗標。您只能使用 API 設定自訂網域。

API

使用下列指令建立 Private Service Connect 執行個體：

curl \
    -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://securesourcemanager.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances?instance_id=INSTANCE_ID \
    -H "Content-Type: application/json" \
    -d '{"private_config":{"is_private":true,"ca_pool":"projects/CA_PROJECT/locations/CA_LOCATION/caPools/CA_POOL_NAME","custom_host_config":{"api":"API_CUSTOM_DOMAIN", "html":"HTML_CUSTOM_DOMAIN", "git_ssh":"GIT_SSH_CUSTOM_DOMAIN", "git_http":"GIT_HTTP_CUSTOM_DOMAIN"}}}'

更改下列內容：

• INSTANCE_ID 替換為您要為執行個體取的名稱。
• LOCATION 替換為您要建立執行個體的地區。如要查看支援的地區，請參閱「地點」。
• PROJECT_ID 改為您要在其中建立執行個體的專案名稱。
• CA_PROJECT，並將其替換為 CA 集區專案的名稱。如果您使用自己的 CA 憑證或自訂網域，則必須設定這個屬性。
• CA_LOCATION，並替換為您建立 CA 集區的區域。 如果您使用自己的 CA 憑證或自訂網域，就必須設定這個屬性。
• CA_POOL_NAME 替換成 CA 集區的名稱。如果您使用自己的 CA 憑證或自訂網域，則必須提供這個屬性。
• API_CUSTOM_DOMAIN，其中包含用於存取 API 的自訂網域，例如 api.source.example.com。只有在使用自訂網域時才須提供。
• 將 HTML_CUSTOM_DOMAIN 替換為網頁介面的自訂網域，例如 source.example.com。只有在使用自訂網域時才須提供。
• 將 GIT_SSH_CUSTOM_DOMAIN 改為 Git SSH 存取的自訂網域，例如 ssh.source.example.com。只有在使用自訂網域時才須提供。
• 將 GIT_HTTP_CUSTOM_DOMAIN 換成 Git HTTP 存取的自訂網域，例如 git.source.example.com。只有在使用自訂網域時才須提供。

注意： 如果您使用 Google管理的憑證，請從這個指令中移除 ca_pool 欄位。如果您未使用自訂網域，請移除 custom_host_config 欄位。

Terraform

如要使用 Terraform 建立 Private Service Connect 執行個體，請使用 google_secure_source_manager_instance 資源，並將 private_config.is_private 欄位設為 true。

系統會開始長時間執行的執行個體建立作業。建立執行個體最多需要 60 分鐘。輸出結果會與下列內容相似：

Create request issued for [my-instance].
done: false
metadata:
  '@type': type.googleapis.com/google.cloud.securesourcemanager.v1.OperationMetadata
  apiVersion: v1
  createTime: '2023-02-27T20:57:52.315609549Z'
  requestedCancellation: false
  target: projects/my-project/locations/us-central1/instances/my-instance
  verb: create
name: projects/my-project/locations/us-central1/operations/operation-1234567894561-5ec69948c0f2b-60dd727f-a9b97a2e

其中 projects/my-project/locations/us-central1/operations/operation-1234567894561-5ec69948c0f2b-60dd727f-a9b97a2e 是 OPERATION_NAME。

您需要 OPERATION_NAME 才能檢查作業狀態。

如要檢查作業狀態，請執行下列指令：

gcloud source-manager operations describe OPERATION_NAME \
    --region=LOCATION

更改下列內容：

• 將 OPERATION_NAME 替換為建立指令回應中的作業名稱。
• LOCATION 替換為您要建立執行個體的地區。如要查看支援的地區，請參閱「地區」。

執行個體建立完成後，輸出內容會列出 Private Service Connect 端點 httpServiceAttachment 和 sshServiceAttachment，以及 html、api、gitHttp 和 gitSsh 的主機名稱。

存取私人執行個體

您可以根據轉送規則建立 Private Service Connect 端點，或根據負載平衡器建立 Private Service Connect 後端，藉此存取 Private Service Connect 執行個體。

以負載平衡器為基礎的 Private Service Connect 後端更具彈性，可與 Cloud Build 等其他 Google Cloud 服務整合，但較為複雜，且會產生額外費用。

以轉送規則為基礎的 Private Service Connect 端點較為簡單，費用也較低。不過，您無法連線至 Cloud Build 或其他Google Cloud 服務。

如要根據負載平衡器為 Private Service Connect 執行個體設定 Private Service Connect 後端，並將其連線至 Cloud Build，請參閱「將 Cloud Build 連線至 Private Service Connect 執行個體」。

根據轉送規則設定 Private Service Connect 端點

1. 如要建立 Private Service Connect 端點，請按照「透過端點存取已發布的服務」一文中的操作說明進行。

2. 如要取得 Secure Source Manager 執行個體 HTTP 和 SSH 服務附件的 URI，請執行下列指令：

   gcloud source-manager instances describe INSTANCE_ID \
       --region=LOCATION
   

   更改下列內容：

   • INSTANCE_ID 換成執行個體名稱。如要列出特定區域中的執行個體，請執行 gcloud source-manager instances list --region=LOCATION。
   • LOCATION 是執行個體的位置。如要查看支援的地區，請參閱「地點」。

   輸出內容包括：

   createTime: '2023-09-22T18:21:35.729454612Z'
   hostConfig:
     api: my-project-012345678901-api.us-central1.p.sourcemanager.dev
     gitHttp: my-project-012345678901-git.us-central1.p.sourcemanager.dev
     gitSsh: my-project-012345678901-ssh.us-central1.p.sourcemanager.dev
     html: my-project-012345678901.us-central1.p.sourcemanager.dev
   name: projects/my-project/locations/us-central1/instances/my-instance
   privateConfig:
     caPool: projects/my-project/locations/us-central1/caPools/my-ca-pool
     httpServiceAttachment: projects/abc12345d1a1234a0a-tp/regions/us-central1/serviceAttachments/http-psc
     isPrivate: true
     sshServiceAttachment: projects/abc12345d1a1234a0a-tp/regions/us-central1/serviceAttachments/ssh-psc
   state: ACTIVE
   updateTime: '2023-09-22T18:39:53.390563549Z'
   

   • projects/abc12345d1a1234a0a-tp/regions/us-central1/serviceAttachments/http-psc 是執行個體的 HTTP 服務附件 URI。
   • projects/abc12345d1a1234a0a-tp/regions/us-central1/serviceAttachments/ssh-psc 是執行個體的 SSH 服務連結 URI。

3. 建立 Private Service Connect 端點後，您需要設定私人 DNS 記錄。如需設定私人 DNS 記錄的操作說明，請參閱「手動設定 DNS」。如果您為執行個體設定自訂網域，請建立 DNS 記錄，將自訂網域對應至服務附件的內部 IP 位址。否則，請使用執行個體「hostConfig」欄位中的主機名稱：

   1. 將 hostConfig.html (或您的 HTML 自訂網域)、hostConfig.api (或您的 API 自訂網域) 和 hostConfig.gitHttp (或您的 Git HTTP 自訂網域) 的值，對應至 HTTP 服務附件的內部 IP 位址。
   2. 將 hostConfig.ssh 的值 (或 Git SSH 自訂網域) 對應至 SSH 服務連結的內部 IP 位址。

   舉例來說，在先前的範例輸出中，hostConfig.html 的值為 my-project-012345678901.us-central1.p.sourcemanager.dev。

   注意： DNS 區域和 Private Service Connect 必須位於相同的虛擬私有雲網路。
   Google Cloud

使用自訂網域進行 Git 驗證

如果私人執行個體使用自訂網域，請在每部機器上執行下列用戶端設定，透過 HTTPS 使用 Git。這項設定會將 Git 連線至 gcloud 憑證輔助程式，以針對自訂網域進行驗證。

1. 設定 Git，為自訂 Git HTTP 網域使用 gcloud 輔助程式：

   git config --global credential.'https://GIT_HTTP_CUSTOM_DOMAIN'.helper gcloud.sh
   

   將 GIT_HTTP_CUSTOM_DOMAIN 替換為您為 Git HTTP 存取設定的自訂網域。

2. 在 gcloud 中授權自訂網域：

   gcloud config set core/credentialed_hosted_repo_domains GIT_HTTP_CUSTOM_DOMAIN
   

   如要授權多個網域，請以半形逗號分隔每個網域。

搭配使用 CA 與 Secure Source Manager API

警告： CA 集區會維護信任的 CA 憑證清單。貴機構的 IT 管理員通常會負責發布 CA 憑證。以下操作說明僅適用於本教學課程，不適合用於正式環境。

Secure Source Manager 包含控制層和資料層。資料平面端點是由 Secure Source Manager 執行個體直接代管，因此您必須連線至執行個體的 API 主機名稱才能存取。

如要使用私有 Secure Source Manager 執行個體，請使用您在「建立服務身分和憑證授權單位集區」一節中建立的 CA。

1. 如要下載 CA，請執行下列指令：

   gcloud privateca pools get-ca-certs CA_POOL \
       --location LOCATION \
       --output-file=root-cert.pem \
       --project PROJECT
   

2. 如要對執行個體發出 API 呼叫，請將 CA 憑證傳遞至資料層 Secure Source Manager API。

   舉例來說，下列指令會將 CA 憑證 root-cert.pem 傳遞至 Secure Source Manager API，列出位置 us-central1 中私人執行個體 my-instance 的存放區。

   curl \
       --cacert root-cert.pem \
       -H "Authorization: Bearer $(gcloud auth print-access-token)" \
       https://my-instance-01234567890-api.us-central1.sourcemanager.dev/v1/projects/01234567890/locations/us-central1/repositories
   

後續步驟

• 將 Cloud Build 連線至 Private Service Connect Secure Source Manager 執行個體。
• 在 VPC Service Controls 服務範圍中設定 Secure Source Manager。