Publish services by using Private Service Connect

As a service producer, you can usePrivate Service Connect to publishservices using internal IP addresses in your VPC network. Yourpublished services are accessible to service consumers by using internal IPaddresses in the consumer VPC networks.

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

Private Service Connect provides two methods to connect to publishedservices:

These endpoint types require slightly different producer configurations. Formore information, seeFeatures and compatibility.

Roles

The followingIAM role providesthe permissions needed to perform the tasks in this guide.

Before you begin

  • ReadAbout published services forinformation about publishing services, including limitations.

  • Decide whether the service should beaccessible from allprojects, or if you want tocontrol which projectscan access your service.

  • Decide whether you want this service to support endpoints, backends, orboth. For more information about endpoints and backends, seePrivate Service Connecttypes.

    For more information about the service configuration requirements, seeFeatures andcompatibility.

  • Decide if you want toconfigure a domain name for theservice, which automates DNSconfiguration for service consumer endpoints. If you do configure a domainname, the same IAM principal that publishes the service mustverify that they have Owner permissions for the domain in theGoogle Search Console. If you configure a domain name, but youdon't own the domain, publishing the service fails. To verify ownership, goto theGoogle SearchConsole.

    The domain name that you specify in the service attachment can be asubdomain of the domain that you verify. For example, you can verifyexample.com and then create a service attachment with a domain name ofus-west1.p.example.com.

  • Decide whether your service will usePROXY protocol toprovide details about consumers' connections.If you plan to use PROXY protocol, make sure that it's supported by bothyour target service type and the service's backend web server software.For information about the types of target servicesthat support PROXY protocol, seeFeatures and compatibility.

Create a target service

To host the service, create one of the following target services in a serviceproducer VPC network:

For information about supported configurations for each target service, seeFeatures andcompatibility.

A service attachment can have only one target service. However, multipleservice attachments can share the same target service.

The IP version of your target service(IPv4 or IPv6) affects which consumers can connect to your published service.For more information, seeIP version translation.

For regional internal proxy Network Load Balancers, the backends can be located inGoogle Cloud, in other clouds, in an on-premises environment, or anycombination of these locations.

You can also publish a service that is hosted on an internal passthrough Network Load Balancer onGoogle Kubernetes Engine. This configuration, including load balancer andservice attachment configuration, is described inCreate an internal passthrough Network Load Balancer withPrivate Service Connectin the GKE documentation.

Create a subnet for Private Service Connect

Create one or more dedicated subnets to use withPrivate Service Connect. You must create the subnet in the sameregion as the service's load balancer.

If you're using the Google Cloud console topublish aservice, you can create the subnets during thatprocedure.

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

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

The IP stack type of the subnet that you create must be compatible with the IPversion of your load balancer's forwarding rule:

  • For IPv4 forwarding rules, create an IPv4-only or dual-stack subnet.
  • For IPv6 forwarding rules, create an IPv6-onlyor dual-stack subnetthat has aninternal IPv6 address range.
  • If you use a dual-stack subnet, either the IPv4 or IPv6address range is used, but not both.

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

Permissions required for this task

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

Permissions

  • compute.subnetworks.create

Roles

SeeRoles for role information.

Console

  1. In the Google Cloud console, go to theVPC networks page.

    Go to VPC networks

  2. Click the name of a VPC network to show itsVPC networkdetails page.

  3. ClickSubnets.

  4. ClickAdd subnet. In the panel that appears, do the following:

    1. Provide a name.
    2. Select a region.
    3. In thePurpose section, selectPrivate Service Connect.
    4. In theIP stack type section, select an IP stack type.
    5. If you are creating an IPv4-only or dual-stack subnet,enter an IPv4 address range—for example,10.10.10.0/24.
    6. If you are creating an IPv6-onlyor dual-stack subnet, clickIPv6 access type and selectInternal.
    7. ClickAdd.

gcloud

Use thegcloud compute networks subnets create command.

  • To create an IPv4-only Private Service Connect subnet, dothe following:

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

  • To create a dual-stack Private Service Connect subnet, dothe following:

    gcloud compute networks subnets createSUBNET_NAME \    --network=NETWORK_NAME \    --region=REGION \    --stack-type=IPV4_IPV6 \    --ipv6-access-type=INTERNAL \    --range=SUBNET_RANGE \    --purpose=PRIVATE_SERVICE_CONNECT

  • To create an IPv6-only Private Service Connect subnet, dothe following:

    gcloud compute networks subnets createSUBNET_NAME \    --network=NETWORK_NAME \    --region=REGION \    --stack-type=IPV6_ONLY \    --ipv6-access-type=INTERNAL \    --purpose=PRIVATE_SERVICE_CONNECT

