Access regional Google APIs through endpoints (original) (raw)

This document explains how to use Private Service Connect endpoints to connect to regional endpoints of supported Google APIs.

For information about other Private Service Connect configurations, seePrivate Service Connect.

Required roles

If you're creating the endpoint in the same project as the subnet that you're connecting it to, see Required roles for your project.

If you're using Shared VPC and are creating the endpoint in a service project, and connecting it to a subnet in the host project, you need the following roles:

Required roles for your project

To get the permissions that you need to manage Private Service Connect endpoints that access regional endpoints, ask your administrator to grant you the following IAM roles:

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.

Additional required roles for Shared VPC configurations

If you're creating an endpoint in a service project that uses an IP address from a host project subnet, you need the following permissions in addition to theRoles for your project (the service project).

Both you and the Network Connectivity Service Account need permissions on the host project.

Roles to grant to your user account

To get the permissions that you need to manage Private Service Connect endpoints that access regional endpoints for Google APIs, ask your administrator to grant you the following IAM roles:

For more information about granting roles, see Manage access to projects, folders, and organizations.

These predefined roles contain the permissions required to manage Private Service Connect endpoints that access regional endpoints for Google APIs. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to manage Private Service Connect endpoints that access regional endpoints for Google APIs:

You might also be able to get these permissions with custom roles or other predefined roles.

Roles to grant to the Network Connectivity Service Account

To ensure that service-PROJECT_NUMBER@gcp-sa-networkconnectivity.iam.gserviceaccount.com has the necessary permissions to manage Private Service Connect endpoints that access regional endpoints for Google APIs, ask your administrator to grant the following IAM roles to service-PROJECT_NUMBER@gcp-sa-networkconnectivity.iam.gserviceaccount.com:

For more information about granting roles, see Manage access to projects, folders, and organizations.

These predefined roles contain the permissions required to manage Private Service Connect endpoints that access regional endpoints for Google APIs. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to manage Private Service Connect endpoints that access regional endpoints for Google APIs:

Your administrator might also be able to give service-PROJECT_NUMBER@gcp-sa-networkconnectivity.iam.gserviceaccount.com these permissions with custom roles or other predefined roles.

Before you begin

  1. Install the Google Cloud CLI. After installation,initialize the Google Cloud CLI by running the following command:
    $ gcloud init
    If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
  2. Enable the Compute Engine, Network Connectivity Center, and Cloud DNS APIs.
    Roles required to enable APIs
    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.
    Enable the APIs
  3. Additionally, enable the API for the target service that you want to access through the Private Service Connect endpoint. For example, if you want to access spanner.me-central2.rep.googleapis.com, enable the Cloud Spanner API. Private Service Connect doesn't automatically enable any APIs.
  4. Ensure that egress firewall rules permit traffic to the endpoint. The default firewall configuration for a VPC network permits this traffic because it contains an implied allow egress rule. Verify that you haven't created a higher priority egress rule that blocks the traffic.

Create a regional Private Service Connect endpoint

You can create a regional Private Service Connect endpoint to send requests to a regional endpoint for a target Google API.

For a list of supported regional endpoints, see Regional service endpoints.

Console

  1. In the Google Cloud console, go to the Private Service Connect page.
    Go to Private Service Connect
  2. Click Connect endpoint.
  3. In Target, select Google API.
  4. In the Scope list, select Regional.
  5. In the Region list, select the region that you want to use.
  6. In the Target service list, select the service that you want to access.
  7. In Endpoint name, enter a name for the endpoint.
  8. In Network, select a network.
  9. In Subnetwork, select a subnetwork.
  10. In IP address, do one of the following to configure an IP address:
  1. Optional: To make the endpoint available from all regions in the VPC network, select Enable global access.
  2. Click Add endpoint.

gcloud

Use the gcloud network-connectivity regional-endpoints createcommandto create the endpoint.

gcloud network-connectivity regional-endpoints create ENDPOINT_NAME
--region=REGION
--address=ADDRESS
--network=projects/PROJECT_ID/global/networks/NETWORK_NAME
--subnetwork=projects/PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME
--target-google-api=REP_DNS_NAME

If you want to make the endpoint available to resources in other regions, add the --enable-global-access flag.

Replace the following:

API

Use the projects.locations.regionalEndpoints.create method to create the endpoint.

HTTP method and URL:

POST https://networkconnectivity.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/regionalEndpoints?regionalEndpointId=ENDPOINT_NAME

{ "accessType": "REGIONAL", "address": "ADDRESS", "network": "projects/PROJECT_ID/global/networks/NETWORK_NAME", "subnetwork": "projects/PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME", "targetGoogleApi": "REP_DNS_NAME" }

Replace the following:

If you're using Shared VPC, you can create an endpoint in a service project that uses an IP address from a subnet in a host project. You can't use the Google Cloud console to create this configuration—you must use the gcloud CLI or the API.

