Create and manage Private Service Connect interfaces

This page describes how producer network administrators can create and manage Private Service Connect interfaces. Private Service Connect interfaces let service producer Virtual Private Cloud (VPC) networks initiate connections to consumer VPC networks.

Before you begin

You must enable the Compute Engine API in your project.
Find the URL of the network attachment that you want to connect to.
If the network attachment is configured to manually accept connections, ensure that a network administrator has added your project to the network attachment's accept list.

Roles

To get the permissions that you need to create Private Service Connect interfaces, ask your administrator to grant you the following IAM roles on your project:

Compute Instance Admin (v1) (roles/compute.instanceAdmin.v1)
Compute Network Admin (roles/compute.networkAdmin)

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

The Compute Instance Admin (v1) role contains the compute.instances.pscInterfaceCreate permission, which is required to create Private Service Connect interfaces.

Create and configure a Private Service Connect interface

To create and configure a virtual machine (VM) instance that has a Private Service Connect interface, complete the following steps.

Create a VM with a Private Service Connect interface

When you create a Private Service Connect interface, you create a VM that has at least two network interfaces. The first interface connects to a producer subnet. The second interface is a Private Service Connect interface that requests a connection to a network attachment in a consumer network.

If the connection is accepted, Google Cloud assigns to the Private Service Connect interface an internal IP address from the subnet that is specified by the network attachment.

If you create a Private Service Connect interface that refers to a network attachment that's configured to manually accept connections and the interface's project is not in the network attachment's accept list, creation of the Private Service Connect interface's VM fails. In this case, work with the consumer organization to add your project to the accept list, and then create a Private Service Connect interface.

When you create a Private Service Connect interface, you can optionally assign to it one or more internal alias IP ranges. If you plan to assign alias IP ranges, contact the consumer organization to determine the appropriate IP address ranges.

To assign an alias IP range, specify the prefix length of the range in CIDR notation. When you assign one or more alias IP ranges to a Private Service Connect interface, Google Cloud allocates the alias IP ranges from the primary IP address range of the subnet that's associated with the network attachment. The Private Service Connect interface's primary IP address is allocated from outside of any alias IP ranges. If there aren't enough IP addresses in the network attachment's subnet to allocate the primary IP address and alias IP ranges, creation of the Private Service Connect interface's VM fails. You can find the specific IP addresses that are assigned by describing the interface's VM.

Console

In the Google Cloud console, go to the VM instances page.

Go to VM instances
Click Create instance.
Enter a Name.
Select a Region that matches the region of the network attachment that you want to connect to.
Select a Zone.
Click Advanced options.
Click Networking.
In the Network interfaces section, click the first network interface, which is the primary network interface, and then do the following:
1. Select a Network for the primary network interface.
2. Select a Subnet for the primary network interface. This subnet must be in the same region as the Private Service Connect interface's network attachment.
Click Add a network interface.
For Interface type, select Private Service Connect.
Enter a Network attachment URL.
Select an IP stack type. To create a dual-stack Private Service Connect interface, the network attachment's subnet must be dual stack.
Optional: To add an alias IP range, in the Prefix length box, enter the prefix length—for example, /30. You can add multiple alias IP ranges by clicking Add IP range, and then entering the prefix length for each additional alias IP range that you want to add.
Click Done.
Click Create.

gcloud

To create a VM with an IPv4-only Private Service Connect interface, use the instances create command.

gcloud compute instances create INSTANCE_NAME \
    --zone=ZONE \
    --machine-type=MACHINE_TYPE \
    --image-project=IMAGE_PROJECT \
    --image=IMAGE \
    --network-interface='network=PRODUCER_NETWORK,subnet=PRODUCER_SUBNET,no-address' \
    --network-interface='network-attachment=projects/CONSUMER_PROJECT_ID/regions/REGION/networkAttachments/ATTACHMENT_NAME'

Replace the following:

INSTANCE_NAME: the name of the new instance
ZONE: the zone of the new instance
MACHINE_TYPE: the instance's machine type, which can be predefined or custom.
IMAGE_PROJECT: the project of the image. For example, if you specify debian-10-buster-v20230809 as the image, specify debian-cloud as the image project. You can view a list of available images, image projects, and image families by using the gcloud compute images list command.
IMAGE: a specific version of a public image—for example, debian-10-buster-v20230809.
PRODUCER_NETWORK: the instance's network.
PRODUCER_SUBNET: the subnet of the VM's primary network interface. This subnet must be in the same region as the Private Service Connect interface's network attachment.
CONSUMER_PROJECT_ID: the ID of the consumer that you want to connect to.
ATTACHMENT_NAME: the name of the network attachment to request a connection to.

To assign the Private Service Connect interface both an IPv4 and an IPv6 address, specify stack-type='IPV4_IPv6'. The network attachment that the interface refers to must be associated with a dual-stack subnet.

gcloud compute instances create INSTANCE_NAME \
    --zone=ZONE \
    --machine-type=MACHINE_TYPE \
    --image-project=IMAGE_PROJECT \
    --image=IMAGE \
    --network-interface='network=PRODUCER_NETWORK,subnet=PRODUCER_SUBNET,no-address' \
    --network-interface='network-attachment=projects/CONSUMER_PROJECT_ID/regions/REGION/networkAttachments/ATTACHMENT_NAME,stack-type='IPV4_IPV6''

To assign the Private Service Connect interface one or more alias IP ranges, specify the prefix length of each alias IP range that you want to assign:

gcloud compute instances create INSTANCE_NAME \
    --zone=ZONE \
    --machine-type=MACHINE_TYPE \
    --image-project=IMAGE_PROJECT \
    --image=IMAGE \
    --network-interface='network=PRODUCER_NETWORK,subnet=PRODUCER_SUBNET,no-address' \
    --network-interface='network-attachment=projects/CONSUMER_PROJECT_ID/regions/REGION/networkAttachments/ATTACHMENT_NAME,aliases=ALIAS_IP_RANGE'

Replace ALIAS_IP_RANGE with one or more prefix lengths in CIDR notation. You can include multiple prefix lengths in a semicolon-separated list—for example, /24;/28.

API

To create a VM with an IPv4-only Private Service Connect interface, send a POST request to the instances.insert method.

POST https://compute.googleapis.com/compute/v1/projects/PRODUCER_PROJECT_ID/zones/INSTANCE_ZONE/instances
{
  "machineType": "zones/MACHINE_TYPE_ZONE/machineTypes/MACHINE_TYPE",
  "name": "VM_NAME",
  "disks": [
    {
      "initializeParams": {
        "sourceImage": "projects/IMAGE_PROJECT/global/images/IMAGE"
      },
      "boot": true
    }
  ],
  "networkInterfaces": [
    {
      "network": "https://compute.googleapis.com/compute/v1/projects/PRODUCER_PROJECT_ID/global/networks/PRODUCER_NETWORK",
      "subnetwork": "https://compute.googleapis.com/compute/v1/projects/PRODUCER_PROJECT_ID/regions/SUBNET_REGION/subnetworks/SUBNET"
    },
    {
      "networkAttachment": "projects/CONSUMER_PROJECT_ID/regions/ATTACHMENT_REGION/networkAttachments/ATTACHMENT_NAME"
    }
  ]
}

Replace the following:

PRODUCER_PROJECT_ID: the ID of the producer project.
INSTANCE_ZONE: the zone of the new instance.
MACHINE_TYPE_ZONE: the zone of the machine type.
MACHINE_TYPE: the machine type of the new VM, which can be predefined or custom.
VM_NAME: the name of the new VM.
IMAGE_PROJECT: the project containing the image. For example, if you specify debian-10-buster-v20200309 as the image, specify debian-cloud as the image project.
IMAGE: a specific version of a public image—for example, debian-10-buster-v20200309.
PRODUCER_PROJECT_ID: the project ID of the interface's project.
PRODUCER_NETWORK: the name of the producer VPC network.
SUBNET_REGION: the region of the primary network interface's subnet. This subnet must be in the same region as the Private Service Connect interface's network attachment.
SUBNET: the name of the primary network interface's subnet.
CONSUMER_PROJECT_ID: the ID of the consumer project.
ATTACHMENT_REGION: the network attachment's region.
ATTACHMENT_NAME: the network attachment's name.