Replace the following:

  • SUBNET_NAME: the name to assign to thesubnet.

  • NETWORK_NAME: the name of the VPCfor the new subnet.

  • REGION: the region for the new subnet. This must bethe same region as the service you are publishing.

  • SUBNET_RANGE: the IPv4 address range to use for thesubnet—for example,10.10.10.0/24.

API

Send aPOST request to thesubnetworks.insert method.

  • To create an IPv4-only Private Service Connect subnet, dothe following:

    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"}

  • To create a dual-stack Private Service Connect subnet, dothe following:

    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",  "stackType": "IPV4_IPV6",  "ipv6AccessType": "INTERNAL"}

  • To create an IPv6-only Private Service Connect subnet, dothe following:

    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/subnetworks{  "name": "SUBNET_NAME",  "network": "projects/PROJECT_ID/global/networks/NETWORK_NAME",  "purpose": "PRIVATE_SERVICE_CONNECT",  "stackType": "IPV6_ONLY",  "ipv6AccessType": "INTERNAL"}

Replace the following:

  • PROJECT_ID: the project for the subnet.

  • REGION: the region for the new subnet. This must bethe same region as the service you are publishing.

  • SUBNET_RANGE: the IPv4 address range to use for thesubnet. For example,10.10.10.0/24.

  • SUBNET_NAME: the name to assign to thesubnet.

  • NETWORK_NAME: the name of the VPCnetwork for the new subnet.

Configure firewall rules

Your network configuration must allow traffic from appropriate source IPaddress ranges to the instances or network endpoints that are configured asbackends for your backend services. If your service uses health checks, you mustalso allow traffic from the health check probes to your backends.

You don't need to take any steps to allow traffic between aPrivate Service Connect endpoint orPrivate Service Connect backend and the associatedservice attachment, or between a service attachment and the associated loadbalancer. Endpoints, backends, and service attachments arelogical components that don't participate in the flow of traffic.

If your backends are in a VPC network, you can useVPC ingress firewall rules or firewall policies to allow thistraffic. For backends that are on-premises or in another cloud, configure thatenvironment to allow traffic to the backends.

When you configure ingress firewall rules for backend services, the source oftraffic depends on the type of load balancer that your service uses:

CategorySource of traffic to backends
Passthrough load balancers:
  • Internal passthrough Network Load Balancer
  • Internal protocol forwarding
  • Port mapping service
The IP address ranges of the Private Service Connect (NAT) subnets associated with the service
Proxy load balancers:
  • Cross-region internal Application Load Balancer
  • Regional internal Application Load Balancer
  • Regional internal proxy Network Load Balancer
  • Secure Web Proxy
The IP address ranges of the associated proxy-only subnets
Services with health checksThe probe IP address ranges of your load balancer type

Publish a service

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

Create the service attachment in the same region as the service's loadbalancer.

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

If you want to view consumer connection information, you can enable PROXYprotocol on supported services. Only enable PROXY protocol if it's supportedby both your targetservice type (known issue) and the service's backend webserver software. For information about the types of target services that supportPROXY protocol, seeFeatures and compatibility.For more information about PROXY protocol, seeConsumer connectioninformation.

The following sections provide instructions for publishing a service that'sbased on a load balancer. For information about creating a service attachmentthat refers to a Secure Web Proxy instance, seeDeploy Secure Web Proxy as a Private Service Connect service attachment.

Publish a service with automatic approval

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

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

When you publish a service with automatic approval, the propagated connectionlimit applies to each consumer project that connects to your serviceattachment.

Permissions required for this task

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

Permissions

  • compute.subnetworks.use
  • compute.serviceAttachments.create

Roles

SeeRoles for role information.

Console

Configure the service

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

    Go to Private Service Connect

  2. Click thePublished services tab.

  3. ClickPublish service.

  4. In theTarget details section, selectLoad balancer.

  5. Select a load balancer type.

  6. Select the internal load balancer that hoststhe service that youwant to publish. The network and region fields are populated with thedetails for the selected internal load balancer.

    Service Project Adminscan select an internal load balancer that has an IP address from aShared VPC network.For more information, seeShared VPC.

  7. If prompted, select the forwarding rule that is associated with theservice that you want to publish.

  8. ForService name, enter a name for the service attachment.