gcloud

  1. Reserve a static IP address to use for the regional endpoint by using thegcloud compute addresses create command. Using a static IP address is optional for IPv4, and required for IPv6.
    Create the address resource in the service project, specifying a subnet in the host project.
    gcloud compute addresses create ADDRESS_NAME \
    --region=REGION \
    --subnet=projects/HOST_PROJECT/regions/REGION/subnetworks/HOST_SUBNET \
    --ip-version=IP_VERSION \
    --project=SERVICE_PROJECT
    Replace the following:
    • ADDRESS_NAME: the name to assign to the reserved IP address.
    • REGION: the region for the endpoint IP address. This must be the same region that contains the service producer's service attachment.
    • HOST_PROJECT: the project ID of the host project.
    • HOST_SUBNET: the name of the subnet for the endpoint IP address.
    • IP_VERSION: the IP version of the IP address, which can be either IPV4 or IPV6. IPV4 is the default. To specify IPV6, the IP address must be connected to a subnet with an internal IPv6 address range.
    • SERVICE_PROJECT: the project ID of the service project
  2. Use the gcloud network-connectivity regional-endpoints createcommandto create the regional endpoint in the service project.
    gcloud network-connectivity regional-endpoints create ENDPOINT_NAME \
    --region=REGION \
    --address=ADDRESS \
    --network=projects/HOST_PROJECT/global/networks/HOST_NETWORK \
    --subnetwork=projects/HOST_PROJECT/regions/REGION/subnetworks/HOST_SUBNET \
    --target-google-api=REP_DNS_NAME \
    --project=SERVICE_PROJECT

If you want to make the endpoint available to resources in other regions, add the --enable-global-access flag.
Replace the following:

API

  1. Reserve a static IP address to use for the regional endpoint. Using a static IP address is optional for IPv4, and required for IPv6.
    Create the address resource in the service project, specifying a subnet in the host project.
    POST https://compute.googleapis.com/compute/v1/projects/SERVICE_PROJECT/regions/REGION/addresses
    {
    "name": "ADDRESS_NAME",
    "addressType": "INTERNAL",
    "subnetwork": "projects/HOST_PROJECT/regions/REGION/subnetworks/HOST_SUBNET",
    "ipVersion": "IP_VERSION"
    }
    Replace the following:
    • SERVICE_PROJECT: the ID of the service project.
    • REGION: the region for the endpoint. This must be the same region as the regional endpoint that you want to connect to.
    • ADDRESS_NAME: the name to assign to the static IP address.
    • HOST_PROJECT: the ID of the host project.
    • HOST_SUBNET: the subnet in the Shared VPC network to reserve the IP address from.
    • IP_VERSION: the IP version of the IP address, which can be either IPV4 or IPV6. IPV4 is the default. To specify IPV6, the IP address must be connected to a subnet with an internal IPv6 address range.
  2. Create the Private Service Connect endpoint by using theprojects.locations.regionalEndpoints.createmethod.
    HTTP method and URL:
    POST https://networkconnectivity.googleapis.com/v1/projects/SERVICE_PROJECT/locations/REGION/regionalEndpoints?regionalEndpointId=ENDPOINT_NAME
    {
    "accessType": "REGIONAL",
    "address": "ADDRESS",
    "network": "projects/HOST_PROJECT/global/networks/HOST_NETWORK",
    "subnetwork": "projects/HOST_PROJECT/regions/REGION/subnetworks/HOST_SUBNET",
    "targetGoogleApi": "REP_DNS_NAME"
    }
    Replace the following:
    • SERVICE_PROJECT: the ID of the service project.
    • REGION: the region that you want to create the endpoint in.
    • ENDPOINT_NAME: a name for the endpoint.
    • ADDRESS: the IPv4 or IPv6 address that you want to use for the endpoint. If omitted, an IPv4 address from the subnetwork is allocated. Use one of the following formats:
      * IPv4 address—for example, 10.0.0.2.
      * IPv4 or IPv6 address resource URI—for example,projects/SERVICE_PROJECT/regions/REGION/addresses/ADDRESS_NAME.
    • HOST_PROJECT: the ID of the host project.
    • HOST_NETWORK: the name of the network in the host project.
    • HOST_SUBNET: the name of the subnet in the host project that you want to connect the endpoint to.
    • REP_DNS_NAME: the hostname of the regional service endpoint that you want to connect to. For example,spanner.me-central2.rep.googleapis.com.

List endpoints

You can list all configured endpoints.

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.
    All endpoints are displayed, including endpoints with regional endpoint targets.

gcloud

Use the gcloud network-connectivity regional-endpoints listcommand.

gcloud network-connectivity regional-endpoints list
--region=REGION

Replace REGION with the region of the endpoints that you want to list.

API

Use theprojects.locations.regionalEndpoints.list method.

GET https://networkconnectivity.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/regionalEndpoints

Replace the following:

Verify that the endpoint is working

Create a virtual machine (VM) instance in the VPC network and region where the endpoint 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.

Replace the following:

The following example request tests that an endpoint with IP address192.168.1.100 can request the Cloud Spanner APIdiscovery document from the regional endpoint in me-central2.

curl --connect-to spanner.me-central2.rep.googleapis.com:443:192.168.1.100:443
'https://spanner.me-central2.rep.googleapis.com/$discovery/rest?version=v1'

Create a private DNS entry for the endpoint

