Access APIs from VMs with external IP addresses

A virtual machine (VM) instance with an external IP address assigned to its network interface can connect to Google APIs and services if the network requirements described on this page are met. Though the connection is made from the VM's external IP address, the traffic stays within Google Cloud and is not sent through the public internet.

Network requirements

You must meet the following requirements to access Google APIs and services from a VM with an external IP address:

  • If you want to connect to Google APIs and services using IPv6, you must meet both of these requirements:

  • Depending on your chosen configuration, you might need to update DNS entries, routes, and firewall rules. For more information, see Summary of configuration options.

Summary of configuration options

The following table summarizes the different ways that you can configure Private Google Access. For more detailed configuration information, see Network configuration.

Domain option DNS configuration Routing configuration Firewall configuration
Default domains No special DNS configuration required.

Ensure that your VPC network can route traffic to the IP address ranges that are used by Google APIs and services.

  • Basic configuration: Confirm that you have default routes with next hop default-internet-gateway and a destination range of 0.0.0.0/0 (for IPv4 traffic) and ::/0 (for IPv6 traffic, if needed). Create those routes if they are missing.
  • Custom configuration: Create routes for the IP address ranges used by Google APIs and services.

Ensure that your firewall rules allow egress to the IP address ranges used by Google APIs and services.

The default allow egress firewall rule allows this traffic, if there is no higher priority rule that blocks it.
private.googleapis.com

Configure DNS records in a private DNS zone to send requests to the following IP addresses:

For IPv4 traffic:

  • 199.36.153.8/30

For IPv6 traffic:

  • 2600:2d00:0002:2000::/64

Ensure that your VPC network has routes to the following IP ranges:

For IPv4 traffic:

  • 199.36.153.8/30
  • 34.126.0.0/18

For IPv6 traffic:

  • 2600:2d00:0002:2000::/64
  • 2001:4860:8040::/42

Ensure that your firewall rules allow egress to the following IP ranges:

For IPv4 traffic:

  • 199.36.153.8/30
  • 34.126.0.0/18

For IPv6 traffic:

  • 2600:2d00:0002:2000::/64
  • 2001:4860:8040::/42
restricted.googleapis.com

Configure DNS records to send requests to the following IP addresses:

For IPv4 traffic:

  • 199.36.153.4/30

For IPv6 traffic:

  • 2600:2d00:0002:1000::/64

Ensure that your VPC network has routes to the following IP ranges:

For IPv4 traffic:

  • 199.36.153.4/30
  • 34.126.0.0/18

For IPv6 traffic:

  • 2600:2d00:0002:1000::/64
  • 2001:4860:8040::/42

Ensure that your firewall rules allow egress to the following IP ranges:

For IPv4 traffic:

  • 199.36.153.4/30
  • 34.126.0.0/18

For IPv6 traffic:

  • 2600:2d00:0002:1000::/64
  • 2001:4860:8040::/42

Network configuration

This section describes the basic network requirements you must meet in order for a VM in your VPC network to access Google APIs and services.

Domain options

Choose the domain that you want to use to access Google APIs and services.

The private.googleapis.com and restricted.googleapis.com virtual IP addresses (VIPs) support only HTTP-based protocols over TCP (HTTP, HTTPS, and HTTP/2). All other protocols, including MQTT and ICMP, are not supported.

Domain and IP address ranges Supported services Example usage

Default domains.

All domain names for Google APIs and services except for private.googleapis.com and restricted.googleapis.com.

Various IP address ranges—you can determine a set of IP ranges that contains the possible addresses used by the default domains by referencing IP addresses for default domains.

Enables API access to most Google APIs and services regardless of whether they are supported by VPC Service Controls. Includes API access to Google Maps, Google Ads, and Google Cloud. Includes Google Workspace web applications such as Gmail and Google Docs, and other web applications.

The default domains are used when you don't configure DNS records for private.googleapis.com and restricted.googleapis.com.

private.googleapis.com

199.36.153.8/30

2600:2d00:0002:2000::/64

Enables API access to most Google APIs and services regardless of whether they are supported by VPC Service Controls. Includes API access to Google Maps, Google Ads, Google Cloud, and most other Google APIs, including the following list. Does not support Google Workspace web applications such as Gmail and Google Docs. Does not support any interactive websites.