Select a Private Service Connect subnet

Select one or more Private Service Connect subnets forthe service. The list is populated with subnets from the selectedinternal load balancer's VPC network, includingsubnets that are shared with a service project throughShared VPC.

If your service attachment uses an internal load balancer with an IPaddress from a Shared VPC network, you must select a sharedsubnet from the same Shared VPC network.

If you want to add a new subnet, you can create one:

  1. ClickSubnets, and then clickReserve new subnet.
  2. Enter a name and optional description for the subnet.
  3. Select a region for the subnet.
  4. Select an IP stack type.
  5. If you are creating an IPv4-only or dual-stack subnet,enter an IPv4 address range to use for the subnet.
  6. ClickAdd.

Complete the configuration

  1. If you want to view consumer connection information, selectUse ProxyProtocol.
  2. SelectAutomatically accept all connections.
  3. If you want to disableconnection reconciliation, clear theEnable connection reconciliation checkbox.

  4. Optional: ClickAdvanced configuration, and then do the following:

    1. If you want to configure a domain name, enter a domain name,including a trailing dot.

      The recommended format for the domain name isREGION.p.DOMAIN.

      You must own the domain name. For more information, seeDNS configuration.

    2. Enter apropagated connections limit. If unspecified,the default value is250.

  5. ClickAdd service.

gcloud

Use thegcloud compute service-attachments create command.

gcloud compute service-attachments createATTACHMENT_NAME \    --region=ATTACHMENT_REGION \    --target-service=TARGET_SERVICE \    --connection-preference=ACCEPT_AUTOMATIC \    --nat-subnets=PSC_SUBNET_LIST \    [ --propagated-connection-limit=PROPAGATED_CONNECTION_LIMIT ] \    [ --enable-proxy-protocol ] \    [ --domain-names=DOMAIN_NAME ]

Replace the following:

  • ATTACHMENT_NAME: the name to assign to theservice attachment.

  • ATTACHMENT_REGION: the region for the newservice attachment. This must be the same region as the IP address ofthe target forwarding rule.

  • TARGET_SERVICE: the URI of the forwarding rulethat is associated with the service that you are publishing.

    • For Cross-region internal Application Load Balancers, use the followingformat:projects/PROJECT_ID/global/forwardingRules/RULE_NAME
    • For all other producer forwarding rules, use the following format:projects/PROJECT_ID/regions/RULE_REGION/forwardingRules/RULE_NAME

    Service Project Adminscan specify the forwarding rule of an internal load balancer that has anIP address from aShared VPC network.For more information, seeShared VPC.

  • PSC_SUBNET_LIST: a comma-separated list of one or moresubnet names to use with this service attachment.

    If you're creating a serviceattachment with a forwarding rule that has an IP address from aShared VPC network, use shared subnets from the sameShared VPC network. For each shared subnet, specify the fullresource URI—for example,--nat-subnets=projects/PROJECT_ID/regions/REGION/subnetworks/SUBNET.

  • PROPAGATED_CONNECTION_LIMIT: the per-projectpropagated connection limit. The default value is250.

  • DOMAIN_NAME: a DNS domain name for the service,including a trailing dot.Recommended format:REGION.p.DOMAIN.

    For more information, seeDNS configuration.

API

Send aPOST request to theserviceAttachments.insert method.

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

Replace the following:

  • PROJECT_ID: the project for the service attachment.

  • ATTACHMENT_REGION: the region for the newservice attachment. This must be the same region as the IP address ofthe target forwarding rule.

  • ATTACHMENT_NAME: the name to assign to theservice attachment.

  • TARGET_SERVICE: the URI of the forwarding ruleassociated with the service you are publishing.

    • For Cross-region internal Application Load Balancers, use the followingformat:projects/PROJECT_ID/global/forwardingRules/RULE_NAME
    • For all other producer forwarding rules, use the following format:projects/PROJECT_ID/regions/RULE_REGION/forwardingRules/RULE_NAME

    Service Project Adminscan specify the forwarding rule of an internal load balancer that has anIP address from aShared VPC network.For more information, seeShared VPC.

  • PSC_SUBNET_1_URI andPSC_SUBNET_2_URI:the subnet URIs to use for this service attachment. You can specify oneor more subnets by URI.

    If you're creating a serviceattachment with a forwarding rule that has an IP address from aShared VPC network, use shared subnets from the sameShared VPC network.

  • DOMAIN_NAME: a DNS domain name for the service,including a trailing dot.Recommended format:REGION.p.DOMAIN.

    For more information, seeDNS configuration.

  • PROPAGATED_CONNECTION_LIMIT: the per-projectpropagated connection limit. The default value is250.

