DEV Community: Zach S.

Verifying Google Cloud egress IP ranges with cloud.json and jq

Zach S. — Tue, 13 Oct 2026 13:03:00 +0000

When GCE workloads or Cloud NAT gateways connect to external partner endpoints, it is common to run into asymmetric reachability issues - connections from one region work normally, while connections from another region (or from a newly reserved NAT IP in the same region) time out on the initial TCP SYN. In most cases, this happens because the destination firewall uses a static IP allowlist that hasn't been updated, or relies on a stale GeoIP database (for example, many regional prefixes in asia-* and europe-* are carved out of Google's ARIN 34.0.0.0/8 block, which still shows Country: US in raw WHOIS if the firewall doesn't ingest Google's IP feeds). To verify how Google advertises your egress IPs externally, you can cross-reference your project's reserved addresses from the Method: addresses.list | Compute Engine API against cloud.json.

Google publishes cloud.json as the machine-readable feed of all customer-usable external IPv4 and IPv6 ranges by region, as documented in Configure Private Google Access | Virtual Private Cloud - Google Cloud Documentation. When you are setting up a new Cloud NAT gateway or troubleshooting an outbound block with a partner network team, you can use this feed to quickly confirm which published CIDR block covers each of your external IPs and when the feed was last updated.

Automating the check with gcloud and jq

To avoid manually searching through more than a thousand prefixes in cloud.json, you can script this check. The script below uses gcloud compute addresses list | Google Cloud SDK to grab your reserved external IPs as JSON, fetches cloud.json, and uses jq to match each IPv4 address to its published CIDR range and regional scope:

#!/bin/bash

# --- Configuration (Replace with your details) ---
PROJECT="<YOUR_PROJECT_ID>"
REGION="<YOUR_REGION>"
CLOUD_IPS_URL="https://www.gstatic.com/ipranges/cloud.json"

echo "Checking external IPs in $PROJECT ($REGION) against $CLOUD_IPS_URL..."
echo "------------------------------------------------------------------------"

