Create a Private Service Connect backend

You can use Private Service Connect backends to connect to supported services by using a load balancer for policy enforcement. You connect to the service through a forwarding rule that is mapped to a backend that contains a Private Service Connect network endpoint group (NEG).

For more information about supported services and configurations, see About Private Service Connect backends.

This guide shows you how to add a Private Service Connect NEG to a load balancer to access either Google APIs or a published service. This guide does not include the full load balancer configuration.

For instructions that include creating a load balancer with a Private Service Connect backend, see the following:

• Create an internal Application Load Balancer to access Google APIs
• Create a global external Application Load Balancer to access a published service

Roles

The Compute Load Balancer Admin role (roles/compute.loadBalancerAdmin) contains the permission required to perform the tasks described in this guide.

Before you begin

1. Determine which API or service you want to connect to:

   • For Google APIs:

     • Choose a locational service endpoint.

   • For published services:

     • If you want to publish your own service, see Publish managed services.

     • If you are connecting to a Google Cloud or third-party published service, ask the producer for the following information:

       • The URI of the service attachment for the service that you want to connect to.

       • Any requirements for what DNS names you use to send requests to. You might need to use specific DNS names in your URL map configuration.

2. Determine which load balancer type supports the service that you want to connect to and make sure that you are familiar with the load balancer that you are updating. This guide describes how to add a Private Service Connect NEG to a load balancer, but you might want to perform additional configuration steps.

   For more information, see Supported load balancers and targets.

Create a Private Service Connect NEG

When you create a NEG, you choose which type of target it connects to:

• A published service
• A locational Google API
• A global Google API

Create a NEG to connect to a published service

When you create a Private Service Connect NEG that points to a published service, you need the service attachment URI for the service. The service attachment has this format: projects/SERVICE_PROJECT/regions/REGION/serviceAttachments/SERVICE_NAME

For information about supported load balancers for this configuration, see Published service targets.

Console

1. In the Google Cloud console, go to the Network endpoint groups page.

   Go to Network endpoint groups
   

2. Click Create network endpoint group.

3. Enter a name for the network endpoint group.

4. For the Network endpoint group type, select Private Service Connect NEG (Regional).

5. Configure the target:

   1. For Target, select Published service.
   2. For Target service, enter the URI of the service attachment.

   3. Select the Network and Subnetwork to create the network endpoint group in.

      The subnet must be in the same region as the published service.

6. Click Create.

gcloud

Use the gcloud compute network-endpoint-groups create command:

gcloud compute network-endpoint-groups create NEG_NAME \
    --network-endpoint-type=private-service-connect \
    --psc-target-service=TARGET_SERVICE \
    --region=REGION \
    --network=NETWORK \
    --subnet=SUBNET

Replace the following:

• NEG_NAME: a name for the network endpoint group.

• TARGET_SERVICE: the URI of the service attachment.

• REGION: the region to create the network endpoint group in. The region must be the same region as the target service.

• NETWORK: the network to create the network endpoint group in. If omitted, the default network is used.

• SUBNET: the subnet to create the network endpoint group in. The subnet must be in the same region as the target service. A subnet must be provided if you provide the network. If both network and subnet are omitted, the default network is used, and the default subnet in the specified REGION is used.

Create a NEG to connect to a locational Google API

You can create a NEG to connect to a locational Google API.

For information about supported load balancers for this configuration, see Locational Google API targets.

Console

1. In the Google Cloud console, go to the Network endpoint groups page.

   Go to Network endpoint groups
   

2. Click Create network endpoint group.

3. Enter a name for the network endpoint group.

4. For the Network endpoint group type, select Private Service Connect NEG (Regional).

5. Configure the target:

   1. For Target, select Google APIs.
   2. Select a Region and the Target service.

6. Click Create.

gcloud

Use the gcloud compute network-endpoint-groups create command:

gcloud compute network-endpoint-groups create NEG_NAME \
    --network-endpoint-type=private-service-connect \
    --psc-target-service=TARGET_SERVICE \
    --region=REGION

Replace the following:

• NEG_NAME: a name for the network endpoint group.

• TARGET_SERVICE: the locational service endpoints that you want to connect to.

• REGION: the region to create the network endpoint group in. The region must be the same region as the target service.

Create a NEG to connect to a global Google API

Preview

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

You can create a Private Service Connect NEG to connect to a global Google API. NEGs are regional, even when they are connecting to global APIs. In this configuration, the region is ignored.

For information about supported load balancers for this configuration, see Global Google API targets.

Console

1. In the Google Cloud console, go to the Network endpoint groups page.

   Go to Network endpoint groups
   

2. Click Create network endpoint group.

3. Enter a name for the network endpoint group.

4. For the Network endpoint group type, select Private Service Connect NEG (Regional).

5. Configure the target:

   1. For Target, select Global Google APIs.
   2. Select a Region and the Target service.

6. Click Create.

gcloud

Use the gcloud compute network-endpoint-groups create command:

gcloud compute network-endpoint-groups create NEG_NAME \
    --network-endpoint-type=private-service-connect \
    --psc-target-service=TARGET_SERVICE \
    --region=REGION