Publish a service with explicit approval

Use these instructions to publish a service if you want to explicitly approveconsumers before they can connect to this service. If you want to approveconsumer connections automatically, seepublishing a service with automaticapproval.

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

Each service attachment has aconsumer accept list and a consumer reject list.The consumer lists determine which endpoints can connect to the service. Agiven service attachment can accept or reject consumers based on one of thefollowing types:

  • Project
  • VPC network
  • Private Service Connect endpoint (Preview)

Each entry in the consumer lists must be of the same type. For example, a givenservice attachment can't accept some consumers based on project and somebased on VPC network. Additionally, specifying consumers byfolder is not supported.

If you add a value to both the accept list and the reject list,connection requests from that consumer are rejected.

To accept users based on individual Private Service Connect endpoints,publish a service with explicit approval, but don't add any values to theconsumer lists. After a consumer connects to your service attachment, you canfind the endpoint's ID-based URI bydescribing the service attachmentor asking the consumer todescribe the endpoint.To accept the connection,add the Private Service Connect endpoint's ID-based URI to your service's consumer accept list.

If your consumer accept and reject lists refer to projects or individualendpoints, the propagated connection limit applies to consumer projects. If yourconsumer accept and reject lists refer to VPC networks, thepropagated connection limit applies to consumer VPC networks.

Permissions required for this task

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

Permissions

  • compute.subnetworks.use
  • compute.serviceAttachments.create

Roles

SeeRoles for role information.

Console

Configure the service

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

    Go to Private Service Connect

  2. Click thePublished services tab.

  3. ClickPublish service.

  4. In theTarget details section, selectLoad balancer.

  5. Select a load balancer type.

  6. Select the internal load balancer that hosts the service that youwant to publish. The network and region fields are populated with thedetails for the selected internal load balancer.

    Service Project Adminscan select an internal load balancer that has an IP address from aShared VPC network.For more information, seeShared VPC.

  7. If prompted, select the forwarding rule associated with the serviceyou want to publish.

  8. ForService name, enter a name for the service attachment.

Select a Private Service Connect subnet

Select one or more Private Service Connect subnets forthe service. The list is populated with subnets from the selectedinternal load balancer's VPC network, includingsubnets that are shared with a service project throughShared VPC.

If your service attachment uses an internal load balancer with an IPaddress from a Shared VPC network, you must select a sharedsubnet from the same Shared VPC network.

If you want to add a new subnet, you can create one:

  1. ClickSubnets, and then clickReserve new subnet.
  2. Enter a name and optional description for the subnet.
  3. Select a region for the subnet.
  4. Select an IP stack type.
  5. If you are creating an IPv4-only or dual-stack subnet,enter an IPv4 address range to use for the subnet.
  6. ClickAdd.

Configure consumer access

  1. If you want to view consumer connection information, selectUse Proxy Protocol.

  2. To configure your consumer accept and reject lists, do one of thefollowing.

    • To accept connections for selected projects, selectAccept connections for selected projects, and then:

      1. For each project that you want to accept connections from, clickAdd accepted project, and then enter the following:

        • The project ID or project number of the project that you want toaccept connections from.
        • A connection limit to specify the maximum numberof endpoints from the specified project that can connect.

      2. Optional: For each project that you want to explicitly rejectconnections from, clickAdd rejected project, and then enterthe project ID or project number.

    • To accept connections for selected networks, selectAccept connections for selected networks, and then:

      1. For each VPC network that you want to acceptconnections from, clickAdd accepted network, and then enterthe following:

        • The project ID or project number of the parent project of thenetwork that you want to accept connections from.
        • The name of the network that you want to accept connectionsfrom.
        • A connection limit to specify the maximum numberof endpoints from the specified network that can connect.

      2. Optional: For each network that you want to explicitly rejectconnections from, clickAdd rejected network, and then enterthe ID or project number of the network's parent project and thenetwork's name.

    • To accept connections for individualPrivate Service Connect endpoints, selectAccept connections for selected projects. Don't add any values tothe consumer accept list at this time. After a consumer requestsa connection to your service, you canadd the endpoint to your consumer accept list.

