Create port mapping services

This page describes how service producers can publish services that usePrivate Service Connect port mapping.

Private Service Connect port mapping lets consumer clientsprivately communicate with specific service ports on specific producer VMsthrough a singlePrivate Service Connectendpoint.

Before you begin

Required roles

To get the permissions that you need to prepare to publish a service with Private Service Connect port mapping, ask your administrator to grant you the following IAM roles on the producer 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.

Create and publish a port mapping service

Port mapping services have similar configurations to internal passthrough Network Load Balancers, buttraffic is not load balanced. To create and publish a port mapping service, dothe following:

  • Create a port mapping NEG
  • Add network endpoints to the port mapping NEG
  • Create a port mapping service
  • Publish the port mapping service

Create a port mapping NEG

Aport mapping network NEGis a regional NEG with the network endpoint type ofGCE_VM_IP_PORTMAP. It'snot possible to change a port mapping NEG's type after it is created.

When you create a port mapping NEG, you choose a subnet. Network endpoints thatyou associate with the port mapping NEG must have a primary network interfacein this subnet.

Console

  1. In the Google Cloud console, go to theNetwork Endpoint Groups page.

    Go to Network Endpoint Groups

  2. ClickCreate network endpoint group.

  3. Enter aName.

  4. ClickNetwork endpoint group type, and then selectPort mapping NEG (Regional).

  5. Select aRegion.

  6. Select aNetwork.

  7. Select aSubnetwork.

  8. ClickCreate.

gcloud

Use thenetwork-endpoints-groups create command.

gcloud compute network-endpoint-groups createNEG \    --region=REGION \    --network=NETWORK \    --subnet=SUBNET \    --network-endpoint-type=GCE_VM_IP_PORTMAP

Replace the following:

  • NEG: the name of the port mapping NEG
  • REGION: the region of the port mapping NEG
  • NETWORK: the VPC network of theport mapping NEG
  • SUBNET: the subnet of the port mapping NEG

API

Send aPOST request to theregionNetworkEndpointGroups.insert method.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/networkEndpointGroups{  "name": "NEG",  "networkEndpointType": "GCE_VM_IP_PORTMAP",  "network": "projects/PROJECT_ID/global/networks/NETWORK",  "subnetwork": "projects/PROJECT_ID/regions/REGION/subnetworks/SUBNET"}

Replace the following:

  • PROJECT_ID: the project ID of the port mappingNEG
  • REGION: the region of the port mapping NEG
  • NEG: the name of the port mapping NEG
  • NETWORK: the VPC network of theport mapping NEG
  • SUBNET: the subnet of the port mapping NEG

Add network endpoints to the port mapping NEG

Create one or more network endpoints with port mappings and attach them tothe port mapping NEG.

Network endpoints for port mapping NEGs are zonal and must fulfill the followingrequirements:

  • Each network endpoint refers to a Compute Engine VM that hasa primary network interface in the same subnet as the port mapping NEG.
  • Each network endpoint refers to a unique client destination port.

  • Each network endpoint must refer to a unique combination of service portand VM.

Console

  1. In the Google Cloud console, go to theNetwork Endpoint Groups page.

    Go to Network Endpoint Groups

  2. Click the name of the port mapping NEG that you want to update.

  3. ClickAdd network endpoints.

  4. ClickVM instance, and then select a VM.

  5. ClickVM port 1, and then enter a service port.

  6. ClickClient port 1, and then enter a client destination port.

  7. For each additional network endpoint that you want to add, clickAdd network endpoint, and then enter the network endpoint details.

  8. ClickCreate.

gcloud

Use thenetwork-endpoint-groups update command. Include an--add-endpoint flag for eachnetwork endpoint that you want to attach.

gcloud compute network-endpoint-groups updateNEG \    --region=REGION \    --add-endpoint=client-destination-port=CLIENT_DESTINATION_PORT_1,instance=projects/PROJECT_ID/zones/ZONE_1/instances/VM_1_NAME,port=VM_1_PORT \    --add-endpoint=client-destination-port=CLIENT_DESTINATION_PORT_2,instance=projects/PROJECT_ID/zones/ZONE_2/instances/VM_2_NAME,port=VM_2_PORT

Replace the following:

  • NEG: the name of the port mapping NEG
  • REGION: the region of the port mapping NEG
  • CLIENT_DESTINATION_PORT_1: the client destinationport of the first network endpoint
  • PROJECT_ID: the project ID of the producerproject
  • ZONE_1: the zone of the first network endpoint
  • VM_1_NAME: the name of the destination VMfor the first network endpoint
  • VM_1_PORT: the service port of the firstnetwork endpoint
  • CLIENT_DESTINATION_PORT_2: the client destination port of thesecond network endpoint
  • ZONE_2: the zone of the second network endpoint
  • VM_2_NAME: the name of the destination VMfor the second network endpoint
  • VM_2_PORT: the service port of the secondnetwork endpoint

API

Send aPOST request to theregionNetworkEndpointGroups.attachNetworkEndpoints method.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/networkEndpointGroups/NEG/attachNetworkEndpoints{  "networkEndpoints": [    {      "clientDestinationPort":CLIENT_DESTINATION_PORT_1,      "instance": "projects/PROJECT_ID/zones/ZONE_1/instances/VM_1_NAME",      "port":SERVICE_PORT_1    },    {      "clientDestinationPort":CLIENT_DESTINATION_PORT_2,      "instance": "projects/PROJECT_ID/zones/ZONE_2/instances/VM_2_NAME",      "port":SERVICE_PORT_2    }  ]}

