Set up a regional internal Application Load Balancer with Cloud Run

This document shows you how to deploy a regional internal Application Load Balancer withCloud Run. To set this up, you use aserverless NEG backend for theload balancer.

Although this document describes a Cloud Run configuration, aserverless NEG for Cloud Run can point to either aCloud Run resource or a Cloud Run functions (2nd gen) resource.

Before you try this procedure, make sure you are familiar with the followingtopics:

This document shows you how to configure an Application Load Balancer that proxiesrequests to a serverless NEG backend.

Serverless NEGs let you useCloud Run services with your load balancer. After you configurea load balancer with the serverless NEG backend, requests to the load balancerare routed to the Cloud Run backend.

Before you begin

  1. Install the Google Cloud CLI
  2. Deploy a Cloud Run service
  3. Configure permissions

Install Google Cloud SDK

Install the Google Cloud CLItool. For conceptual and installation information about the gcloud CLI, seegcloud CLI overview.

If you haven't run the gcloud CLI previously, first rungcloud init to initialize your gcloud CLIdirectory.

Deploy a Cloud Run service

The instructions on this page assume you already have aCloud Run service running.

For the example on this page, you can useany of theCloud Run quickstarts to deploy aCloud Run service.

The serverless NEG, the load balancer, and any client VMs must be in the sameregion as the Cloud Run service.

To prevent access to the Cloud Run service from theinternet,restrict network ingress tointernal. Trafficfrom the internal Application Load Balancer is consideredinternal traffic.

gcloud run deployCLOUD_RUN_SERVICE_NAME \    --platform=managed \    --allow-unauthenticated \    --ingress=internal \    --region=REGION \    --image=IMAGE_URL

Note the name of the service that you create. The rest of this page shows youhow to set up a load balancer that routes requests to this service.

Configure permissions

To follow this guide, you need to create a serverless NEG and create aload balancer in a project. You must be either a projectowner oreditor, or you have the followingCompute Engine IAM roles andpermissions:

TaskRequired role
Create load balancer and networking componentsCompute Network Admin (roles/compute.networkAdmin)
Create and modify NEGsCompute Instance Admin (v1) (roles/compute.instanceAdmin.v1)
Create and modify SSL certificatesSecurity Admin (roles/iam.securityAdmin)

Configure the network and subnets

To configure the network and its subnets, perform the following tasks:

  • Create a Virtual Private Cloud (VPC) network and subnet.
  • Create a proxy-only subnet.

Create the VPC network

Create a custom mode VPC network, then the subnets that you wantwithin a region.

Console

  1. In the Google Cloud console, go to theVPC networks page.

    Go to VPC networks

  2. ClickCreate VPC network.

  3. ForName, enterlb-network.

  4. ForSubnet creation mode, selectCustom.

  5. In theNew subnet section, specify the following configurationparameters for a subnet:

    1. ForName, enterlb-subnet.
    2. Select aRegion.
    3. ForIP address range, enter10.1.2.0/24.
    4. ClickDone.

  6. ClickCreate.

gcloud

  1. Create the custom VPC network by using thegcloud computenetworks create command:

    gcloud compute networks create lb-network --subnet-mode=custom

  2. Create a subnet in thelb-network network. This example uses anIP address range of10.1.2.0/24 for the subnet. You can configureanyvalid subnet range.

    gcloud compute networks subnets create lb-subnet \    --network=lb-network \    --range=10.1.2.0/24 \    --region=REGION

Create a proxy-only subnet

Create a proxy-only subnet for allregional Envoy-based loadbalancers in aspecific region of thelb-network network.

Console

  1. In the Google Cloud console, go to theVPC networks page.

    Go to VPC networks

  2. Click the name of the Shared VPC network that you want to add theproxy-only subnet to.

  3. ClickAdd subnet.

  4. In theName field, enterproxy-only-subnet.

  5. Select aRegion.

  6. SetPurpose toRegional Managed Proxy.

  7. Enter anIP address range as10.129.0.0/23.

  8. ClickAdd.

gcloud

Create the proxy-only subnet by using thegcloud compute networks subnetscreate command.

This example uses an IP address range of10.129.0.0/23 for theproxy-only subnet. You can configure anyvalid subnetrange.

  gcloud compute networks subnets create proxy-only-subnet \      --purpose=REGIONAL_MANAGED_PROXY \      --role=ACTIVE \      --region=REGION \      --network=lb-network \      --range=10.129.0.0/23