You must create private DNS entries so that clients can direct requests to your Private Service Connect endpoint.

We recommend creating a private zone that uses the same hostname as the target regional endpoint:SERVICE.REGION.rep.DOMAINand create an apex record in that zone.

For example, if your Private Service Connect endpoint has a target of spanner.me-central2.rep.googleapis.com, create a private zone forspanner.me-central2.rep.googleapis.com that contains an apex record forspanner.me-central2.rep.googleapis.com. Creating records in the domain apex means that you can access the public hostname of other regional endpoints— for example, logging.me-central2.rep.googleapis.com.

The following sections describe how to use Cloud DNS to create a private zone and an apex DNS record.

Create a private zone

Console

  1. In the Google Cloud console, go to the Create a DNS zone page.
    Go to Create a DNS zone
  2. For the Zone type, select Private.
  3. For Zone name, enter a name. For example, if your Private Service Connect endpoint points tospanner.me-central2.rep.googleapis.com, enterspanner-me-central2-rep-googleapis-com.
  4. For DNS name, specify the hostname of the target regional endpoint followed by a trailing dot. For example,spanner.me-central2.rep.googleapis.com..
  5. Optional: Add a description.
  6. Under Options, select Default (private).
  7. Select the VPC networks where you want the private zone to be visible. Only the VPC networks that you select are authorized to query records in the zone.
  8. Click Create.

gcloud

Run the dns managed-zones create command:

gcloud dns managed-zones create ZONE_NAME
--dns-name=REP_DNS_NAME.
--networks=VPC_NETWORK_LIST
--visibility=private
--description="Private zone for REP_DNS_NAME"

Replace the following:

API

Send a POST request using themanagedZones.create method:

HTTP method and URL:

POST https://dns.googleapis.com/dns/v1/projects/PROJECT_ID/managedZones

Request JSON body:

{ "name": "ZONE_NAME", "dnsName": "REP_DNS_NAME.", "description": "DESCRIPTION", "visibility": "private", "privateVisibilityConfig": { "kind": "dns#managedZonePrivateVisibilityConfig", "networks": [ { "kind": "dns#managedZonePrivateVisibilityConfigNetwork", "networkUrl": "NETWORK_1_URL" }, { "kind": "dns#managedZonePrivateVisibilityConfigNetwork", "networkUrl": "NETWORK_2_URL" } ] } }

Replace the following:

Add a DNS record to the zone

Console

  1. In the Google Cloud console, go to the Cloud DNS zones page.
    Go to Cloud DNS zones
  2. Click the name of the managed zone that you want to add the record to.
  3. On the Zone details page, click Add standard.
  4. On the Create record set page, leave the DNS name field blank. Leaving the field blank creates a resource record at the domain apex.
  5. For Resource record type, select A.
  6. In the IPv4 address field, enter or select the IP address of the Private Service Connect endpoint.
  7. Click Create.

gcloud

To add a resource record set, use the gcloud dns record-sets createcommand:

gcloud dns record-sets create REP_DNS_NAME
--rrdatas=ADDRESS
--type=RECORD_TYPE
--ttl=TTL
--zone=ZONE_NAME

Replace the following:

API

To add a resource record set, use theresourceRecordSets.create method:

HTTP method and URL:

POST https://www.googleapis.com/dns/v1/projects/PROJECT_ID/managedZones/ZONE_NAME/rrsets

Request JSON body:

{ "name": "REP_DNS_NAME.", "type": "RECORD_TYPE", "ttl": TTL, "rrdatas": [ "ADDRESS" ] }

Replace the following:

Configure clients to use the private endpoint name

You must configure clients to use the private DNS names instead of the public DNS names. See the documentation for your client or client library for information about configuring it to use custom endpoints. The following pages include configuration steps for some common clients:

Get detailed information about an endpoint

You can view the configuration details of an endpoint.

gcloud

Use the gcloud network-connectivity regional-endpoints describecommand.

gcloud network-connectivity regional-endpoints describe
ENDPOINT_NAME --region=REGION

Replace the following:

API

Use the projects.locations.regionalEndpoints.get command.

GET https://networkconnectivity.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/regionalEndpoints/ENDPOINT_NAME

Replace the following:

Update the global access configuration

You can't update a Private Service Connect endpoint that has a regional endpoint target. If you need to change the global access setting for the endpoint, delete the endpoint and create a new endpoint that has the required global access setting.

Delete an endpoint

You can delete an endpoint.

gcloud

Use the gcloud network-connectivity regional-endpoints deletecommand.

gcloud network-connectivity regional-endpoints delete
ENDPOINT_NAME --region=REGION

Replace the following:

API

Use the projects.location.regionalEndpoints.delete command.

DELETE https://networkconnectivity.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/regionalEndpoints/ENDPOINT_NAME

Replace the following:

Access endpoints from hybrid networks

Clients in networks that are connected to Google Cloud with VLAN attachments for Cloud Interconnect or Cloud VPN tunnels can reach Private Service Connect endpoints.

You must configure systems in the other network so that they can make queries to your private DNS zones.

If you implemented the private DNS zones by using Cloud DNS, complete the following steps: