Serverless network endpoint groups overview

A network endpoint group (NEG) specifies a group of backend endpoints for a load balancer. A serverless NEG is a backend that points to a Cloud Run, App Engine, Cloud Functions, or API Gateway service.

A serverless NEG can represent one of the following:

A Cloud Run service or a group of services.
A Cloud Functions function or a group of functions.
An App Engine app (Standard or Flex), a specific service within an app, a specific version of an app, or a group of services.
An API Gateway that provides access to your services through a REST API consistent across all services, regardless of service implementation. This capability is in Preview.

Use cases

Serverless NEGs are supported with the following load balancers:

Global external HTTP(S) load balancer and global external HTTP(S) load balancer (classic): Cloud Run, App Engine, and Cloud Functions are supported.
Regional external HTTP(S) load balancer: Only Cloud Run is supported.
Internal HTTP(S) load balancer: Only Cloud Run is supported.

When your HTTP(S) load balancer is enabled for serverless apps, you can do the following:

Configure your serverless app to serve from a dedicated IPv4 IP address that is not shared with other services.
Map a single URL to multiple serverless functions or services that serve at the same domain. In this document, see URL masks.
Share URL space with other Google Cloud compute platforms. By using multiple backend services, a single load balancer can send traffic to multiple backend types. The load balancer selects the correct backend service based on the host or path of the request URL.
Reuse the same SSL certificates and private keys that you use for Compute Engine, Google Kubernetes Engine, and Cloud Storage. Reusing the same certificates eliminates the need to manage separate certificates for serverless apps.

Global external HTTP(S) load balancer and global external HTTP(S) load balancer (classic)

Setting up a global external HTTP(S) load balancer or a global external HTTP(S) load balancer (classic) enables your serverless apps to integrate with existing cloud services. You can do the following:

Protect your service with Google Cloud Armor, an edge DDoS defense/WAF security product available to all services accessed through an external HTTP(S) load balancer. There are some limitations associated with this capability, especially for Cloud Run and App Engine.
Enable your service to optimize delivery using Cloud CDN. Cloud CDN caches content close to your users. Cloud CDN provides capabilities like cache invalidation and Cloud CDN signed URLs.
Use Google's Edge infrastructure to terminate user's HTTP(S) connections closer to the user, thus decreasing latency.

To learn how to configure a load balancer with a serverless compute backend, see the following documentation:

Integrating an external HTTP(S) load balancer with API Gateway enables your serverless backends to take advantage of all the features provided by Cloud Load Balancing. For more information, see External HTTP(S) load balancer for API Gateway. To configure an external HTTP(S) load balancer to route traffic to an API Gateway, see Getting started with an external HTTP(S) load balancer for API Gateway. This capability is in Preview.

Regional external HTTP(S) load balancer

Using a regional external HTTP(S) load balancer lets you run workloads with regulatory or compliance requirements on Cloud Run backends. For example, if you require that your application's network configurations and traffic termination reside in a specific region, a regional external HTTP(S) load balancer is often the preferred option to comply with the necessary jurisdictional controls.

To learn how to configure a regional external HTTP(S) load balancer with a serverless compute backend, see Set up a regional external HTTP(S) load balancer with Cloud Run.

Internal HTTP(S) load balancer

When an internal HTTP(S) load balancer is configured with Cloud Run backends, you can do the following:

Enable advanced traffic management features such as fault injection, header rewrites, redirects, traffic splitting, and more, for your Cloud Run services.
Seamlessly migrate legacy services from Compute Engine, GKE, or on-premises, to Cloud Run and take advantage of weight-based traffic splitting to gradually shift traffic to Cloud Run without any downtime.
Protect your Cloud Run services with VPC Service Controls.
Establish a single, policy-enforcing internal ingress point for your services running in Cloud Run, Compute Engine, and GKE.

To learn how to configure an internal HTTP(S) load balancer with a serverless compute backend, see Set up an internal HTTP(S) load balancer with Cloud Run.

The rest of this page discusses how to use serverless NEGs with your HTTP(S) load balancers.

For more information about other types of NEGs, see Network endpoint groups overview.

Endpoint types

Serverless NEGs do not have any network endpoints such as ports or IP addresses. They can only point to an existing Cloud Run, App Engine, API Gateway, or Cloud Functions service residing in the same region as the NEG.