Replace the following:

  • PROJECT_ID: the project ID of the producerproject
  • REGION: the region of the port mapping NEG
  • NEG: the name of the port mapping NEG
  • CLIENT_DESTINATION_PORT_1: the client destinationport of the first network endpoint
  • ZONE_1: the zone of the first network endpoint
  • VM_1_NAME: the name of the destination VMfor the first network endpoint
  • SERVICE_PORT_1: the service port of the firstnetwork endpoint
  • CLIENT_DESTINATION_PORT_2: the client destinationport of the second network endpoint
  • ZONE_2: the zone of the second network endpoint
  • VM_2_NAME: the name of the destination VMfor the second network endpoint
  • SERVICE_PORT_2: the service port of the secondnetwork endpoint

Create a port mapping service

To create a port mapping service, complete the following steps.

You can't change the port mapping NEG that is associated with abackend service after you add the NEG. However, you canupdate the port mapping NEG's network endpoints.

You can't update the connection of a forwarding rule after it is created.If you need to connect to a different backend service,delete the forwarding rule,and then create a new one.

Console

Start your configuration

  1. In the Google Cloud console, go to theLoad balancing page.

    Go to Load balancing

  2. ClickCreate load balancer.
  3. ForType of load balancer, selectNetwork Load Balancer (TCP/UDP/SSL) and clickNext.
  4. ForProxy or passthrough, selectPassthrough load balancer and clickNext.
  5. ForPublic facing or internal, selectInternal and clickNext.
  6. ClickConfigure.

Basic configuration

  1. Enter aLoad balancer name.
  2. Select aRegion.
  3. Select aNetwork.

Backend configuration

  1. ForBackend type, selectPort mapping network endpoint group.
  2. Select aPort mapping network endpoint group.

Frontend configuration

  1. ClickFrontend configuration.
  2. Optional: Enter aName.
  3. Optional: Enter aDescription.
  4. Select aProtocol.
  5. Select aSubnetwork.
  6. ClickDone.
  7. ClickCreate.

gcloud

  1. To create a backend service, use thebackend-services create command.

    gcloud compute backend-services createSERVICE \    --load-balancing-scheme=internal \    --region=REGION \    --network=NETWORK

    Replace the following:

    • SERVICE: the name of the backend service
    • REGION: the region of the backend service
    • NETWORK: the producer VPCnetwork of the backend service

  2. To add your port mapping NEG to the backend service, use thebackend-services add-backend command.

    You can't add multiple port mapping NEGs to a single backend service.

    gcloud compute backend-services add-backendSERVICE \    --network-endpoint-group=NEG \    --network-endpoint-group-region=REGION

    ReplaceNEG with the name of the port mappingNEG.

  3. To create a forwarding rule for your port mapping service, use theforwarding-rules create command.

    The forwarding rule must beconfigured to forward traffic for all client destination ports.

    gcloud compute forwarding-rules createRULE \    --load-balancing-scheme=INTERNAL \    --ip-protocol=PROTOCOL \    --network=NETWORK \    --subnet=SUBNET \    --address=IP_ADDRESS \    --ports=ALL \    --region=REGION \    --backend-service=SERVICE

    Replace the following:

    • RULE: the name of the forwarding rule
    • PROTOCOL: the protocol of the forwarding rule,which can be eitherTCP orUDP
    • SUBNET: the producer subnet, which must bethe same subnet that's associated with the port mapping NEG
    • IP_ADDRESS: the IP address of the forwardingrule, which must come from the IP address range of the producersubnet

API

  1. To create a backend service, send aPOST request to theregionBackendServices.insert method.

    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/backendServices{  "name": "SERVICE",  "loadBalancingScheme": "INTERNAL",  "network": "projects/PROJECT_ID/global/networks/NETWORK"}

    Replace the following:

    • PROJECT_ID: the ID of the backend service'sproject
    • REGION: the region of the backend service
    • SERVICE: the name of the backend service
    • NETWORK: the producer VPCnetwork

  2. To add your port mapping NEG to the backend service, send aPATCHrequest to theregionBackendServices.patch method.

    You can't add multiple port mapping NEGs to a single backend service.

    PATCH https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/backendServices/SERVICE{  "backends": [    {      "group": "https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/networkEndpointGroups/NEG"    }  ]}

    ReplaceNEG with the name of your portmapping NEG.

  3. To create a forwarding rule for your port mapping service, send aPOSTrequest to theforwardingRules.insert method.

    The forwarding rule must beconfigured to forward traffic for all client destination ports.

    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/forwardingRules{  "name": "RULE",  "loadBalancingScheme": "INTERNAL",  "IPProtocol": "PROTOCOL",  "network": "projects/PROJECT_ID/global/networks/NETWORK",  "subnetwork": "projects/PROJECT_ID/regions/REGION/subnetworks/SUBNET",  "IPAddress": "IP_ADDRESS",  "allPorts": true,  "backendService": "projects/PROJECT_ID/regions/REGION/backendServices/SERVICE"}

    Replace the following:

    • RULE: the name of the forwarding rule
    • PROTOCOL: the protocol of the forwarding rule,which can be eitherTCP orUDP
    • SUBNET: the producer subnet, which must bethe same subnet that's associated with the port mapping NEG
    • IP_ADDRESS: the IP address of the forwardingrule, which must come from the IP address range of the producer subnet

Publish the port mapping service

To make your port mapping service available to consumers,publish the serviceby creating a service attachment. When you create the service attachment,specify the forwarding rule that is associated with your port mapping service.

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 2025-12-17 UTC.