通过端点访问 Google API

本文档介绍如何使用 Private Service Connect 端点连接到 Google API。您可以将 API 请求发送到端点的内部 IP 地址，而不是将请求发送到服务端点（例如 storage.googleapis.com）的公共 IP 地址。

您还可以使用 Private Service Connect 来访问其他 VPC 网络中的服务和发布服务。

角色

以下 IAM 角色提供了执行本指南中任务所需的权限。

任务	角色
创建端点	以下所有角色： Compute Network Admin (`roles/compute.networkAdmin`)、 Service Directory Editor (`roles/servicedirectory.editor`) 和 DNS Administrator (`roles/dns.admin`)。
配置专用 Google 访问通道（可选）	Compute Network Admin (`roles/compute.networkAdmin`)

准备工作

如需了解详情（包括 DNS 配置和限制），请参阅使用端点连接到 Google API 的简介。
Private Service Connect 不会自动启用任何 API。您必须通过 Google Cloud 控制台中的“API 和服务”页面单独启用您需要使用的 Google API。
您必须在项目中启用 Compute Engine API。
您必须在项目中启用 Service Directory API。
您必须在项目中启用 Cloud DNS API。
您必须选择要用于端点的 IP 地址。如需了解您可以使用哪些 IP 地址，请参阅 IP 地址要求。
出站防火墙规则必须允许流向端点的流量。VPC 网络的默认防火墙配置允许此流量，因为它包含隐含的允许出站规则。确认您未创建优先级更高的出站流量规则来阻止流量。
没有分配外部 IP 地址的虚拟机实例 (VM) 实例必须使用启用了专用 Google 访问通道的子网，才能使用端点访问 Google API 和服务。

具有外部 IP 地址的虚拟机可以使用端点访问 Google API 和服务，即使其子网停用了专用 Google 访问通道也是如此。与端点的连接在 Google 的网络中进行。
如果您的 VPC 网络不包含任何端点，请检查 p.googleapis.com 是否存在 Cloud DNS 专用区域。如果该区域存在，请在创建端点之前将其删除。如果您不删除，则用于 Private Service Connect 的 Service Directory DNS 地区创建会失败。如需了解详情，请参阅问题排查。
无法从对等互连的 VPC 网络访问端点。

为子网启用专用 Google 访问通道

没有分配外部 IP 地址的虚拟机必须连接到启用了专用 Google 访问通道的子网，才能使用端点访问 Google API 和服务。

如虚拟机具有多个接口，请连接使用默认路由（通常为 nic0）的接口。

从虚拟机发送的数据包的来源 IP 地址必须与虚拟机接口的主要内部 IPv4 地址或来自别名 IP 地址范围的内部 IPv4 地址相匹配。

如需在子网上启用专用 Google 访问通道，请按以下步骤操作。

控制台

在 Google Cloud 控制台中，进入 VPC 网络页面。

进入 VPC 网络页面
点击您需要为其启用专用 Google 访问通道的子网所属网络的名称。
点击子网的名称。系统会显示子网详情页面。
点击修改。
在专用 Google 访问通道部分，选择开启。
点击保存。

gcloud

确定该子网的名称和地区。如需列出特定网络的子网，请使用以下命令：
```
gcloud compute networks subnets list --filter=NETWORK_NAME
```

运行以下命令以启用专用 Google 访问通道：

gcloud compute networks subnets update SUBNET_NAME \
--region=REGION \
--enable-private-ip-google-access

运行以下命令以验证专用 Google 访问通道是否已启用：

gcloud compute networks subnets describe SUBNET_NAME \
--region=REGION \
--format="get(privateIpGoogleAccess)"

请替换以下内容：

SUBNET_NAME：子网的名称
REGION：子网的地区
NETWORK_NAME：包含子网的 VPC 网络的名称

Terraform

您可以用 Terraform 资源在子网上启用专用 Google 访问通道。

resource "google_compute_network" "network" {
  project                 = var.project # Replace this with your project ID in quotes
  name                    = "tf-test"
  auto_create_subnetworks = false
}

