Query Cloud Number Registry

Preview

This product is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products are available "as is" and might have limited support. For more information, see the launch stage descriptions.

This page explains how to query information that is stored in Cloud Number Registry.

Before you begin

1. Set up Cloud Number Registry.
2. Select the project in your organization that has been configured to provide Cloud Number Registry access.
3. Verify that you have the permissions required to complete this guide.

Required roles

To get the permissions that you need to view information stored in Cloud Number Registry, ask your administrator to grant you the Cloud Number Registry IPAM Viewer (roles/cloudnumberregistry.ipamViewer) IAM role on your project. For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Show IP address utilization

You can view IP address utilization for discovered ranges or custom ranges.

Show utilization of a discovered range

gcloud

Show utilization of a discovered range by using the gcloud alpha number-registry discovered-ranges show-utilization command.

gcloud alpha number-registry discovered-ranges show-utilization DISCOVERED_RANGE_NAME \
    --location=global

Replace the following:

• DISCOVERED_RANGE_NAME: the name of the discovered range.

Show utilization of a custom range

gcloud

Show utilization of a custom range by using the gcloud alpha number-registry custom-ranges show-utilization command.

gcloud alpha number-registry custom-ranges show-utilization CUSTOM_RANGE_NAME \
    --location=global

Replace the following:

• CUSTOM_RANGE_NAME: the name of the custom range.

Find free IP ranges

You can find available IP address ranges within discovered ranges or custom ranges.

Find free IP ranges in discovered ranges

When you find free IP ranges in discovered ranges, the following limitations apply:

• Results might include unusable addresses in IPv4 subnet ranges and unusable addresses in IPv6 subnet ranges.

• Results might include ephemeral IP addresses that are assigned to instances that are shut down.

gcloud

Find free IP ranges in discovered ranges by using the gcloud alpha number-registry discovered-ranges find-free-ip-ranges command.

gcloud alpha number-registry discovered-ranges find-free-ip-ranges DISCOVERED_RANGE_NAME \
    --cidr-prefix-length=PREFIX_LENGTH \
    --range-count=RANGE_COUNT \
    --location=global

Replace the following:

• DISCOVERED_RANGE_NAME: the name of the discovered range.
• PREFIX_LENGTH: the CIDR prefix length of the ranges to find. Use 32 to find individual IPv4 addresses.
• RANGE_COUNT: the number of free ranges to find.

Find free IP ranges in custom ranges

If a custom range doesn't exist for a given IP address range, the range is considered to be a free IP range. If you want to use Cloud Number Registry to find free IP ranges within custom ranges, make sure that all in-use IP addresses and IP address ranges have a corresponding custom range.

gcloud

Find free IP ranges in custom ranges by using the gcloud alpha number-registry custom-ranges find-free-ip-ranges command.

gcloud alpha number-registry custom-ranges find-free-ip-ranges CUSTOM_RANGE_NAME \
    --cidr-prefix-length=PREFIX_LENGTH \
    --range-count=RANGE_COUNT \
    --location=global

Replace the following:

• CUSTOM_RANGE_NAME: the name of the custom range.
• PREFIX_LENGTH: the CIDR prefix length of the ranges to find. Use 32 to find individual IPv4 addresses.
• RANGE_COUNT: the number of free ranges to find.

Search IP resources

You can search for IP address resources within a registry book.

You can use the following filters in queries:

• realm: The realm name to search in—for example, prod-realm-5.
• parent_range: The URI of the parent range you want to search within—for example, projects/project3/locations/global/customRanges/range7.
• ip_address: The IP address to search for—for example, 10.10.10.46.
• ip_version: The IP version to filter for.
• attribute_text: The attribute text to search for within ranges—for example, production.
• attribute: The attribute key and value to filter for—for example, attribute:(environment=production).

You can combine filters in the following ways:

• You can combine two or more filters in the same query by using AND.
• You can use AND NOT in combination with the attribute:(KEY=VALUE) filter only.

• You can use either attribute or attribute_text in a given query, but not both.

gcloud

Search IP resources by using the gcloud alpha number-registry registry-books search-ip-resources command.

gcloud alpha number-registry registry-books search-ip-resources REGISTRY_BOOK \
    --query=QUERY \
    --show-utilization \
    --location=global

Replace the following:

• REGISTRY_BOOK: the name of the registry book to search within.
• QUERY: the query for your search—for example:
  • "attribute:(resourceName=projects/project123/regions/us-east1/subnetworks/subnet1)"
  • "realm=vpc-global-123456789 AND ip_address=10.10.10.46"
  • "realm=vpc-global-123456789 AND ip_version=IPV6"
  • "ip_address=\"2001:db8::/64\""
  • "realm=vpc-global-123456789 AND attribute_text=production"
  • "realm=vpc-global-123456789 AND attribute:(team=\"Sales Europe\")"
  • "parent_range=projects/project3/locations/global/customRanges/range7 AND attribute:(team=marketing)"
  • "parent_range=projects/project3/locations/global/customRanges/range7 AND NOT attribute:(environment=production)"