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 by using internal IP addresses in the consumer VPC networks.

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

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.

Before you begin

Create a supported load balancer

To host the service, create one of the following load balancers in a service producer VPC network:

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

You can associate each service attachment with the forwarding rule of a single load balancer. You can't associate multiple service attachments with the same forwarding rule.

The IP version of your load balancer's forwarding rule (IPv4 or IPv6) affects which consumers can connect to your published service. IPv6 forwarding rules are available in Preview. For more information, see IP version translation.

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

You can also publish a service that is hosted on an internal passthrough Network Load Balancer on Google Kubernetes Engine. This configuration, including load balancer and service attachment configuration, is described in Create an internal passthrough Network 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.

If you want to publish a service that serves IPv6 traffic (Preview), you must use dual-stack subnets.

Console

  1. In the Google Cloud console, 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 Subnets.

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

    1. Provide a Name.
    2. Select a Region.
    3. In the Purpose section, select Private Service Connect.
    4. Select an IP stack type.
    5. Enter an IPv4 range. For example, 10.10.10.0/24.
    6. Click Add.

gcloud 

gcloud compute networks subnets create SUBNET_NAME \
    --network=NETWORK_NAME \
    --region=REGION \
    --stack-type=STACK_TYPE \
    --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.

  • STACK_TYPE: the stack type of the subnet, which can be either IPV4_ONLY or IPV4_IPV6. The default is IPV4_ONLY.

  • SUBNET_RANGE: the IPv4 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",
  "stackType": "STACK_TYPE"
}

Replace the following:

  • PROJECT_ID: the project for the subnet.

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

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

  • SUBNET_NAME: the name to assign to the subnet.

  • NETWORK_NAME: the name of the VPC network for the new subnet.

  • STACK_TYPE: the stack type of the subnet, which can be IPV4_ONLY or IPV4_IPV6.

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 Application Load Balancer)
  • 130.211.0.0/22
  • 35.191.0.0/16
 Global external Application 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.

The following 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_LIST

Replace the following:

  • NAME: the name of the firewall rule.

  • 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_LIST

Replace the following:

  • NAME: the name of the firewall rule.

  • 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. To configure hierarchical firewall rules to allow this traffic, see Hierarchical firewall policies.

Publish a service

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

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 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 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 Consumer connection information.

You can associate single-stack and dual-stack subnets with the same service attachment. If your load balancer is configured for IPv6 traffic (Preview), you must use dual-stack subnets.

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 Load balancer type for the service that you want to publish:

    • Internal passthrough Network Load Balancer
    • Regional internal proxy Network Load Balancer
    • Regional internal Application Load Balancer

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

    Service Project Admins can select an internal load balancer that has an IP address from a Shared VPC network. For more information, see Shared VPC.

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

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

  8. Select one or more Private Service Connect Subnets for the service. The list is populated with subnets from the selected internal load balancer's VPC network, including subnets that are shared with a service project through Shared VPC.

    If your service attachment uses an internal load balancer with an IP address from a Shared VPC network, you must select a shared subnet from the same Shared VPC network.

    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. Select an IP stack type.
    5. Enter the IPv4 range to use for the subnet and click Add.

  9. If you want to view consumer connection information, select Use Proxy Protocol.

  10. Select Automatically accept all connections.

  11. If you want to disable connection reconciliation, clear the Enable connection reconciliation checkbox.

  12. If you want to configure a domain name, do the following:

    1. Click Advanced configuration.

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

  13. 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 that is associated with the service that you are publishing.

    Service Project Admins can specify the forwarding rule of an internal load balancer that has an IP address from a Shared VPC network. For more information, see Shared VPC.

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

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

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

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

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

    Service Project Admins can specify the forwarding rule of an internal load balancer that has an IP address from a Shared VPC network. For more information, see Shared VPC.

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

    If you're creating a service attachment with a forwarding rule that has an IP address from a Shared VPC network, use shared subnets from the same Shared VPC network.

  • 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 approval

Use these instructions to publish a service if you want to explicitly approve consumers before they can connect to this service. If you want to approve consumer connections automatically, see publishing a service with automatic approval.

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

Each service attachment has a consumer accept list and a consumer reject list, which are used to determine which endpoints can connect to the service. A given service attachment can use either projects or networks in these lists, but not both. Specifying consumers by folder is not supported.

