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 virtual machine (VM) instances 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.
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 beta 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 NEGREGION
: the region of the port mapping NEGNETWORK
: the VPC network of the port mapping NEGSUBNET
: the subnet of the port mapping NEG
API
Send a POST
request to the
regionNetworkEndpointGroups.insert
method.
POST https://compute.googleapis.com/compute/beta/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 NEGREGION
: the region of the port mapping NEGNEG
: the name of the port mapping NEGNETWORK
: the VPC network of the port mapping NEGSUBNET
: 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.
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 beta 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 NEGREGION
: the region of the port mapping NEGCLIENT_DESTINATION_PORT_1
: the client destination port of the first network endpointPROJECT_ID
: the project ID of the producer projectZONE_1
: the zone of the first network endpointVM_1_NAME
: the name of the destination VM for the first network endpointVM_1_PORT
: the service port of the first network endpointCLIENT_DESTINATION_PORT_2
: the client destination port of the second network endpointZONE_2
: the zone of the second network endpointVM_2_NAME
: the name of the destination VM for the second network endpointVM_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/beta/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 projectREGION
: the region of the port mapping NEGNEG
: the name of the port mapping NEGCLIENT_DESTINATION_PORT_1
: the client destination port of the first network endpointZONE_1
: the zone of the first network endpointVM_1_NAME
: the name of the destination VM for the first network endpointSERVICE_PORT_1
: the service port of the first network endpointCLIENT_DESTINATION_PORT_2
: the client destination port of the second network endpointZONE_2
: the zone of the second network endpointVM_2_NAME
: the name of the destination VM for the second network endpointSERVICE_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.
- 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 beta compute backend-services create SERVICE \ --load-balancing-scheme=internal \ --region=REGION \ --network=NETWORK
Replace the following:
SERVICE
: the name of the backend serviceREGION
: the region of the backend serviceNETWORK
: 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 beta 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 beta 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 rulePROTOCOL
: the protocol of the forwarding rule, which can be eitherTCP
orUDP
SUBNET
: the producer subnet, which must be the same subnet that's associated with the port mapping NEGIP_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 theregionBackendServices.insert
method.POST https://compute.googleapis.com/compute/beta/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 projectREGION
: the region of the backend serviceSERVICE
: the name of the backend serviceNETWORK
: the producer VPC network
To add your port mapping NEG to the backend service, send a
PATCH
request to theregionBackendServices.patch
method.You can't add multiple port mapping NEGs to a single backend service.
PATCH https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/regions/REGION/backendServices/SERVICE { "backends": [ { "group": "https://compute.googleapis.com/compute/beta/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 theforwardingRules.insert
method.The forwarding rule must be configured to forward traffic for all client destination ports.
POST https://compute.googleapis.com/compute/beta/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 rulePROTOCOL
: the protocol of the forwarding rule, which can be eitherTCP
orUDP
SUBNET
: the producer subnet, which must be the same subnet that's associated with the port mapping NEGIP_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.