Create and manage Private Service Connectinterfaces

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

Before you begin

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:

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

You might also be able to get the required permissions throughcustom roles or otherpredefined roles.

The Compute Instance Admin (v1) role contains thecompute.instances.pscInterfaceCreate permission, which is required to createPrivate Service Connect interfaces.

Create VMs with Private Service Connect interfaces

To create a Private Service Connect interface connection, youneed a virtual machine (VM) instance that has at least two network interfaces.The first interface connects to a producer subnet. The other interfaces can bePrivate Service Connect interfaces that request connections tonetwork attachments in differentconsumer VPC networks.

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

When you create a VM with multiple Private Service Connectinterfaces, each Private Service Connect interface must connectto a different network attachment that is in a different VPCnetwork.

Caution: Make sure that the VM connects only to network attachments from asingle consumer.Multi-tenant architectures can let one consumer takeactions that cause a loss of connectivity for other consumers that are connectedto the same VM.

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

When you create a Private Service Connect interface, you canoptionally assign to it one or more internalalias IP ranges.If you plan to assign alias IP ranges, contact the consumer organization todetermine the appropriate IP address ranges.

To assign an alias IP range, specify the prefix length of the range in CIDRnotation. When you assign one ormore alias IP ranges to a Private Service Connect interface,Google Cloud allocates the alias IP ranges from the primary IP addressrange of the subnet that's associated with thenetwork attachment. The Private Service Connect interface'sprimary IP address is allocated from outside of any alias IP ranges.If there aren't enough IP addresses in the network attachment's subnet toallocate the primary IP address and alias IP ranges,creation of the Private Service Connect interface's VM fails. Youcan find the specific IP addresses that are assigned bydescribing the interface's VM.

Important: After creating a Private Service Connect interface,you mustconfigure routingbefore traffic can flow through the interface.

Console

Create a VM instance

  1. In the Google Cloud console, go to theVM instances page:

    Go to VM instances

  2. ClickCreate instance.

  3. Enter a name.

  4. ClickRegion, and then select the region of the network attachmentthat you want to connect to.

  5. Select a zone.

  6. To configure the VM's default network interface, do the following:

    1. ClickNetworking.
    2. In theNetwork interfaces section, click the first networkinterface, which is the default network interface.
    3. Select a network.
    4. Select a subnet that is in the same region as thePrivate Service Connect interface's network attachment.
    5. Select an IP stack type.

  7. ClickDone.

Add Private Service Connect interfaces

You can repeat these steps for each interface that youwant to add.

Add a virtual Private Service Connect interface

  1. ClickAdd a network interface.
  2. ForInterface type, selectPrivate Service Connect.
  3. Enter the URL of this interface's network attachment.
  4. Select anIP stack typefor the interface. The network attachment'ssubnet determines the possible stack types.
  5. Optional: To add an alias IP range, do the following:
    1. In theAlias IP ranges section, clickAdd IP range.
    2. In thePrefix length box, enter the prefix length—forexample,/30. You can add multiple alias IP ranges by clickingAdd IP range, and then entering the prefix length for eachadditional alias IP range that you want to add.
  6. ClickDone.

Add a dynamic Private Service Connect interface

  1. ClickAdd a dynamic network interface.
  2. ForInterface type, selectPrivate Service Connect.
  3. Select a parent network interface.
  4. Enter a VLAN ID.
  5. Select anIP stack typefor the interface. The network attachment'ssubnet determines the possible stack types.
  6. Optional: To add an alias IP range, do the following:
    1. In theAlias IP ranges section, clickAdd IP range.
    2. In thePrefix length box, enter the prefix length—forexample,/30. You can add multiple alias IP ranges by clickingAdd IP range, and then entering the prefix length for eachadditional alias IP range that you want to add.
  7. ClickDone.

To create the VM, clickCreate.