When you create a serverless NEG, you specify the fully qualified domain name (FQDN) of the Cloud Run, App Engine, API Gateway, or Cloud Functions service. The endpoint is of type SERVERLESS. Other endpoint types are not supported in a serverless NEG.

A serverless NEG cannot have more than one endpoint. The endpoint points to either a serverless application or a URL mask. The load balancer serves as the frontend for the serverless compute application and proxies traffic to the specified endpoint. However, if the backend service contains multiple serverless NEGs in different regions, the load balancer sends traffic to the NEG in the closest region to minimize request latency.

Network tier

For global external HTTP(S) load balancers, you can use a serverless NEG in a load balancer using either Standard or Premium Network Service Tiers. The Premium Tier is required only if you want to set up serverless NEGs in multiple regions.

Regional external HTTP(S) load balancers are always Standard Tier.

Internal HTTP(S) load balancers are always Premium tier.

Load balancing components

A load balancer using a serverless NEG backend requires special configuration only for the backend service. The frontend configuration is the same as any other proxy-based Google Cloud load balancer. Additionally, internal HTTP(S) load balancers require a proxy-only subnet to run Envoy proxies on your behalf.

The following diagrams show a sample serverless NEG deployment.

External HTTP(S)

This diagram shows how a serverless NEG fits into a global external HTTP(S) load balancer architecture.

This diagram shows how a serverless NEG fits into a regional external HTTP(S) load balancer architecture.

Regional external HTTP(S) load balancing for serverless apps

Internal HTTP(S)

This diagram shows how a serverless NEG fits into the internal HTTP(S) load balancer model.

Simple HTTPS Load Balancing (click to enlarge) — Internal HTTP(S) Load Balancing for serverless apps

Frontend components

No special frontend configuration is required for load balancing with serverless NEG backends. Forwarding rules are used to route traffic by IP address, port, and protocol to a target proxy. The target proxy then terminates connections from clients.

URL maps are used by HTTP(S) load balancers to set up URL-based routing of requests to the appropriate backend services.

For more details on each of these components, refer the architecture sections of the specific load balancer overviews:

Backend service

Backend services provide configuration information to the load balancer. Load balancers use the information in a backend service to direct incoming traffic to one or more attached backends. Serverless NEGs can be used as backends for certain load balancers.

A global backend service (used by global external HTTP(S) load balancers) can have several serverless NEGs attached to it, but only one serverless NEG per region. A regional backend service (used by internal HTTP(S) load balancers and regional external HTTP(S) load balancers) can only have one serverless NEG attached to it.

Each serverless NEG can point to either of the following:

The FQDN for a single function or service
A URL mask that points to multiple functions or services that serve at the same domain

A URL mask is a URL schema template that tells the serverless NEG backend how to map the user request to the correct service. URL masks are useful if you are using a custom domain for your serverless application and have multiple services serving at the same domain. Instead of creating a separate serverless NEG for each function or service, you can create the NEG with a generic URL mask for the custom domain. For more information and examples, see URL masks.

For additional restrictions when adding a serverless NEG as a backend, see Limitations.

URL masks

A serverless NEG backend can point to either a single Cloud Run (or App Engine or Cloud Functions if applicable) service, or a URL mask that points to multiple services. A URL mask is a template of your URL schema. The serverless NEG uses this template to map the request to the appropriate service.

URL masks are an optional feature that make it easier to configure serverless NEGs when your serverless application is comprised of multiple Cloud Run, Cloud Functions, or App Engine services. Serverless NEGs used with internal HTTP(S) load balancers can only use a URL mask that points to Cloud Run services.

URL masks are useful if your serverless app is mapped to a custom domain rather than the default address that Google Cloud provides. With a custom domain such as example.com, you could have multiple services deployed to different subdomains or paths on the same domain. In such cases, instead of creating a separate serverless NEG backend for each service, you can create a single serverless NEG with a generic URL mask for the custom domain (for example, example.com/<service>). The NEG extracts the service name from the request's URL.

The following illustration shows an external HTTP(S) load balancer with a single backend service and serverless NEG, that uses a URL mask to map user requests to different services.

Distributing traffic to serverless apps (click to enlarge) — Using a URL mask to distribute traffic to different services

URL masks work best when your application's services use a predictable URL schema. The advantage of using a URL mask instead of a URL map is that you don't need to create separate serverless NEGs for the login and search services. You also don't need to modify your load balancer configuration each time you add a new service to your application.