Complete the configuration

  1. Optional: If you want to disableconnection reconciliation,clear theEnable connection reconciliation checkbox.

  2. Optional: ClickAdvanced configuration, and then do the following:

    1. If you want to configure a domain name, enter a domain name,including a trailing dot.

      The recommended format for the domain name isREGION.p.DOMAIN.

      You must own the domain name. For more information, seeDNS configuration.

    2. Enter apropagated connections limit. If unspecified,the default value is250.

  3. ClickAdd service.

gcloud

Use thegcloud compute service-attachments create command.

gcloud compute service-attachments createATTACHMENT_NAME \    --region=ATTACHMENT_REGION \    --target-service=TARGET_SERVICE \    --connection-preference=ACCEPT_MANUAL \    --consumer-accept-list=ACCEPTED_PROJECT_OR_NETWORK_1=LIMIT_1,ACCEPTED_PROJECT_OR_NETWORK_2=LIMIT_2 \    --consumer-reject-list=REJECTED_PROJECT_OR_NETWORK_1,REJECTED_PROJECT_OR_NETWORK_2 \    --nat-subnets=PSC_SUBNET_LIST \    [ --propagated-connection-limit=PROPAGATED_CONNECTION_LIMIT ] \    [ --enable-proxy-protocol ] \    [ --domain-names=DOMAIN_NAME ] \    [ --reconcile-connections ]

Replace the following:

  • ATTACHMENT_NAME: the name to assign to theservice attachment.

  • ATTACHMENT_REGION: the region for the newservice attachment. This must be the same region as the IP address ofthe target forwarding rule.

  • TARGET_SERVICE: the URI of the forwarding rulethat is associated with the service that you are publishing.

    • For Cross-region internal Application Load Balancers, use the followingformat:projects/PROJECT_ID/global/forwardingRules/RULE_NAME
    • For all other producer forwarding rules, use the following format:projects/PROJECT_ID/regions/RULE_REGION/forwardingRules/RULE_NAME

    Service Project Adminscan specify the forwarding rule of an internal load balancer that has anIP address from aShared VPC network.For more information, seeShared VPC.

  • ACCEPTED_PROJECT_OR_NETWORK_1 andACCEPTED_PROJECT_OR_NETWORK_2: the project IDs, projectnames, or network URIs to accept.--consumer-accept-list is optional and can contain one or more projects ornetworks, but not a mix of both types.

  • LIMIT_1 andLIMIT_2: the connectionlimits for the projects or networks. The connection limit is the number ofconsumer endpoints or backends that can connect to thisservice. Each accepted project or network must have a connection limitconfigured.

  • REJECTED_PROJECT_OR_NETWORK_1 andREJECTED_PROJECT_OR_NETWORK_2: the project IDs, projectnames, or network URIs to reject.--consumer-reject-list is optional andcan contain one or more projects or networks, but not a mix of both types.

  • PSC_SUBNET_LIST: a comma-separated list of one or moresubnet names to use with this service attachment.

    If you're creating a serviceattachment with a forwarding rule that has an IP address from aShared VPC network, use shared subnets from the sameShared VPC network. For each shared subnet, specify the fullresource URI—for example,--nat-subnets=projects/PROJECT_ID/regions/REGION/subnetworks/SUBNET.

  • PROPAGATED_CONNECTION_LIMIT: thepropagated connection limit. The default value is250.

  • DOMAIN_NAME: a DNS domain name for the service,including a trailing dot.Recommended format:REGION.p.DOMAIN.

    For more information, seeDNS configuration.

API