To assign the Private Service Connect interface both an IPv4 and an IPv6 address, specify "stack-type": "IPV4_IPv6". The network attachment that the interface refers to must be associated with a dual-stack subnet.

POST https://compute.googleapis.com/compute/v1/projects/PRODUCER_PROJECT_ID/zones/INSTANCE_ZONE/instances
{
  "machineType": "zones/MACHINE_TYPE_ZONE/machineTypes/MACHINE_TYPE",
  "name": "VM_NAME",
  "disks": [
    {
      "initializeParams": {
        "sourceImage": "projects/IMAGE_PROJECT/global/images/IMAGE"
      },
      "boot": true
    }
  ],
  "networkInterfaces": [
    {
      "network": "https://compute.googleapis.com/compute/v1/projects/PRODUCER_PROJECT_ID/global/networks/PRODUCER_NETWORK",
      "subnetwork": "https://compute.googleapis.com/compute/v1/projects/PRODUCER_PROJECT_ID/regions/SUBNET_REGION/subnetworks/SUBNET"
    },
    {
      "networkAttachment": "projects/CONSUMER_PROJECT_ID/regions/ATTACHMENT_REGION/networkAttachments/ATTACHMENT_NAME",
      "stackType": "IPV4_IPV6"
    }
  ]
}

To assign the Private Service Connect interface one or more alias IP ranges, specify the prefix length of each alias IP range that you want to assign.

POST https://compute.googleapis.com/compute/v1/projects/PRODUCER_PROJECT_ID/zones/INSTANCE_ZONE/instances
{
  "machineType": "zones/MACHINE_TYPE_ZONE/machineTypes/MACHINE_TYPE",
  "name": "VM_NAME",
  "disks": [
    {
      "initializeParams": {
        "sourceImage": "projects/IMAGE_PROJECT/global/images/IMAGE"
      },
      "boot": true
    }
  ],
  "networkInterfaces": [
    {
      "network": "https://compute.googleapis.com/compute/v1/projects/PRODUCER_PROJECT_ID/global/networks/PRODUCER_NETWORK",
      "subnetwork": "https://compute.googleapis.com/compute/v1/projects/PRODUCER_PROJECT_ID/regions/SUBNET_REGION/subnetworks/SUBNET"
    },
    {
      "aliasIpRanges": [
        {
          "ipCidrRange": "ALIAS_IP_RANGE"
        }
      ],
      "networkAttachment": "projects/CONSUMER_PROJECT_ID/regions/ATTACHMENT_REGION/networkAttachments/ATTACHMENT_NAME"
    }
  ]
}

Replace ALIAS_IP_RANGE with a prefix length in CIDR notation—for example, /28. You can specify multiple alias IP ranges in the aliasIpRanges list in the following form:

"aliasIpRanges": [
  {
    "ipCidrRange": "/28"
  },
  {
    "ipCidrRange": "/30"
  }
]

For more information about creating VM instances, see Create and start a VM instance.

Allow SSH connectivity

Ensure that firewall rules are configured to allow ingress SSH connections to your Private Service Connect interface's VM.

Find the Google Cloud name of your Private Service Connect interface

To configure routing, you need to know the Google Cloud name of your Private Service Connect interface.

Console

In the Google Cloud console, go to VM instances:

Go to VM instances
Click the name of the VM that has your Private Service Connect interface.
In the Network interfaces section, find and note the name of your Private Service Connect interface—for example, nic1.

gcloud

Use the compute instances describe command.
```
gcloud compute instances describe VM_NAME
  --zone=ZONE
```
Replace the following:
- VM_NAME: the name of the VM to that has your Private Service Connect interface.
- ZONE: the VM's zone.
In the command's output, find and note the Google Cloud name of your Private Service Connect interface—for example, nic1.