Replace the following:

• NEG_NAME: a name for the network endpoint group.

• TARGET_SERVICE: the global Google API that you want to connect to.

• REGION: the region to create the network endpoint group in.

Add a Private Service Connect backend to a load balancer

You can configure a supported load balancer to direct traffic to a Private Service Connect NEG backend.

For more information about supported configurations, see Specifications.

Add a backend to an Application Load Balancer

Add a NEG to a global external Application Load Balancer, an internal Application Load Balancer, or a regional external Application Load Balancer.

Console

Edit the load balancer

1. In the Google Cloud console, go to the Load balancing page.

   Go to Load balancing

2. Click the load balancer that you want to modify.

3. Click Edit.

Update the backend configuration

1. Click Backend configuration.
2. Expand the list of backend services, and select Create a backend service.
3. Enter a name for the backend service.
4. Set the Backend type to Private Service Connect network endpoint group.
5. In the Backends section, click the Private Service Connect network endpoint group list, and select the Private Service Connect NEG that you created. Click Done.

6. If you are configuring a global external Application Load Balancer to connect to a published service in multiple regions, and you have created more than one Private Service Connect NEG, click Add backend to select another NEG.

   Repeat this step until all NEGs for this managed service are added to the backend service.

7. Click Create.

Update the routing rules

1. Click Routing rules.
2. Enter a Host and Path for each backend service that you have added.
3. To review the configuration, click Review and finalize.
4. Click Create.

gcloud

Update the backend configuration

1. Create a backend service for the target service.

   • If you are adding the backend service to a regional load balancer, use the --region flag to specify the same region as the load balancer.

     gcloud compute backend-services create BACKEND_SERVICE_NAME \
         --load-balancing-scheme=SCHEME \
         --protocol=HTTPS \
         --region=REGION
     

     Replace the following:

     • BACKEND_SERVICE_NAME: the name of the backend service.
     • SCHEME: the load balancing scheme for the load balancer that you are modifying:
       • For a regional external Application Load Balancer, use EXTERNAL_MANAGED.
       • For an internal Application Load Balancer, use INTERNAL_MANAGED.
     • REGION: the region of the backend service. Use the same region as the NEG.

   • If you are adding the backend service to a global external Application Load Balancer, use the --global flag.

     gcloud compute backend-services create BACKEND_SERVICE_NAME \
         --load-balancing-scheme=EXTERNAL_MANAGED \
         --protocol=HTTPS \
         --global
     

     Replace BACKEND_SERVICE_NAME with the name of the backend service.

2. Add the Private Service Connect NEG that points to the target service.

   • If you are adding a backend service to a regional load balancer, use the --region flag to specify the same region as the load balancer.

     gcloud compute backend-services add-backend BACKEND_SERVICE_NAME \
         --network-endpoint-group=NEG_NAME \
         --network-endpoint-group-region=NEG_REGION \
         --region=REGION
     

     Replace the following:

     • BACKEND_SERVICE_NAME: the name of the backend service.
     • NEG_NAME: the name of the network endpoint group.
     • NEG_REGION: the region of the network endpoint group.
     • REGION: the region of the backend service.

   • If you are adding a backend service to a global external Application Load Balancer, use the --global flag.

     If you have created multiple NEGs in different regions for the same service, repeat this step to add all of the NEGs to the backend service.

     gcloud compute backend-services add-backend BACKEND_SERVICE_NAME \
         --network-endpoint-group=NEG_NAME \
         --network-endpoint-group-region=NEG_REGION \
         --global
     

     Replace the following:

     • BACKEND_SERVICE_NAME: the name of the backend service.
     • NEG_NAME: the name of the network endpoint group.
     • NEG_REGION: the region of the network endpoint group.

Update the routing rules

1. For each backend service that you created, add a path matcher to the load balancer's URL map.

   • If the URL map is regional, specify the region by using the --region flag.

     gcloud compute url-maps add-path-matcher URL_MAP_NAME \
         --path-matcher-name=PATH_MATCHER \
         --default-service=BACKEND_SERVICE_NAME \
         --region=REGION
     

     Replace the following:

     • URL_MAP_NAME: the name of the URL map.
     • PATH_MATCHER: a name for the path matcher.
     • BACKEND_SERVICE_NAME: the name of the backend service.
     • REGION: the region of the URL map.

   • If the URL map is global, specify the --global flag.

     gcloud compute url-maps add-path-matcher URL_MAP_NAME \
         --path-matcher-name=PATH_MATCHER \
         --default-service=BACKEND_SERVICE_NAME \
         --global
     

     Replace the following:

     • URL_MAP_NAME: the name of the URL map.
     • PATH_MATCHER: a name for the path matcher.
     • BACKEND_SERVICE_NAME: the name of the backend service.