resource "google_compute_subnetwork" "vpc_subnetwork" {
  project                  = google_compute_network.network.project
  name                     = "test-subnetwork"
  ip_cidr_range            = "10.2.0.0/16"
  region                   = "us-central1"
  network                  = google_compute_network.network.id
  private_ip_google_access = true
}

如需了解如何应用或移除 Terraform 配置，请参阅基本 Terraform 命令。

创建端点

选择满足要求的 IP 地址后，您可以创建一个端点。

端点使用全局转发规则连接到 Google API 和服务。每个转发规则都会计入 Private Service Connect 的各 VPC 网络配额。

Google API 和服务的端点创建后无法更新。如果您需要更新 Google API 和服务的端点，请删除端点，然后创建新端点。

执行此任务所需的权限

如需执行此任务，您必须获得以下权限或下列其中一个 IAM 角色。

适用于 gcloud CLI 和 API 的权限

compute.globalForwardingRules.pscCreate
compute.globalForwardingRules.create
compute.networks.use
compute.globalAddresses.use
servicedirectory.namespaces.create
servicedirectory.namespaces.associatePrivateZone
dns.managedZones.create

Google Cloud 控制台的权限

compute.forwardingRules.list
compute.globalForwardingRules.list
compute.networks.list
compute.backendBuckets.list
compute.backendServices.list
compute.instanceGroupManagers.list
compute.targetPools.list
compute.targetSslProxies.list
compute.targetTcpProxies.list
compute.urlMaps.list

角色

如需了解角色，请参阅角色。

控制台

在 Google Cloud 控制台中，转到 Private Service Connect 页面。

转到 Private Service Connect
点击已连接的端点标签页。
点击连接端点。
在目标部分中，选择您要使用的目标 API 软件包：
- 所有 Google API
- VPC-SC
对于端点名称，请输入端点的名称。
为端点选择网络。
为端点选择 IP 地址。

该 IP 地址必须满足这些要求。

如果您需要新的 IP 地址，可以创建一个：
1. 点击创建 IP 地址。
2. 为 IP 地址输入名称和说明。
3. 输入您要使用的 IP 地址，然后点击保存。
如果尚未为此 VPC 网络配置 Service Directory 区域，请选择您要使用的区域。

用于在给定 VPC 网络中访问 Google API 和服务的所有端点使用相同的 Service Directory 区域。
如果此 VPC 网络尚未配置 Service Directory 命名空间，请配置您要使用的命名空间：
- 如需使用自动分配的命名空间，请点击命名空间下拉菜单，然后选择自动分配的命名空间。
- 要选择用于其他网络的现有命名空间，请点击命名空间下拉菜单，然后从列表中选择一个命名空间。该列表会显示该项目中的所有命名空间。您必须选择仅用于访问 Google API 的端点的命名空间。
- 如需创建新的命名空间，请点击命名空间下拉菜单，然后点击创建命名空间。输入命名空间，然后点击创建。
您用于访问给定 VPC 网络中 Google API 和服务的所有端点都使用相同的 Service Directory 命名空间。
点击添加端点。

gcloud

预留要分配给端点的全局内部 IP 地址。
```
gcloud compute addresses create ADDRESS_NAME \
  --global \
  --purpose=PRIVATE_SERVICE_CONNECT \
  --addresses=ENDPOINT_IP \
  --network=NETWORK_NAME
```
请替换以下内容：
- ADDRESS_NAME：分配给预留 IP 地址的名称。
- ENDPOINT_IP：为端点预留的 IP 地址。
  
  该 IP 地址必须满足这些要求。
