创建 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 从 VPC 网络内部以私密方式访问 托管式服务，请参阅 Private Service Connect。

Secure Source Manager 是一项单租户服务。除非有合同关系的多个公司需要使用单个实例进行协作，否则单个 Secure Source Manager 实例应仅包含来自一个 Google Cloud 客户的用户。

如果您与多家公司合作，并希望与他们协作处理源代码，建议您为每家公司创建一个单独的实例。

准备工作

登录您的 Google 账号。

如果您还没有 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 Admin 角色 (roles/accesscontextmanager.policyAdmin)
• 实例的 Instance Owner 角色 (roles/securesourcemanager.instanceOwner)
• 如需创建服务身份和证书授权机构池，请在组织中授予 CA Service Operation Manager (roles/privateca.caManager) 角色

创建服务身份和证书授权机构池

本部分介绍了如何使用您自己的 CA 证书。如果您打算将自定义网域与专用实例搭配使用，则必须使用您自己的 CA 证书。如需使用 Google 管理的证书而不使用自定义网域， 您只需运行 gcloud source-manager instances create 命令，而无需创建服务身份和 CA 池。 Google如需了解详情，请参阅创建 Private Service Connect Secure Source Manager 实例。

如果您使用的是自己的 CA 证书，则在创建专用 Secure Source Manager 实例时，必须指定证书授权机构 (CA) 池名称。系统会向 CA 池发送为实例的 HTTPS SSL 证书签名的请求。

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. 创建启用了基于 CSR 的 证书请求的证书授权机构 (CA) 池。

3. 创建 CA。您可以根据需要创建根 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 标志。Google您只能使用 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 替换为用于 Web 界面访问的自定义网域，例如 source.example.com。仅当您使用自定义网域时，才需要填写此字段。
• GIT_SSH_CUSTOM_DOMAIN 替换为用于 Git SSH 访问的自定义网域，例如 ssh.source.example.com。仅当您使用自定义网域时，才需要填写此字段。
• GIT_HTTP_CUSTOM_DOMAIN 替换为用于 Git HTTP 访问的自定义网域，例如 git.source.example.com。仅当您使用自定义网域时，才需要填写此字段。

注意： 如果您使用 Google 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 后端更加 灵活，可让您与其他 Google Cloud 服务（如 Cloud Build）集成，但更复杂且需要额外付费。

基于转发规则的 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。 如果您为实例配置了自定义网域，请创建将自定义网域映射到服务连接的内部 IP 地址的 DNS 记录。否则，请使用实例的 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 以将 gcloud 帮助程序用于自定义 Git HTTP 网域：

   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。