Console
Start free

Access Google APIs through endpoints

This document explains how to use Private Service Connect endpoints to connect to Google APIs. Instead of sending API requests to the publicly available IP addresses for service endpoints such as storage.googleapis.com, you can send the requests to the internal IP address of an endpoint.

You can also use Private Service Connect to access services in another VPC network and to publish services.

Roles

The following IAM roles provide the permissions needed to perform the tasks in this guide.

Task Roles
Create an endpoint All of the following roles:
Compute Network Admin (roles/compute.networkAdmin),
Service Directory Editor (roles/servicedirectory.editor), and
DNS Administrator (roles/dns.admin)
Configure Private Google Access (optional) Compute Network Admin (roles/compute.networkAdmin)

Before you begin

Enable Private Google Access for a subnet

VMs without an external IP address assigned must be connected to a subnet with Private Google Access enabled to access Google APIs and services using an endpoint.

If the VM has more than one interface, connect the interface that is configured with a default route (usually nic0).

The source IP address of packets sent from the VM must match the VM interface's primary internal IPv4 address or an internal IPv4 address from an alias IP range.

To enable Private Google Access on a subnet, follow these steps.

Console

  1. In the Google Cloud console, go to the VPC networks page.

    Go to VPC networks

  2. Click the name of the network that contains the subnet for which you need to enable Private Google Access.

  3. Click the name of the subnet. The Subnet details page is displayed.

  4. Click Edit.

  5. In the Private Google Access section, select On.

  6. Click Save.

gcloud

  1. Determine the name and region of the subnet. To list the subnets for a particular network, use the following command:

    gcloud compute networks subnets list --filter=NETWORK_NAME

  2. Run the following command to enable Private Google Access:

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

  3. Verify that Private Google Access is enabled by running this command:

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

Replace the following:

  • SUBNET_NAME: the name of the subnet
  • REGION: the region for the subnet
  • NETWORK_NAME: the name of the VPC network that contains the subnet

Terraform

You can use the Terraform resource to enable Private Google Access on a subnet.

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
}

To learn how to apply or remove a Terraform configuration, see Basic Terraform commands.

Create an endpoint

After you have chosen an IP address that meets the requirements, you can create an endpoint.

An endpoint connects to Google APIs and services using a global forwarding rule. Each forwarding rule counts toward the per VPC network quota for Private Service Connect.

You can't update an endpoint for Google APIs and services after it is created. If you need to update an endpoint for Google APIs and services, delete the endpoint, and then create a new one.

Console

  1. In the Google Cloud console, go to the Private Service Connect page.

    Go to Private Service Connect

  2. Click the Connected endpoints tab.

  3. Click Connect endpoint.

  4. For Target, select the target API bundle that you want to use:

    • All Google APIs
    • VPC-SC

  5. For Endpoint name, enter a name for the endpoint.

  6. Select a Network for the endpoint.

  7. Select an IP Address for the endpoint.

    The IP address must meet these requirements.

    If you need a new IP address, you can create one:

    1. Click Create IP address.
    2. Enter a Name and Description for the IP address.
    3. Enter the IP address you want to use and click Save .

  8. If a Service Directory region is not already configured for this VPC network, select the region you want to use.

    All endpoints that are used to access Google APIs and services in a given VPC network use the same Service Directory region.

  9. If a Service Directory namespace is not already configured for this VPC network, configure the namespace you want to use:

    • To use an automatically assigned namespace, click the Namespace drop-down menu and select the automatically assigned namespace.

    • To select an existing namespace that is used in another network, click the Namespace drop-down menu and select a namespace from the list. The list displays all namespaces in the project. You must select a namespace that is used only for endpoints that are used to access Google APIs.

    • To create a new namespace, click the Namespace drop-down menu and click Create namespace. Enter the namespace and click Create.

    All endpoints that you use to access Google APIs and services in a given VPC network use the same Service Directory namespace.

  10. Click Add endpoint.