Domain names that match:

  • accounts.google.com (only the paths needed for OAuth authentication)
  • *.aiplatform-notebook.cloud.google.com
  • *.aiplatform-notebook.googleusercontent.com
  • appengine.google.com
  • *.appspot.com
  • *.backupdr.cloud.google.com
  • backupdr.cloud.google.com
  • *.backupdr.googleusercontent.com
  • backupdr.googleusercontent.com
  • *.cloudfunctions.net
  • *.cloudproxy.app
  • *.composer.cloud.google.com
  • *.composer.googleusercontent.com
  • *.datafusion.cloud.google.com
  • *.datafusion.googleusercontent.com
  • *.dataproc.cloud.google.com
  • dataproc.cloud.google.com
  • *.dataproc.googleusercontent.com
  • dataproc.googleusercontent.com
  • dl.google.com
  • gcr.io or *.gcr.io
  • *.googleapis.com
  • *.gke.goog
  • *.gstatic.com
  • *.kernels.googleusercontent.com
  • *.ltsapis.goog
  • *.notebooks.cloud.google.com
  • *.notebooks.googleusercontent.com
  • packages.cloud.google.com
  • pkg.dev or *.pkg.dev
  • pki.goog or *.pki.goog
  • *.run.app
  • source.developers.google.com
  • storage.cloud.google.com

Use private.googleapis.com to access Google APIs and services by using a set of IP addresses only routable from within Google Cloud.

Choose private.googleapis.com under these circumstances:

  • You don't use VPC Service Controls.
  • You do use VPC Service Controls, but you also need to access Google APIs and services that are not supported by VPC Service Controls.1

restricted.googleapis.com

199.36.153.4/30

2600:2d00:0002:1000::/64

Enables API access to Google APIs and services that are supported by VPC Service Controls.

Blocks access to Google APIs and services that do not support VPC Service Controls. Does not support Google Workspace APIs or Google Workspace web applications such as Gmail and Google Docs.

Use restricted.googleapis.com to access Google APIs and services by using a set of IP addresses only routable from within Google Cloud.

Choose restricted.googleapis.com when you only need access to Google APIs and services that are supported by VPC Service Controls.

The restricted.googleapis.com domain does not permit access to Google APIs and services that do not support VPC Service Controls.1
1 If you need to restrict users to just the Google APIs and services that support VPC Service Controls, use restricted.googleapis.com, as it provides additional risk mitigation for data exfiltration. Using restricted.googleapis.com denies access to Google APIs and services that are not supported by VPC Service Controls. See Setting up private connectivity in the VPC Service Controls documentation for more details.

IPv6 support for private.googleapis.com and restricted.googleapis.com

The following IPv6 address ranges can be used to direct traffic from IPv6 clients to Google APIs and services:

  • private.googleapis.com: 2600:2d00:0002:2000::/64
  • restricted.googleapis.com: 2600:2d00:0002:1000::/64

Consider configuring the IPv6 addresses if you want to use the private.googleapis.com or restricted.googleapis.com domain, and you have clients that use IPv6 addresses. IPv6 clients that also have IPv4 addresses configured can reach Google APIs and services by using the IPv4 addresses. Not all services accept traffic from IPv6 clients.

DNS configuration

For connectivity to Google APIs and services, you can choose to send packets to the IP addresses associated with the private.googleapis.com or restricted.googleapis.com VIP. To use a VIP, you must configure DNS so that VMs in your VPC network reach services by using the VIP addresses instead of the public IP addresses.

The following sections describe how to use DNS zones to send packets to the IP addresses that are associated with your chosen VIP. Follow the instructions for all scenarios that apply to you:

When you configure DNS records for the VIPs, use only the IP addresses that are described in the following steps. Do not mix addresses from the private.googleapis.com and restricted.googleapis.com VIPs. This can cause intermittent failures because the services that are offered differ based on a packet's destination.

Configure DNS for googleapis.com

Create a DNS zone and records for googleapis.com:

  1. Create a private DNS zone for googleapis.com. Consider creating a Cloud DNS private zone for this purpose.

  2. In the googleapis.com zone, create the following private DNS records for either private.googleapis.com or restricted.googleapis.com, depending on which domain you've chosen to use.

    • For private.googleapis.com:

      1. Create an A record for private.googleapis.com pointing to the following IP addresses: 199.36.153.8, 199.36.153.9, 199.36.153.10, 199.36.153.11.

      2. To connect to APIs using IPv6 addresses, also configure an AAAA record for private.googleapis.com pointing to 2600:2d00:0002:2000::.

    • For restricted.googleapis.com:

      1. Create an A record for restricted.googleapis.com pointing to the following IP addresses: 199.36.153.4, 199.36.153.5, 199.36.153.6, 199.36.153.7.

      2. To connect to APIs using IPv6 addresses, also create an AAAA record for restricted.googleapis.com pointing to 2600:2d00:0002:1000::.

    To create private DNS records in Cloud DNS, see add a record.

  3. In the googleapis.com zone, create a CNAME record for *.googleapis.com that points to the domain that you've configured: private.googleapis.com or restricted.googleapis.com.

