Publishing services 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.

To publish a service, do the following:

  • Host the service using an internal TCP/UDP load balancer in the service producer VPC network.

  • Create a service attachment in the same region as the internal TCP/UDP load balancer.

To connect to a service, a service consumer configures a Private Service Connect endpoint to access the service in the same region.

You can also use Private Service Connect to connect to Google APIs and services.

Roles

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

Before you begin

To publish a service using Private Service Connect, the service must be hosted on backends of an internal TCP/UDP load balancer.

Decide whether the service should be accessible from all projects, or if you want to control which projects can access your service.

Limitations

Each internal TCP/UDP load balancer can be referenced only by a single service attachment. You cannot configure multiple service attachments that use the same load balancer.

Not all internal TCP/UDP load balancer features are supported. If your load balancer uses any of these features, you cannot use it to publish a service using Private Service Connect.

Also, a service attachment cannot reference a forwarding rule for internal protocol forwarding.

Subnets that you create for Private Service Connect have the following limitations:

  • You cannot use the same subnet in multiple service attachment configurations.

  • You cannot assign IP addresses from Private Service Connect subnets to resources.

Service attachment API

During Preview, use the beta version of the service attachment API.

Old field New field Details
producerForwardingRule targetService String
consumerForwardingRules connectedEndpoints Object, output-only
forwardingRule endpoint Object, output-only

Creating a subnet for Private Service Connect

You must create one or more dedicated subnets for 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.

For information about Private Service Connect subnets, see Private Service Connect subnets.

Console

  1. Go to the VPC networks page.
    Go to VPC networks
  2. Click the name of a VPC network to show its VPC network details page.
  3. 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.
    5. Click Add.

gcloud 

gcloud beta 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/beta/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.

Publishing 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.

Console

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

    Go to Private Service Connect

  2. Click the Published services tab.

  3. Click Publish service.

  4. Select the Internal load balancer associated with the service you want to publish.

    The network and region fields are populated with the details for the selected internal load balancer.

  5. If prompted, select the Forwarding rule associated with the service that you want to publish.

  6. For Service name, enter a name for the service attachment.

  7. 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.

  8. If you want to view consumer connection information, select Use Proxy Protocol. For more information, see Viewing consumer connection information.

  9. Select Automatically accept connections for all projects.

  10. Click Add service.

gcloud

If you want to view consumer connection information, use the optional --enable-proxy-protocol flag. For more information, see Viewing consumer connection information.

gcloud beta 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 ]

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.

API

If you want to view consumer connection information, include enableProxyProtocol: true. For more information, see Viewing consumer connection information

POST https://compute.googleapis.com/compute/beta/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",
  ],
}

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.

Publishing 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.

gcloud

If you want to view consumer connection information, use the optional --enable-proxy-protocol flag. For more information, see Viewing consumer connection information.

gcloud beta 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 ]

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 Private Service Connect endpoints 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.

API

If you want to view consumer connection information, include enableProxyProtocol: true. For more information, see Viewing consumer connection information.

POST https://compute.googleapis.com/compute/beta/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",
    },
  ],
}

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 Private Service Connect endpoints that can connect to this service. Each accepted project must have a connection limit configured.

Viewing 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 instead, you can enable PROXY protocol. If PROXY protocol is enabled, you can get the consumer's source IP address and PSC connection ID from the PROXY protocol header.

The PSC connection ID 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 PSC connection ID in network order

You can view the 8-byte PSC connection ID from the consumer forwarding rule or the producer service attachment. The PSC connection ID is a globally unique ID used identify a Private Service Connect forwarding rule. You can use the PSC connection ID 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.

Managing requests for access to a published service

If you have published a service with explicit project approval, you can accept or reject connection requests from consumer projects.

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

After a consumer endpoint connection is accepted for a service, the endpoint can connect to the service until the service attachment is deleted. This applies whether the project was accepted explicit or because the consumer endpoint connected when the connection preference was set to automatically accept connections.

  • If you remove a project from the accept list, any previously accepted consumer endpoints in that project can connect to the service. Connections from new consumer endpoints in that project must be accepted before the endpoint can connect.

  • If you add a project to the reject list, any previously accepted consumer endpoints in that project can connect to the service. Connections from new consumer endpoints in that project are rejected from connecting to the service.

gcloud

  1. Describe the service attachment you want to modify.

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

  2. Accept or reject consumer projects.

    You can specify --consumer-accept-list or --consumer-reject-list, or both. You can specify multiple values in --consumer-accept-list and --consumer-reject-list.

    gcloud beta compute service-attachments update ATTACHMENT_NAME \
    --region=REGION \
    --consumer-accept-list=ACCEPTED_PROJECT_1=LIMIT_1,ACCEPTED_PROJECT_2=LIMIT_2 \
    --consumer-reject-list=REJECTED_PROJECT_1,REJECTED_PROJECT_2

    Replace the following:

    • ATTACHMENT_NAME: the name to assign to the service attachment.

    • REGION: the region where the service attachment is located.

    • 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 Private Service Connect endpoints 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.

