Access published services through endpoints (original) (raw)

This document explains how to access services in another VPC network by using Private Service Connect endpoints. You can connect to your own services, or those provided by other service producers, including by Google.

For more information about services, see publish managed services.

Before you begin

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 endpoints that access published services, 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 endpoints that access published services. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to manage endpoints that access published services:

You might also be able to get these permissions with 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).

To get the permissions that you need to manage endpoints that access published services, 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 endpoints that access published services. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to manage endpoints that access published services:

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

Create an endpoint

An endpoint connects to services in another VPC network using a Private Service Connect forwarding rule. Each forwarding rule counts toward the per project quota for Private Service Connect forwarding rules to access services in another VPC network.

When you create an endpoint, it is automatically registered withService Directory, using a 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 new one.

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.
  3. Click Connect endpoint.
  4. For Target, select Published service.
  5. For Target service, enter the service attachment URI that you want to connect to.
    The service attachment URI is in this format:projects/SERVICE_PROJECT/regions/REGION/serviceAttachments/SERVICE_NAME
  6. For Endpoint name, enter a name to use for the endpoint.
  7. Select a Network for the endpoint.
  8. Select a Subnetwork for the endpoint.
  9. Select an IP address for the endpoint. If you need a new IP address, you can create one:
    1. Click the IP address drop-down menu and select Create IP address.
    2. Enter a Name and optional Description for the IP address.
    3. Select an IP version.
    4. If you're creating an IPv4 address, select Assign automatically orLet me choose.
      If you selected Let me choose, enter the Custom IP addressyou want to use.
    5. Click Reserve.
  10. To make the endpoint available from any region, select Enable global access.
  11. Select a Namespace from the drop-down list or create a new namespace.
    The Region is populated based on the selected subnetwork.
  12. Click Add endpoint.

gcloud

  1. Reserve an internal IP address to assign to the endpoint.
    gcloud compute addresses create ADDRESS_NAME \
    --region=REGION \
    --subnet=SUBNET \
    --ip-version=IP_VERSION
    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.
    • 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 specifyIPV6, the IP address must be connected to asubnet with an internal IPv6 address range.
  2. Create a forwarding rule to connect the endpoint to the service producer's service attachment. By default, endpoints are available only from their own region. To make an endpoint available from any region, use the --allow-psc-global-access flag.
    • Create an endpoint that can be accessed only from its own region.
      gcloud compute forwarding-rules create ENDPOINT_NAME \
      --region=REGION \
      --network=NETWORK_NAME \
      --address=ADDRESS_NAME \
      --target-service-attachment=SERVICE_ATTACHMENT \
      [ --service-directory-registration=projects/PROJECT_ID/locations/REGION/namespaces/NAMESPACE ]
    • Create an endpoint that can be accessed from any region.
      gcloud compute forwarding-rules create ENDPOINT_NAME \
      --region=REGION \
      --network=NETWORK_NAME \
      --address=ADDRESS_NAME \
      --target-service-attachment=SERVICE_ATTACHMENT \
      --allow-psc-global-access \
      [ --service-directory-registration=projects/PROJECT_ID/locations/REGION/namespaces/NAMESPACE ]

Replace the following:

API

  1. Reserve an internal IP address to assign to the endpoint.
    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/addresses
    {
    "name": "ADDRESS_NAME",
    "addressType": "INTERNAL",
    "subnetwork": "SUBNET_URI",
    "ipVersion": "IP_VERSION"
    }
    Replace the following:
    • PROJECT_ID: your project ID.
    • REGION: the region for the endpoint. This must be the same region that contains the service producer's service attachment.
    • ADDRESS_NAME: the name to assign to the reserved IP address.
    • SUBNET_URI: the subnet for the IP address. Use the subnetworks.list method or gcloud compute networks subnets list --uri to find the URLs of your networks.
    • IP_VERSION: the IP version of the IP address, which can be either IPV4 or IPV6. IPV4 is the default. To specifyIPV6, the IP address must be connected to asubnet with an internal IPv6 address range.
  2. Create a forwarding rule to connect the endpoint to the service producer's service attachment. By default, endpoints are available only from their own region. To make an endpoint available from any region, set allowPscGlobalAccess to true.
    • Create an endpoint that can be accessed only from its own region.
      POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/forwardingRules
      {
      "name": "ENDPOINT_NAME",
      "IPAddress": "ADDRESS_URI",
      "target": "SERVICE_ATTACHMENT",
      "network": "NETWORK_URI",
      "serviceDirectoryRegistrations": [
      {
      "namespace": "NAMESPACE"
      }
      ]
      }
    • Create an endpoint that can be accessed from any region.
      POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/forwardingRules
      {
      "name": "ENDPOINT_NAME",
      "IPAddress": "ADDRESS_URI",
      "target": "SERVICE_ATTACHMENT",
      "network": "NETWORK_URI",
      "allowPscGlobalAccess": true,
      "serviceDirectoryRegistrations": [
      {
      "namespace": "NAMESPACE"
      }
      ]
      }
      Replace the following:
    • PROJECT_ID: your project ID.
    • REGION: the region for the endpoint.
    • ENDPOINT_NAME: the name to assign to the endpoint.
    • ADDRESS_URI: the URI of the reserved address on the associated network.
    • SERVICE_ATTACHMENT: the URI of the service producer's service attachment. For example:projects/SERVICE_PROJECT/regions/REGION/serviceAttachments/SERVICE_NAME
    • NETWORK_URI: the VPC network for the endpoint. Use the network.list method or gcloud compute networks list --uri to find the URI of your network.
    • NAMESPACE: the namespace for the endpoint. If you specify a namespace that doesn't exist, the namespace is created. If you omit the namespace field, the default namespace of goog-psc-default is assigned.

Service Project Admins can create endpoints in Shared VPC service projects that use IP addresses from connected Shared VPC networks. Creating endpoints of this type is not available in the Google Cloud console. You must 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 a Shared VPC network that can be accessed from a single region. To enable global access, or to choose a namespace for Service Directory, seeCreate an endpoint.

gcloud

  1. Reserve an internal IP address to assign to the endpoint. Create the address resource in the service project, specifying a subnet in the host project.
    The IP address must be in the same region as the service producer's service attachment.
    gcloud compute addresses create ADDRESS_NAME \
    --region=REGION \
    --subnet=projects/HOST_PROJECT/regions/REGION/subnetworks/HOST_SUBNET \
    --ip-version=IP_VERSION
    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 host project subnet that provides 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.
  2. To create the endpoint in the service project, do one of the following:
    • If you have permission to use all subnets in the host project, use the following command:
      gcloud compute forwarding-rules create ENDPOINT_NAME \
      --region=REGION \
      --network=projects/HOST_PROJECT/global/networks/HOST_NETWORK \
      --address=projects/SERVICE_PROJECT/regions/REGION/addresses/ADDRESS_NAME \
      --target-service-attachment=SERVICE_ATTACHMENT
      Replace the following:
      * ENDPOINT_NAME: the name to assign to the endpoint.
      * REGION: the region for the endpoint. This must be the same region that contains the service producer's service attachment.
      * HOST_PROJECT: the project ID of the Shared VPC network's project.
      * HOST_NETWORK: the name of the Shared VPC network that contains the endpoint's IP address.
      * SERVICE_PROJECT: the ID of the service project.
      * ADDRESS_NAME: the name of the reserved IP address.
      * SERVICE_ATTACHMENT: the URI of the service producer's service attachment. For example:projects/PRODUCER_PROJECT/regions/REGION/serviceAttachments/SERVICE_NAME
    • If you have permission to use only some subnets in the host project, specify a shared subnet by using the following command:
      gcloud compute forwarding-rules create ENDPOINT_NAME \
      --region=REGION \
      --subnet=projects/HOST_PROJECT/regions/REGION/subnetworks/HOST_SUBNET \
      --address=projects/SERVICE_PROJECT/regions/REGION/addresses/ADDRESS_NAME \
      --target-service-attachment=SERVICE_ATTACHMENT
      Replace HOST_SUBNET with the name of the subnet that contains the endpoint's IP address.

