Access published services through endpoints

This document explains how toaccessservices in anotherVPC network by using Private Service Connectendpoints. You can connect to your own services, or those provided by otherservice producers, including by Google.

For more information about services, seepublish managedservices.

Before you begin

• ReadAbout connecting to services by usingendpoints,including limitations.
• You mustenabletheCompute Engine API in yourproject.
• You mustenabletheService Directory APIin your project.
• You mustenabletheCloud DNS API in your project.
• Identify or create aregular subnet to use toassign an IP address for the endpoint.
  • The subnet must be in the same region as the service that you want toconnect to.
  • You can use an IPv4 address from an IPv4-only subnet or a dual-stacksubnet.
  • You can use an IPv6 address from an IPv6-onlyor dual-stack subnet if the subnet hasaninternal IPv6 address range.
  • The IP version of the IP address affects which published services theendpoint can connect to. For more information, seeIP versiontranslation.
• Egress firewall rules must permit traffic to the internal IP addressof the endpoint. Theimplied allowegress firewall rulepermits egress to any destination IP address. If you've created anyegress deny firewall rules in your VPC network, or ifyou've created hierarchical firewall policies which modify theimplied allowed egress behavior, access to the endpoint might beaffected. Create a specific egress allow firewall rule or policy topermit traffic to the service endpoint's internal IP addressdestination.
• You must have the URI of the service attachment for the service. Forexample,projects/SERVICE_PROJECT/regions/REGION/serviceAttachments/SERVICE_NAME

Required roles

To get the permissions that you need to access published services through endpoints, ask your administrator to grant you the following IAM roles:

• Create, view, and delete endpoints in your project:Compute Network Admin (roles/compute.networkAdmin) on your project
• Create, view, and delete endpoints in a Shared VPC service project:
  • Compute Network Admin (roles/compute.networkAdmin) on the service project
  • Compute Network User (roles/compute.networkUser) on the host project
• Automatically or manually configure DNS entries for an endpoint in your project:
  • DNS Administrator (roles/dns.admin) on your project
  • Service Directory Editor (roles/servicedirectory.editor) on your project
• Automatically or manually configure DNS entries for an endpoint in a Shared VPC service project:
  • DNS Administrator (roles/dns.admin) on the service project
  • Service Directory Editor (roles/servicedirectory.editor) on the service project

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

These predefined roles contain the permissions required to access published services through endpoints. To see the exact permissions that are required, expand theRequired permissions section:

You might also be able to get these permissions withcustom roles or otherpredefined roles.

Create an endpoint

An endpoint connects to services inanother VPC network using aPrivate Service Connect forwarding rule. Each forwarding rulecounts toward theper project quota forPrivate Service Connect forwarding rules to access services inanother VPC network.

When you create an endpoint, it isautomatically registered withService Directory, usinga namespace that you choose, or the default namespace,goog-psc-default.

If you want to make the endpoint available from more than one region, turn onglobal access.

You can only update the global access field of endpoints for published services.If you want to update other fields, delete the endpoint, and then create a newone.

Create an endpoint with an IP address from a Shared VPC network

Service Project Admins can createendpoints in Shared VPC serviceprojects that use IP addresses from connectedShared VPC networks.Creating endpoints of this type is not available in the Google Cloud console. Youmust use the Google Cloud CLI or send an API request. For more information, seeShared VPC.

This example shows how to create an endpoint with an IP address from aShared VPC network that can be accessed from a single region. To enableglobal access, or to choose a namespace for Service Directory, seeCreate an endpoint.

List endpoints

You can list all configured endpoints.

gcloud compute forwarding-rules list \    --filter 'target~serviceAttachments'

NAME  REGION  IP_ADDRESS  IP_PROTOCOL  TARGETRULEIP          TCPREGION/serviceAttachments/SERVICE_NAME

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/forwardingRules

View endpoint details

You can view all the configuration details of anendpoint, including the endpoint'sconnection statusand URI.

To find a Private Service Connect endpoint's ID-based URI, use theGoogle Cloud CLI or send an API request.The ID-based URI is displayed in theselfLinkWithId field. The serviceproducer might need this URI if the service attachment's consumer accept list isconfigured to accept consumers based on individualPrivate Service Connect endpoints.

gcloud compute forwarding-rules describe \ENDPOINT_NAME --region=REGION

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/forwardingRules/ENDPOINT_NAME

Label an endpoint