Configure DNS for other domains

Some Google APIs and services are provided using additional domain names, including *.gcr.io, *.gstatic.com, *.pkg.dev, pki.goog, and *.run.app. Refer to the domain and IP address ranges table in Domain options to determine if the additional domain's services can be accessed using private.googleapis.com or restricted.googleapis.com. Then, for each of the additional domains:

  1. Create a DNS zone for DOMAIN (for example, gcr.io). If you're using Cloud DNS, make sure this zone is located in the same project as your googleapis.com private zone.

  2. In this DNS zone, create the following private DNS records for either private.googleapis.com or restricted.googleapis.com, depending on which domain you've chosen to use.

    • For private.googleapis.com:

      1. Create an A record for DOMAIN pointing to the following IP addresses: 199.36.153.8, 199.36.153.9, 199.36.153.10, 199.36.153.11.

      2. To connect to APIs using IPv6 addresses, also create an AAAA record for DOMAIN pointing to 2600:2d00:0002:2000::.

    • For restricted.googleapis.com:

      1. Create an A record for DOMAIN pointing to the following IP addresses: 199.36.153.4, 199.36.153.5, 199.36.153.6, 199.36.153.7.

      2. To connect to APIs using IPv6 addresses, also create an AAAA record for restricted.googleapis.com pointing to 2600:2d00:0002:1000::.

  3. In the DOMAIN zone, create a CNAME record for *.DOMAIN that points to DOMAIN. For example, create a CNAME record for *.gcr.io that points to gcr.io.

Configure DNS for Cloud Storage custom domain names

If you are using Cloud Storage buckets, and you send requests to a Cloud Storage custom domain name, configuring DNS records for the custom Cloud Storage domain name to point to the IP addresses for private.googleapis.com or restricted.googleapis.com is not sufficient to allow access to the Cloud Storage buckets.

If you want to send requests to a Cloud Storage custom domain name, you must also explicitly set the HTTP request's Host header and TLS SNI to storage.googleapis.com The IP addresses for private.googleapis.com and restricted.googleapis.com do not support custom Cloud Storage hostnames in HTTP request Host headers and TLS SNIs.

Routing options

Your VPC network must have appropriate routes whose next hops are the default internet gateway. Google Cloud does not support routing traffic to Google APIs and services through other VM instances or custom next hops. Despite being called default internet gateway, packets sent from VMs in your VPC network to Google APIs and services remain within Google's network.

  • If you select the default domains, your VM instances connect to Google APIs and services using a subset of Google's external IP addresses. These IP addresses are publicly routable, but the path from a VM in a VPC network to those addresses remains within Google's network.

  • Google doesn't publish routes on the internet to any of the IP addresses used by either the private.googleapis.com or restricted.googleapis.com domains. Consequently, these domains can only be accessed by VMs in a VPC network or on-premises systems connected to a VPC network.

If your VPC network contains a default route whose next hop is the default internet gateway, you can use that route to access Google APIs and services, without needing to create custom routes. See routing with a default route for details.

If you have replaced a default route (destination 0.0.0.0/0 or ::0/0) with a custom route whose next hop is not the default internet gateway, you can meet the routing requirements for Google APIs and services using custom routing instead.

If your VPC network does not have an IPv6 default route, you won't have IPv6 connectivity to Google APIs and services. Add an IPv6 default route to allow IPv6 connectivity.

Routing with a default route

Each VPC network contains an IPv4 default route (0.0.0.0/0) when it is created. If you enable external IPv6 addresses on a subnet, a system-generated IPv6 default route (::/0) is added to that VPC network.

The default routes provides a path to the IP addresses for the following destinations:

  • The default domains.

  • private.googleapis.com: 199.36.153.8/30 and 2600:2d00:0002:2000::/64.

  • restricted.googleapis.com: 199.36.153.4/30 and 2600:2d00:0002:1000::/64.

To check the configuration of a default route in a given network, follow these directions.

Console

  1. In the Google Cloud console, go to the Routes page.

    Go to Routes

  2. Filter the list of routes to show just the routes for the network you need to inspect.

  3. Look for a route whose destination is 0.0.0.0/0 for IPv4 traffic or ::/0 for IPv6 traffic and whose next hop is default internet gateway.

gcloud

Use the following gcloud command, replacing NETWORK_NAME with the name of the network to inspect:

gcloud compute routes list \
    --filter="default-internet-gateway NETWORK_NAME"

If you need to create a replacement default IPv4 route, see Adding a static route.

If you need to create a replacement default IPv6 route, see Adding an IPv6 default route.

Custom routing

