Publish services by using Private Service Connect

As a service producer, you can use Private Service Connect to publish services using internal IP addresses in your VPC network. Your published services are accessible to service consumers using internal IP addresses in their VPC networks.

This guide describes how to use Private Service Connect to publish a service. To publish a service, you do the following:

Host the service on a supported load balancer with a supported configuration.
Create a service attachment that points to the forwarding rule associated with the load balancer.

Private Service Connect provides two methods to connect to published services:

These endpoint types require slightly different producer configurations. For more information, see Features and compatibility.

Roles

The following IAM role provides the permissions needed to perform the tasks in this guide.

Compute Network Admin (roles/compute.networkAdmin)

Before you begin

Read About published services for more information, including DNS configuration and limitations.
Decide whether the service should be accessible from all projects, or if you want to control which projects can access your service.
Decide whether you want this service to support endpoints, backends, or both. For more information about endpoints and backends, see Private Service Connect types.

For more information about the service configuration requirements, see Features and compatibility.

Supported load balancer types

You can host the service using the following load balancers:

Internal TCP/UDP load balancer in a service producer VPC network.
Internal HTTP(S) load balancer in a service producer VPC network.
Internal protocol forwarding in a service producer VPC network.
Internal regional TCP proxy load balancer in a service producer VPC network. The backends can be located in Google Cloud, in other clouds, in an on-premises environment, or any combination of these locations.

For information about supported configurations for each load balancer type, see Features and compatibility.

You can also publish a service that is hosted on an internal TCP/UDP load balancer on Google Kubernetes Engine. This configuration, including load balancer and service attachment configuration, is described in Create an internal TCP/UDP load balancer with Private Service Connect in the GKE documentation.

Create a subnet for Private Service Connect

Create one or more dedicated subnets to use with Private Service Connect. If you're using the Google Cloud console to publish a service, you can create the subnets during that procedure.

If you need to make more IP addresses available to an existing service, see Add or remove subnets from a published service.

You can also create a Private Service Connect subnet in a Shared VPC host project.

Create the subnet in the same region as the service's load balancer.

You can't convert a regular subnet to a Private Service Connect subnet.

Permissions required for this task

To perform this task, you must have been granted the following permissions or one of the following IAM roles.

Permissions

compute.subnetworks.create

Roles

See Roles for role information.

Console

In the Google Cloud console, go to the VPC networks page.

Go to VPC networks
Click the name of a VPC network to show its VPC network details page.
Click Add subnet. In the panel that appears:
1. Provide a Name.
2. Select a Region.
3. In the Purpose section, select Private Service Connect.
4. Enter an IP address range. For example, 10.10.10.0/24.
5. Click Add.

gcloud

gcloud compute networks subnets create SUBNET_NAME \
    --network=NETWORK_NAME --region=REGION \
    --range=SUBNET_RANGE --purpose=PRIVATE_SERVICE_CONNECT

Replace the following:

SUBNET_NAME: the name to assign to the subnet.
NETWORK_NAME: the name of the VPC for the new subnet.
REGION: the region for the new subnet. This must be the same region as the service you are publishing.
SUBNET_RANGE: the IP address range to use for the subnet. For example, 10.10.10.0/24.

API

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/subnetworks

{
  "ipCidrRange": "SUBNET_RANGE",
  "name": "SUBNET_NAME",
  "network": "projects/PROJECT_ID/global/networks/NETWORK_NAME",
  "purpose": "PRIVATE_SERVICE_CONNECT",
}

Replace the following:

PROJECT_ID: the project for the subnet.
SUBNET_NAME: the name to assign to the subnet.
NETWORK_NAME: the name of the VPC network for the new subnet.
REGION: the region for the new subnet. This must be the same region as the service you are publishing.
SUBNET_RANGE: the IP address range to use for the subnet. For example, 10.10.10.0/24.

Configure firewall rules

Configure firewall rules to allow traffic between the endpoints or backends and the service attachment. Client requests originate from different locations depending on the Private Service Connect type.

Private Service Connect type	IP address ranges for client traffic	Details
Endpoint (based on a forwarding rule)	The IP address ranges of the Private Service Connect subnets associated with this service.	If you are using the default network, the pre-populated `default-allow-internal` rule allows this traffic, unless there is a higher priority rule that blocks it.
Backend (based on a global external HTTP(S) load balancer)	`130.211.0.0/22` `35.191.0.0/16`	global external HTTP(S) load balancers are implemented on Google Front Ends (GFEs), which use these IP address ranges.

If your firewall configuration doesn't already allow traffic from the appropriate endpoint type, configure firewall rules to allow it.