You can manage labels for endpoints. For detailed instructions, seelabeling resources.

Delete an endpoint

You can delete an endpoint.

However, the following Service Directory configurations arenotdeleted when you delete the endpoint:

• Service Directory namespace
• Service Directory DNS zone

The Service Directory namespace andService Directory DNS zone can be used by other services. Check thatthe namespace is empty before youdelete the Service Directorynamespaceordelete the Service Directory DNSzone.

gcloud compute forwarding-rules deleteENDPOINT_NAME \    --region=REGION

DELETE https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/forwardingRules/ENDPOINT_NAME

Access endpoints from hybrid networks

• The VLAN attachment or Cloud VPN tunnel must terminate in the sameVPC network (or Shared VPC network) as the endpoint.Clients in peered VPC networks cannot reach endpoints.

• Client traffic from VLAN attachments or Cloud VPN tunnels can reachendpoints in another region ifglobal access is configured.

• Both Dataplane v1 and Dataplane v2 are supported for the VLAN attachments.For more information about Dataplane versions, seeDataplane v2.

If you want to access the endpointby using its DNS name, you must configure systems in the other network so thatthey can make queries to your private DNS zones.

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

• Create aninbound server policy in theVPC network to which your other network connects.

• Identify theinbound forwarder entry pointsin the region where your VLAN attachment or Cloud VPN tunnel islocated, in the VPC network to which your other networkconnects.

• Configure systems and DNS name servers in the other network to forward theDNS names for the endpoint to an inbound forwarder entrypoint in the same region as the VLAN attachment or Cloud VPN tunnelthat connects to the VPC network.

View Service Directory DNS zones

If the prerequisites forautomatic DNS configurationare met, aDNS zone is created with a name in the formatNAMESPACE--REGION.

If the zone is not present,view the details for theendpoint and check if the endpointconfiguration includes a value for the namespace.

• If the endpoint has a namespace configuration, seeConfigure aService Directory DNS zone.

• If the endpoint does not have a namespace configuration, seeRegister anendpoint withService Directory.

Other ways to configure DNS

If the prerequisites forautomatic DNS configurationare not met, you can create DNS entries in other ways:

• If the endpoint has a namespace configured, seeConfigure aService Directory DNS zone.

• If the endpoint does not have a namespace configured, seeRegister anendpoint withService Directory.

• If you prefer to manually configure DNS, seeConfigure DNSmanually.

Configure a Service Directory DNS zone

If an endpoint is registered withService Directory, but the published service thatit connects to does not have a domain name configured, no DNS changes are made.

If you want to replicate theautomatic DNS configuration,you can manually configure a Service Directory DNS zone that isbacked by the Service Directory namespace. After the zone iscreated, DNS entries for the endpoint areautomatically created.

Create aService Directory DNSzone with thefollowing configuration:

• Zone name: SpecifyNAMESPACE--REGION,whereNAMESPACE is the namespace that theendpoint is registered to, andREGION is the region where the endpoint is created.

• DNS name: The DNS domain that the service producer is using for theirpublished services. Check with the service producer for thisinformation.

  The DNS name might have the formatREGION.p.DOMAIN. For example, if theservice producer's public domain isexample.com, and theirpublishedservice is inus-west1, then we recommend that they make their serviceavailable usingus-west1.p.example.com domain names. Include a trailingdot—for example,us-west1.p.example.com.

• Service Directory namespace: The namespace that youconfigured for this endpoint.

View the endpoint detailsto find the Service Directory namespace and region.

With this configuration, if you have configured aService Directory DNS zone with theus-west1.p.example.com DNSname, and you create an endpoint with thenameanalytics, a DNS record foranalytics.us-west1.p.example.com isautomatically created.

Register an endpoint with Service Directory

New endpoints are automaticallyregistered with Service Directory. However, if aendpoint was created before automaticregistration with Service Directory was enabled, thisconfiguration might be missing.

You candelete theendpointandcreate a new one, which is registered withService Directory automatically.

Or you can follow these steps to register an existingendpoint with aService Directory namespace.

1. Create aService Directorynamespacefor the endpoint,NAMESPACE.

2. Create aService Directoryservicefor the endpoint,SERVICE_NAME.

   For the service, use the same name as the name of the forwarding rule usedfor the endpoint,ENDPOINT_NAME.

3. Create aService Directoryendpoint,using the namedefault and use the IP address and port (443) of theendpoint.