To learn how to construct and configure a URL mask for a serverless NEG, see the following:

Limitations

A serverless NEG cannot have any network endpoints such as IP address or port.
Serverless NEGs can point only to serverless applications residing in the same region where the NEG is created.
For a load balancer that is using a Serverless NEG backend, the serverless NEG must be created in the same project as the backing Cloud Run, App Engine, API Gateway, or Cloud Functions services pointed to by the NEG. You might see requests failing if you connect a service that is not in the same project as the serverless NEG.
A load balancer configured with a serverless NEG cannot detect whether the underlying serverless app or service is working as expected. This means that even if your service is returning errors, the load balancer continues to direct traffic to it. Make sure to thoroughly test new versions of your services before routing user traffic to them.

Limitations with backend services

The following limitations apply to backend services that have a serverless NEG backend:

A global backend service can have one serverless NEG per region. To combine multiple serverless NEGs in a single backend service, all the NEGs must represent functionally equivalent deployments in different regions. For example, the NEGs can point to the same Cloud Run, App Engine, or Cloud Functions service deployed in different regions.
A regional backend service can only have one serverless NEG attached to it.
The backend service must be created in the same project as the serverless NEG and the backing Cloud Run, App Engine, API Gateway, or Cloud Functions service. If you're setting up a Shared VPC deployment with cross-project service referencing, the load balancer's frontend components (IP address, forwarding rule, target proxy, and URL map) can be created in a different project.
The backend service timeout setting does not apply to backend services with serverless NEG backends. Attempting to modify the backend service's resource.timeoutSec property results in the following error: Timeout sec is not supported for a backend service with Serverless network endpoint groups.
For backend services with serverless NEG backends, the default timeout is 60 minutes. This timeout is not configurable. If your application needs long-running connections, configure your clients to retry requests on failure.
All serverless NEGs combined in a backend service must also use the same type of backend. This means Cloud Run serverless NEGs can only be combined with other Cloud Run serverless NEGs, App Engine serverless NEGs can only be combined with App Engine serverless NEGs, etc.
You cannot mix serverless NEGs with other types of NEGs (zonal or internet NEGs) in the same backend service. For example, you cannot route to a GKE cluster and a Cloud Run service from the same backend service.
When setting up backend services that route to serverless NEGs, certain fields are restricted:
- You cannot specify a balancing mode. That is, the RATE,UTILIZATION, and CONNECTION values have no effect on the load balancer's traffic distribution.
- Health checks are not supported for serverless backends. Therefore, backend services containing serverless NEG backends cannot be configured with health checks.
You cannot use the gcloud compute backend-services edit command to modify a backend service with a serverless NEG backend. As a workaround, use the gcloud compute backend-services update command instead.

Additional limitations apply depending on the type of load balancer and the serverless backend.

Limitations with internal HTTP(S) load balancers and regional external HTTP(S) load balancers

Serverless NEGs used with internal HTTP(S) load balancers or regional external HTTP(S) load balancers can only point to Cloud Run services.
For projects that are using serverless NEGs, the queries per second (QPS) limit is 1000 QPS per project for traffic sent to any serverless NEGs configured with regional external HTTP(S) load balancers or internal HTTP(S) load balancers. This limit is aggregated across all regional HTTP(S) load balancers in the project. This is not a per load balancer limit.

Limitations with global external HTTP(S) load balancers

Limitations with Cloud Run

An external HTTP(S) load balancer with serverless NEGs does not support Cloud Run for Anthos.
External HTTP(S) load balancers don't support authenticated requests to Cloud Run services.

Limitations with Cloud Functions

IAP does not work with Cloud Functions.

Limitations with App Engine

Multi-region load balancing is not supported with App Engine. This is because App Engine requires 1 region per project.
Only one IAP policy is allowed on the request path. For example, if you have already set an IAP policy in the backend service, you should not set another IAP policy on the App Engine app.

We recommend that you use ingress controls so that your app only receives requests sent from the load balancer (and the VPC if you use it). Otherwise, users can use your app's App Engine URL to bypass the load balancer, Google Cloud Armor security policies, SSL certificates, and private keys that are passed through the load balancer.

Limitations with API Gateway

For more information, see Limitations on serverless NEGs and API Gateway.

Pricing

To see pricing information for load balancers with serverless NEGs, see All networking pricing: Cloud Load Balancing.