If you change from accepting consumers based on project to accepting consumers based on network, or the other way around, do the following:

  • Replace all of the approved projects or networks in a single operation.
  • If you need to provide the same access as before, make sure that the new accept and reject lists are equivalent to the previous ones.

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

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 Load balancer type for the service that you want to publish:

    • Internal passthrough Network Load Balancer
    • Regional internal proxy Network Load Balancer
    • Regional internal Application Load Balancer

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

    Service Project Admins can select an internal load balancer that has an IP address from a Shared VPC network. For more information, see Shared VPC.

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

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

  8. Select one or more Private Service Connect Subnets for the service. The list is populated with subnets from the selected internal load balancer's VPC network, including subnets that are shared with a service project through Shared VPC.

    If your service attachment uses an internal load balancer with an IP address from a Shared VPC network, you must select a shared subnet from the same Shared VPC network.

    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. Select an IP stack type.
    5. Enter the IPv4 range to use for the subnet and click Add.

  9. If you want to view consumer connection information, select Use Proxy Protocol.

  10. If you want to accept connections for selected projects, select Accept connections for selected projects.

    1. For each project that you want to accept connections from, do the following:
      1. Click Add accepted project, and then enter the following:
        • The project ID or project number of the project that you want to accept connections from.
        • A Connection limit to specify the maximum number of endpoints from the specified project that can connect.
    2. Optional: For each project that you want to explicitly reject connections from, click Add rejected project, and then enter the project ID or project number.

  11. If you want to accept connections for selected networks, select Accept connections for selected networks.

    1. For each network that you want to accept connections from, do the following:
      1. Click Add accepted network, and then enter the following:
        • The project ID or project number of the parent project of the network that you want to accept connections from.
        • The name of the network that you want to accept connections from.
        • A Connection limit to specify the maximum number of endpoints from the specified network that can connect.
    2. Optional: For each network that you want to explicitly reject connections from, click Add rejected network, and then enter the ID or project number of the network's parent project and the network's name.

  12. If you want to disable connection reconciliation, clear the Enable connection reconciliation checkbox.

  13. If you want to configure a domain name, do the following:

    1. Click Advanced configuration.

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

  14. 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_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 \
    [--enable-proxy-protocol ] \
    [--domain-names=DOMAIN_NAME] \
    [--reconcile-connections]

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 that is associated with the service that you are publishing.

    Service Project Admins can specify the forwarding rule of an internal load balancer that has an IP address from a Shared VPC network. For more information, see Shared VPC.

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

  • LIMIT_1 and LIMIT_2: the connection limits for the projects or networks. The connection limit is the number of consumer endpoints or backends that can connect to this service. Each accepted project or network must have a connection limit configured.

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

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

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

  • 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

  • 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/REGION/serviceAttachments
{
  "name": "ATTACHMENT_NAME",
  "region": "REGION",
  "connectionPreference": "ACCEPT_MANUAL",
  "targetService": "RULE_URI",
  "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"
    }
  ],
  "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.

      Service Project Admins can specify the forwarding rule of an internal load balancer that has an IP address from a Shared VPC network. For more information, see Shared VPC.

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

      If you're creating a service attachment with a forwarding rule that has an IP address from a Shared VPC network, use shared subnets from the same Shared VPC network.

    • REJECTED_PROJECT_1 and REJECTED_PROJECT_2: the project IDs or numbers of projects to reject. consumerRejectLists is optional and can contain one or more projects.

    • ACCEPTED_PROJECT_1 and ACCEPTED_PROJECT_2: the project IDs or numbers of the projects to accept. consumerAcceptLists 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.

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

    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"
  ],
  "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"
    }
  ],
  "domainNames": [
    "DOMAIN_NAME"
  ]
}

    Replace the following:

    • REJECTED_PROJECT_ID_1 and REJECTED_PROJECT_ID_2: the IDs of the parent projects of the networks that you want to reject. consumerRejectLists is optional and can contain one or more networks.
    • REJECTED_NETWORK_1 and REJECTED_NETWORK_2: the names of the networks that you want to reject.
    • ACCEPTED_PROJECT_ID_1 and ACCEPTED_PROJECT_ID_2: the IDs of the parent projects of the networks that you want to accept. consumerAcceptLists is optional and can contain one or more networks.
    • ACCEPTED_NETWORK_1 and ACCEPTED_NETWORK_2: the names of the networks that you want to accept.
    • LIMIT_1 and LIMIT_2: the connection limits for the networks. 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.

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

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

View consumer connection information

For information about viewing consumer connection information by using PROXY protocol, see Viewing 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, 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.

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

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

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 that you want to delete.

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

Disconnections after upgrading the Google provider for Terraform

If you've used the Google provider for Terraform with versions earlier than 4.76.0 to create service attachments, do not upgrade to versions 4.76.0 through 4.81.x. When you run terraform apply after upgrading to versions 4.76.0 through 4.81.x, Terraform might unintentionally delete and recreate the service attachments and close existing Private Service Connect connections. Recreated service attachments do not automatically re-establish Private Service Connect connections.

If you upgrade to version 4.82.0 and then run terraform apply, your service attachments are not deleted, but the reconcile connections setting is set to true. If the setting was previously set to false, some Private Service Connect connections might close.

  • Upgrading to Google provider versions 4.76.0 through 4.81.x. In this scenario, the output of terraform plan includes the following:

    -/+ resource "google_compute_service_attachment" "SERVICE_NAME" {
  ...
        ~ reconcile_connections = false -> true # forces replacement
  ...

    Use the workaround to prevent this issue.

  • Upgrading to Google provider versions 4.82.0. In this scenario, the output of terraform plan includes the following:

    ~ reconcile_connections = false -> true

    If you ignore this warning and apply the changes, Terraform updates the service attachment to turn on connection reconciliation. Depending on their connection status, changing from false to true might close some existing connections. For more information, see Connection reconciliation.

    Use the workaround to prevent this issue.

Workaround

We recommend that you upgrade the Google provider for Terraform to version 4.82.0 or later. This version prevents the unintentional deletion and recreation of service attachments.

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

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

    $ gcloud compute service-attachments describe SERVICE_NAME --region=REGION

    The output includes the reconcileConnections field, which can be true or false.

    reconcileConnections: false

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

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

    For an example configuration, see Service Attachment Reconcile Connections on GitHub.

Patch updates for service attachments

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.

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

  2. Edit the command output to remove any deleted projects from the accept list and 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 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

Connectivity is not established

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

Consumer connections time out

If consumer connections time out, check if your service requires long-running connections. The TCP Established Connection Idle Timeout for Private Service Connect NAT is 20 minutes. If your service needs a longer timeout, you might need to make some configuration changes to help ensure that the connections don't time out. For more information, see NAT specifications.