After you have registered the endpointwith Service Directory, follow the instructions toConfigure aService Directory DNS zone.

Configure DNS manually

If you've prevented automatic DNS configuration, or if it is not enabled in yourconfiguration, you can useCloud DNS to manuallycreate DNS records

For more information, see the following pages:

• Access Control: theDNS Administratorrole (roles/dns.admin) provides thepermissions needed to create DNS zones and records.

• Create a private zone.

  • When you configure a private zone, you provide a DNS name. Use the DNSdomain that the service producer is using for their publishedservices. Check with the service producer for this information.

    It might have this format:REGION.p.DOMAIN. For example, if theservice producer's public domain isexample.com, and their publishedservice is inus-west1, then we recommend that they make their serviceavailable usingus-west1.p.example.com domain names.

• Add a record.

Known issues

Unhealthy backends receive traffic with global access endpoints

It's possible to connect aglobal accessendpoint to a published service that'snot configured for global access. However, health checks don't work correctlyin this configuration. As a result, traffic might be sent to unhealthybackends and dropped.

Only enable global access for an endpoint if you know that the serviceattachment's load balancer is configured for global access.

If your endpoint is affected by this issue, do one of the following:

• If you don't want to use global access,disable global access for your endpoint.
• If you want to use global access, ask the service producer toenable global access for the load balancer's forwarding rule.

Turning off global access for an endpoint doesn't interrupt network traffic forworkloads in the same region as the endpoint. However, after global access isdisabled, clients from other regions can't access the endpoint.

Troubleshooting

Private DNS zone creation fails

When you create an endpoint, aService Directory DNS zone is created. Zone creation can fail forthese reasons:

• You haven't enabled the Cloud DNS API in your project.

• You don't have the required permissions to create aService Directory DNS zone.

• A DNS zone with the same zone name exists in this VPC network.

• A DNS zone for the same domain name already exists in this VPCnetwork.

To manually create the Service Directory DNS zone, do thefollowing:

1. Verify that the Cloud DNS API isenabled in your project.

2. Verify that you have the required permissions to create theService Directory DNS zone:

   • dns.managedZones.create
   • dns.networks.bindPrivateDNSZone
   • servicedirectory.namespaces.associatePrivateZone

3. If there is a conflicting zone, but it is no longer needed,delete the DNSzone.

4. Create a Service Directory DNS zone thatis backed by the Service Directory namespace associated with yourendpoint.

Endpoint creation fails when global access is configured

Not all Private Service Connect published services supportendpoints with global access. If you create an endpoint with global access andthe published service doesn't support it, you see this error message:

Private Service Connect global access is not supported for the given forwardingrule, since its producer service does not support consumer global access.

Create the endpoint without the global access option.

Endpoint creation succeeds, but connectivity is not established

If you successfully create an endpoint for published services but connectivityis not established, check the endpoint'sconnection status.The connection status might indicate steps that you can take to resolve theissue.

Propagated connection errors

For information about troubleshooting propagated connections, seeTroubleshoot Private Service Connect connection propagationerrors.

Endpoint has performance issues or connection timeouts

If your endpoint has performance issues or intermittent connection timeouts,it might be due to dropped packets. You can investigate dropped packets bychecking the metrics that are described in the following sections.

Dropped packets to published service

Theprivate_service_connect/consumer/dropped_sent_packets_countmetrictracks packets from a Private Service Connect consumer such asan endpoint to a published service that are dropped because the endpointexceeded itsmaximum connectionsto the service.

If an endpoint reports values for this metric, consider the following solutions:

• Create additional endpoints that connect to the published service.
• Reduce the number of connections through this endpoint.
• Ask the service producer to increase the capacity of their publishedservice—for example, by adding more virtual machine (VM) instances ornetwork endpoints.

Dropped packets from published services

Theprivate_service_connect/consumer/dropped_received_packets_countmetrictracks packets sent from a published service to aPrivate Service Connect consumer such as an endpoint that aredropped because Private Service Connect can't find a matchingconnection for response packets.

Private Service Connect only allows connections that areinitiated from the consumer VPC network. When a consumerinitiates a connection, the connection is tracked in order to matchresponse packets from the published service with an existing connection. IfPrivate Service Connect can't find a match for a response packet,the packet is dropped.

Private Service Connect might not find a match for a responsepacket if a published service sends response packets after a connection hastimed out. If you see values for this metric, contact the service producer.They might be able toconfigure their service to avoid this issue.