This example configuration lets you create VPC firewall rules to allow traffic from client IP address ranges to the backend VMs in the producer service load balancer. This configuration assumes that the backend VMs have been configured with a network tag.

Example ingress rule:

gcloud compute firewall-rules create NAME \
  --network=NETWORK_NAME \
  --direction=ingress \
  --action=allow \
  --target-tags=TAG \
  --source-ranges=CLIENT_IP_RANGES_LIST \
  --rules=RULES

Replace the following:

NETWORK_NAME: the network that contains the service and Private Service Connect subnet.
TAG: the target tag that is applied to the backend VMs in the producer service load balancer.
CLIENT_IP_RANGES_LIST: the IP address ranges where client traffic originates from. For more information, see the preceding table.
RULES_LIST: a comma-separated list of protocols and destination ports to which the rule applies. For example, tcp,udp.

Example egress rule:

gcloud compute firewall-rules create NAME \
  --network=NETWORK_NAME \
  --direction=egress \
  --action=allow \
  --target-tags=TAG \
  --destination-ranges=CLIENT_IP_RANGES_LIST \
  --rules=RULES

Replace the following:

NETWORK_NAME: the network that contains the service and Private Service Connect subnet.
TAG: the target tag that is applied to the backend VMs in the producer service load balancer.
CLIENT_IP_RANGES_LIST: the IP address ranges where client traffic originates from. For more information, see the preceding table.
RULES_LIST: a comma-separated list of protocols and destination ports to which the rule applies. For example, tcp,udp.

For more information about configuring VPC firewall rules, see VPC firewall rules overview. If you want to configure hierarchical firewall rules to allow this traffic, see Hierarchical firewall policies overview.

Publish a service

To publish a service, you create a service attachment. You can make the service available in one of two ways:

You can publish a service with automatic project approval.
You can publish a service with explicit project approval.

Create the service attachment in the same region as the service's load balancer.

Each service attachment can point to one or more Private Service Connect subnets, but a Private Service Connect subnet cannot be used in more than one service attachment.

Publish a service with automatic project approval

Use these instructions to publish a service and automatically let any consumer connect to this service. If you want to approve consumer connections explicitly, see publishing a service with explicit project approval.

When you publish a service, you create a service attachment. Service consumers use the service attachment details to connect to your service.

If you want to view consumer connection information, you can enable PROXY protocol on supported services. For information about supported services, see Features and compatibility. For more information about PROXY protocol, see Viewing consumer connection information.

Permissions required for this task

To perform this task, you must have been granted the following permissions or one of the following IAM roles.

Permissions

compute.subnetworks.use
compute.serviceAttachments.create

Roles

See Roles for role information.

Console

In the Google Cloud console, go to the Private Service Connect page.

Go to Private Service Connect
Click the Published services tab.
Click Publish service.
Select the Load balancer type for the service that you want to publish:
- Internal TCP/UDP Load balancer
- Internal TCP Proxy Load balancer
- Internal HTTP(S) Load balancer
Select the Internal load balancer that hosts the service that you want to publish.

The network and region fields are populated with the details for the selected internal load balancer.
If prompted, select the Forwarding rule associated with the service that you want to publish.
For Service name, enter a name for the service attachment.
Select one or more Subnets for the service. If you want to add a new subnet, you can create one:
1. Click Reserve new subnet
2. Enter a Name and optional Description for the subnet.
3. Select a Region for the subnet.
4. Enter the IP range to use for the subnet and click Add.
If you want to view consumer connection information, select Use Proxy Protocol.
If you want to configure a domain name, enter a Domain name, including a trailing dot.

The recommended format for the domain name is REGION.p.DOMAIN.

You must own the domain name. For more information, see DNS configuration.
Select Automatically accept connections for all projects.
Click Add service.

gcloud

gcloud compute service-attachments create ATTACHMENT_NAME \
    --region=REGION \
    --producer-forwarding-rule=RULE_NAME  \
    --connection-preference=ACCEPT_AUTOMATIC \
    --nat-subnets=PSC_SUBNET_LIST \
    [ --enable-proxy-protocol ] \
    [ --domain-names=DOMAIN_NAME ]

Replace the following:

ATTACHMENT_NAME: the name to assign to the service attachment.
REGION: the region for the new service attachment. This must be the same region as the service you are publishing.
RULE_NAME: the name of the forwarding rule associated with the service you are publishing.
PSC_SUBNET_LIST: a comma-separated of one or more subnets to use with this service attachment.
DOMAIN_NAME: a DNS domain name for the service, including a trailing dot. Recommended format: REGION.p.DOMAIN.

