Setting up zonal NEGs

This document contains instructions for configuring zonal network endpoint groups (NEGs). Before you configure zonal NEGs, read Network endpoint groups overview.

Load balancing with zonal NEGs

Zonal NEGs can be used as backends for backend services in the following types of load balancers:

  • An external HTTP(S) load balancer
  • An internal HTTP(S) load balancer
  • An SSL proxy load balancer
  • A TCP proxy load balancer

For more information about load balancing with zonal NEGs, see Zonal NEGs overview: Load balancing.

The primary use case for zonal NEGs is container-native load balancing so that you can distribute traffic among microservices running in containers on your VMs. Container-native load balancing enables load balancers to target Pods directly and to make load distribution decisions at the Pod-level instead of at the VM-level. There are two ways to configure container-native load balancing: either use NEGs managed by GKE Ingress, or use standalone NEGs.

For instructions, see:

Configuring zonal network endpoint groups (NEGs) and adding endpoints

The rest of this page describes how to configure zonal NEGs before or after you've already created a load balancer. Note that some of these actions do not apply to zonal NEGs created and managed by Ingress.

Creating zonal network endpoint groups

Console

To create a zonal network endpoint group:

  1. Go to the Network Endpoint Groups page in the Google Cloud Console.
    Go to the Network Endpoint Groups page
  2. Click CREATE NETWORK ENDPOINT GROUP.
  3. For the Network endpoint group type, select Network endpoint type: Zonal.
  4. Enter the Name of the network endpoint group.
  5. Select the VPC Network location.
  6. Select the VPC network.
  7. Select the Subnet.
  8. Select the Zone.
  9. Select the Network endpoint type.
  10. Enter the Network endpoint default port.
  11. Click Create

gcloud

To create a zonal network endpoint group:

gcloud compute network-endpoint-groups create NEG_NAME \
    --zone=ZONE \
    --network=NETWORK
    [--subnet=SUBNET]
    [--default-port=DEFAULT_PORT]

In this command, the flags are defined as follows:

  • NEG_NAME is the name of the new network endpoint group. The name must be unique within the zone.
  • ZONE is the name of the zone in which the NEG is created.
  • NETWORK is the name of the network in which the NEG is created. If omitted, Google Cloud uses a network named default.
  • SUBNET is the name of the subnet to which the network endpoints belong. This flag is optional if the network is an auto mode network. If omitted, the NEG resides in the automatically-created subnet of the selected zone's region. The flag is required if the network is a custom mode network or if you need to specify a manually-created subnet.
  • DEFAULT_PORT is the default port associated with the NEG. This flag is optional. If omitted, all endpoints must be specified by IP:port. If included, the port portion can be omitted from the endpoint specification and the default port is assumed.

For example:

gcloud compute network-endpoint-groups create my-lb-neg \
    --network=my-network \
    --subnet=my-subnet \
    --default-port=80  \
    --zone=asia-southeast1-a

Adding endpoints to a network endpoint group

Console

To add endpoints to a network endpoint group:

  1. Go to the Network Endpoint Groups page in the Google Cloud Console.
    Go to the Network Endpoint Groups page
  2. Click the Name of the network endpoint group to which you want to add endpoints. You see the Network endpoint group detail page.
  3. In the Network endpoints in this group section, click Add network endpoint. You see the Add network endpoint page.
  4. Select a VM instance to add its internal IP addresses as network endpoints and click Add. You see the Network interface, zone, and subnet of the VM.
  5. Enter the IP address or range of the new network endpoint.
  6. Select the Port type.
    1. If you select Default, the endpoint uses the default port for all enpoints in the network endpoint group.
    2. If you select Custom, enter the Port number for the endpoint to use.
  7. To add more endpoints, click Add network endpoint and repeat steps 5 and 6.
  8. After you add all the endpoints that you need, click Add.

gcloud

To add endpoints to a network endpoint group:

gcloud compute network-endpoint-groups update NEG_NAME \
    [--zone=ZONE] \
    --add-endpoint 'instance=INSTANCE_NAME,[ip=IP_ADDRESS],[port=PORT]' \
    [--add-endpoint ...]