- NETWORK_NAME：端点的 VPC 网络的名称。
创建转发规则以将端点连接到 Google API 和服务。
```
gcloud compute forwarding-rules create ENDPOINT_NAME \
  --global \
  --network=NETWORK_NAME \
  --address=ADDRESS_NAME \
  --target-google-apis-bundle=API_BUNDLE \
  [ --service-directory-registration=REGION_NAMESPACE_URI ]
```
请替换以下内容：
- ENDPOINT_NAME：分配给端点的名称。名称必须是 1-20 个字符的字符串，仅包含小写字母和数字。名称必须以字母开头。
- NETWORK_NAME：端点的 VPC 网络的名称。
- ADDRESS_NAME：关联网络中预留地址的名称。
- API_BUNDLE：通过端点提供的 API 软件包。请参阅支持的 API 列表。
  - 使用 all-apis 可访问所有受支持的 API。
  - 使用 vpc-sc 限制对支持 VPC Service Controls 的 Google API 的访问。
- REGION_NAMESPACE_URI：您要使用的 Service Directory 区域或命名空间的 URI。此 URI 必须引用您要在其中创建端点的项目。
  - 您只能使用 projects/PROJECT_NAME/locations/REGION 定义区域。
  - 您可以使用 projects/PROJECT_NAME/locations/REGION/namespaces/NAMESPACE 定义区域和命名空间。
  如果您完全省略 --service-directory-registration，或设置不带命名空间的区域，则会发生以下情况：
  - 如果此 VPC 网络已配置地区或命名空间，则使用这些默认值。
  - 如果未配置区域，则区域会设置为 us-central1。如果未配置命名空间，则分配系统生成的命名空间。

API

预留要分配给端点的全局内部 IP 地址。
```
POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/addresses

{
"name": ADDRESS_NAME,
"address": ENDPOINT_IP,
"addressType": "INTERNAL",
"purpose": PRIVATE_SERVICE_CONNECT,
"network": NETWORK_URL
}
```
请替换以下内容：
- PROJECT_ID：您的项目 ID。
- ADDRESS_NAME：分配给预留 IP 地址的名称。
- ENDPOINT_IP：为端点预留的 IP 地址。
  
  该 IP 地址必须满足这些要求。
- NETWORK_URL：端点的 VPC 网络。使用 network.list 方法或 gcloud compute networks list --uri 查找网络的网址。
创建转发规则以将端点连接到 Google API 和服务。
```
POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/forwardingRules
{
 "IPAddress": ADDRESS_URL,
 "network": NETWORK_URL,
 "name": ENDPOINT_NAME,
 "target": API_BUNDLE,
 "serviceDirectoryRegistrations : [
   {
     "service_directory_region": REGION,
     "namespace": "NAMESPACE"

   }
 ],
}
```
请替换以下内容：
- PROJECT_ID：您的项目 ID。
- ENDPOINT_NAME：分配给端点的名称。名称必须是 1-20 个字符的字符串，仅包含小写字母和数字。名称必须以字母开头。
- NETWORK_URL：端点的 VPC 网络。使用 network.list 方法或 gcloud compute networks list --uri 查找网络的网址。
- ADDRESS_URL：关联网络上的预留地址的网址。使用 globalAddress.list 方法或 gcloud compute addresses list --uri 查找预留地址的网址。
- API_BUNDLE：通过端点提供的 API 软件包。请参阅支持的 API 列表。
  - 使用 all-apis 可访问所有受支持的 API。
  - 使用 vpc-sc 限制对支持 VPC Service Controls 的 Google API 的访问。
- REGION：您要使用的 Service Directory 区域。例如 us-central1。如果省略 REGION，并且已为此 VPC 网络配置区域，则使用该地区。如果未配置区域，则区域会设置为 us-central1。
- NAMESPACE：您要使用的 Service Directory 命名空间的名称。如果省略 NAMESPACE，并且已为此 VPC 网络配置命名空间，则使用该命名空间。如果未配置命名空间，则分配系统生成的命名空间。

Terraform

您可以使用以下 Terraform 资源创建端点：

resource "google_compute_global_address" "default" {
  project      = google_compute_network.network.project
  name         = "global-psconnect-ip"
  address_type = "INTERNAL"
  purpose      = "PRIVATE_SERVICE_CONNECT"
  network      = google_compute_network.network.id
  address      = "10.3.0.5"
}