gcloud

  1. Reserve a global internal IP address to assign to the endpoint.

    gcloud compute addresses create ADDRESS_NAME \
  --global \
  --purpose=PRIVATE_SERVICE_CONNECT \
  --addresses=ENDPOINT_IP \
  --network=NETWORK_NAME

    Replace the following:

    • ADDRESS_NAME: the name to assign to the reserved IP address.

    • ENDPOINT_IP: the IP address to reserve for the endpoint.

      The IP address must meet these requirements.

    • NETWORK_NAME: the name of the VPC network for the endpoint.

  2. Create a forwarding rule to connect the endpoint to Google APIs and services.

    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 ]

    Replace the following:

    • ENDPOINT_NAME: the name to assign to the endpoint. The name must be a string of 1-20 characters, containing only lower-case letters and numbers. The name must start with a letter.

    • NETWORK_NAME: the name of the VPC network for the endpoint.

    • ADDRESS_NAME: the name of the reserved address on the associated network.

    • API_BUNDLE: the bundle of APIs to make available using the endpoint. See the list of supported APIs.

      • Use all-apis to give access to all supported APIs.

      • Use vpc-sc to restrict access to Google APIs that support VPC Service Controls.

    • REGION_NAMESPACE_URI: the URI of the Service Directory region or namespace that you want to use. This URI must reference the same project that you are creating the endpoint in.

      • You can define a region only with projects/PROJECT_NAME/locations/REGION.

      • You can define a region and namespace with projects/PROJECT_NAME/locations/REGION/namespaces/NAMESPACE.

      If you you omit --service-directory-registration completely, or set a region without a namespace, the following occurs:

      • If a region or namespace is already configured for this VPC network, those defaults are used.

      • If a region is not configured, the region is set to us-central1. If a namespace is not configured, a system-generated namespace is assigned.

API

  1. Reserve a global internal IP address to assign to the endpoint.

    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
}

    Replace the following:

    • PROJECT_ID: your project ID.

    • ADDRESS_NAME: the name to assign to the reserved IP address.

    • ENDPOINT_IP: the IP address to reserve for the endpoint.

      The IP address must meet these requirements.

    • NETWORK_URL: the VPC network for the endpoint. Use the network.list method or gcloud compute networks list --uri to find the URLs of your networks.

  2. Create a forwarding rule to connect the endpoint to Google APIs and services.

    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"

   }
 ],
}

    Replace the following:

    • PROJECT_ID: your project ID.

    • ENDPOINT_NAME: the name to assign to the endpoint. The name must be a string of 1-20 characters, containing only lower-case letters and numbers. The name must start with a letter.

    • NETWORK_URL: the VPC network for the endpoint. Use the network.list method or gcloud compute networks list --uri to find the URLs of your networks.

    • ADDRESS_URL: the URL of the reserved address on the associated network. Use the globalAddresses.list method or gcloud compute addresses list --uri to find the URLs of your reserved addresses.

    • API_BUNDLE: the bundle of APIs to make available using the endpoint. See the list of supported APIs.

      • Use all-apis to give access to all supported APIs.

      • Use vpc-sc to restrict access to Google APIs that support VPC Service Controls.

    • REGION: the Service Directory region you want to use. For example, us-central1. If you omit REGION, and a region is already configured for this VPC network, that region is used. If a region is not configured, the region is set to us-central1.

    • NAMESPACE: the name of the Service Directory namespace that you want to use. If you omit NAMESPACE, and a namespace is already configured for this VPC network, that namespace is used. If a namespace is not configured, a system-generated namespace is assigned.

Terraform

You can use the following Terraform resources to create an endpoint:

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 = ""
}

Verify that the endpoint is working

Create a VM instance in the VPC network where Private Service Connect is configured. Run the following command on the VM to verify that the Private Service Connect endpoint is working. Endpoints don't respond to ping (ICMP) requests.

curl -v ENDPOINT_IP/generate_204

Replace ENDPOINT_IP with the IP address of the endpoint.

If the endpoint is working, you see an HTTP 204 response code.

List endpoints

You can list all configured endpoints.