API

  1. Reserve an internal IP address to assign to the endpoint. 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 that contains the service producer's service attachment.
    • ADDRESS_NAME: the name to assign to the reserved IP address.
    • HOST_PROJECT: the ID of the host project.
    • HOST_SUBNET: the subnet in the host project.
    • 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. To create the endpoint in the service project, do one of the following:
    • If you have permission to use all subnets in the host project, make the following request:
      POST https://compute.googleapis.com/compute/v1/projects/SERVICE_PROJECT/regions/REGION/forwardingRules
      {
      "name": "ENDPOINT_NAME",
      "IPAddress": "projects/SERVICE_PROJECT/regions/REGION/addresses/ADDRESS_NAME",
      "target": "SERVICE_ATTACHMENT",
      "network": "projects/HOST_PROJECT/global/networks/HOST_NETWORK"
      }
      Replace the following:
      * SERVICE_PROJECT: the service project ID.
      * REGION: the region for the endpoint. This must be the same region that contains the service producer's service attachment.
      * ENDPOINT_NAME: the name to assign to the endpoint.
      * SERVICE_PROJECT: the ID of the service project.
      * ADDRESS_NAME: the name of the reserved IP address.
      * SERVICE_ATTACHMENT: the URI of the service producer's service attachment. For example:projects/PRODUCER_PROJECT/regions/REGION/serviceAttachments/SERVICE_NAME
      * HOST_PROJECT: the ID of the host project.
      * HOST_NETWORK: the name of the Shared VPC network that contains the endpoint's IP address.
    • If you have permission to use only some subnets in the host project, specify a shared subnet by making the following request:
      POST https://compute.googleapis.com/compute/v1/projects/SERVICE_PROJECT/regions/REGION/forwardingRules
      {
      "name": "ENDPOINT_NAME",
      "IPAddress": "projects/SERVICE_PROJECT/regions/REGION/addresses/ADDRESS_NAME",
      "target": "SERVICE_ATTACHMENT",
      "subnetwork": "projects/HOST_PROJECT/regions/REGION/subnetworks/HOST_SUBNET"
      }
      Replace HOST_SUBNET with the name of the subnet that contains the endpoint's IP address.

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.
    The endpoints are displayed.

gcloud

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

The output is similar to the following:

NAME REGION IP_ADDRESS IP_PROTOCOL TARGET RULE IP TCP REGION/serviceAttachments/SERVICE_NAME

API

This API call returns all forwarding rules, not only endpoints used to access services.

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

Replace the following:

View endpoint details

You can view all the configuration details of an endpoint, including the endpoint's connection statusand URI.

To find a Private Service Connect endpoint's ID-based URI, use the Google Cloud CLI or send an API request. The ID-based URI is displayed in the selfLinkWithId field. The service producer might need this URI if the service attachment's consumer accept list is configured to accept consumers based on individual Private Service Connect 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.
  3. Click the endpoint that you want to view.

gcloud

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

Replace the following:

API

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

Replace the following:

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 are _not_deleted when you delete the endpoint:

The Service Directory namespace and Service Directory DNS zone can be used by other services. Check that the namespace is empty before you delete the Service Directory namespaceor delete the Service Directory DNS zone.

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.
  3. Select the endpoint that you want to delete, and then click Delete.

gcloud

gcloud compute forwarding-rules delete ENDPOINT_NAME
--region=REGION

Replace the following:

API

DELETE https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/forwardingRules/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.

If you want to access the endpoint by using its DNS name, 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:

View Service Directory DNS zones

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