In the above command:

  • NEG_NAME is the name of the NEG.
  • ZONE is the name of the zone in which the NEG resides.
  • INSTANCE_NAME is the name of the VM to which the IP address belongs.
  • IP_ADDRESS is the IP address for the network endpoint being added.
  • PORT is the port of the network endpoint being added. The port is optional if default port is specified in the NEG.

For example:

gcloud compute network-endpoint-groups update my-lb-neg \
    --zone=asia-southeast1-a
    --add-endpoint 'instance=my-vm1,ip=10.1.1.1,port=80' \

Adding a zonal NEG to a backend service

Console

To add a network endpoint group to a backend service:

  1. Go to the Load balancing page in the Google Cloud Console.
    Go to the Load balancing page
  2. Click the name of the load balancer whose backend service you want to edit.
  3. On the Load balancer details page, click Edit .
  4. On the Edit load balancer page, click Backend configuration.
  5. On the Backend configuration page, click Edit .
  6. Click +Add backend.
  7. Select a Zonal network endpoint group and click Done.
  8. Click Update.

gcloud

To add a NEG to a backend service:

gcloud compute backend-services add-backend BACKEND_SERVICE \
    [--network-endpoint-group=NETWORK_ENDPOINT_GROUP] \
    [--network-endpoint-group-zone=ZONE]

For example:

gcloud compute backend-services add-backend my-lb \
   --network-endpoint-group my-lb-neg \
   --network-endpoint-group-zone=asia-southeast1-a \
   --global \
   --balancing-mode=RATE \
   --max-rate-per-endpoint=5

Removing a NEG from a backend service

Console

  1. Go to the Load balancing page in the Google Cloud Console.
    Go to the Load balancing page
  2. Click the name of the load balancer whose backend service you want to edit.
  3. On the Load balancer details page, click Edit .
  4. On the Edit load balancer page, click Backend configuration.
  5. On the Backend configuration page, click Edit for the backend service from which you are removing the NEG.
  6. In the Backend section, locate the NEG you want to remove and click the trash can icon for that NEG.
  7. Click Update.

gcloud

To remove a NEG from a backend service:

gcloud compute backend-services remove-backend BACKEND_SERVICE \
    --network-endpoint-group=NETWORK_ENDPOINT_GROUP \
    --network-endpoint-group-zone=NETWORK_ENDPOINT_GROUP_ZONE

For example:

gcloud compute backend-services remove-backend my-lb \
    --network-endpoint-group=my-lb-neg \
    --network-endpoint-group-zone=asia-southeast1-a

Removing endpoints from a network endpoint group

When a network endpoint is removed from a load balancing NEG, it triggers connection draining based on the drain parameters specified in the backend service. If multiple backend services refer to the same NEG, the maximum drain interval across all backend services is applied.

Console

To remove endpoints from a network endpoint group:

  1. Go to the Network Endpoint Groups page in the Google Cloud Console.
    Go to the Network Endpoint Groups page
  2. Click the Name of the network endpoint group from which you want to delete endpoints. You see the Network endpoint group detail page.
  3. Select the network endpoints you want to delete and click Remove endpoint.

gcloud

To remove endpoints from a network endpoint group:

gcloud compute network-endpoint-groups update NEG_NAME \
[--zone=ZONE] \
--remove-endpoint 'instance=INSTANCE_NAME,[ip=IP],[port=PORT]' \
--remove-endpoint ...

For example:

gcloud compute network-endpoint-groups update my-lb-neg \
     --remove-endpoint 'instance=my-vm1,ip=10.1.1.1,port=80' \
     --zone=asia-southeast1-a

Listing network endpoint groups

Console

To view a list of network endpoint groups, go to the Network Endpoint Groups page in the Google Cloud Console.
Go to the Network Endpoint Groups page

gcloud

To list network endpoint groups:

gcloud compute network-endpoint-groups list

Describing a specific network endpoint group

Console

To get the details of a specific network endpoint group:

  1. Go to the Network Endpoint Groups page in the Google Cloud Console.
    Go to the Network Endpoint Groups page
  2. Click the name of the network endpoint group whose details you want to see.

