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, or Cloud Functions service.

A serverless NEG can represent:

  • A Cloud Run service or a group of services sharing the same URL pattern.
  • A Cloud Functions function or a group of functions sharing the same URL pattern.
  • An App Engine app (Standard or Flex), a specific service within an app, or even a specific version of an app.

When HTTP(S) Load Balancing is enabled for serverless apps, you can:

  • Configure your serverless app to serve from a dedicated IPv4 and/or IPv6 IP address that is not shared with other services.
  • Map a single URL to several services running in different regions, allowing requests to be routed to the region closest to the user. This is supported only for Cloud Run (fully managed).
  • Reuse the same SSL certificates and private keys that you use for Compute Engine, Google Kubernetes Engine and Cloud Storage. This eliminates the need to manage separate certificates for serverless apps.

Setting up HTTP(S) Load Balancing also enables your serverless apps to integrate with existing Cloud services. You can:

  • Share URL space with other Google Cloud technologies. By using multiple backend services, a single external HTTP(S) load balancer can send traffic to Cloud Run (fully managed), App Engine, Cloud Functions, Compute Engine, Google Kubernetes Engine and Cloud Storage based on the host or path of the request URL.
  • Protect your service with Google Cloud Armor, an edge DDoS defense/WAF security product available to all services accessed through a external HTTP(S) load balancer. Note that there are some limitations associated with this capability, especially for Cloud Run (fully managed) and App Engine.
  • Enable your service to optimize delivery using Cloud CDN. With Cloud CDN, you can cache 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.

The rest of this document discusses how to use serverless NEGs with HTTP(S) Load Balancing. You cannot use serverless NEGs with other load balancer types.

For more information about other types of NEGs, see:

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 (fully managed), App Engine, 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 (fully managed), App Engine, 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. Because only one endpoint is allowed in each serverless NEG, the load balancer serves as the frontend only, and proxies traffic to the specified serverless endpoint. However, if the backend service contains multiple serverless NEGs, the load balancer balances traffic between these NEGs, thus minimizing request latency.

Network tier

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.

Load balancing components

This is how a serverless NEG fits into the HTTP(S) Load Balancing model.

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

Forwarding rule