Send aPOST request to theserviceAttachments.insert method.

  • To publish a service and explicitly approve consumers based on project,send the following request:

    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/ATTACHMENT_REGION/serviceAttachments{  "name": "ATTACHMENT_NAME",  "region": "ATTACHMENT_REGION",  "connectionPreference": "ACCEPT_MANUAL",  "targetService": "TARGET_SERVICE",  "enableProxyProtocol": false,  "natSubnets": [    "PSC_SUBNET_1_URI",    "PSC_SUBNET_2_URI"  ],  "consumerRejectLists": [    "REJECTED_PROJECT_1",    "REJECTED_PROJECT_2"  ],  "consumerAcceptLists": [    {      "projectIdOrNum": "ACCEPTED_PROJECT_1",      "connectionLimit": "LIMIT_1"    },    {      "projectIdOrNum": "ACCEPTED_PROJECT_2",      "connectionLimit": "LIMIT_2"    }  ],  "propagatedConnectionLimit": "PROPAGATED_CONNECTION_LIMIT",  "domainNames": [    "DOMAIN_NAME"  ]}

    Replace the following:

    • PROJECT_ID: the project for the service attachment.

    • ATTACHMENT_REGION: the region for the newservice attachment. This must be the same region as the IP address ofthe target forwarding rule.

    • ATTACHMENT_NAME: the name to assign to theservice attachment.

    • TARGET_SERVICE: the URI of the forwarding ruleassociated with the service you are publishing.

      • For Cross-region internal Application Load Balancers, use the followingformat:projects/PROJECT_ID/global/forwardingRules/RULE_NAME
      • For all other producer forwarding rules, use the following format:projects/PROJECT_ID/regions/RULE_REGION/forwardingRules/RULE_NAME

      Service Project Adminscan specify the forwarding rule of an internal load balancer that has anIP address from aShared VPC network.For more information, seeShared VPC.

    • PSC_SUBNET_1_URI andPSC_SUBNET_2_URI:the subnet URIs to use for this service attachment. You can specify oneor more subnets by URI.

      If you're creating a serviceattachment with a forwarding rule that has an IP address from aShared VPC network, use shared subnets from the sameShared VPC network.

    • REJECTED_PROJECT_1 andREJECTED_PROJECT_2: the project IDs or numbers ofprojects to reject.consumerRejectLists is optional and can containone or more projects.

    • ACCEPTED_PROJECT_1 andACCEPTED_PROJECT_2: the project IDs or numbers of theprojects to accept.consumerAcceptLists is optional and can containone or more projects.

    • LIMIT_1 andLIMIT_2: theconnection limits for the projects. The connection limit is the numberof consumer endpoints or backends that can connect to thisservice. 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, seeDNS configuration.

  • To publish a service and explicitly approve consumers based onVPC network, send the following request:

    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/ATTACHMENT_REGION/serviceAttachments{  "name": "ATTACHMENT_NAME",  "region": "ATTACHMENT_REGION",  "connectionPreference": "ACCEPT_MANUAL",  "targetService": "TARGET_SERVICE",  "enableProxyProtocol": false,  "natSubnets": [    "PSC_SUBNET_1_URI",    "PSC_SUBNET_2_URI"  ],  "consumerRejectLists": [    "projects/REJECTED_PROJECT_ID_1/global/networks/REJECTED_NETWORK_1",    "projects/REJECTED_PROJECT_ID_2/global/networks/REJECTED_NETWORK_2"  ],  "consumerAcceptLists": [    {      "networkUrl": "projects/ACCEPTED_PROJECT_ID_1/global/networks/ACCEPTED_NETWORK_1",      "connectionLimit": "LIMIT_1"    },    {      "networkUrl": "projects/ACCEPTED_PROJECT_ID_2/global/networks/ACCEPTED_NETWORK_2",      "connectionLimit": "LIMIT_2"    }  ],  "propagatedConnectionLimit":PROPAGATED_CONNECTION_LIMIT,  "domainNames": [    "DOMAIN_NAME"  ]}

    Replace the following:

    • REJECTED_PROJECT_ID_1 andREJECTED_PROJECT_ID_2: the IDs of the parent projectsof the networks that you want to reject.consumerRejectLists is optional and can contain one or more networks.
    • REJECTED_NETWORK_1 andREJECTED_NETWORK_2: the names of the networks that youwant to reject.
    • ACCEPTED_PROJECT_ID_1 andACCEPTED_PROJECT_ID_2: the IDs of the parent projectsof the networks that you want to accept.consumerAcceptLists is optional andcan contain one or more networks.
    • ACCEPTED_NETWORK_1 andACCEPTED_NETWORK_2: the names of the networks that youwant to accept.
    • LIMIT_1 andLIMIT_2: theconnection limits for the networks. The connection limit is the numberof consumer endpoints or backends that can connect to thisservice. 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, seeDNS configuration.

  • To publish a service with connection reconciliation enabled, send arequest that's similar to the previous requests, but include thefollowing field:

    {  ...  "reconcileConnections": true  ...}

View consumer connection information

For information about viewing consumer connection information by usingPROXY protocol, seeViewing consumer connection information.

Manage requests for access to a published service

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

You can also switch between automatic and explicit project acceptance for a publishedservice. For more information, seeChange 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,seeAdd 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 permissionsor one of the following IAM roles.

