Create port mapping services

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

Private Service Connect port mapping lets consumer clients privately communicate with specific service ports on specific producer VMs through a single Private Service Connect endpoint.

Before you begin

You must enable the Compute Engine API in your project.
You must create VMs for each of the network endpoints that you want to attach to the port mapping NEG. The VMs must all be in the same region.
Read About published services.
Read About Private Service Connect port mapping.

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:

Compute Load Balancer Admin (roles/compute.loadBalancerAdmin)
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.

Create and publish a port mapping service

Port mapping services have similar configurations to internal passthrough Network Load Balancers, but traffic is not load balanced. To create and publish a port mapping service, do the 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

A port mapping network NEG is a regional NEG with the network endpoint type of GCE_VM_IP_PORTMAP. It's not 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 that you associate with the port mapping NEG must have a primary network interface in this subnet.

Console

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

Go to Network Endpoint Groups
Click Create network endpoint group.
Enter a Name.
Click Network endpoint group type, and then select Port mapping NEG (Regional).
Select a Region.
Select a Network.
Select a Subnetwork.
Click Create.

gcloud

Use the network-endpoints-groups create command.

gcloud compute network-endpoint-groups create NEG \
    --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 the port mapping NEG
SUBNET: the subnet of the port mapping NEG

API

Send a POST request to the regionNetworkEndpointGroups.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 mapping NEG
REGION: the region of the port mapping NEG
NEG: the name of the port mapping NEG
NETWORK: the VPC network of the port 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 to the port mapping NEG.

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

Each network endpoint refers to a Compute Engine VM that has a 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 port and VM.

Console

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

Go to Network Endpoint Groups
Click the name of the port mapping NEG that you want to update.
Click Add network endpoints.
Click VM instance, and then select a VM.
Click VM port 1, and then enter a service port.
Click Client port 1, and then enter a client destination port.
For each additional network endpoint that you want to add, click Add network endpoint, and then enter the network endpoint details.
Click Create.

gcloud

Use the network-endpoint-groups update command. Include an --add-endpoint flag for each network endpoint that you want to attach.

gcloud compute network-endpoint-groups update NEG \
    --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 destination port of the first network endpoint
PROJECT_ID: the project ID of the producer project
ZONE_1: the zone of the first network endpoint
VM_1_NAME: the name of the destination VM for the first network endpoint
VM_1_PORT: the service port of the first network endpoint
CLIENT_DESTINATION_PORT_2: the client destination port of the second network endpoint
ZONE_2: the zone of the second network endpoint
VM_2_NAME: the name of the destination VM for the second network endpoint
VM_2_PORT: the service port of the second network endpoint

API

Send a POST request to the regionNetworkEndpointGroups.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 producer project
REGION: the region of the port mapping NEG
NEG: the name of the port mapping NEG
CLIENT_DESTINATION_PORT_1: the client destination port of the first network endpoint
ZONE_1: the zone of the first network endpoint
VM_1_NAME: the name of the destination VM for the first network endpoint
SERVICE_PORT_1: the service port of the first network endpoint
CLIENT_DESTINATION_PORT_2: the client destination port of the second network endpoint
ZONE_2: the zone of the second network endpoint
VM_2_NAME: the name of the destination VM for the second network endpoint
SERVICE_PORT_2: the service port of the second network 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 a backend service after you add the NEG. However, you can update 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

In the Google Cloud console, go to the Load balancing page.

Go to Load balancing
Click Create load balancer.
For Type of load balancer, select Network Load Balancer (TCP/UDP/SSL) and click Next.
For Proxy or passthrough, select Passthrough load balancer and click Next.
For Public facing or internal, select Internal and click Next.
Click Configure.

Basic configuration

Enter a Load balancer name.
Select a Region.
Select a Network.

Backend configuration

For Backend type, select Port mapping network endpoint group.
Select a Port mapping network endpoint group.

Frontend configuration

Click Frontend configuration.
Optional: Enter a Name.
Optional: Enter a Description.
Select a Protocol.
Select a Subnetwork.
Click Done.
Click Create.

gcloud

To create a backend service, use the backend-services create command.
```
gcloud compute backend-services create SERVICE \
    --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 VPC network of the backend service
To add your port mapping NEG to the backend service, use the backend-services add-backend command.

You can't add multiple port mapping NEGs to a single backend service.
```
gcloud compute backend-services add-backend SERVICE \
    --network-endpoint-group=NEG \
    --network-endpoint-group-region=REGION
```
Replace NEG with the name of the port mapping NEG.
To create a forwarding rule for your port mapping service, use the forwarding-rules create command.

The forwarding rule must be configured to forward traffic for all client destination ports.
```
gcloud compute forwarding-rules create RULE \
    --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 either TCP or UDP
- SUBNET: the producer subnet, which must be the same subnet that's associated with the port mapping NEG
- IP_ADDRESS: the IP address of the forwarding rule, which must come from the IP address range of the producer subnet

API

To create a backend service, send a POST request to the regionBackendServices.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's project
- REGION: the region of the backend service
- SERVICE: the name of the backend service
- NETWORK: the producer VPC network

To add your port mapping NEG to the backend service, send a PATCH request to the regionBackendServices.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"
    }
  ]
}

Replace NEG with the name of your port mapping NEG.

To create a forwarding rule for your port mapping service, send a POST request to the forwardingRules.insert method.

The forwarding rule must be configured 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 either TCP or UDP
- SUBNET: the producer subnet, which must be the same subnet that's associated with the port mapping NEG
- IP_ADDRESS: the IP address of the forwarding rule, 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 service by 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

Update a port mapping service