The forwarding rule is part of the frontend configuration and contains an external IP address, the IP version (IPv4 or IPv6), a protocol (HTTP or HTTPS (includes HTTP/2), and a port number (80 or 443).

Target proxy

Serverless NEGs can only be used with HTTP and HTTPS target proxies. Services that use serverless NEGs cannot be used with TCP or SSL target proxies.

URL map

The forwarding selection for an external HTTP(S) load balancer is based on a URL map. With a URL map, target HTTP(S) proxies determine the backend service to be used by checking the request host name and path in the URL map. Load balancers can have multiple backend services referenced from the URL map. Each backend service can be associated with a different backend type. For example, you can have a backend service for a serverless NEG and another backend service for Compute Engine instance groups.

Backend service

Serverless NEGs can be used as backends for backend services in a load balancer. A backend service can be backed by several serverless NEGs, but each serverless NEG can only point to either the FQDN for a single Cloud Run (fully managed) (or App Engine or Cloud Functions service, or a URL mask that points to multiple services serving 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 application and have multiple Cloud Run (fully managed), Cloud Functions, or App Engine services serving at the same domain. In such cases, instead of creating a separate serverless NEG for each Cloud Run (fully managed), App Engine, or Cloud Functions service, you can create the NEG with a generic URL mask for the custom domain (for example, example.com/<service>) and allow the NEG to extract the service name from the request's URL. For more information and examples, see URL Masks.

There are additional restrictions to keep in mind when adding a serverless NEG as a backend. For more information, see Limitations.

URL Masks

URL masks are an optional feature that make it easier to configure serverless NEGs when your application consists of multiple Cloud Run (fully managed), Cloud Functions, or App Engine services. A serverless NEG backend can point to either a single Cloud Run (fully managed) (or App Engine or Cloud Functions) service, or a URL mask that points to multiple services.

A URL mask is a template of your URL schema. The serverless NEG will use this template (for example, example.com/<service>) to extract the service name from the incoming request's URL and map the request to the appropriate service.

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 Cloud Run (fully managed), Cloud Functions, or App Engine services deployed to different subdomains or paths on the same domain. In such cases, instead of creating a separate serverless NEG backend for each Cloud Run (fully managed), App Engine, or Cloud Functions service, you can create a single serverless NEG with a generic URL mask for the custom domain (for example, example.com/<service>) and allow the NEG to extract 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 Setting up serverless NEGs.

Limitations

  • You cannot use the Google Cloud Console to create a serverless NEG. Use either the gcloud command-line tool or the API. For conceptual and installation information about the tool, see gcloud Overview.
  • A serverless NEG cannot have any network endpoints such as IP address or port.
  • Serverless NEGs can point only to Cloud Run (fully managed), App Engine, or Cloud Functions services residing in the same region where the NEG is created.
  • Load balancers using serverless NEG backends must be created in the same project as the Cloud Run (fully managed), App Engine, or Cloud Functions services pointed to by the NEG.
  • Cloud Monitoring is not supported for serverless NEG backends. Backend services with other types of backends are not impacted.
  • An external HTTP(S) load balancer configured with a serverless NEG cannot detect if the underlying serverless resource (such as an App Engine, Cloud Functions, or Cloud Run (fully managed) service) is working as expected. This means that if your service in one region is returning errors but the overall Cloud Run (fully managed), Cloud Functions, or App Engine infrastructure in that region is operating normally, your external HTTP(S) load balancer will not automatically direct traffic away to other regions. Make sure you thoroughly test new versions of your services before routing user traffic to them.

Limitations associated with backend services that have a serverless NEG backend:

  • A backend service may only contain one serverless NEG per region. If you want 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 (fully managed), App Engine, or Cloud Functions service deployed in different regions.
  • You cannot modify the default 30-second backend service timeout of a serverless NEG backend service. Attempting to modify the backend service configuration to increase the timeout (by setting the resource.timeoutSec property) results in the following error: Timeout sec is not supported for a backend service with Serverless network endpoint groups.
  • All serverless NEGs combined in a backend service must also use the same type of backend. This means Cloud Run (fully managed) serverless NEGs can only be combined with other Cloud Run (fully managed) 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, this means that you cannot route to a GKE cluster and a Cloud Run (fully managed) 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.

Additional limitations might apply depending on the serverless compute platform you are using.

Limitations with Cloud Run (fully managed)

  • Identity-Aware Proxy (IAP) does not work with Cloud Run (fully managed).
  • You cannot disable the URLs Google Cloud automatically assigns to Cloud Run (fully managed) services. Users who already have the Cloud Run (fully managed) service's default URL can bypass the load balancer and go directly to the service URL. This means that even though you can configure Google Cloud Armor security policies through the load balancer, users with the default URL can circumvent these policies.

Limitations with Cloud Functions

  • IAP does not work with Cloud Functions.
  • You cannot disable the URLs Google Cloud automatically assigns to Cloud Functions functions. However, you can use the internal-and-gclb ingress setting to allow only internal traffic and traffic sent to a public IP exposed by the external HTTP(S) load balancer. Traffic sent to cloudfunctions.net or any other custom domain set up through Cloud Functions is blocked. This prevents users from circumventing any access controls (such as Google Cloud Armor security policies) set up through the external HTTP(S) load balancer.

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.

  • You cannot disable the URLs Google Cloud automatically assigns to App Engine services. Users who already have the App Engine service's default URL can bypass the load balancer and go directly to the service URL. This means that even though you can configure Google Cloud Armor security policies, SSL certificates, and private keys through the load balancer, users with the default URL can circumvent these policies.

Pricing

To see pricing information for external HTTP(S) load balancers with serverless NEGs, see Network Pricing.

What's next