Create the load balancer

In the following diagram, the load balancer uses a serverless NEG backendto direct requests to a serverless Cloud Run service.

Traffic going from the load balancer to the serverless NEG backends uses specialroutes defined outside your VPC that aren't subject to firewallrules. Therefore, if your load balancer only has serverless NEG backends, youdon't need to create firewall rules to allow traffic from the proxy-only subnetto the serverless backend.

Internal HTTP or HTTPS load balancing architecture for a Cloud Run application.
Internal HTTP or HTTPS load balancing architecture for a Cloud Run application (click to enlarge).

Console

Select the load balancer type

  1. In the Google Cloud console, go to theLoad balancing page.

    Go to Load balancing

  2. ClickCreate load balancer.
  3. ForType of load balancer, selectApplication Load Balancer (HTTP/HTTPS) and clickNext.
  4. ForPublic facing or internal, selectInternal and clickNext.
  5. ForCross-region or single region deployment, selectBest for regional workloads and clickNext.
  6. ClickConfigure.

Basic configuration

  1. For the name of the load balancer, enterserverless-lb.
  2. Select theNetwork aslb_network.
  3. Keep the window open to continue.

Configure the frontend

  1. Before you proceed, make sure you have anSSL certificate.
  2. ClickFrontend configuration.
  3. Enter aName.
  4. To configure an internal Application Load Balancer, fill in the fields as follows.
    1. ForProtocol, selectHTTPS.
    2. ForSubnetwork, select the subnetwork.
    3. ForIP version, selectIPv4.
    4. ForIP address, selectEphemeral.
    5. ForPort, select443.

    6. ForChoose certificate repository, selectClassic Certificates.

      The following example shows you how to create Compute Engine SSL certificates:

    7. ClickCreate a new certificate.
      1. In theName field, enter a name.
      2. In the appropriate fields, upload your PEM-formatted files:
        • Certificate
        • Private key
      3. ClickCreate.

    If you want to test this process without setting up an SSL certificate resource, you can set up an HTTP load balancer.

  5. Optional: To create an HTTP load balancer, do the following:
    1. ForProtocol, selectHTTP.
    2. ForSubnetwork, select the subnetwork.
    3. ForIP version, selectIPv4.
    4. ForIP address, selectEphemeral.
    5. ForPort, select80.
  6. ClickDone.

Configure the backend services

  1. ClickBackend configuration.
  2. In theCreate or select backend services menu, hold the pointer overBackend services, and then selectCreate a backend service.
  3. In theCreate a backend service window, enter aName.
  4. ForBackend type, selectServerless network endpoint group.
  5. LeaveProtocol unchanged. This parameter is ignored.
  6. ForBackends > New backend, selectCreate serverless network endpoint group.
    1. In theCreate serverless network endpoint group window, enter aName.
    2. ForRegion, the region of the load balancer is displayed.
    3. From theServerless network endpoint group type field, selectCloud Run. Cloud Run is the only supported type.
    4. SelectSelect service name.
    5. From theService list, select the Cloud Run service that you want to create a load balancer for.
    6. ClickDone.
    7. ClickCreate.

  7. Optional: Configure a default backend security policy. The default security policy throttles traffic over a user-configured threshold. For more information about default security policies, see theRate limiting overview.

    1. To opt out of the Cloud Armor default security policy, selectNone in theCloud Armor backend security policy list.
    2. To configure the Cloud Armor default security policy, selectDefault security policy in theCloud Armor backend security policy list.
    3. In thePolicy name field, accept the automatically generated name or enter a name for your security policy.
    4. In theRequest count field, accept the default request count or enter an integer between1 and10,000.
    5. In theInterval field, select an interval.
    6. In theEnforce on key field, choose one of the following values:All,IP address, orX-Forwarded-For IP address. For more information about these options, seeIdentifying clients for rate limiting.
  8. In theCreate backend service window, clickCreate.

Configure routing rules

Routing rules determine how your traffic is directed. You can direct traffic to a backend service or a Kubernetes service. Any traffic not explicitly matched with a host and path matcher is sent to the default service.

  1. ClickSimple host and path rule.
  2. Select a backend service from theBackend list.

Review the configuration

  1. ClickReview and finalize.
  2. Review the values forBackend,Host and Path rules andFrontend.
  3. Optional: ClickEquivalent Code to view the REST API request that will be used to create the load balancer.
  4. ClickCreate. Wait for the load balancer to be created.
  5. Click the name of the load balancer (serverless-lb).
  6. Note the IP address of the load balancer for the next task.