resource "google_compute_global_forwarding_rule" "default" {
  project               = google_compute_network.network.project
  name                  = "globalrule"
  target                = "all-apis"
  network               = google_compute_network.network.id
  ip_address            = google_compute_global_address.default.id
  load_balancing_scheme = ""
}

验证端点是否正常运行

在配置了 Private Service Connect 的 VPC 网络中创建一个虚拟机实例。在虚拟机上运行以下命令以验证 Private Service Connect 端点正常运行。端点不会响应 ping (ICMP) 请求。

curl -v ENDPOINT_IP/generate_204

将 ENDPOINT_IP 替换为端点的 IP 地址。

如果端点正常运行，您会看到 HTTP 204 响应代码。

列出端点

您可以列出所有已配置的端点。

执行此任务所需的权限

如需执行此任务，您必须获得以下权限或下列其中一个 IAM 角色。

适用于 gcloud CLI 和 API 的权限

compute.globalForwardingRules.list

Google Cloud 控制台的权限

compute.forwardingRules.list
compute.globalForwardingRules.list
compute.networks.list
compute.backendBuckets.list
compute.backendServices.list
compute.instanceGroupManagers.list
compute.targetPools.list
compute.targetSslProxies.list
compute.targetTcpProxies.list
compute.urlMaps.list

角色

如需了解角色，请参阅角色。

控制台

在 Google Cloud 控制台中，转到 Private Service Connect 页面。

转到 Private Service Connect
点击已连接的端点标签页。

页面上将会显示端点。

gcloud

gcloud compute forwarding-rules list  \
--filter target="(all-apis OR vpc-sc)" --global

输出类似于以下内容：

NAME  REGION  IP_ADDRESS  IP_PROTOCOL  TARGET
RULE          IP          TCP          all-apis

获取有关端点的信息

您可以查看端点的所有配置详细信息。

执行此任务所需的权限

如需执行此任务，您必须获得以下权限或下列其中一个 IAM 角色。

适用于 gcloud CLI 和 API 的权限

compute.globalForwardingRules.get

Google Cloud 控制台的权限

compute.forwardingRules.list
compute.globalForwardingRules.list
compute.networks.list
compute.backendBuckets.list
compute.backendServices.list
compute.instanceGroupManagers.list
compute.targetPools.list
compute.targetSslProxies.list
compute.targetTcpProxies.list
compute.urlMaps.list

角色

如需了解角色，请参阅角色。

控制台

在 Google Cloud 控制台中，转到 Private Service Connect 页面。

转到 Private Service Connect
点击已连接的端点标签页。

页面上将会显示端点。
点击要查看其详细信息的端点。

gcloud

gcloud compute forwarding-rules describe \
    ENDPOINT_NAME --global

为端点添加标签

您可以管理端点的标签。如需了解详情，请参阅为资源添加标签。

执行此任务所需的权限

如需执行此任务，您必须获得以下权限或下列其中一个 IAM 角色。

权限

compute.globalForwardingRules.pscSetLabels
compute.globalForwardingRules.setLabels

角色

如需了解角色，请参阅角色。

删除端点

您可以删除端点。

执行此任务所需的权限

如需执行此任务，您必须获得以下权限或下列其中一个 IAM 角色。

适用于 gcloud CLI 和 API 的权限

compute.globalForwardingRules.pscDelete
compute.globalForwardingRules.delete
servicedirectory.namespaces.delete
dns.managedZones.delete

Google Cloud 控制台的权限

compute.forwardingRules.list
compute.globalForwardingRules.list
compute.networks.list
compute.backendBuckets.list
compute.backendServices.list
compute.instanceGroupManagers.list
compute.targetPools.list
compute.targetSslProxies.list
compute.targetTcpProxies.list
compute.urlMaps.list

角色

如需了解角色，请参阅角色。

控制台

在 Google Cloud 控制台中，转到 Private Service Connect 页面。

转到 Private Service Connect
点击已连接的端点标签页。
选择要删除的端点，然后点击删除。