Find the guest OS name of your Private Service Connect interface

To configure routing, you need to know the guest OS name of your Private Service Connect interface, which is different than the interface's name in Google Cloud.

To find the interface's name on a Debian VM, do the following. For VMs with other operating systems, consult the public documentation of the operating system.

Connect to your Private Service Connect interface's VM.
Run the following command:
```
ip address
```
In the list of network interfaces, find and note the interface name that is associated with your Private Service Connect interface's IP address—for example, ens5.

Find the gateway IP of your Private Service Connect interface

To configure routing, you need to know the IP address of your Private Service Connect interface's default gateway.

Connect to your Private Service Connect interface's VM.
Send the following GET request from your interface's VM to the associated metadata server:
```
curl http://metadata.google.internal/computeMetadata/v1/instance/network-interfaces/INTERFACE_NUMBER/gateway -H "Metadata-Flavor: Google" && echo
```
Replace INTERFACE_NUMBER with the numeric part of the Google Cloud name for your Private Service Connect interface. For example, if your interface's name is nic1, use a value of 1.

Add routes for consumer subnets

You must add a route to your Private Service Connect interface's default gateway for each consumer subnet that connects to your Private Service Connect interface. This ensures that traffic that is bound for the consumer network egresses from the Private Service Connect interface.

The following steps describe how to temporarily update the routing table for a VM that uses the Debian operating system. To update the table permanently, or to update the route on a different operating system, consult the operating system's public documentation.

Connect to your Private Service Connect interface's VM.
Run the following command for each consumer subnet that connects to your Private Service Connect interface:
```
sudo ip route add CONSUMER_SUBNET_RANGE via GATEWAY_IP dev OS_INTERFACE_NAME
```
Replace the following:
- CONSUMER_SUBNET_RANGE: the IP address range of your consumer subnet.
- GATEWAY_IP: the IP address of the default gateway for your interface's subnet.
- OS_INTERFACE_NAME: the guest OS name for your Private Service Connect interface—for example, ens5.

Create an instance template with a Private Service Connect interface

You can create instance templates that include Private Service Connect interfaces.

Console

Go to the Instance templates page.

Go to Instance templates
Click Create instance template.
Enter a Name for the instance template.
Click Advanced options.
Click Networking.
In the Network interfaces section, click the expander arrow.
Select a Network and Subnetwork for the instance template's primary network interface.
Click Done.
Click Add a network interface.
Click Private Service Connect.
Select a Network and Subnetwork for your Private Service Connect interface.
Click Done.
Click Create.

gcloud

Use the instance-templates create command.

gcloud compute instance-templates create NAME \
    --machine-type=MACHINE_TYPE \
    --network-interface=subnet=SUBNET \
    --region=REGION \
    --image-project=IMAGE_PROJECT \
    --image=IMAGE \
    --network-interface=network-attachment=projects/ATTACHMENT_PROJECT_ID/regions/ATTACHMENT_REGION/networkAttachments/ATTACHMENT_NAME

Replace the following:

NAME: the name of the instance template.
MACHINE_TYPE: the predefined or custom machine type for VMs that are created by using this instance template—for example, f1-micro.
SUBNET: the subnet of the instance template. When you create a VM by using this instance template, the VM's primary network interface is assigned an internal IP address from this subnet.
REGION: the region of the instance template's subnet.
IMAGE_PROJECT: the project of the image. For example, if you specify debian-10-buster-v20230809 as the image, specify debian-cloud as the image project. You can view a list of available images, image projects, and image families by using the gcloud compute images list command.
IMAGE: a specific version of a public image—for example, debian-10-buster-v20230809.
ATTACHMENT_PROJECT_ID: the ID of the network attachment's project.
ATTACHMENT_REGION: the region of the network attachment.
ATTACHMENT_NAME: the name of the network attachment. When you create a VM by using this instance template, the Private Service Connect interface requests a connection to this network attachment.