When you use the Google Cloud console to create an HTTP(S) load balancer with a serverless NEG backend, logging is enabled by default. You can use thegcloud compute backend-services update command to disable logging if needed.

gcloud

  1. Create a serverless NEG for your Cloud Run service:
        gcloud compute network-endpoint-groups createSERVERLESS_NEG_NAME \        --region=REGION \        --network-endpoint-type=serverless  \        --cloud-run-service=CLOUD_RUN_SERVICE_NAME
  2. Create a regional backend service. Set the--protocol to HTTP. This parameter is ignored but it is required because the--protocol otherwise defaults to TCP.
        gcloud compute backend-services createBACKEND_SERVICE_NAME \        --load-balancing-scheme=INTERNAL_MANAGED \        --protocol=HTTP \        --region=REGION
  3. Add the serverless NEG as a backend to the backend service:
        gcloud compute backend-services add-backendBACKEND_SERVICE_NAME \        --region=REGION \        --network-endpoint-group=SERVERLESS_NEG_NAME \        --network-endpoint-group-region=REGION
  4. Create a regional URL map to route incoming requests to the backend service:
        gcloud compute url-maps createURL_MAP_NAME \        --default-service=BACKEND_SERVICE_NAME \        --region=REGION
     This example URL map only targets one backend service representing a single serverless app, so you don't need to set up host rules or path matchers.
  5. Optional: Perform this step if you are using HTTPS between the client and the load balancer. This step isn't required for HTTP load balancers.

    You can create either Compute Engine or Certificate Manager certificates. Use any of the following methods to create certificates using Certificate Manager:

    After you create certificates, attach the certificate directly to the targetproxy.

    To create a regional self-managed SSL certificate resource:
        gcloud compute ssl-certificates createSSL_CERTIFICATE_NAME \        --certificateCRT_FILE_PATH \        --private-keyKEY_FILE_PATH \        --region=REGION
  6. Create a regional target proxy to route requests to the URL map.

    For an HTTP load balancer, create an HTTP target proxy:
        gcloud compute target-http-proxies createTARGET_HTTP_PROXY_NAME \        --url-map=URL_MAP_NAME \        --region=REGION
     For an HTTPS load balancer, create an HTTPS target proxy. The proxy is the portion of the load balancer that holds the SSL certificate for HTTPS Load Balancing, so you also load your certificate in this step.
        gcloud compute target-https-proxies createTARGET_HTTPS_PROXY_NAME \        --ssl-certificates=SSL_CERTIFICATE_NAME \        --url-map=URL_MAP_NAME \        --region=REGION
  7. Create a forwarding rule to route incoming requests to the proxy. Don't use the proxy-only subnet for the forwarding rule IP address. You can configure any valid IP address from the subnet (lb-subnet).

    For an HTTP load balancer:
        gcloud compute forwarding-rules createHTTP_FORWARDING_RULE_NAME \        --load-balancing-scheme=INTERNAL_MANAGED \        --network=lb-network \        --subnet=lb-subnet \        --target-http-proxy=TARGET_HTTP_PROXY_NAME \        --target-http-proxy-region=REGION \        --region=REGION \        --ports=80
     For an HTTPS load balancer:
        gcloud compute forwarding-rules createHTTPS_FORWARDING_RULE_NAME \        --load-balancing-scheme=INTERNAL_MANAGED \        --network=lb-network \        --subnet=lb-subnet \        --target-https-proxy=TARGET_HTTPS_PROXY_NAME \        --target-https-proxy-region=REGION \        --region=REGION \        --ports=443

Test the load balancer

Now that you have configured your load balancer, you can start sendingtraffic to the load balancer's IP address.

Create a client VM

This example creates a client VM (vm-client) in the same region as theload balancer. The client is used to validate the load balancer's configurationand demonstrate expected behavior.

gcloud

The client VM can be in any zone in the same region as theload balancer, and it can use any subnet in the same VPCnetwork.

gcloud compute instances create vm-client \    --image-family=debian-12 \    --image-project=debian-cloud \    --tags=allow-ssh \    --network=lb-network \    --subnet=lb-subnet \    --zone=ZONE

Configure the firewall rule

This example requires the following firewall rule for the test client VM:

fw-allow-ssh. An ingress rule, applicable to the test client VM,that allows incoming SSH connectivity on TCP port22 from anyaddress. You can choose a more restrictive source IP address range for thisrule; for example, you can specify just the IP address ranges of the system fromwhich you initiate SSH sessions. This example uses the target tagallow-ssh.

Console

  1. In the Google Cloud console, go to theFirewall policies page.
    Go to Firewall policies
  2. ClickCreate firewall rule to create the rule to allow incomingSSH connections:
    • Name:allow-ssh
    • Network:lb-network
    • Direction of traffic:Ingress
    • Action on match:Allow
    • Targets:Specified target tags
    • Target tags:allow-ssh
    • Source filter:IPv4 ranges
    • Source IPv4 ranges:0.0.0.0/0
    • Protocols and ports:
      • ChooseSpecified protocols and ports.
      • Select theTCP checkbox, and then enter22 for the port number.
  3. ClickCreate.

gcloud

Create thefw-allow-ssh firewall rule to allow SSH connectivity toVMs with the network tagallow-ssh. When you omitsource-ranges,Google Cloudinterprets the rule to mean anysource.

gcloud compute firewall-rules create fw-allow-ssh \  --network=lb-network \  --action=allow \  --direction=ingress \  --target-tags=allow-ssh \  --rules=tcp:22

Send traffic to the load balancer

It might take a few minutes for the load balancer configuration topropagate after you first deploy it.

  • Connect to the client instance using SSH.

    gcloud compute ssh vm-client \  --zone=ZONE

  • Verify that the load balancer is serving the Cloud Runservice homepage as expected.

    For HTTP testing, run:

    curlIP_ADDRESS

    For HTTPS testing, run:

    curl -k -s 'https://TEST_DOMAIN_URL:443' --connect-toTEST_DOMAIN_URL:443:IP_ADDRESS:443

    ReplaceTEST_DOMAIN_URL with the domain associated with yourapplication. For example,test.example.com.

    The-k flag causes curl to skip certificate validation.

Additional configuration options

This section expands on the configuration example to provide alternative andadditional configuration options. All of the tasks are optional. You can performthem in any order.

Using a URL mask

When creating a serverless NEG, instead of selecting a specificCloud Run service, you can use a URL mask to point tomultiple services serving at the same domain. A URL mask is a template of yourURL schema. The serverless NEG uses this template to extract the servicename from the incoming request's URL and map the request to the appropriateservice.

URL masks are particularly useful if your service ismapped to a customdomain rather than to the default addressthat Google Cloud provides for the deployed service. A URL mask lets youtarget multiple services and versions with a single rule even when yourapplication is using a custom URL pattern.

If you haven't already done so, make sure you read theServerless NEGSoverview: URLMasks.

Construct a URL mask

To construct a URL mask for your load balancer, start with the URL of yourservice. This example uses a sample serverless app running athttps://example.com/login. This is the URL where the app'slogin serviceis served.

  1. Remove thehttp orhttps from the URL. You are left withexample.com/login.
  2. Replace the service name with a placeholder for the URL mask.
    • Cloud Run: Replace theCloud Run service name with theplaceholder<service>. If the Cloud Runservice has a tag associated with it,replace the tag name with the placeholder<tag>.In this example, the URL mask you are left with isexample.com/<service>.

  3. Optional: If the service name can beextracted from the path portion of the URL, the domain can be omitted. Thepath part of the URL mask is distinguishedby the first slash (/) character. If a slash (/) is not present in theURL mask, the mask is understood to represent the host only. Therefore, forthis example, the URL mask can be reduced to/<service>.

    Similarly, if<service> can be extracted from the host part of theURL, you can omit the path altogether from the URL mask.

    You can also omitany host or subdomain components that come before the first placeholder aswell as any path components that come after the last placeholder. In suchcases, the placeholder captures the required information for the component.

Here are a few more examples that demonstrate these rules:

This table assumes that you have a custom domain calledexample.com andall your Cloud Run services are beingmappedto this domain.

Service, Tag nameCloud Run custom domain URLURL mask
service: loginhttps://login-home.example.com/web<service>-home.example.com
service: loginhttps://example.com/login/webexample.com/<service> or /<service>
service: login, tag: testhttps://test.login.example.com/web<tag>.<service>.example.com
service: login, tag: testhttps://example.com/home/login/testexample.com/home/<service>/<tag> or /home/<service>/<tag>
service: login, tag: testhttps://test.example.com/home/login/web<tag>.example.com/home/<service>