gcloud

    gcloud compute forwarding-rules delete \
        ENDPOINT_NAME --global

将 ENDPOINT_NAME 替换为要删除的端点的名称。

使用端点

如需使用端点，请向解析为端点 IP 地址的 DNS 主机名发送请求。

如果您能将客户端配置为使用自定义端点，并且为要使用的 API 和服务创建了 p.googleapis.com DNS 记录，则可以使用自动创建的 p.googleapis.com DNS 名称。如需了解详情，请参阅使用 p.googleapis.com DNS 名称。

例如，如果您的端点名称为 xyz，则系统会为 API 软件包中的 storage-xyz.p.googleapis.com、compute-xyz.p.googleapis.com 和其他常用 API 创建 DNS 记录。
如果您使用的客户端未配置为使用自定义端点，或者您想要使用的服务没有对应的 p.googleapis.com DNS 记录，则可以使用默认 DNS 名称创建 DNS 记录。如需了解详情，请参阅使用默认 DNS 名称创建 DNS 记录。

例如，为 storage.googleapis.com 和 compute.googleapis.com 创建 DNS 记录。

使用 `p.googleapis.com` DNS 名称

创建端点时，Service Directory 会为通过端点提供的常用 API 和服务创建 DNS 记录。系统只会为默认 DNS 名称以 googleapis.com 结尾的 API 和服务以及这些 API 和服务中的一部分创建 DNS 记录。

将在 p.googleapis.com 专用地区中创建 DNS 记录。这些记录会指向端点 IP 地址，并使用以下格式：SERVICE-ENDPOINT.p.googleapis.com

例如，如果您的端点名称为 xyz，则系统会为 storage-xyz.p.googleapis.com、compute-xyz.p.googleapis.com 和其他受支持的 API 创建 DNS 记录。

可以配置为使用自定义端点的客户端可以使用 p.googleapis.com DNS 名称向端点发送请求。

如需了解如何将客户端配置为使用自定义端点，请参阅客户端或客户端库的文档。例如：

Python：您可以在客户端选项中配置 api_endpoint。
Go：您可以在 ClientOptions 中配置 WithEndpoint。
.NET：您可以在客户端的构建器类中配置 Endpoint。
gcloud：您可以在 gcloud CLI 中配置 api_endpoint_overrides。

使用默认 DNS 名称创建 DNS 记录

在以下情况下，您需要创建 DNS 记录，以将 API 和服务的默认 DNS 名称定向到您的端点：

您的客户端或应用无法配置为使用 p.googleapis.com DNS 名称。
您需要访问受支持的服务，但系统没有为该服务自动创建 p.googleapis.com DNS 名称。

如需创建指向 Private Service Connect 端点的 DNS 记录，请按照以下说明操作：

为您需要的网域（例如 googleapis.com 或 gcr.io）创建 DNS 区域。为此，请考虑创建 Cloud DNS 专用区域。
在此 DNS 区域中：
1. 为网域（区域）名称本身创建 A 记录；例如 googleapis.com 或 gcr.io。将此 A 记录指向端点的 IP 地址。如果您使用的是 Cloud DNS，请参阅添加记录。
2. 为其他网域的所有可能的主机名创建 CNAME 记录，格式为一个星号和一个点后跟网域（区域）名称，例如 *.googleapis.com 或 *.gcr.io。将此 CNAME 记录指向同一区域中的 A 记录。例如，将 *.googleapis.com 指向 googleapis.com，或将 *.gcr.io 指向 gcr.io。

从本地主机访问端点

如果您的本地网络连接到 VPC 网络，您可以使用 Private Service Connect 和端点的内部 IP 地址从本地主机访问 Google API 和服务。