gcloud

  • To create a VM with a virtualPrivate Service Connect interface, use thegcloud compute instances create command.

    gcloud compute instances createINSTANCE_NAME \    --zone=ZONE \    --machine-type=MACHINE_TYPE \    --image-project=IMAGE_PROJECT \    --image-family=IMAGE_FAMILY \    --network-interface='subnet=PRODUCER_SUBNET,no-address' \    --network-interface='network-attachment=ATTACHMENT_URI,stack-type=STACK_TYPE

    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, whichcan bepredefined orcustom—for example,n1-standard-1

    • IMAGE_PROJECT: the project of the image family

      For example, if you specifydebian-12 as the image family, specifydebian-cloud as the imageproject. You can view a list of available images, image projects,and image families by using thegcloud compute images list command.

    • IMAGE_FAMILY: theimage family of the instance

      This creates the VM with the most recent, non-deprecated OS image inthe image family. For example, if you specifydebian-12,Compute Engine uses the latest version of the OS image in theDebian 12 image family.

    • PRODUCER_SUBNET: the subnet of the VM'sprimary network interface

      This subnet must be in the same region as thePrivate Service Connect interface's networkattachment.

    • ATTACHMENT_URI: the URI of the networkattachment—for example:projects/CONSUMER_PROJECT_ID/regions/REGION/networkAttachments/ATTACHMENT_NAME

    • STACK_TYPE: thestack type ofthe Private Service Connect interface

      To create an interface with an IPv4 address, specifyIPV4_ONLY (the default). To create an interface that uses bothan IPv4 and an IPv6 address (dual-stack), specifyIPV4_IPV6.For IPv6 only, specifyIPV6_ONLY.

      The interface's stack type must be compatible with the stack typeof the network attachment's subnet.

  • To create a VM with a dynamic Private Service Connectinterface, use the following command:

    gcloud compute instances createINSTANCE_NAME \    --zone=ZONE \    --machine-type=MACHINE_TYPE \    --image-project=IMAGE_PROJECT \    --image-family=IMAGE_FAMILY \    --network-interface='subnet=PRODUCER_SUBNET,no-address' \    --network-interface='network-attachment=ATTACHMENT_URI,vlan=VLAN_ID,stack-type=STACK_TYPE'

    ReplaceVLAN_ID with the VLAN ID of the dynamicPrivate Service Connect interface, which must be aninteger from 2 to 255.

    VLAN IDs must be unique for each dynamic interface that shares aparent vNIC. You can reuse the same ID for otherdynamic interfaces that areassociated with different vNICs.

  • To assign alias IP ranges to a Private Service Connectinterface, use the following command:

    gcloud compute instances createINSTANCE_NAME \    --zone=ZONE \    --machine-type=MACHINE_TYPE \    --image-project=IMAGE_PROJECT \    --image-family=IMAGE_FAMILY \    --network-interface='subnet=PRODUCER_SUBNET,no-address' \    --network-interface='network-attachment=ATTACHMENT_URI,vlan=VLAN_ID,stack-type=STACK_TYPE,aliases=ALIAS_IP_RANGES'

    ReplaceALIAS_IP_RANGES with one or more alias IPranges to assign to the interface. You can enter specific ranges(192.168.100.0/24), specific IP addresses (192.168.100.1), orprefix lengths in CIDR format (/24). You can enter multiple valuesin a semicolon-separated list. You can't enter multiple values ofdifferent types. For example,192.168.100.0/24;/28 isn'tsupported.

  • To create a VM with multiple Private Service Connectinterfaces, include separate--network-interface flags for eachinterface, where each flag refers to a different network attachment.

    For dynamic Private Service Connect interfaces,the parent vNIC is determined by the order of flags in the command.The parent vNIC is the first vNIC that you specify before the dynamicinterface.

    You can create dynamic and virtualPrivate Service Connect interfaces that coexist on thesame VM. For example, the following command creates a VM with bothvirtual and dynamic Private Service Connect interfaces.

    The parent of the dynamic Private Service Connectinterfaces that have VLAN IDs2 and3 is the firstvNIC, connecting toproducer-subnet. The parent of the dynamicinterface that has VLAN ID4 is the vNIC that connects toproducer-subnet-2. The last interface is a virtualPrivate Service Connect interface.

    gcloud compute instances create producer-vm \    --zone=us-west-1a \    --network-interface='subnet=producer-subnet,no-address' \    --network-interface='network-attachment=projects/consumer-project/regions/us-west-1/networkAttachments/consumer-1-network-attachment,vlan=2' \    --network-interface='network-attachment=projects/consumer-project/regions/us-west-1/networkAttachments/consumer-2-network-attachment,vlan=3' \    --network-interface='network=producer-vpc-2,subnet=producer-subnet-2' \    --network-interface='network-attachment=projects/consumer-project/regions/us-west-1/networkAttachments/consumer-3-network-attachment,vlan=4' \    --network-interface='network-attachment=projects/consumer-project/regions/us-west-1/networkAttachments/consumer-4-network-attachment'