Permissions

  • compute.serviceAttachments.list

Roles

SeeRoles for role information.

Console

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

    Go to Private Service Connect

  2. Click thePublished services tab.

    The Private Service Connect service attachments aredisplayed.

gcloud

Use thegcloud compute service-attachments list command.

gcloud compute service-attachments list [--regions=REGION_LIST]

ReplaceREGION_LIST with a comma-separated list of one or moreregions that you want to view service attachments for. For example,us-central1 orus-west1,us-central1.

API

To view all service attachments in a given region or in all regions, sendaGET request to theserviceAttachments.list method.

  • 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 someconfiguration details in the Google Cloud console, for example, the serviceattachment URI that service consumers need to connect to your service. To viewall details, including thepscConnectionId and the ID-based endpoint URI(endpointWithId) values for the service attachment's consumers, use theGoogle Cloud CLI or send an API request.

Permissions required for this task

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

Permissions

  • compute.serviceAttachments.get

Roles

SeeRoles for role information.

Console

You can view details for a published service. TheService attachmentfield contains the service attachment URI.

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

    Go to Private Service Connect

  2. Click thePublished services tab.

  3. Click the service that you want to view.

gcloud

  • To view details for a published service, use thegcloud compute service-attachments describe command.TheselfLink field contains the service attachment URI.

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

    Replace the following:

    • ATTACHMENT_NAME: the name of the serviceattachment.

    • REGION: the region for the service attachment.

  • To view details for a published service, including the ID-based endpointURIs that you can use to accept individual endpoints, use thegcloud beta compute service-attachments describe command.For each endpoint in the list of connected endpoints, theendpointWithId field contains the endpoint's ID-based URI.

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

API

  • To view details for a published service, send aGET request to theserviceAttachments.get method.TheselfLink 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.

  • To view details for a published service, including the ID-based endpoint URIs that you can use to accept individual endpoints, send aGET request to the beta version of theserviceAttachments.get method. For each endpoint in the list of connected endpoints, theendpointWithId field contains the endpoint's ID-based URI.

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

Delete a published service

You can delete a published service, even if there are consumerconnections to the service attachment. Deleting the publishedservice removes the service attachment only. The associated load balancer is notdeleted. When you delete a published service, thefollowing applies:

Permissions required for this task

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

Permissions

  • compute.serviceAttachments.delete

Roles

SeeRoles for role information.

Console

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

    Go to Private Service Connect

  2. Click thePublished services tab.

  3. Click the service that you want to delete.

  4. ClickDelete.

gcloud

Use thegcloud compute service-attachments delete command.

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

API

Send aDELETE request to theserviceAttachments.delete method.

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

Health check failures with global access consumer endpoints

Consumers can connect aglobal accessendpoint to a published service that'snot configured for global access. However, health checks don't work correctlyin this configuration. As a result, traffic might be sent to unhealthy backendsand dropped.

If you publish a service by using an internal passthrough Network Load Balancer or internal protocolforwarding (target instance), and your service is affected by this issue, dothe following.

  • If you want to use global access, do the following:
    1. Enable global access for the load balancer's forwarding rule.
    2. If the load balancer is managed by Google Kubernetes Engine, you must also updatethe corresponding Service manifest and apply it to your cluster. For moreinformation about this GKE-specific configuration, seeGlobal access.
    3. Update any automation so that new producer load balancers thatsupport global access Private Service Connect endpoints areconfigured for global access.
  • If you don't want to use global access, ask the consumer todisable global access for the endpoint.

Turning on global access for a published service doesn't interrupt networktraffic.

Health check failures with global access Private Service Connect NEGs

There is a known issue with consumer Private Service Connect NEGsthat are configured for global access. A Private Service Connect NEGis configured for global access if it's associated with aglobal backend service.

If a consumer connects a Private Service Connect NEG that is configuredfor global access to a producer load balancer, and the service producer disablesglobal access for that load balancer, health checks don't work correctly. As aresult, traffic might be sent to unhealthy backends and dropped.

If you publish a service by using an internal load balancer that supportsglobal access, and your service is affected by this issue, do the following.

  • If you want to use global access, do the following:
    1. Enable global accessfor the load balancer's forwarding rule.
    2. If the load balancer is managed by Google Kubernetes Engine, you must alsoupdate the corresponding Service manifest and apply it to your cluster.For more information about this GKE-specificconfiguration, seeGlobal access.
    3. Update any automation so that new producer load balancers thatsupport global access Private Service Connect NEGs areconfigured for global access.
  • If you don't want to use global access, ask the consumer to reconfigurethe Private Service Connect NEG for regional access. To do this,the consumer mustremove their Private Service Connect NEG from the global backend serviceand thenattach the NEG to a regional backend service.