gcloud

To get the details of a specific network endpoint group:

gcloud compute network-endpoint-groups describe NEG_NAME \
    [--zone=ZONE]

In the above command:

  • NEG_NAME is the name of the network endpoint group.
  • ZONE, which is optional, is the name of the zone where the NEG was created.

For example, the following gcloud command lists information about the network endpoint group my-lb-neg.

gcloud compute network-endpoint-groups describe my-lb-neg \
    --zone=asia-southeast1-a

The output of the command is the following:

    creationTimestamp: '2018-04-09T14:51:34.381-07:00'
    id: '5260475207627726473'
    kind: compute#networkEndpointGroup
    loadBalancer:
      defaultPort: 80
      network: https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/global/networks/default
      zone: https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/asia-southeast1-a

Removing network endpoint groups

A network endpoint group cannot be deleted if it is attached to a backend service. Before you delete a NEG, ensure that it is detached from the backend service.

Deleting a VM immediately causes all network endpoints on the VM to be removed from the NEG, closing all connections. Deleting a NEG after deleting a backend service also removes all endpoints in that NEG without connection draining.

Console

To remove a network endpoint group from a backend service:

  1. Go to the Load balancing page in the Google Cloud Console.
    Go to the Load balancing page
  2. Click the name of the load balancer whose backend service you want to edit.
  3. On the Load balancer details page, click Edit .
  4. On the Edit load balancer page, click Backend configuration.
  5. On the Backend configuration page, click Edit for the backend service from which you are removing the NEG.
  6. In the Backend section, locate the NEG you want to remove and click the trash can icon for that NEG.
  7. Click Update.

To delete a network endpoint group:

  1. Go to the Network Endpoint Groups page in the Google Cloud Console.
    Go to the Network Endpoint Groups page
  2. Locate the network endpoint group you want to delete.
  3. Click the trash can icon in that row.

gcloud

To remove a network endpoint group from a backend service:

gcloud compute backend-services remove-backend BACKEND_SERVICE \
    [--network-endpoint-group=NETWORK_ENDPOINT_GROUP] \
    [--network-endpoint-group-zone=ZONE]

To delete a network endpoint group:

gcloud compute network-endpoint-groups delete NEG_NAME \
    --zone=ZONE

For example:

gcloud compute backend-services remove-backend my-neg-backend \
    --network-endpoint-group=my-lb-neg \
    --network-endpoint-group-zone=southeast1-a
gcloud compute network-endpoint-groups delete my-lb-neg \
    --zone=asia-southeast1-a

Listing endpoints in a network endpoint group

Console

To view a list of endpoints in a network endpoint group:

  1. Go to the Network Endpoint Groups page in the Google Cloud Console.
    Go to the Network Endpoint Groups page
  2. Click the Name of the network endpoint group from which you want to delete endpoints. You see the Network endpoint group detail page, on which the endpoints for the endpoint group are listed.
  3. To filter the endpoints, create key:value pairs in the text field under Network endpoints in this group.

gcloud

To list all of the network endpoints in a network endpoint group:

gcloud compute network-endpoint-groups list-network-endpoints NEG_NAME \
    [--zone=ZONE]

Custom filtering when you list endpoints in a network endpoint group

Custom filtering is a beta feature.

You can use a custom filter to limit which endpoints in a network endpoint group are listed. Custom filtering is enabled only for the REST API. You cannot use custom filtering from the Cloud Console or using the gcloud command-line interface.

For details, see the documentation for the method networkEndpointGroups.listNetworkEndpoints.

Health checking network endpoints

Backend services with zonal NEG backends must use a health check whose port specification is either:

  • a fixed (numbered) port (--port)
  • configured to use the serving port of the network endpoint (--use-serving-port)

The example that follows creates a health check that uses the serving port of the network endpoint with the --use-serving-port flag. Note that the --use-serving-port flag is implemented with gcloud compute health-checks create, but not with gcloud compute health-checks update.

You cannot use a legacy health check with a zonal NEG backend. For more information, see Health Check Concepts.