您的本地网络必须使用 Cloud VPN 隧道或 Cloud Interconnect 的 VLAN 连接来连接到 VPC 网络。
端点必须位于连接到本地网络的 VPC 网络中。
本地网络必须具有端点的相应路由。配置 Cloud Router 自定义路由通告，以通告管理 Cloud VPN 隧道或 VLAN 连接的路由的 BGP 会话上的端点的路由。
- 如果您的本地网络使用等价多路径 (ECMP) 路由将流量分配到 Private Service Connect 端点，则必须确保单个 TCP 连接的所有数据包都通过同一 Cloud VPN 隧道或 VLAN 连接路由。如果已建立的 TCP 连接的数据包通过多条路径进行路由，则可能会遇到间歇性 TCP 重置 (RST) 问题。为了帮助防止重置，请配置本地对等路由器以保持一致的下一个跃点目的地。
您必须配置本地系统，以便它们可以对您的专用 DNS 区域进行查询。

如果您已使用 Cloud DNS 实现专用 DNS 区域，请完成以下步骤：
- 在本地网络连接到的 VPC 网络中，创建入站服务器政策。
- 在您的本地网络所连接的 VPC 网络中，于您的 Cloud VPN 隧道和 VLAN 连接所在的区域找到入站转发器入口点。
- 配置本地系统和本地 DNS 域名服务器，以将 Private Service Connect 端点的 DNS 名称转发到 VPC 网络连接的 Cloud VPN 隧道或 VLAN 连接所在区域的入站转发器入口点。

问题排查

以下部分介绍了如何解决用于访问 Google API 的 Private Service Connect 端点的问题。

创建专用 DNS 区域失败

当您创建端点时，系统会创建一个 Service Directory DNS 区域。区域创建可能会由于以下原因而失败：

您尚未在项目中启用 Cloud DNS API。
您没有创建 Service Directory DNS 区域所需的权限。
此 VPC 网络中已存在具有同一地区名称的 DNS 地区。
此 VPC 网络中已存在用于 p.googleapis.com 的 DNS 地区。

由于之前删除失败，可能存在冲突的地区。

如需创建 Service Directory DNS 地区，请执行以下操作：

验证是否已在您的项目中启用 Cloud DNS API。
验证您是否拥有创建 Service Directory DNS 区域所需的权限：
- dns.managedZones.create
- servicedirectory.namespaces.associatePrivateZone
删除 DNS 区域。
创建 Service Directory DNS 区域，此区域由与端点关联的 Service Directory 命名空间支持。

创建区域时，请使用以下值：
- 地区名称：使用系统在创建尝试失败期间的同一地区名称。错误消息会显示使用的区域名称。
- DNS 名称：p.googleapis.com.（包括结尾句点）。
- Service Directory 命名空间：为您创建的 Private Service Connect 端点查找 Service Directory 命名空间，并在创建 Service Directory DNS 时使用此命名空间。
Service Directory 命名空间采用以下格式：goog-psc-NETWORK_NAME-NETWORK_ID。

删除专用 DNS 区域失败

当您删除 VPC 网络中最后一个端点时，关联的 Service Directory 配置（包括 DNS 区域）会被删除。

删除失败的原因如下：

您无权删除 DNS 地区。
该地区包含用户定义的 DNS 条目，这些条目并非由 Service Directory 创建。

如需解决此问题，请执行以下操作：

验证您是否具有 dns.managedZones.delete 权限。如需了解详情，请参阅 Cloud DNS 文档中的访问权限控制。
删除 DNS 区域。

通过端点访问 Google API

角色

准备工作

为子网启用专用 Google 访问通道

控制台

gcloud

Terraform

创建端点

执行此任务所需的权限

控制台

gcloud

API

Terraform

验证端点是否正常运行

列出端点

执行此任务所需的权限

控制台

gcloud

获取有关端点的信息

执行此任务所需的权限

控制台

gcloud

为端点添加标签

执行此任务所需的权限

删除端点

执行此任务所需的权限

控制台

gcloud

使用端点

使用 p.googleapis.com DNS 名称

使用默认 DNS 名称创建 DNS 记录

从本地主机访问端点

问题排查

创建专用 DNS 区域失败

删除专用 DNS 区域失败

使用 `p.googleapis.com` DNS 名称