API

  • To create a VM with a virtual Private Service Connectinterface, send a request to theinstances.insert method.

    HTTP method and URL:

    POST https://compute.googleapis.com/compute/v1/projects/PRODUCER_PROJECT_ID/zones/INSTANCE_ZONE/instances

    Request JSON body:

    {  "machineType": "zones/MACHINE_TYPE_ZONE/machineTypes/MACHINE_TYPE",  "name": "VM_NAME",  "disks": [    {      "initializeParams": {        "sourceImage": "projects/IMAGE_PROJECT/global/images/family/IMAGE_FAMILY"      },      "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/PRODUCER_SUBNET"    },    {      "networkAttachment": "ATTACHMENT_URI",      "stackType": "STACK_TYPE"    }  ]}

    Replace the following:

    • PRODUCER_PROJECT_ID: the ID of the VM's project
    • INSTANCE_ZONE: the zone of the new instance
    • MACHINE_TYPE_ZONE: the zone of the machine type
    • MACHINE_TYPE: the instance's machine type, whichcan bepredefined orcustom—for example,n1-standard-1
    • VM_NAME: the name of the VM instance

    • IMAGE_PROJECT: the project of the image family

      For example, if you specifydebian-12 as the image family, specifydebian-cloud as the imageproject. You can view a list of available images, image projects,and image families by using thegcloud compute images list command.

    • IMAGE_FAMILY: theimage family of the instance

      This creates the VM with the most recent, non-deprecated OS image inthe image family. For example, if you specifydebian-12,Compute Engine uses the latest version of the OS image in theDebian 12 image family.

    • PRODUCER_NETWORK: the network of the VM'sprimary network interface

    • SUBNET_REGION: the region of the subnet of theVM's primary network interface

    • PRODUCER_SUBNET: the subnet of the VM'sprimary network interface

      This subnet must be in the same region as thePrivate Service Connect interface's networkattachment.

    • ATTACHMENT_URI: the URI of the networkattachment—for example:projects/CONSUMER_PROJECT_ID/regions/REGION/networkAttachments/ATTACHMENT_NAME

    • STACK_TYPE: thestack type ofthe Private Service Connect interface.

      To create an interface with an IPv4 address, specifyIPV4_ONLY (the default). To create an interface that uses bothan IPv4 and an IPv6 address (dual-stack), specifyIPV4_IPV6.For IPv6 only, specifyIPV6_ONLY.

      The interface's stack type must be compatible with the stack typeof the network attachment's subnet.

  • To create a VM with a dynamic Private Service Connectinterface, send the following request. Include a VLAN ID in the networkinterface object to specify the creation of a dynamicPrivate Service Connect interface.

    HTTP method and URL:

    POST https://compute.googleapis.com/compute/v1/projects/PRODUCER_PROJECT_ID/zones/INSTANCE_ZONE/instances

    Request JSON body:

    {  "machineType": "zones/MACHINE_TYPE_ZONE/machineTypes/MACHINE_TYPE",  "name": "VM_NAME",  "disks": [    {      "initializeParams": {        "sourceImage": "projects/IMAGE_PROJECT/global/images/family/IMAGE_FAMILY"      },      "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/PRODUCER_SUBNET"    },    {      "networkAttachment": "ATTACHMENT_URI",      "vlan":VLAN_ID,      "stackType": "IPV4_IPV6"    }  ]}

    ReplaceVLAN_ID with the VLAN ID of the dynamicPrivate Service Connect interface, which must be aninteger from 2 to 255.

    VLAN IDs must be unique for each dynamic interface that shares aparent vNIC. You can reuse the same ID for otherdynamic interfaces that areassociated with different vNICs.

  • To assign alias IP ranges to a Private Service Connectinterface, send the following request. Include thealiasesIpRanges field.

    HTTP method and URL:

    POST https://compute.googleapis.com/compute/v1/projects/PRODUCER_PROJECT_ID/zones/INSTANCE_ZONE/instances

    Request JSON body:

    {  "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/PRODUCER_SUBNET"    },    {      "aliasIpRanges": [        {          "ipCidrRange": "ALIAS_IP_RANGE"        }      ],      "networkAttachment": "ATTACHMENT_URI"    }  ]}

    ReplaceALIAS_IP_RANGE with an alias IPranges to assign to the interface. You can enter a specific range(192.168.100.0/24), specific IP address (192.168.100.1), orprefix length in CIDR format (/24).

    You can specify multiple alias IP rangesin thealiasIpRanges array. Each range must be specified in the sameform:

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

  • To create a VM with multiple Private Service Connectinterfaces, include separate objects in thenetworkInterfaces arrayfor each interface, where each interface object refers to a differentnetwork attachment.

    For dynamic Private Service Connect interfaces,the parent vNIC is determined by the order of objects in the array.The parent vNIC is the first vNIC that you specify before the dynamicinterface.

    You can create dynamic and virtualPrivate Service Connect interfaces that coexist on thesame VM. For example, the following request creates a VM with bothvirtual and dynamic Private Service Connect interfaces.

    The parent of the dynamic Private Service Connectinterfaces that have VLAN IDs2 and3 is the firstvNIC, connecting toproducer-subnet. The parent of the dynamicinterface that has VLAN ID4 is the vNIC that connects toproducer-subnet-2. The last interface is a virtualPrivate Service Connect interface.

    {"machineType":"zones/us-west-1a/machineTypes/e2-medium","name":"producer-vm","disks":[{"initializeParams":{"sourceImage":"projects/debian-cloud/global/images/family/debian-11"},"boot":true}],"networkInterfaces":[{"network":"https://www.googleapis.com/compute/v1/projects/producer-project-id/global/networks/producer-vpc-1","subnetwork":"https://www.googleapis.com/compute/v1/projects/producer-project-id/regions/us-west-1/subnetworks/producer-subnet"},{"networkAttachment":"projects/consumer-project1/regions/us-west-1/networkAttachments/consumer-1-network-attachment","vlan":2},{"networkAttachment":"projects/consumer-project2/regions/us-west-1/networkAttachments/consumer-2-network-attachment","vlan":3},{"network":"https://www.googleapis.com/compute/v1/projects/producer-project-id/global/networks/producer-vpc-2","subnetwork":"https://www.googleapis.com/compute/v1/projects/producer-project-id/regions/us-west-1/subnetworks/producer-subnet-2"},{"networkAttachment":"projects/consumer-project3/regions/us-west-1/networkAttachments/consumer-3-network-attachment","vlan":4},{"networkAttachment":"projects/consumer-project4/regions/us-west-1/networkAttachments/consumer-4-network-attachment"}]}```

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

Add dynamic Private Service Connect interfaces to existing VMs

You can add a dynamic Private Service Connect interfaceto an existing VM without restarting the VM.

You mustconfigure routingbefore traffic can flow through a new Private Service Connectinterface.

Console

  1. In the Google Cloud console, go to theVM instances page:

    Go to VM instances

  2. Click the name of the VM that you want to update.

  3. ClickEdit.

  4. In theNetworking section, clickAdd a dynamic network interface.

  5. ForInterface type, selectPrivate Service Connect.

  6. Select a parent network interface.

  7. Enter a VLAN ID.

  8. Enter the URL of this interface's network attachment.

  9. Select an IP stack type for the interface. The network attachment'ssubnetdetermines the possible stack types.

  10. Optional: To add an alias IP range, do the following:

    1. In theAlias IP ranges section, clickAdd IP range.
    2. In thePrefix length box, enter the prefix length—forexample,/30. You can add multiple alias IP ranges by clickingAdd IP range, and then entering the prefix length for eachadditional alias IP range that you want to add.

  11. ClickDone.

  12. ClickSave.

gcloud

To add a single dynamic Private Service Connectinterface to an existing VM, use thegcloud compute instances network-interfaces add command.

To add multiple dynamic Private Service Connectinterfaces, repeat the command for each interface that you want to add.

gcloud compute instances network-interfaces addINSTANCE_NAME \    --zone=ZONE \    --vlan=VLAN_ID \    --parent-nic-name=PARENT_NIC_NAME \    --network-attachment=ATTACHMENT_URI

Replace the following:

  • INSTANCE_NAME: the name of the instance to update
  • ZONE: the zone of the instance to update

  • VLAN_ID: an ID (integer from 2 to 4094)for the dynamic Private Service Connect interface

    VLAN IDs must be unique for each dynamic interface that shares aparent vNIC. You can reuse the same ID for otherdynamic interfaces that areassociated with different vNICs.

  • PARENT_NIC_NAME: the name of the newVLAN NIC's parent network interface—for example,nic0.

  • ATTACHMENT_URI: the URI of the networkattachment—for example:projects/CONSUMER_PROJECT_ID/regions/REGION/networkAttachments/ATTACHMENT_NAME

API

To add a single dynamic Private Service Connectinterface to an existing VM, send a request to theinstances.addNetworkInterface method.

To add multiple dynamic Private Service Connectinterfaces, repeat the request for each interface that you want to add.

HTTP method and URL:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_NAME/addNetworkInterface

Request JSON body:

{  "networkAttachment": "ATTACHMENT_URI",  "parentNicName": "PARENT_NIC_NAME",  "vlan":VLAN_ID}

Replace the following:

  • PROJECT_ID: the ID of the VM's project
  • ZONE: the zone of the VM

  • INSTANCE_NAME: the name of the VM to update

  • ATTACHMENT_URI: the URI of the networkattachment—for example:projects/CONSUMER_PROJECT_ID/regions/REGION/networkAttachments/ATTACHMENT_NAME

  • PARENT_NIC_NAME: the name of the newVLAN NIC's parent network interface—for example,nic0

  • VLAN_ID: an ID (integer from 2 to 4094)for the VLAN NIC Private Service Connect interface

    VLAN NIC interface IDs must be unique for each VLAN NIC under aparent network interface, but you can reuse the same ID for otherVLAN NICs that are associated with different parent networkinterfaces.

Migrate from virtual to dynamic Private Service Connect interfaces

To configure your service to usedynamic Private Service Connect interfaces instead ofvirtual Private Service Connect interfaces, do the following.

  1. Create a VM that uses dynamic Private Service Connect interfaces.
  2. Configure routing for the new VM.
  3. Update your service to use the new VM.
  4. Delete the VM that uses virtual Private Service Connect interfaces.

Create and manage Private Service Connect interfaces by using instance templates

You can create and manage Private Service Connectinterfaces by usinginstance templates.

After you create an instance template, you can use it to:

To create instance templates that use alias IP ranges or multiplePrivate Service Connect interfaces, use the same approach ascreating VMs with Private Service Connect interfaces.Instance templates only support specifying alias IP ranges by prefix length.

Console

  1. In the Google Cloud console, go to theInstance templates page:

    Go to Instance templates

  2. ClickCreate instance template.

  3. Enter aName for the instance template.

  4. ClickAdvanced options.

  5. ClickNetworking.

  6. In theNetwork interfaces section, click theexpander arrow.

  7. Select a network and subnetwork for the instance template'sprimary network interface.

  8. ClickDone.

  9. To add a Private Service Connect interface,do the following. You can repeat these steps for each interface that youwant to add:

    • For a virtual Private Service Connect interface, dothe following:
      1. ClickAdd a network interface.
      2. ForInterface type, selectPrivate Service Connect.
    • For a dynamic Private Service Connect interface,do the following:
      1. ClickAdd dynamic network interface.
      2. ForInterface type, selectPrivate Service Connect.
      3. Select a parent network interface.
      4. Enter a VLAN ID.

  10. To complete the configuration of yourPrivate Service Connect interface, do the following:

    1. Enter the URL of this interface's network attachment.
    2. Select an IP stack type for the interface. The network attachment'ssubnetdetermines the possible stack types.
    3. Optional: To add an alias IP range, do the following:
      1. In theAlias IP ranges section, clickAdd IP range.
      2. In thePrefix length box, enter the prefix length—forexample,/30. You can add multiple alias IP ranges by clickingAdd IP range, and then entering the prefix length for eachadditional alias IP range that you want to add.
    4. ClickDone.

  11. To create the VM, clickCreate.

gcloud

  • To create an instance template with a virtualPrivate Service Connect interface, use thegcloud compute instance-templates create command.

    gcloud compute instance-templates createNAME \    --machine-type=MACHINE_TYPE \    --image-project=IMAGE_PROJECT \    --image-family=IMAGE_FAMILY \    --region=REGION \    --network-interface='subnet=PRODUCER_SUBNET,no-address' \    --network-interface='network-attachment=ATTACHMENT_URI,stack-type=STACK_TYPE'

    Replace the following:

    • NAME: the name of the new instance template
    • MACHINE_TYPE: the instance's machine type, whichcan bepredefined orcustom—for example,n1-standard-1

    • IMAGE_PROJECT: the project of the image family

      For example, if you specifydebian-12 as the image family, specifydebian-cloud as the imageproject. You can view a list of available images, image projects,and image families by using thegcloud compute images list command.

    • IMAGE_FAMILY: theimage family of the instance

      This creates the VM with the most recent, non-deprecated OS image inthe image family. For example, if you specifydebian-12,Compute Engine uses the latest version of the OS image in theDebian 12 image family.

    • REGION: the region of the instance template'sproducer subnet.

    • PRODUCER_SUBNET: the subnet of the instancetemplate

      When you create a VM by using this instance template, the VM'sprimary network interface is assigned an internal IP address fromthis subnet. This subnet must be in the same region as thePrivate Service Connect interface's networkattachment.

    • ATTACHMENT_URI: the URI of the networkattachment—for example:projects/CONSUMER_PROJECT_ID/regions/REGION/networkAttachments/ATTACHMENT_NAME

    • STACK_TYPE: thestack type ofthe instance template'sPrivate Service Connect interface.

      To create an interface with an IPv4 address, specifyIPV4_ONLY (the default). To create an interface that uses bothan IPv4 and an IPv6 address (dual-stack), specifyIPV4_IPV6.For IPv6 only, specifyIPV6_ONLY.

      The interface's stack type must be compatible with the stack typeof the network attachment's subnet.

  • To create an instance template with a dynamicPrivate Service Connect interface, use the followingcommand:

    gcloud compute instance-templates createNAME \    --machine-type=MACHINE_TYPE \    --image-project=IMAGE_PROJECT \    --image-family=IMAGE_FAMILY \    --region=REGION \    --network-interface='subnet=PRODUCER_SUBNET,no-address' \    --network-interface='network-attachment=ATTACHMENT_URI,vlan=VLAN_ID,stack-type=STACK_TYPE'

    ReplaceVLAN_ID with the VLAN ID of the dynamicPrivate Service Connect interface, which must be aninteger from 2 to 255.

    VLAN IDs must be unique for each dynamic interface that shares aparent vNIC. You can reuse the same ID for otherdynamic interfaces that areassociated with different vNICs.

API

  • To create an instance template with a virtualPrivate Service Connect interface, make a requestto theinstanceTemplates.insert method.

    HTTP method and URL:

    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/instanceTemplates

    Request JSON body:

    {  "name": "NAME",  "properties": {    "disks": [      {        "boot": true,        "initializeParams": {          "sourceImage": "projects/IMAGE_PROJECT/global/images/family/IMAGE_FAMILY"        }      }    ],    "machineType": "MACHINE_TYPE",    "networkInterfaces": [      {        "subnetwork": "https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/SUBNET_REGION/subnetworks/PRODUCER_SUBNET"      },      {        "networkAttachment": "ATTACHMENT_URI",        "stackType": "STACK_TYPE"      }    ]  }}

    Replace the following:

    • PROJECT_ID: the project ID of the instancetemplate
    • NAME: the name of the new instance template

    • IMAGE_PROJECT: the project of the image family

      For example, if you specifydebian-12 as the image family, specifydebian-cloud as the imageproject. You can view a list of available images, image projects,and image families by using thegcloud compute images list command.

    • IMAGE_FAMILY: theimage family of the instance

      This creates the VM with the most recent, non-deprecated OS image inthe image family. For example, if you specifydebian-12,Compute Engine uses the latest version of the OS image in theDebian 12 image family.

    • MACHINE_TYPE: the instance's machine type, whichcan bepredefined orcustom—for example,n1-standard-1

    • SUBNET_REGION: the region of the instancetemplate's producer subnet.

    • PRODUCER_SUBNET: the subnet of the instancetemplate

      When you create a VM by using this instance template, the VM'sprimary network interface is assigned an internal IP address fromthis subnet. This subnet must be in the same region as thePrivate Service Connect interface's networkattachment.

    • ATTACHMENT_URI: the URI of the networkattachment—for example:projects/CONSUMER_PROJECT_ID/regions/REGION/networkAttachments/ATTACHMENT_NAME

    • STACK_TYPE: thestack type ofthe instance template'sPrivate Service Connect interface

      To create an interface with an IPv4 address, specifyIPV4_ONLY (the default). To create an interface that uses bothan IPv4 and an IPv6 address (dual-stack), specifyIPV4_IPV6.For IPv6 only, specifyIPV6_ONLY.

      The interface's stack type must be compatible with the stack typeof the network attachment's subnet.

  • To create an instance template with a dynamicPrivate Service Connect interface, make the followingrequest.

    HTTP method and URL:

    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/instanceTemplates

    Request JSON body:

    {  "name": "NAME",  "properties": {    "disks": [      {        "boot": true,        "initializeParams": {          "sourceImage": "projects/IMAGE_PROJECT/global/images/family/IMAGE_FAMILY"        }      }    ],    "machineType": "MACHINE_TYPE",    "networkInterfaces": [      {        "subnetwork": "https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/SUBNET_REGION/subnetworks/PRODUCER_SUBNET"      },      {        "networkAttachment": "ATTACHMENT_URI",        "vlan":VLAN_ID,        "stackType": "STACK_TYPE"      }    ]  }}

    ReplaceVLAN_ID with the VLAN ID of the dynamicPrivate Service Connect interface, which must be aninteger from 2 to 255.

    VLAN IDs must be unique for each dynamic interface that shares aparent vNIC. You can reuse the same ID for otherdynamic interfaces that areassociated with different vNICs.

For more information about creating instance templates, seeCreate instance templates.

Describe a Private Service Connect interface

You can describe a VM to view the details of itsPrivate Service Connect interfaces. Each interface's name, IPaddress, alias IP ranges, network attachment, and consumer subnet are listed inthe network interfaces section of the VM's description.

Console

  1. In the Google Cloud console, go to theVM instances page.

    Go to VM instances

  2. Click the VM that has your Private Service Connectinterface.

  3. In theNetwork interfaces section, view the detailsof your Private Service Connect interface.

gcloud

gcloud compute instances describeVM_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.

Terminate Private Service Connect interface connections

To terminate a connection between a virtualPrivate Service Connect interface and a network attachment,delete the interface's VM.

To terminate a connection between a dynamicPrivate Service Connect interface and a network attachment, doone of the following:

  • Remove the dynamic Private Service Connect interface.
  • Delete the dynamic Private Service Connect interface's VM.

Remove a dynamic Private Service Connect interface

You can remove a dynamic Private Service Connect interfacewithout restarting the associated VM.

Console

  1. In the Google Cloud console, go to theVM instances page:

    Go to VM instances

  2. Click the name of the VM that you want to update.

  3. ClickEdit.

  4. In theDynamic network interfaces section, clickDelete next tothe interface that you want to delete.

gcloud

Use thegcloud compute instances network-interfaces delete command.

gcloud compute instances network-interfaces deleteINSTANCE_NAME \    --zone=ZONE \    --network-interface=INTERFACE_NAME

Replace the following:

  • INSTANCE_NAME: the name of the interface's VMinstance
  • ZONE: the zone of the interface's VM instance

  • INTERFACE_NAME: the Google Cloud name of thedynamic Private Service Connect interface todelete

    For example,nic0.10 is the name of adynamic Private Service Connect interface, wherenic0is the parent and10 is the VLAN ID.

API

Send a request to theinstances.deleteNetworkInterface method.

HTTP method and URL:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_NAME/deleteNetworkInterface?networkInterfaceName=INTERFACE_NAME

Replace the following:

  • PROJECT_ID: the project ID of the interface's VM
  • ZONE: the zone of the interface's VM
  • INSTANCE_NAME: the name of the interface's VM

  • INTERFACE_NAME: the Google Cloud name of thedynamic Private Service Connect interface todelete

    For example,nic0.10 is the name of adynamic Private Service Connect interface, wherenic0is the parent vNIC name and10 is the VLAN ID.

Delete a VM with a Private Service Connect interface

Deleting a VM terminates any Private Service Connect interfaceconnections.

For information about deleting a VM, seeDelete an instance.

What's next?

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