API

  1. Describe the service attachment you want to modify. 

    GET https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/regions/REGION/serviceAttachments/ATTACHMENT_NAME
    1. Accept or reject the consumer projects.
    PATCH https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/regions/REGION/serviceAttachments/ATTACHMENT_NAME

{
  ...
  "consumerAcceptLists": [
    {
      "projectIdOrNum": "ACCEPTED_PROJECT_1"
      "connectionLimit": "LIMIT_1",
    },
    {
      "projectIdOrNum": "ACCEPTED_PROJECT_2"
      "connectionLimit": "LIMIT_2",
    }
  ],
  "consumerRejectLists": [
    "REJECTED_PROJECT_1",
    "REJECTED_PROJECT_2",
  ],
  ...
}

    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.

    • 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 Private Service Connect endpoints that can connect to this service. Each accepted project must have a connection limit configured.

Changing the connection preference for a published service

You can switch between automatic and explicit project acceptance for a published service.

Changing from automatic acceptance to explicit acceptance does not affect consumer endpoints that had connected to the service before this change. Existing consumer endpoints can connect to the published service until the service attachment is deleted. New consumer endpoints must be accepted before they can connect to the service. See Managing requests for access to a published service for more information.

gcloud

  • Change the connection preference for the service attachment from ACCEPT_AUTOMATIC to ACCEPT_MANUAL.

    You control which projects can connect to your service using --consumer-accept-list and --consumer-reject-list. You can configure the accept and reject lists when you change the connection preference, or update the lists later.

    gcloud beta compute service-attachments update ATTACHMENT_NAME \
    --region=REGION \
    --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 ]

    • ATTACHMENT_NAME: the name of the service attachment.

    • REGION: the region where the service attachment is located.

    • 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 Private Service Connect endpoints 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.

  • Change the connection preference for the service attachment from ACCEPT_MANUAL to ACCEPT_AUTOMATIC.

    If you have values in the accept list or reject list, set them to empty when you change the connection preference ("").

    gcloud beta compute service-attachments update ATTACHMENT_NAME \
    --region=REGION \
    --connection-preference=ACCEPT_AUTOMATIC \
     --consumer-accept-list="" \
     --consumer-reject-list=""

    • ATTACHMENT_NAME: the name of the service attachment.

    • REGION: the region where the service attachment is located.

API

  • Change the connection preference for the service attachment from ACCEPT_AUTOMATIC to ACCEPT_MANUAL.
PATCH https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/regions/REGION/serviceAttachments/ATTACHMENT_NAME

{
  ...
  "connectionPreference": "ACCEPT_MANUAL",
  "consumerAcceptLists": [
    {
      "projectIdOrNum": "ACCEPTED_PROJECT_1"
      "connectionLimit": "LIMIT_1",
    },
    {
      "projectIdOrNum": "ACCEPTED_PROJECT_2"
      "connectionLimit": "LIMIT_2",
    }
  ],
  "consumerRejectLists": [
    "REJECTED_PROJECT_1",
    "REJECTED_PROJECT_2",
  ],
  ...
}

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.

  • 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 Private Service Connect endpoints that can connect to this service. Each accepted project must have a connection limit configured.

  • Change the connection preference for the service attachment from ACCEPT_MANUAL to ACCEPT_AUTOMATIC.

    If the consumerAcceptLists or consumerRejectLists fields specify any projects, set them to empty when you change the connection preference to ACCEPT_AUTOMATIC.

PATCH https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/regions/REGION/serviceAttachments/ATTACHMENT_NAME

{
  ...
  "connectionPreference": "ACCEPT_AUTOMATIC",
  "consumerAcceptLists": [ ],
  "consumerRejectLists": [ ],
  ...
}

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.

Listing published services

You can list all services.

Console

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

    Go to Private Service Connect

  2. Click the Published services tab.

    The Private Service Connect service attachments are displayed.

gcloud

  1. List service attachments.

    gcloud beta 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/beta/projects/PROJECT_ID/regions/REGION/serviceAttachments

  • View all service attachments in all regions:

    GET https://compute.googleapis.com/compute/beta/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.

Viewing details for a published service

You can view all configuration details of a published service. The details include the service attachment URI that service consumers need to connect to your service.

Console

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

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

    Go to Private Service Connect

  2. Click the Published services tab.

  3. 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 beta 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/beta/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.

Deleting a published service

You can delete a published service, even if there are consumer connections to the service attachment. Deleting the published service removes only the service attachment. It does not delete the internal TCP/UDP load balancer.

Console

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

    Go to Private Service Connect

  2. Click the Published services tab.

  3. Click the service you want to delete.

  4. Click Delete.

gcloud 

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

API 

DELETE https://compute.googleapis.com/compute/beta/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.