For more information, see DNS configuration.

API

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/serviceAttachments
{
  "name": "ATTACHMENT_NAME",
  "connectionPreference": "ACCEPT_AUTOMATIC",
  "targetService": "RULE_URI",
  "enableProxyProtocol": false,
  "natSubnets": [
    "PSC_SUBNET_1_URI",
    "PSC_SUBNET_2_URI",
  ],
  "domainNames": [
    "DOMAIN_NAME",
  ],
}

Replace the following:

PROJECT_ID: the project for the service attachment.
ATTACHMENT_NAME: the name to assign to the service attachment.
REGION: the region for the new service attachment. This must be the same region as the service you are publishing.
RULE_URI: the name of the forwarding rule associated with the service you are publishing.
PSC_SUBNET_1_URI and PSC_SUBNET_2_URI: the subnet URIs to use for this service attachment. You can specify one or more subnets by URI.
DOMAIN_NAME: a DNS domain name for the service, including a trailing dot. Recommended format: REGION.p.DOMAIN.

For more information, see DNS configuration.

Publish a service with explicit project approval

Use these instructions to publish a service such that you must explicitly approve consumers who want to connect to this service. If you want to approve consumer connections automatically, see publishing a service with automatic project approval.

When you publish a service, you create a service attachment. Service consumers use the service attachment details to connect to your service.

If you add a project to both the accept list and the deny list, connection requests from that project are rejected.

Permissions required for this task

To perform this task, you must have been granted the following permissions or one of the following IAM roles.

Permissions

compute.subnetworks.use
compute.serviceAttachments.create

Roles

See Roles for role information.

Console

In the Google Cloud console, go to the Private Service Connect page.

Go to Private Service Connect
Click the Published services tab.
Click Publish service.
Select the Load balancer type: Internal TCP/UDP Load Balancer or Internal HTTP(S) Load Balancer.
Select the Internal load balancer that hosts the service that you want to publish.

The network and region fields are populated with the details for the selected internal load balancer.
If prompted, select the Forwarding rule associated with the service you want to publish.
For Service name, enter a name for the service attachment.
Select one or more Subnets for the service.

If you want to add a new subnet, you can create one:
1. Click Reserve new subnet
2. Enter a Name and optional Description for the subnet.
3. Select a Region for the subnet.
4. Enter the IP range to use for the subnet and click Add.
If you want to view consumer connection information, select the Protocols checkbox.
If you want to configure a domain name, enter a Domain name, including a trailing dot.

The recommended format for the domain name is REGION.p.DOMAIN.

You must own the domain name. For more information, see DNS configuration.
Select Accept connections for selected projects.
Click Add accepted project, and then enter the details of the projects that you want to allow to connect to this service:
- Project name: the name of the project to allow connections from.
- Connection limit: the number of Private Service Connect endpoints in the consumer VPC network that can connect to the service attachment in the producer VPC network.
Click Add service.

gcloud

gcloud compute service-attachments create ATTACHMENT_NAME \
    --region=REGION \
    --producer-forwarding-rule=RULE_NAME  \
    --connection-preference=ACCEPT_MANUAL \
    --consumer-accept-list=ACCEPTED_PROJECT_1=LIMIT_1,ACCEPTED_PROJECT_2=LIMIT_2 \
    --consumer-reject-list=REJECTED_PROJECT_1,REJECTED_PROJECT_2 \
    --nat-subnets=PSC_SUBNET_LIST \
    [ --enable-proxy-protocol ] \
    [--domain-names=DOMAIN_NAME]

Replace the following:

ATTACHMENT_NAME: the name to assign to the service attachment.
REGION: the region for the new service attachment. This must be the same region as the service you are publishing.
RULE_NAME: the name of the forwarding rule associated with the service you are publishing.
ACCEPTED_PROJECT_1 and ACCEPTED_PROJECT_2: the projects to accept. --consumer-accept-list is optional and can contain one or more projects.
LIMIT_1 and LIMIT_2: the connection limits for the projects. The connection limit is the number of consumer endpoints or backends that can connect to this service. Each accepted project must have a connection limit configured.
REJECTED_PROJECT_1 and REJECTED_PROJECT_2: the projects to reject. --consumer-reject-list is optional and can contain one or more projects.
PSC_SUBNET_LIST: a comma-separated list of one or more subnets to use with this service attachment.
DOMAIN_NAME: a DNS domain name for the service, including a trailing dot. Recommended format: REGION.p.DOMAIN.

For more information, see DNS configuration.