You can specify additional configuration, such as image name and boot disk size. For more information, see Create a new instance template.

API

Make a POST request to the instanceTemplates.insert method.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/instanceTemplates
{
  "name": "NAME",
  "properties": {
    "disks": [
      {
        "boot": true,
        "initializeParams": {
          "sourceImage": "projects/IMAGE_PROJECT/global/images/IMAGE"
        }
      }
    ],
    "machineType": "MACHINE_TYPE",
    "networkInterfaces": [
      {
        "subnetwork": "https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/SUBNET_REGION/subnetworks/SUBNET"
      },
      {
        "networkAttachment": "projects/ATTACHMENT_PROJECT_ID/regions/ATTACHMENT_REGION/networkAttachments/NETWORK_ATTACHMENT"
      }
    ]
  }
}

Replace the following:

PROJECT_ID: the ID of the project to create the instance template in.
NAME: the name of the instance template.
IMAGE_PROJECT: the project of the image. For example, if you specify debian-10-buster-v20230809 as the image, specify debian-cloud as the image project. You can view a list of available images and image projects by using the gcloud compute images list command.
IMAGE: a specific version of a public image—for example, debian-10-buster-v20230809.
MACHINE_TYPE: the predefined or custom machine type for VMs that are created by using this instance template—for example, f1-micro.
SUBNET_REGION: the region of the instance template's subnet.
SUBNET: the subnet of the instance template. When you create a VM by using this instance template, the VM's primary network interface is assigned an internal IP address from this subnet.
ATTACHMENT_PROJECT_ID: the ID of the network attachment's project.
ATTACHMENT_REGION: the region of the network attachment.
NETWORK_ATTACHMENT: the name of the network attachment. When you create a VM by using this instance template, the Private Service Connect interface requests a connection to this network attachment.

For more information about creating instance templates, see Create instance templates.

Use a Private Service Connect interface with VPC Service Controls

You can use Private Service Connect interfaces with VPC Service Controls. This lets a producer VPC network access Google APIs and services through a consumer VPC network, while the consumer organization can apply the security benefits of VPC Service Controls.

To use a Private Service Connect interface with VPC Service Controls, you must update the routing table of the Private Service Connect interface's VM. Replace the default route with a route that sends traffic through the Private Service Connect interface to the Private Service Connect interface's default gateway.

The following steps temporarily update the routing table for VMs that use Debian. To add the route permanently, or to update the route for a different operating system, consult the operating system's public documentation.

Console

In the Google Cloud console, go to the VM instances page:

Go to VM instances
Click the name of the VM that has your Private Service Connect interface.
Run the following command:
```
sudo ip route replace default via GATEWAY_IP dev OS_INTERFACE_NAME
```
Replace the following:
- GATEWAY_IP: the IP address of the default gateway for your interface's subnet.
- OS_INTERFACE_NAME: the guest OS name for your Private Service Connect interface—for example, ens5.

Describe a Private Service Connect interface

You can describe a VM to view the details of its Private Service Connect interface. The interface's IP address, alias IP ranges, network attachment, and consumer subnet are listed in the network interfaces section of the VM's description.

Console

In the Google Cloud console, go to the VM instances page.

Go to VM instances
Click the VM that has your Private Service Connect interface.
In the Network interfaces section, view the details of your Private Service Connect interface.

gcloud

gcloud compute instances describe VM_NAME
    --zone=ZONE

Replace the following:

VM_NAME: the name of your interface's VM.
ZONE: your VM's zone.

API

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME

Replace the following:

PROJECT_ID: the VM's project ID.
ZONE: the zone of the VM.
VM_NAME: the name of the VM.

Delete a VM with a Private Service Connect interface

To delete a Private Service Connect interface, you must delete the VM instance that it is attached to. For more information, see Delete an instance.

What's next?

Configure security for a network that has a Private Service Connect interface connection.
Manage destination overlap in a network that has a Private Service Connect interface connection.