Accessing 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:

  • You must enable the Google APIs you need to use on the APIs & services page in the Google Cloud Console.

  • If you use the private.googleapis.com or the restricted.googleapis.com domain names, you'll need to create DNS records to direct traffic to the IP addresses associated with those domains. See Network configuration for guidance.

  • Your network must have appropriate routes for the destination IP ranges used by Google APIs and services. These routes must use the default internet gateway next hop. If you use the private.googleapis.com or the restricted.googleapis.com domain names, you only need one route (per domain). Otherwise, you'll need to create multiple routes. See Routing options for details.

  • Egress firewalls must permit traffic to the IP address ranges used by Google APIs and services. The implied allow egress firewall rule satisfies this requirement. For other ways to meet the firewall requirement, see Firewall configuration.

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.

You should first choose the domain on which you access Google APIs and services.

The private.googleapis.com and restricted.googleapis.com 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, Google Cloud. Includes Google Workspace 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
Enables API access to most Google APIs and services regardless of whether they are supported by VPC Service Controls. Includes API access to Maps, Google Ads, Google Cloud, and most other Google APIs, including the lists below. Does not support Google Workspace web applications. Does not support any interactive websites.

Domain names that end with:
  • googleapis.com
  • googleadapis.com
  • ltsapis.goog
  • gcr.io
  • pkg.dev
  • gstatic.com
  • appspot.com
  • cloudfunctions.net
  • pki.goog
  • cloudproxy.app
  • run.app
  • datafusion.googleusercontent.com
  • datafusion.cloud.google.com
  • notebooks.cloud.google.com
  • notebooks.googleusercontent.com
Host/domain names that match:
  • appengine.google.com
  • gcr.io
  • packages.cloud.google.com
  • pkg.dev
  • pki.goog
  • source.developers.google.com

Use private.googleapis.com to access Google APIs and services 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.

restricted.googleapis.com

199.36.153.4/30
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 web applications or Google Workspace APIs.

Use restricted.googleapis.com to access Google APIs and services 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 — restricted.googleapis.com does not permit access to Google APIs and services that do not support VPC Service Controls.

DNS configuration

If you choose either private.googleapis.com or restricted.googleapis.com, you need to configure DNS such that VMs in your VPC network resolve requests to *.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 one of the following A records, depending on the chosen domain:

    • 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
    • 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

    If you're using Cloud DNS, add the records to the googleapis.com private zone.

  3. In the googleapis.com zone, create a CNAME record for *.googleapis.com that points to whichever A record you created in the previous step.

Some Google APIs and services are provided using additional domain names, including *.gcr.io, *.gstatic.com, and pki.goog. Refer to the domain and IP address ranges table in network requirements 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 the additional 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 an A record for the domain (zone) name itself; for example, gcr.io. Point this A record to the same four IP addresses for the custom domain name you chose (either private.googleapis.com or restricted.googleapis.com).
    • Create a CNAME record for all of the additional domain's possible host names by using an asterisk and a dot followed by the domain (zone) name; for example, *.gcr.io. Point this CNAME record to the A record in the same zone. For example, point *.gcr.io to gcr.io.

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 on any domain, without needing to create custom routes. See routing with a default route for details.

If you have replaced the default route with a custom static route having a destination of 0.0.0.0/0 and a next hop that's not the default internet gateway, you can meet the routing requirements for Google APIs and services using custom routing instead. Consider custom routing in these situations:

  • You have a custom static route with destination 0.0.0.0/0 and next hop being a Cloud VPN tunnel, an internal TCP/UDP load balancer, or another VM instance.
  • You use a Cloud Router to accept a custom dynamic route having a destination of 0.0.0.0/0.

Routing with a default route

Each VPC network contains a default route when it is created. This route's next hop is the default internet gateway, and it provides a path to the default domains, private.googleapis.com, and restricted.googleapis.com.

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

Console

  1. Go to the Routes page in the Google Cloud Console.
    Go to the Routes page
  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 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 route, see Adding a static 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 you choose.

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

Console

  1. Go to the Routes page in the Google Cloud Console.
    Go to the Routes page
  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). 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.

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

Follow these steps to determine the IP address ranges used by the default domains, such as *.googleapis.com and *.gcr.io.

  • 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. The following example shows you how to get this range using Python.

Python

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 macOS, this script requires a Python 3 runtime configured as follows:

  • Install the current version Python 3 runtime for macOS.
  • Run the included Install Certificates.command from the Python folder in your Applications folder to install a list of trusted root certificates (cert.pem) for the Python runtime to use. Replace VERSION with the Python version you installed (like 3.8):
    sudo "/Applications/Python VERSION/Install Certificates.command"
  • Install the netaddr module by running:
    sudo pip3 install netaddr
#!/usr/bin/env python3

import json
import netaddr
import urllib.request

goog_url="https://www.gstatic.com/ipranges/goog.json"
cloud_url="https://www.gstatic.com/ipranges/cloud.json"

def read_url(url):
   try:
      s = urllib.request.urlopen(url).read()
      return json.loads(s)
   except urllib.error.HTTPError:
      print("Invalid HTTP response from %s" % url)
      return {}
   except json.decoder.JSONDecodeError:
      print("Could not parse HTTP response from %s" % url)
      return {}

def main():
   goog_json=read_url(goog_url)
   cloud_json=read_url(cloud_url)

   if goog_json and cloud_json:
      print("{} published: {}".format(goog_url,goog_json.get('creationTime')))
      print("{} published: {}".format(cloud_url,cloud_json.get('creationTime')))
      goog_cidrs = netaddr.IPSet()
      for e in goog_json['prefixes']:
         if e.get('ipv4Prefix'):
            goog_cidrs.add(e.get('ipv4Prefix'))
      cloud_cidrs = netaddr.IPSet()
      for e in cloud_json['prefixes']:
         if e.get('ipv4Prefix'):
            cloud_cidrs.add(e.get('ipv4Prefix'))
      print("IP ranges for Google APIs and services default domains:")
      for i in goog_cidrs.difference(cloud_cidrs).iter_cidrs():
         print(i)

if __name__=='__main__':
   main()