API

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/serviceAttachments
{
  "name": "ATTACHMENT_NAME",
  "region": "REGION",
  "connectionPreference": "ACCEPT_MANUAL",
  "targetService": "RULE_URI",
  "enableProxyProtocol": false,
  "natSubnets": [
    "PSC_SUBNET_1_URI",
    "PSC_SUBNET_2_URI",
  ],
  "consumerRejectList": [
    "REJECTED_PROJECT_1",
    "REJECTED_PROJECT_2",
  ],
  "consumerAcceptList": [
    "consumerProjectLimit": {
      "projectId": "ACCEPTED_PROJECT_1",
      "connectionsLimit": "LIMIT_2",
    },
    "consumerProjectLimit": {
      "projectId": "ACCEPTED_PROJECT_2",
      "connectionsLimit": "LIMIT_2",
    },
  ],
  "domainNames": [
    "DOMAIN_NAME",
  ],
}

Replace the following:

PROJECT_ID: the project for the service attachment.
REGION: the region for the service attachment.
ATTACHMENT_NAME: the name to assign to the service attachment.
RULE_URI: the URI of the forwarding rule associated with the service you are publishing.
PSC_SUBNET_1_URI and PSC_SUBNET_2_URI: the subnet URIs to use for this service attachment. You can specify one or more subnets by URI.
REJECTED_PROJECT_1 and REJECTED_PROJECT_2: the projects to reject. consumerRejectList is optional and can contain one or more projects.
ACCEPTED_PROJECT_1 and ACCEPTED_PROJECT_2: the projects to accept. consumerAcceptList is optional and can contain one or more projects.
LIMIT_1 and LIMIT_2: the connection limits for the projects. The connection limit is the number of consumer endpoints or backends that can connect to this service. Each accepted project must have a connection limit configured.
DOMAIN_NAME: a DNS domain name for the service, including a trailing dot. Recommended format: REGION.p.DOMAIN.

For more information, see DNS configuration.

View consumer connection information

By default, Private Service Connect translates the consumer's source IP address to an address in one of the Private Service Connect subnets in the service producer's VPC network. If you want to see the consumer's original source IP address, you can enable PROXY protocol.

Not all services support PROXY protocol. For more information, see Features and compatibility.

If PROXY protocol is enabled, you can get the consumer's source IP address and PSC connection ID (pscConnectionId) from the PROXY protocol header.

When you enable PROXY protocol for a service attachment, the change applies to new connections only. Existing connections do not include the PROXY protocol header.

If you enable PROXY protocol, check the documentation for your backend web server software for information about parsing and processing incoming PROXY protocol headers in the client connection TCP payloads. If PROXY protocol is enabled on the service attachment, but the backend web server is not configured to process PROXY protocol headers, web requests might be malformed. If requests are malformed, the server can't interpret the request.

The pscConnectionId is encoded in the PROXY protocol header in Type-Length-Value (TLV) format.

Field	Field Length	Field Value
Type	1 byte	`0xE0` (PP2_TYPE_GCP)
Length	2 bytes	`0x8` (8 bytes)
Value	8 bytes	The 8-byte `pscConnectionId` in network order

You can view the 8-byte pscConnectionId from the consumer forwarding rule or the producer service attachment.

The pscConnectionId is globally unique for all active connections at a given point in time. However, over time, a pscConnectionId might be reused in these scenarios:

Within a given VPC network, if you delete an endpoint (forwarding rule), and create a new endpoint using the same IP address, the same pscConnectionId might be used.
If you delete a VPC network that contained endpoints (forwarding rules), after a seven day waiting period, the pscConnectionId used for those endpoints might be used for a different endpoint in another VPC network.

You can use pscConnectionId for debugging and to trace the source of packets.

Also, a 16-byte PSC attachment ID is available from the producer service attachment. The PSC attachment ID is a globally unique ID that identifies a Private Service Connect service attachment. You can use the PSC attachment ID for visibility and debugging. The PSC attachment ID is not included in the PROXY protocol header.

Manage requests for access to a published service

If you have a published service with explicit project approval, you can accept or reject connection requests from consumer projects. For more information, see Manage requests for access to a published service.

You can also switch between automatic and explicit project acceptance for a published service. For more information, see Change the connection preference for a published service

Add or remove subnets from a published service

You can add or remove subnets from a published service. For more information, see Add or remove subnets from a published service.

List published services

You can list all services.

Permissions required for this task

To perform this task, you must have been granted the following permissions or one of the following IAM roles.

Permissions

compute.serviceAttachments.list

Roles

See Roles for role information.

Console

In the Google Cloud console, go to the Private Service Connect page.

Go to Private Service Connect
Click the Published services tab.