Turning on global access for a published service doesn't interrupt networktraffic.

Disconnections after upgrading the Google provider for Terraform

If you've used the Google provider for Terraform with versions earlier than4.76.0 to create service attachments, don't upgrade to versions 4.76.0 through4.81.x. When you runterraform apply after upgrading to versions 4.76.0through 4.81.x, Terraform might unintentionally delete and recreate the serviceattachments and close existing Private Service Connectconnections. Recreated service attachments don't automatically re-establishPrivate Service Connect connections.

If you upgrade to version 4.82.0 and then runterraform apply, your serviceattachments are not deleted, but thereconcileconnectionssetting is set to true. If the setting was previously set to false, somePrivate Service Connect connections might close.

Workaround

We recommend that you upgrade theGoogle provider for Terraform to version4.82.0 orlater.This version prevents the unintentional deletion and recreation of serviceattachments.

If you can't upgrade immediately, or if you can upgrade but you also want toprevent Terraform from changing the connection reconciliation setting, updateyour Terraform configuration to explicitly set the connection reconciliationsetting.

  1. View the detailed configuration for the service attachment, and note thereconcileConnections setting.

    gcloud compute service-attachments describeSERVICE_NAME --region=REGION

    The output includes thereconcileConnections field, which can be true orfalse.

    reconcileConnections: false

  2. Update your Terraform configuration file to explicitly use the same settingthat is used on the service attachment.

    resource "google_compute_service_attachment" "SERVICE_NAME" {  ...  reconcile_connections    = false}

    For an example configuration, seeService AttachmentReconcileConnections on GitHub.

TLS errors with PROXY protocol

If you publish a service with PROXY protocol enabled, but your target servicetype doesn't support PROXY protocol, consumers can connect to your service withendpoints. However, traffic doesn't flow through the connection, and workloadsreceive errors related to TLS.

To resolve this issue, update the service attachment to disable PROXYprotocol.

For information about the types of target services that support PROXY protocol,seeFeatures and compatibility.

Troubleshooting

Error when updating a service attachment

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

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

  1. Use thegcloud compute service-attachments describe command to show theconfiguration of the service attachment that you want to modify.

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

      gcloud compute service-attachments describeATTACHMENT_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 theservice attachment, do the following:

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

      The reject list output looks similar to the following:

      PROJECT_1,PROJECT_2,PROJECT_3

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

  3. Update the service attachment to remove the deleted projects.

    • To update the accept list, do the following:

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

    • To update the reject list, do the following:

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

Connectivity is not established

If a consumer has created an endpoint or backend that refers to your serviceattachment but connectivity is not established, check the service attachment'sconnection status.The connection status might indicate steps that you can take to resolve theissue.

Consumer connections time out

If consumer connections time out, check if your service requires long-runningconnections. The TCP Established Connection Idle Timeout forPrivate Service Connect NAT is 20 minutes. If your service needsa longer timeout, you might need to make some configuration changes to helpensure that the connections don't time out. For more information, seeNAT specifications.

Propagated connection errors

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

Published service has performance issues or connection timeouts

If your published service has performance issues or intermittent connectiontimeouts, it might be due to dropped packets. You can investigate droppedpackets by checking the metrics that are described in the following sections.

Dropped packets from consumers

Theprivate_service_connect/producer/dropped_received_packets_count metric tracks packets from an endpoint orbackend to a published service that are dropped because the endpoint or backendexceeded itsmaximum connections tothe service.

If a published service reports values for this metric, consider the followingsolutions:

  • Increase the capacity of your published service—for example, by addingmore virtual machine (VM) instances or network endpoints.
  • Ask the service consumer to create additional endpoints or backends thatconnect to the published service.
  • Ask the service consumer to reduce the number of connections through theirendpoint or backend.

Dropped packets to consumers

Theprivate_service_connect/producer/dropped_sent_packets_count metrictracks packets sent from a published service to an endpoint or backend that aredropped because Private Service Connect can't find a matchingconnection for response packets.

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

This might happen if a published service sends response packets after aconnection has timed out. For information about avoiding issues withconnections timing out, seeNAT specifications.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-18 UTC.