Console

  1. In the Google Cloud console, go to the Cloud DNS zones page.
    Go to Cloud DNS zones
  2. Look for a private zone with the nameNAMESPACE--REGION.

gcloud

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

Other ways to configure DNS

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

Configure a Service Directory DNS zone

If an endpoint is registered with Service Directory, but the published service that it 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 is backed by the Service Directory namespace. After the zone is created, DNS entries for the endpoint are automatically created.

Create a Service Directory DNS zone with the following configuration:

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

With this configuration, if you have configured a Service Directory DNS zone with the us-west1.p.example.com DNS name, and you create an endpoint with the name analytics, a DNS record for analytics.us-west1.p.example.com is automatically created.

Register an endpoint with Service Directory

New endpoints are automatically registered with Service Directory. However, if a endpoint was created before automatic registration with Service Directory was enabled, this configuration might be missing.

You can delete the endpointand create a new one, which is registered with Service Directory automatically.

Or you can follow these steps to register an existing endpoint with a Service Directory namespace.

  1. Create a Service Directory namespacefor the endpoint, NAMESPACE.
  2. Create a Service Directory servicefor the endpoint, SERVICE_NAME.
    For the service, use the same name as the name of the forwarding rule used for the endpoint,ENDPOINT_NAME.
  3. Create a Service Directory endpoint, using the name default and use the IP address and port (443) of the endpoint.

After you have registered the endpoint with Service Directory, follow the instructions to Configure a Service Directory DNS zone.

Configure DNS manually

If you've prevented automatic DNS configuration, or if it is not enabled in your configuration, you can use Cloud DNS to manually create DNS records

For more information, see the following pages:

Known issues

Unhealthy backends receive traffic with global access endpoints

It's possible to connect a global accessendpoint to a published service that's not configured for global access. However, health checks don't work correctly in this configuration. As a result, traffic might be sent to unhealthy backends and dropped.

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

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

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

Troubleshooting

Private DNS zone creation fails

When you create an endpoint, a Service Directory DNS zone is created. Zone creation can fail for these reasons:

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

  1. Verify that the Cloud DNS API isenabled in your project.
  2. Verify that you have the required permissions to create the Service 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 DNS zone.
  4. Create a Service Directory DNS zone that is backed by the Service Directory namespace associated with your endpoint.

Endpoint connection status is pending

A PENDING connection status typically means that the producer's service attachment has received your connection request, but the connection is not yet accepted. An endpoint with the PENDING connection status must transition toACCEPTED before traffic can flow between your VPC network and the published service.

Common causes for the PENDING status include the following:

Endpoint creation fails when global access is configured

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

Private Service Connect global access is not supported for the given forwarding rule, 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 connectivity is not established, check the endpoint'sconnection status. The connection status might indicate steps that you can take to resolve the issue.

Endpoint connection status is accepted, but traffic doesn't flow

If an endpoint has an ACCEPTED connection status, but traffic can't reach the published service, the service producer might have recently updated the target service of the service attachment. During a target service update, traffic is briefly interrupted. For information about recent or ongoing target service updates, or to verify the state of the service, contact the service producer.

Propagated connection errors

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

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 by checking the metrics that are described in the following sections.

Dropped packets to published service

The private_service_connect/consumer/dropped_sent_packets_countmetrictracks packets from a Private Service Connect consumer such as an endpoint to a published service that are dropped because the endpoint exceeded its maximum connectionsto the service.

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

Dropped packets from published services

Theprivate_service_connect/consumer/dropped_received_packets_countmetrictracks packets sent from a published service to a Private Service Connect consumer such as an endpoint that are dropped because Private Service Connect can't find a matching connection for response packets.

Private Service Connect only allows connections that are initiated from the consumer VPC network. When a consumer initiates a connection, the connection is tracked in order to match response packets from the published service with an existing connection. If Private 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 response packet if a published service sends response packets after a connection has timed out. If you see values for this metric, contact the service producer. They might be able toconfigure their service to avoid this issue.