The Private Service Connect service attachments are displayed.

gcloud

List service attachments.
```
gcloud compute service-attachments list [--regions=REGION_LIST]
```
Replace the following:
- REGION_LIST: a comma-separated list of one or more regions that you want to view service attachments for. For example, us-central1 or us-west1,us-central1.

API

You can view all service attachments in a given region or in all regions.

View all service attachments in a region:

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

View all service attachments in all regions:
```
GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/aggregated/serviceAttachments
```
Replace the following:
- PROJECT_ID: the project for the service attachment.
- REGION: the region for the service attachment.
- ATTACHMENT_NAME: the name of the service attachment.

View details for a published service

You can view the configuration details of a published service. You can view some configuration details in the Google Cloud console, for example, the service attachment URI that service consumers need to connect to your service. To view all details, including the pscConnectionId values for the service attachment's consumers, use the Google Cloud CLI or the API.

Permissions required for this task

To perform this task, you must have been granted the following permissions or one of the following IAM roles.

Permissions

compute.serviceAttachments.get

Roles

See Roles for role information.

Console

You can view details for a published service. The Service attachment field contains the service attachment URI.

In the Google Cloud console, go to the Private Service Connect page.

Go to Private Service Connect
Click the Published services tab.
Click the service that you want to view.

gcloud

You can view details for a published service. The selfLink field contains the service attachment URI.

gcloud compute service-attachments describe \
    ATTACHMENT_NAME --region=REGION

API

You can view details for a published service. The selfLink field contains the service attachment URI.

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

Replace the following:

PROJECT_ID: the project for the service attachment.
REGION: the region for the service attachment.
ATTACHMENT_NAME: the name of the service attachment.

Delete a published service

You can delete a published service, even if there are consumer connections to the service attachment. Deleting the published service removes the service attachment only. The associated load balancer is not deleted. When you delete a published service, the following applies:

Traffic from endpoints (based on forwarding rules) is no longer sent to the load balancer.
Traffic from backends (based on global external HTTP(S) load balancers) is sent to the load balancer until the load balancer is deleted.

Permissions required for this task

To perform this task, you must have been granted the following permissions or one of the following IAM roles.

Permissions

compute.serviceAttachments.delete

Roles

See Roles for role information.

Console

In the Google Cloud console, go to the Private Service Connect page.

Go to Private Service Connect
Click the Published services tab.
Click the service that you want to delete.
Click Delete.

gcloud

gcloud compute service-attachments delete \
    ATTACHMENT_NAME --region=REGION

API

DELETE https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/serviceAttachments/ATTACHMENT_NAME

Replace the following:

PROJECT_ID: the project for the service attachment.
REGION: the region for the service attachment.
ATTACHMENT_NAME: the name of the service attachment.

Known issues

When you update a service attachment using the PATCH API, you must provide all fields for the service attachment in the request body, not only the fields you are updating. Use serviceAttachments.get to retrieve all fields.

Troubleshooting

Error when updating a service attachment

If you see the following error message when you update a service attachment, the accept list or the reject list might include deleted projects: The resource PROJECT was not found.

Remove the deleted projects from the service attachment configuration to resolve the issue.

Use the gcloud compute service-attachments describe command to show the configuration of the service attachment that you want to modify.

To output the accept list in a format you can use later to update the service attachment, do the following:

gcloud compute service-attachments describe ATTACHMENT_NAME \
  --region=REGION --flatten="consumerAcceptLists[]" \
  --format="csv[no-heading,separator='='](consumerAcceptLists.projectIdOrNum,consumerAcceptLists.connectionLimit)" \
  | xargs | sed -e 's/ /,/g'

The accept list output looks similar to the following:

PROJECT_1=LIMIT_1,PROJECT_2=LIMIT_2,PROJECT_3=LIMIT_3

To output the reject list in a format you can use later to update the service attachment, do the following:

gcloud compute service-attachments describe ATTACHMENT_NAME \
  --region=REGION \
  --format="value[delimiter=','](consumerRejectLists[])"

The reject list output looks similar to the following:

PROJECT_1,PROJECT_2,PROJECT_3

Edit the command output to remove any deleted projects from the accept list and the reject list.

Update the service attachment to remove the deleted projects.

To update the accept list, do the following:

gcloud compute service-attachments update ATTACHMENT_NAME \
  --region=REGION \
  --consumer-accept-list=UPDATED_ACCEPT_LIST

To update the reject list, do the following:

gcloud compute service-attachments update ATTACHMENT_NAME \
  --region=REGION \
  --consumer-reject-list=UPDATED_REJECT_LIST