2. For each hostname, add a host rule.

   Each host rule can reference only one path matcher, but two or more host rules can reference the same path matcher.

   • If the URL map is regional, specify the region by using the --region flag.

     gcloud compute url-maps add-host-rule URL_MAP_NAME \
         --hosts=HOST \
         --path-matcher-name=PATH_MATCHER \
         --region=REGION
     

     Replace the following:

     • URL_MAP_NAME: the name of the URL map.
     • HOST: the hostname to send requests to for this service.
     • PATH_MATCHER: the name of the path matcher.
     • REGION: the region of the URL map.

   • If the URL map is global, specify the --global flag.

     gcloud compute url-maps add-host-rule URL_MAP_NAME \
         --hosts=HOST \
         --path-matcher-name=PATH_MATCHER \
         --global
     

     Replace the following:

     • URL_MAP_NAME: the name of the URL map.
     • HOST: the hostname to send requests to for this service.
     • PATH_MATCHER: the name of the path matcher.

Add a backend to a regional internal proxy Network Load Balancer

You can add a Private Service Connect NEG backend to a regional internal proxy Network Load Balancer if the NEG is pointing to a published service. Regional internal proxy Network Load Balancers support only one backend service.

To configure the regional internal proxy Network Load Balancer, follow the instructions to set up a regional internal proxy Network Load Balancer with zonal backends, but don't complete the "Create the zonal NEGs" steps or configure health checks. Instead of configuring a zonal NEG, use the following instructions to add the Private Service Connect NEG that you created to a Private Service Connect backend.

Console

1. In the regional internal proxy Network Load Balancer that you are creating, click Backend configuration.
2. For Backend type, select Private Service Connect network endpoint group.
3. For New backend, select the NEG that you created.
4. Retain the remaining default values, and then click Done.
5. In the Google Cloud console, verify that there is a check mark next to Backend configuration. If not, double-check that you have completed all of the steps.

gcloud

1. Create a backend service for the target service.

   gcloud compute backend-services create BACKEND_SERVICE_NAME \
       --load-balancing-scheme=INTERNAL_MANAGED \
       --protocol=TCP \
       --region=REGION
   

   Replace the following:

   • BACKEND_SERVICE_NAME: the name of the backend service.
   • REGION: the region of the backend service. Use the same region as the NEG.

2. Add the Private Service Connect NEG that points to the target service.

   gcloud compute backend-services add-backend BACKEND_SERVICE_NAME \
       --network-endpoint-group=NEG_NAME \
       --network-endpoint-group-region=NEG_REGION \
       --region=REGION
   

   Replace the following:

   • BACKEND_SERVICE_NAME: the name of the backend service.
   • NEG_NAME: the name of the network endpoint group.
   • NEG_REGION: the region of the network endpoint group.
   • REGION: the region of the backend service.

Add a backend to a regional external proxy Network Load Balancer

You can add a Private Service Connect NEG backend to a regional external proxy Network Load Balancer if the NEG is pointing to a published service. This load balancer supports only one backend service.

To configure the load balancer, follow the instructions to set up a regional external proxy Network Load Balancer with zonal backends, but don't complete the "Create the zonal NEGs" steps or configure health checks. Instead of configuring a zonal NEG, use the following instructions to add the Private Service Connect NEG that you created to a Private Service Connect backend.

Console

1. In the regional external proxy Network Load Balancer that you are creating, click Backend configuration.
2. For Backend type, select Private Service Connect network endpoint group.
3. For New backend, select the NEG that you created.
4. Retain the remaining default values, and then click Done.
5. In the Google Cloud console, verify that there is a check mark next to Backend configuration. If not, double-check that you have completed all of the steps.

gcloud

1. Create a backend service for the target service.

   gcloud compute backend-services create BACKEND_SERVICE_NAME \
       --load-balancing-scheme=EXTERNAL_MANAGED \
       --protocol=TCP \
       --region=REGION
   

   Replace the following:

   • BACKEND_SERVICE_NAME: the name of the backend service.
   • REGION: the region of the backend service. Use the same region as the NEG.

2. Add the Private Service Connect NEG that points to the target service.

   gcloud compute backend-services add-backend BACKEND_SERVICE_NAME \
       --network-endpoint-group=NEG_NAME \
       --network-endpoint-group-region=NEG_REGION \
       --region=REGION
   

   Replace the following:

   • BACKEND_SERVICE_NAME: the name of the backend service.
   • NEG_NAME: the name of the network endpoint group.
   • NEG_REGION: the region of the network endpoint group.
   • REGION: the region of the backend service.

List backends

You can list all configured Private Service Connect backends.

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 Private Service Connect backends are displayed in the Load balancer endpoints section.

Describe a backend

You can describe a Private Service Connect backend to view its details, including its connection status.

Console

1. List the available backends.
2. Click the backend that you want to describe.

Troubleshooting

Error accessing load balancer's forwarding rule

If you see a 404 error when you try to access your load balancer's forwarding rule, the error might have one of the following causes:

• The URL map hasn't propagated yet.

  If you just created the load balancer, try waiting a few minutes.

• The URL that you are using in your request does not match a URL defined in the URL map.

  Verify that the URL you are trying matches the URL map configuration in your load balancer.

• The service producer backend does not support the URL that you are trying to access

  Ask the service producer to verify which URL you should use to access their service.