# Fetch reserved external IPs and match each IPv4 address against cloud.json CIDRs in jq
jq -rn \
  --argjson addrs "$(gcloud compute addresses list \
    --project="$PROJECT" \
    --regions="$REGION" \
    --filter="addressType=EXTERNAL" \
    --format=json)" \
  --argjson cloud "$(curl -s "$CLOUD_IPS_URL")" '
  # Convert an IPv4 address string into a 32-bit integer for CIDR matching
  def ip2int:
    split(".") | map(tonumber) | (.[0] * 16777216) + (.[1] * 65536) + (.[2] * 256) + .[3];

  # Regional IPv4 addresses omit ipVersion in the API response, while IPv6 reservations set "IPV6"
  $addrs[] | select((.ipVersion // "IPV4") == "IPV4") as $a |
  ($a.address | ip2int) as $ip_int |
  (
    [
      $cloud.prefixes[]
      | select(has("ipv4Prefix"))
      | (.ipv4Prefix | split("/")) as $parts
      | ($parts[0] | ip2int) as $net_int
      | ($parts[1] | tonumber) as $mask
      | (pow(2; 32 - $mask)) as $size
      | select($ip_int >= $net_int and $ip_int < ($net_int + $size))
    ][0] // { ipv4Prefix: "UNLISTED", scope: "UNKNOWN" }
  ) as $match |
  "Name: \($a.name) | IP: \($a.address) | Tier: \($a.networkTier) | Prefix: \($match.ipv4Prefix) | Scope: \($match.scope)"
'

Let's list the reserved external IP addresses in our target region first:

~  gcloud compute addresses list \
    --project="my-gcp-project" \
    --regions="us-south1" \
    --format='table(name, address, region.basename(), networkTier, status)'

NAME       ADDRESS         REGION     NETWORK_TIER  STATUS
nat-ip-a0  34.174.136.135  us-south1  PREMIUM       RESERVED
nat-ip-a1  34.174.242.159  us-south1  PREMIUM       RESERVED
nat-ip-a2  34.0.132.72     us-south1  STANDARD      RESERVED

Running the script maps each external IP to its parent CIDR block and regional scope in cloud.json:

~  bash gce-egress-prefix-check.sh

Checking external IPs in my-gcp-project (us-south1) against https://www.gstatic.com/ipranges/cloud.json...
------------------------------------------------------------------------
Name: nat-ip-a0 | IP: 34.174.136.135 | Tier: PREMIUM | Prefix: 34.174.0.0/16 | Scope: us-south1
Name: nat-ip-a1 | IP: 34.174.242.159 | Tier: PREMIUM | Prefix: 34.174.0.0/16 | Scope: us-south1
Name: nat-ip-a2 | IP: 34.0.132.72 | Tier: STANDARD | Prefix: 34.0.128.0/19 | Scope: us-south1

Under the hood: Reading the cloud.json payload

When you fetch cloud.json, the response includes a top-level syncToken and creationTime, followed by a prefixes array. For IPv4 ranges in us-south1, the JSON payload looks like this:

{
  "syncToken": "1791792540784",
  "creationTime": "2026-10-12T01:09:00.784842",
  "prefixes": [
    {
      "ipv4Prefix": "34.0.128.0/19",
      "service": "Google Cloud",
      "scope": "us-south1"
    },
    {
      "ipv4Prefix": "34.174.0.0/16",
      "service": "Google Cloud",
      "scope": "us-south1"
    }
  ]
}

Notice that nat-ip-a0 (PREMIUM tier) and nat-ip-a2 (STANDARD tier) come from different CIDR blocks (34.174.0.0/16 vs. 34.0.128.0/19) within us-south1. Compute Engine tracks the network service tier on each address resource (networkTier), while cloud.json groups both Premium and Standard tier external ranges under the same regional scope, as described in IP addresses | Compute Engine - Google Cloud Documentation:

{
  "address": "34.0.132.72",
  "addressType": "EXTERNAL",
  "kind": "compute#address",
  "name": "nat-ip-a2",
  "networkTier": "STANDARD",
  "region": "https://www.googleapis.com/compute/v1/projects/my-gcp-project/regions/us-south1",
  "status": "RESERVED"
}

If you are using external IPv6 ranges on dual-stack subnets, cloud.json also includes the regional /44 IPv6 blocks under the ipv6Prefix field:

{
  "ipv6Prefix": "2600:1901:8140::/44",
  "service": "Google Cloud",
  "scope": "us-south1"
}

A few quick constraints

API Support: Listing static external IPs works with both regional Method: addresses.list | Compute Engine and global/cross-region Method: addresses.aggregatedList | Compute Engine.
gcloud Support: Filter out internal RFC 1918 reservations by passing --filter="addressType=EXTERNAL" to gcloud compute addresses list | Google Cloud SDK. If your VMs use ephemeral external IPs instead of reserved addresses, pull .networkInterfaces[].accessConfigs[].natIP from gcloud compute instances list | Google Cloud SDK.
cloud.json vs. goog.json: Google publishes two separate IP range files. cloud.json lists customer-usable Google Cloud ranges with regional scope values, while goog.json covers all Google-owned prefixes without regional scopes.
IPv4 vs. IPv6 Keys: In addresses.list, the Compute Engine API populates "ipVersion": "IPV6" on IPv6 reservations but omits ipVersion on regional IPv4 addresses, so filter with select((.ipVersion // "IPV4") == "IPV4") before passing .address to ip2int. Similarly, each entry in cloud.json .prefixes[] uses either ipv4Prefix or ipv6Prefix, so guard IPv4 prefix splitting with select(has("ipv4Prefix")).

Next steps

Next time an external endpoint drops traffic from a new region or Cloud NAT gateway, run this script to confirm the exact ipv4Prefix and creationTime in cloud.json. If the destination firewall hasn't picked up the prefix yet, sharing the specific regional block (or your reserved /32 NAT IPs) gives the remote network team what they need to update their allowlist.

Real-time IP capacity in Google Cloud subnets

Zach S. — Wed, 17 Jun 2026 15:46:58 +0000

When managing Shared VPCs, most teams allocate dedicated IP subnets for each service project to keep firewall rules simple, but this isolation often leads to poor IP utilization — it is not uncommon to see subnet IP utilization hovering in the low teens. On the other hand, using large shared subnets requires coordinating workload deployments to ensure there is enough internal IP address space for everyone. To optimize these shared networks, you need real-time visibility. The WITH_UTILIZATION query parameter on the Method: subnetworks.list | Compute Engine API solves this by returning the exact count of allocated and free IP addresses for each subnet IP range.

This capability is designed for query-time decisions. For example, if you need to deploy a GCE workload requiring 100 instances, you can search for a subnet with enough capacity. This query-time data comes directly from Google Cloud's internal IP allocator and includes both primary and secondary CIDR ranges.

Automating the search with gcloud and jq

To automate capacity checks before you deploy, you can script this check. The script below uses gcloud compute networks subnets list | Google Cloud SDK to grab the utilization data as JSON, and then uses jq to parse, filter, and sort the subnets based on your required capacity:

#!/bin/bash

# --- Configuration (Replace with your details) ---
PROJECT="<YOUR_PROJECT_ID>"
NETWORK_NAME="<YOUR_VPC_NETWORK_NAME>"
REGION="<YOUR_REGION>"
REQUIRED_IP_CAPACITY=100

echo "Searching $NETWORK_NAME in $REGION for subnets with >= $REQUIRED_IP_CAPACITY free IPs..."
echo "------------------------------------------------------------------------"

# Fetch subnets with utilization data, output as JSON, and pipe to jq
gcloud compute networks subnets list \
    --project="$PROJECT" \
    --network="$NETWORK_NAME" \
    --regions="$REGION" \
    --view=WITH_UTILIZATION \
    --format=json | \
jq -r --argjson min_ips "$REQUIRED_IP_CAPACITY" '
  [ 
    .[] | {
      name: .name,
      cidr: .ipCidrRange,
      # Safely extract totalFreeIp: if it is null, substitute "0" before converting to a number
      free_ips: (.utilizationDetails.ipv4Utilizations[0].totalFreeIp // "0" | tonumber)
    } 
    # Keep only the subnets that meet the minimum requirement
    | select(.free_ips >= $min_ips)
  ] 

  # Sort ascending by free_ips, then reverse to get descending order
  | sort_by(.free_ips) 
  | reverse 

  # Format the final output into clean, readable strings
  | .[] 
  | "Subnet: \(.name) | CIDR: \(.cidr) | Free IPs: \(.free_ips)"
'

Let's list the configured subnets in our target region first:

~  gcloud compute networks subnets list \
    --project="my-gcp-project" \
    --format='table(name, region, network, ipCidrRange)'

NAME       REGION      NETWORK  RANGE
subnet-a0  us-south1  vpc-a    10.0.0.0/28
subnet-a1  us-south1  vpc-a    10.0.1.0/28
subnet-a2  us-south1  vpc-a    10.0.2.0/28
subnet-a3  us-south1  vpc-a    10.0.3.0/28
subnet-a4  us-south1  vpc-a    10.0.4.0/28
subnet-a5  us-south1  vpc-a    10.0.5.0/24
subnet-a6  us-south1  vpc-a    10.0.6.0/25
subnet-a7  us-south1  vpc-a
subnet-a8  us-south1  vpc-a
subnet-a9  us-south1  vpc-a

Running the script returns only the subnets that can safely host our 100-instance workload:

~  bash gce-subnet-utilization.sh

Searching vpc-a in us-south1 for subnets with >= 100 free IPv4 addresses...
------------------------------------------------------------------------
Subnet: subnet-a5 | CIDR: 10.0.5.0/24 | Free IPs: 252
Subnet: subnet-a6 | CIDR: 10.0.6.0/25 | Free IPs: 124

Under the hood: Reading the utilization payload

When you request a subnet list with the utilization view, the API returns a utilizationDetails object. For a standard subnet with only a primary IPv4 address configured, the JSON payload looks like this:

"utilizationDetails": {
  "ipv4Utilizations": [
    {
      "totalAllocatedIp": "4",
      "totalFreeIp": "252"
    }
  ]
}

Notice that the totalAllocatedIp is 4. In any primary IPv4 range, Google Cloud reserves four IP addresses for default routing and metadata, as detailed in the Subnets | Virtual Private Cloud - Google Cloud Documentation.

If you have secondary ranges configured (often used for GKE Pods), the API includes utilization metrics for each secondary range, identified by rangeName:

"utilizationDetails": {
  "ipv4Utilizations": [
    {
      "totalAllocatedIp": "4",
      "totalFreeIp": "124"
    },
    {
      "rangeName": "a6-secondary",
      "totalAllocatedIp": "0",
      "totalFreeIp": "4096"
    }
  ]
}

The API also breaks down IPv6 utilization if you are running dual-stack subnets. It tracks external instance IPs, load balancer endpoints, and internal IPv6 allocations separately:

"utilizationDetails": {
  "externalIpv6InstanceUtilization": {
    "totalAllocatedIp": { "high": "0", "low": "0" },
    "totalFreeIp": { "high": "0", "low": "9223372036854775808" }
  },
  "externalIpv6LbUtilization": {
    "totalAllocatedIp": { "high": "0", "low": "0" },
    "totalFreeIp": { "high": "0", "low": "9223372036854775808" }
  },
  "internalIpv6Utilization": {
    "totalAllocatedIp": { "high": "0", "low": "8589934592" },
    "totalFreeIp": { "high": "0", "low": "18446744065119617024" }
  }
}

A few quick constraints

API Support: The WITH_UTILIZATION parameter works with both Method: subnetworks.get | Compute Engine and Method: subnetworks.list | Compute Engine.
gcloud Support: You can pass the parameter in gcloud using --view=WITH_UTILIZATION, as documented in gcloud compute networks subnets list | Google Cloud SDK.
JSON Strings: The API returns allocated and free counts as strings in the JSON payload. Make sure to cast them (like using tonumber in jq) before running any mathematical comparisons.

Next steps

Next time you are building a deployment pipeline, try integrating the WITH_UTILIZATION view. It is a simple way to programmatically ensure you have enough network headroom before kicking off a deployment.