As an alternative to a default route, you can use custom static routes, each having a more specific destination, and each using the default internet gateway next hop. The number of routes you need and their destination IP addresses depend on the domain that you choose.

  • Default domains: you must have routes for the IP address ranges for Google APIs and services.
  • private.googleapis.com: 199.36.153.8/30 and 2600:2d00:0002:2000::/64
  • restricted.googleapis.com: 199.36.153.4/30 and 2600:2d00:0002:1000::/64

Additionally, we recommend that you add routes for 34.126.0.0/18 and 2001:4860:8040::/42. For more information, see Summary of configuration options.

To check the configuration of custom routes for Google APIs and services in a given network, follow these directions.

Console

  1. In the Google Cloud console, go to the Routes page.

    Go to Routes

  2. Use the Filter table text field to filter the list of routes using the following criteria, replacing NETWORK_NAME with the name of your VPC network.

    • Network: NETWORK_NAME
    • Next hop type: default internet gateway

  3. Look at the Destination IP range column for each route. If you chose the default domains, check for several custom static routes, one for each IP address range used by the default domain. If you chose private.googleapis.com or restricted.googleapis.com, look for that domain's IP range.

gcloud

Use the following gcloud command, replacing NETWORK_NAME with the name of the network to inspect:

gcloud compute routes list \
    --filter="default-internet-gateway NETWORK_NAME"

Routes are listed in table format unless you customize the command with the --format flag. Look in the DEST_RANGE column for the destination of each route. If you chose the default domains, check for several custom static routes, one for each IP address range used by the default domain. If you chose private.googleapis.com or restricted.googleapis.com, look for that domain's IP range.

If you need to create routes, see Adding a static route.

Firewall configuration

The firewall configuration of your VPC network must allow access from VMs to the IP addresses used by Google APIs and services. The implied allow egress rule satisfies this requirement.

In some firewall configurations, you need to create specific egress allow rules. For example, suppose you've created an egress deny rule that blocks traffic to all destinations (0.0.0.0 for IPv4 or ::/0 for IPv6). In that case, you must create one egress allow firewall rule whose priority is higher than the egress deny rule for each IP address range used by your chosen domain for Google APIs and services.

Additionally, we recommend that you include 34.126.0.0/18 and 2001:4860:8040::/42 in your egress allow firewall rule. For more information, see Summary of configuration options.

To create firewall rules, see Creating firewall rules. You can limit the VMs to which the firewall rules apply when you define the target of each egress allow rule.

IP addresses for default domains

This section describes how to create a list of default domain IP ranges used by Google APIs and services, such as *.googleapis.com and *.gcr.io. These ranges are allocated dynamically and change often, so it's not possible to define specific IP ranges for individual services or APIs. To maintain an accurate list, set up automation to run the script every day. For alternatives to maintaining a list of IP address ranges, consider using the private.googleapis.com VIP or Private Service Connect.

  • Google publishes the complete list of IP ranges that it makes available to users on the internet in goog.json.

  • Google also publishes a list of global and regional external IP addresses ranges available for customers' Google Cloud resources in cloud.json.

The IP addresses used by the default domains for Google APIs and services fit within the list of ranges computed by taking away all ranges in cloud.json from those in goog.json. These lists are updated frequently.

You can use the following Python script to create a list of IP address ranges that include those used by the default domains for Google APIs and services.

For information about running this script, see How to run.

from __future__ import print_function

import json

try:
    from urllib import urlopen
except ImportError:
    from urllib.request import urlopen
    from urllib.error import HTTPError

import netaddr

IPRANGE_URLS = {
    "goog": "https://www.gstatic.com/ipranges/goog.json",
    "cloud": "https://www.gstatic.com/ipranges/cloud.json",
}


def read_url(url):
    try:
        return json.loads(urlopen(url).read())
    except (IOError, HTTPError):
        print("ERROR: Invalid HTTP response from %s" % url)
    except json.decoder.JSONDecodeError:
        print("ERROR: Could not parse HTTP response from %s" % url)


def get_data(link):
    data = read_url(link)
    if data:
        print("{} published: {}".format(link, data.get("creationTime")))
        cidrs = netaddr.IPSet()
        for e in data["prefixes"]:
            if "ipv4Prefix" in e:
                cidrs.add(e.get("ipv4Prefix"))
            if "ipv6Prefix" in e:
                cidrs.add(e.get("ipv6Prefix"))
        return cidrs


def main():
    cidrs = {group: get_data(link) for group, link in IPRANGE_URLS.items()}
    if len(cidrs) != 2:
        raise ValueError("ERROR: Could process data from Google")
    print("IP ranges for Google APIs and services default domains:")
    for ip in (cidrs["goog"] - cidrs["cloud"]).iter_cidrs():
        print(ip)


if __name__ == "__main__":
    main()