Creating a serverless NEG with a URL mask

Console

For a new load balancer, you can use the same end-to-end process asdescribed previously in this document. When configuring the backend service,instead of selecting a specific service, enter a URL mask.

If you have an existing load balancer, you can edit the backend configurationand have the serverless NEG point to a URL mask instead of a specific service.

To add a URL mask-based serverless NEG to an existing backend service,do the following:

  1. In the Google Cloud console, go to theLoad balancing page.
    Go to Load balancing
  2. Click the name of the load balancer that has the backend service you want to edit.
  3. On theLoad balancer details page, clickEdit.
  4. On theEdit global external Application Load Balancer page, clickBackend configuration.
  5. On theBackend configuration page, clickEdit for the backend service you want to modify.
  6. ClickAdd backend.
  7. SelectCreate Serverless network endpoint group.
    1. For theName, enterhelloworld-serverless-neg.
    2. UnderRegion, the region of the load balancer is displayed.
    3. UnderServerless network endpoint group type,Cloud Run is the only supported network endpoint group type.
      1. SelectUse URL Mask.
      2. Enter a URL mask. For information about how to create a URL mask, seeConstructing a URL mask.
      3. ClickCreate.

  8. In theNew backend, clickDone.
  9. ClickUpdate.

gcloud

To create a serverless NEG with a sample URL mask ofexample.com/<service>:

gcloud compute network-endpoint-groups createSERVERLESS_NEG_MASK_NAME \    --region=REGION \    --network-endpoint-type=serverless \    --cloud-run-url-mask="example.com/<service>"

Update client HTTP keepalive timeout

The load balancer created in the previous steps has been configured witha default value for theclient HTTP keepalivetimeout.

To update the client HTTP keepalive timeout, use the following instructions.

Console

  1. In the Google Cloud console, go to theLoad balancing page.

    Go to Load balancing.

  2. Click the name of the load balancer that you want to modify.
  3. ClickEdit.
  4. ClickFrontend configuration.
  5. ExpandAdvanced features. ForHTTP keepalive timeout, enter a timeout value.
  6. ClickUpdate.
  7. To review your changes, clickReview and finalize, and then clickUpdate.

gcloud

For an HTTP load balancer, update the target HTTP proxy by using thegcloud compute target-http-proxies update command.

      gcloud compute target-http-proxies updateTARGET_HTTP_PROXY_NAME \          --http-keep-alive-timeout-sec=HTTP_KEEP_ALIVE_TIMEOUT_SEC \          --region=REGION

For an HTTPS load balancer, update the target HTTPS proxy by using thegcloud compute target-https-proxies update command.

      gcloud compute target-https-proxies updateTARGET_HTTP_PROXY_NAME \          --http-keep-alive-timeout-sec=HTTP_KEEP_ALIVE_TIMEOUT_SEC \          --regionREGION

Replace the following:

  • TARGET_HTTP_PROXY_NAME: the name of the target HTTP proxy.
  • TARGET_HTTPS_PROXY_NAME: the name of the target HTTPS proxy.
  • HTTP_KEEP_ALIVE_TIMEOUT_SEC: the HTTP keepalive timeout value from 5 to 600 seconds.

Deleting a serverless NEG

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

Console

  1. To make sure the serverless NEG you want to delete is not in use by any backend service, go to theBackend services tab on theLoad balancing components page.
    Go to Backend services
  2. If the serverless NEG is in use, do the following:
    1. Click the name of the backend service that is using the serverless NEG.
    2. ClickEdit.
    3. From the list ofBackends, click to remove the serverless NEG backend from the backend service.
    4. ClickSave.

  3. Go to theNetwork endpoint group page in the Google Cloud console.
    Go to Network endpoint group
  4. Select the checkbox for the serverless NEG you want to delete.
  5. ClickDelete.
  6. ClickDelete again to confirm.

gcloud

To remove a serverless NEG from a backend service, you must specifythe region where the NEG was created.

gcloud compute backend-services remove-backendBACKEND_SERVICE_NAME \    --network-endpoint-group=SERVERLESS_NEG_NAME \    --network-endpoint-group-region=REGION \    --region=REGION

To delete the serverless NEG:

gcloud compute network-endpoint-groups deleteSERVERLESS_NEG_NAME \    --region=REGION

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-15 UTC.