This document shows you two sample configurations for setting up an internal Application Load Balancer in a Shared VPC environment:
- The first example creates all the load balancer components and backends in one service project.
- The second example creates the load balancer's frontend components and URL map in one service project, while the load balancer's backend service and backends are created in a different service project. This type of deployment, where the URL map references a backend service in another project, is referred to as Cross-project service referencing.
Both examples require the same upfront configuration to grant permissions and set up Shared VPC before you can start creating load balancers.
These are not the only Shared VPC configurations supported by internal Application Load Balancers. For other valid Shared VPC architectures, see Shared VPC architectures.
If you don't want to use a Shared VPC network, see Set up an internal Application Load Balancer.
Before you begin
- Read Shared VPC overview.
- Read Internal Application Load Balancer overview, including the Shared VPC architectures section.
Permissions required
Setting up a load balancer on a Shared VPC network requires some initial setup and provisioning by an administrator. After the initial setup, a service project owner can do one of the following:
- Deploy all the load balancer's components and its backends in a service project.
- Deploy the load balancer's backend components (backend service and backends) in service projects that can be referenced by a URL map in another service or host project.
This section summarizes the permissions required to follow this guide to set up a load balancer on a Shared VPC network.
Set up Shared VPC
The following roles are required for the following tasks:
- Perform one-off administrative tasks such as setting up the Shared VPC and enabling a host project.
- Perform administrative tasks that must be repeated every time you want to onboard a new service project. This includes attaching the service project, provisioning and configuring networking resources, and granting access to the service project administrator.
These tasks must be performed in the Shared VPC host project. We recommend that the Shared VPC Admin also be the owner of the Shared VPC host project. This automatically grants the Network Admin and Security Admin roles.
Task | Required role |
---|---|
Set up Shared VPC, enable host project, and grant access to service project administrators | Shared VPC Admin |
Create subnets in the Shared VPC host project and grant access to service project administrators | Network Admin |
Add and remove firewall rules | Security Admin |
After the subnets have been provisioned, the host project owner must grant the Network User role in the host project to anyone (typically service project administrators, developers, or service accounts) who needs to use these resources.
Task | Required role |
---|---|
Use VPC networks and subnets belonging to the host project | Network User |
This role can be granted on the project level or for individual subnets. We recommend that you grant the role on individual subnets. Granting the role on the project provides access to all current and future subnets in the VPC network of the host project.
Deploy load balancer and backends
Service project administrators need the following roles in the service project to create load balancing resources and backends. These permissions are granted automatically to the service project owner or editor.
Task | Required role |
---|---|
Create load balancer components | Network Admin |
Create instances | Instance Admin |
Create and modify SSL certificates | Security Admin |
Prerequisites
In this section, you need to perform the following steps:
The steps in this section do not need to be performed every time you want to create a new load balancer. However, you must ensure that you have access to the resources described here before you proceed to creating the load balancer.
Configure the network and subnets in the host project
You need a Shared VPC network with two subnets: one for the load balancer's frontend and backends and one for the load balancer's proxies.This example uses the following network, region, and subnets:
Network. The network is named
lb-network
.Subnet for load balancer's frontend and backends. A subnet named
lb-frontend-and-backend-subnet
in theus-west1
region uses10.1.2.0/24
for its primary IP range.Subnet for proxies. A subnet named
proxy-only-subnet
in theus-west1
region uses10.129.0.0/23
for its primary IP range.
Configure the subnet for the load balancer's frontend and backends
This step does not need to be performed every time you want to create a new load balancer. You only need to ensure that the service project has access to a subnet in the Shared VPC network (in addition to the proxy-only subnet).All the steps in this section must be performed in the host project.
Console
- In the Google Cloud console, go to the VPC networks page.
- Click Create VPC network.
- For Name, enter
lb-network
. In the Subnets section:
- Set the Subnet creation mode to Custom.
In the New subnet section, enter the following information:
- Name:
lb-frontend-and-backend-subnet
Region:
us-west1
IP address range:
10.1.2.0/24
- Name:
Click Done.
Click Create.
gcloud
Create a VPC network with the
gcloud compute networks create
command:gcloud compute networks create lb-network --subnet-mode=custom
Create a subnet in the
lb-network
network in theus-west1
region:gcloud compute networks subnets create lb-frontend-and-backend-subnet
--network=lb-network
--range=10.1.2.0/24
--region=us-west1
Terraform
Create a VPC network:
Create a subnet in the
us-west1
region:
Configure the proxy-only subnet
The proxy-only subnet is used by all regional Envoy-based load
balancers in the us-west1
region, in the lb-network
VPC network. There can only be one
active proxy-only subnet per region, per network.
Do not perform this step if there is already a proxy-only subnet reserved in the
us-west1
region in this network.
All the steps in this section must be performed in the host project.
Console
- In the Google Cloud console, go to the VPC networks page.
- Click the name of the Shared VPC network:
lb-network
. - Click Add subnet.
- For Name, enter
proxy-only-subnet
. - For Region, select
us-west1
. - Set Purpose to Regional Managed Proxy.
- For IP address range, enter
10.129.0.0/23
. - Click Add.
gcloud
Create the proxy-only subnet with the gcloud compute networks subnets
create
command:
gcloud compute networks subnets create proxy-only-subnet \ --purpose=REGIONAL_MANAGED_PROXY \ --role=ACTIVE \ --region=us-west1 \ --network=lb-network \ --range=10.129.0.0/23
Terraform
Create the proxy-only subnet:
Give service project admins access to the backend subnet
Service project administrators require access to thelb-frontend-and-backend-subnet
subnet so that they can provision the load
balancer's backends.
A Shared VPC Admin must grant access to the backend subnet to service project administrators (or developers who deploy resources and backends that use the subnet). For instructions, see Service Project Admins for some subnets.
Configure firewall rules in the host project
This example uses the following firewall rules:fw-allow-health-check
. An ingress rule, applicable to the instances being load balanced, that allows all TCP traffic from the Google Cloud health checking systems in130.211.0.0/22
and35.191.0.0/16
. This example uses the target tagload-balanced-backend
to identify the instances to which it should apply.
fw-allow-proxies
. An ingress rule, applicable to the instances being load balanced, that allows TCP traffic on ports80
,443
, and8080
from the load balancer's managed proxies. This example uses the target tagload-balanced-backend
to identify the instances to which it should apply.
fw-allow-ssh
. An ingress rule, applicable to the instances being load balanced, that allows incoming SSH connectivity on TCP port22
from any address. You can choose a more restrictive source IP range for this rule. For example, you can specify just the IP ranges of the system from which you initiate SSH sessions. This example uses the target tagallow-ssh
to identify the virtual machines (VMs) to which the firewall rule applies.
All the steps in this section must be performed in the host project.
Console
In the Google Cloud console, go to the Firewall policies page.
- Click Create firewall rule to create the rule to allow Google Cloud health checks:
- Name:
fw-allow-health-check
- Network:
lb-network
- Direction of traffic: Ingress
- Action on match: Allow
- Targets: Specified target tags
- Target tags:
load-balanced-backend
- Source filter: IPv4 ranges
- Source IPv4 ranges:
130.211.0.0/22
and35.191.0.0/16
- Protocols and ports:
- Choose Specified protocols and ports.
- Check TCP and enter
80
for the port number.
As a best practice, limit this rule to just the protocols and ports that match those used by your health check. If you use
tcp:80
for the protocol and port, Google Cloud can use HTTP on port80
to contact your VMs, but it cannot use HTTPS on port443
to contact them. - Click Create.
- Click Create firewall rule to create the rule to allow Google Cloud health checks:
- Name:
fw-allow-proxies
- Network:
lb-network
- Direction of traffic: Ingress
- Action on match: Allow
- Targets: Specified target tags
- Target tags:
load-balanced-backend
- Source filter: IPv4 ranges
- Source IPv4 ranges:
10.129.0.0/23
- Protocols and ports:
- Choose Specified protocols and ports.
- Check TCP and enter
80, 443, 8080
for the port numbers.
- Click Create.
- Click Create firewall rule to create the rule to allow Google Cloud health checks:
- Name:
fw-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:
- Choose Specified protocols and ports.
- Check TCP and enter
22
for the port number.
- Click Create.
gcloud
Create the
fw-allow-health-check
firewall rule to allow Google Cloud health checks. This example allows all TCP traffic from health check probers. However, you can configure a narrower set of ports to meet your needs.gcloud compute firewall-rules create fw-allow-health-check \ --network=lb-network \ --action=allow \ --direction=ingress \ --source-ranges=130.211.0.0/22,35.191.0.0/16 \ --target-tags=load-balanced-backend \ --rules=tcp
Create the
fw-allow-proxies
firewall rule to allow traffic from the Envoy proxy-only subnet to reach your backends.gcloud compute firewall-rules create fw-allow-proxies \ --network=lb-network \ --action=allow \ --direction=ingress \ --source-ranges=10.129.0.0/23 \ --target-tags=load-balanced-backend \ --rules=tcp:80,tcp:443,tcp:8080
Create the
fw-allow-ssh
firewall rule to allow SSH connectivity to VMs with the network tagallow-ssh
. When you omitsource-ranges
, Google Cloud interprets the rule to mean any source.gcloud compute firewall-rules create fw-allow-ssh \ --network=lb-network \ --action=allow \ --direction=ingress \ --target-tags=allow-ssh \ --rules=tcp:22
Terraform
Create a firewall rule to allow Google Cloud health checks.
Create a firewall rule to allow traffic from the Envoy proxy-only subnet to reach your backends.
Create a firewall rule to allow SSH connectivity to VMs with the network tag
allow-ssh
.
Set up Shared VPC in the host project
This step entails enabling a Shared VPC host project, sharing subnets of the host project, and attaching service projects to the host project so that the service projects can use the Shared VPC network. To set up Shared VPC in the host project, see the following pages:
The rest of these instructions assume that you have already set up Shared VPC. This includes setting up IAM policies for your organization and designating the host and service projects.
Don't proceed until you have set up Shared VPC and enabled the host and service projects.
After completing the steps defined in this prerequisites section, you can pursue either of the following setups:
Configure a load balancer in the service project
This example creates an internal Application Load Balancer where all the load balancing components (forwarding rule, target proxy, URL map, and backend service) and backends are created in the service project.
The internal Application Load Balancer's networking resources such as the proxy-only subnet and the subnet for the backend instances are created in the host project. The firewall rules for the backend instances are also created in the host project.
This section shows you how to set up the load balancer and backends. These steps should be carried out by the service project administrator (or a developer operating within the service project) and do not require involvement from the host project administrator. The steps in this section are largely similar to the standard steps to set up an internal Application Load Balancer.
The example on this page explicitly sets a reserved internal IP address for the internal Application Load Balancer's forwarding rule, rather than allowing an ephemeral internal IP address to be allocated. As a best practice, we recommend reserving IP addresses for forwarding rules.
Create the managed instance group backend
This section shows how to create a template and a managed instance group. The managed instance group provides VM instances running the backend servers of an example internal Application Load Balancer. Traffic from clients is load balanced to these backend servers. For demonstration purposes, backends serve their own hostnames.
Console
Create an instance template. In the Google Cloud console, go to the Instance templates page.
- Click Create instance template.
- For Name, enter
l7-ilb-backend-template
. - Ensure that the Boot disk is set to a Debian image, such as
Debian GNU/Linux 12 (bookworm). These instructions use commands that
are only available on Debian, such as
apt-get
. If you need to change the Boot disk, click Change.- For Operating System, select Debian.
- For Version, select one of the available Debian images such as Debian GNU/Linux 12 (bookworm).
- Click Select.
- Click Advanced options, and then click Networking.
- Enter the following Network
tags:
allow-ssh
,load-balanced-backend
. - In the Network interfaces section, select Networks shared with me (from host project: HOST_PROJECT_ID).
- Select the
lb-frontend-and-backend-subnet
subnet from thelb-network
network. - Click Management. For Management, insert the following
script into the Startup script field.
#! /bin/bash apt-get update apt-get install apache2 -y a2ensite default-ssl a2enmod ssl vm_hostname="$(curl -H "Metadata-Flavor:Google"
http://metadata.google.internal/computeMetadata/v1/instance/name)" echo "Page served from: $vm_hostname" |
tee /var/www/html/index.html systemctl restart apache2 - Click Create.
Create a managed instance group. In the Google Cloud console, go to the Instance groups page.
- Click Create instance group.
- Choose New managed instance group (stateless). For more information, see Stateless or stateful MIGs.
- For Name, enter
l7-ilb-backend-example
. - For Location, select Single zone.
- For Region, select
us-west1
. - For Zone, select
us-west1-a
. - For Instance template, select
l7-ilb-backend-template
. Specify the number of instances that you want to create in the group.
For this example, specify the following options for Autoscaling:
- For Autoscaling mode, select
Off:do not autoscale
. - For Maximum number of instances, enter
2
.
Optionally, in the Autoscaling section of the UI, you can configure the instance group to automatically add or remove instances based on instance CPU usage.
- For Autoscaling mode, select
Click Create.
gcloud
The gcloud
instructions in this guide assume that you are using Cloud
Shell or another environment with bash installed.
Create a VM instance template with an HTTP server with the
gcloud compute instance-templates create
command.gcloud compute instance-templates create l7-ilb-backend-template \ --region=us-west1 \ --network=projects/HOST_PROJECT_ID/global/networks/lb-network \ --subnet=projects/HOST_PROJECT_ID/regions/us-west1/subnetworks/lb-frontend-and-backend-subnet \ --tags=allow-ssh,load-balanced-backend \ --image-family=debian-12 \ --image-project=debian-cloud \ --metadata=startup-script='#! /bin/bash apt-get update apt-get install apache2 -y a2ensite default-ssl a2enmod ssl vm_hostname="$(curl -H "Metadata-Flavor:Google" \ http://metadata.google.internal/computeMetadata/v1/instance/name)" echo "Page served from: $vm_hostname" | \ tee /var/www/html/index.html systemctl restart apache2' \ --project=SERVICE_PROJECT_ID
Create a managed instance group in the zone with the
gcloud compute instance-groups managed create
command.gcloud compute instance-groups managed create l7-ilb-backend-example \ --zone=us-west1-a \ --size=2 \ --template=l7-ilb-backend-template \ --project=SERVICE_PROJECT_ID
Terraform
Create a VM instance template.
Create a managed instance group.
For HTTP:
For HTTPS:
Configure the load balancer
This section shows you how to create the internal Application Load Balancer resources:
- HTTP health check
- Backend service with a managed instance group as the backend
- A URL map
- SSL certificate (required only for HTTPS)
- Target proxy
- Forwarding rule
Proxy availability
Depending on the number of service projects that are using the same Shared VPC network, you might reach quotas or limits more quickly than in the network deployment model where each Google Cloud project hosts its own network.
For example, sometimes Google Cloud regions don't have enough proxy capacity for a new internal Application Load Balancer. If this happens, the Google Cloud console provides a proxy availability warning message when you are creating your load balancer. To resolve this issue, you can do one of the following:
- Wait for the capacity issue to be resolved.
Contact your Google Cloud sales team to increase these limits.
Console
Switch context to the service project
- In the Google Cloud console, go to the Dashboard page.
- Click the Select from list at the top of the page. In the Select from window that appears, select the service project where you want to create the load balancer.
Start your configuration
In the Google Cloud console, go to the Load balancing page.
- Click Create load balancer.
- For Type of load balancer, select Application Load Balancer (HTTP/HTTPS) and click Next.
- For Public facing or internal, select Internal and click Next.
- For Cross-region or single region deployment, select Best for regional workloads and click Next.
- Click Configure.
Basic configuration
- For the Name of the load balancer, enter
l7-ilb-shared-vpc
. - For the Region, select
us-west1
. For the Network, select lb-network (from Project: HOST_PROJECT_ID).
If you see a Proxy-only subnet required in Shared VPC network warning, confirm that the host project admin has created the
proxy-only-subnet
in theus-west1
region in thelb-network
Shared VPC network. Load balancer creation succeeds even if you do not have permission to view the proxy-only subnet on this page.Keep the window open to continue.
Configure the backend
- Click Backend configuration.
- From the Create or select backend services menu, select Create a backend service.
- Set the Name of the backend service to
l7-ilb-backend-service
. - Set the Backend type to Instance groups.
- In the New backend section:
- Set the Instance group to
l7-ilb-backend-example
. - Set the Port numbers to
80
. - Set the Balancing mode to Utilization.
- Click Done.
- Set the Instance group to
- In the Health check section, choose Create a health check with the
following parameters:
- Name:
l7-ilb-basic-check
- Protocol:
HTTP
- Port:
80
- Name:
- Click Save and Continue.
- Click Create.
Configure the routing rules
- Click Routing rules. Ensure that the
l7-ilb-backend-service
is the only backend service for any unmatched host and any unmatched path.
For information about traffic management, see Setting up traffic management.
Configure the frontend
For HTTP:
- Click Frontend configuration.
- Set the Name to
l7-ilb-forwarding-rule
. - Set the Protocol to
HTTP
. - Set the Subnetwork to
lb-frontend-and-backend-subnet
. Don't select the proxy-only subnet for the frontend even if it is an option in the list. - Set the Port to
80
. - Click the IP address menu, and then click Create IP address.
- In the Reserve a static internal IP address panel, provide the
following details:
- For the Name, enter
ip-address-shared-vpc
. - For Static IP address, click Let me choose. For Custom IP
address, enter
10.1.2.99
. - (Optional) If you want to share this IP address with different frontends, for set Purpose to Shared.
- For the Name, enter
- Click Done.
For HTTPS:
If you are using HTTPS between the client and the load balancer, you need one or more SSL certificate resources to configure the proxy. For information about how to create SSL certificate resources, see SSL certificates. Google-managed certificates aren't currently supported with internal Application Load Balancers.
- Click Frontend configuration.
- In the Name field, enter
l7-ilb-forwarding-rule
. - In the Protocol field, select
HTTPS (includes HTTP/2)
. - Set the Subnetwork to
lb-frontend-and-backend-subnet
. Don't select the proxy-only subnet for the frontend even if it is an option in the list. - Ensure that the Port is set to
443
to allow HTTPS traffic. - Click the IP address menu, and then click Create IP address.
- In the Reserve a static internal IP address panel, provide the
following details:
- For the Name, enter
ip-address-shared-vpc
. - For Static IP address, click Let me choose. For Custom IP
address, enter
10.1.2.99
. - (Optional) If you want to share this IP address with different frontends, for set Purpose to Shared.
- For the Name, enter
- Click the Certificate list.
- If you already have a self-managed SSL certificate resource that you want to use as the primary SSL certificate, select it from the menu.
- Otherwise, select Create a new certificate.
- Fill in a Name of
l7-ilb-cert
. - In the appropriate fields, upload your PEM-formatted files:
- Public key certificate
- Certificate chain
- Private key
- Click Create.
- Fill in a Name of
- To add certificate resources in addition to
the primary SSL certificate resource:
- Click Add certificate.
- Select a certificate from the Certificates list or click Create a new certificate and follow the previous instructions.
- Click Done.
Review and finalize the configuration
- Click Create.
gcloud
Define the HTTP health check with the
gcloud compute health-checks create http
command.gcloud compute health-checks create http l7-ilb-basic-check \ --region=us-west1 \ --use-serving-port \ --project=SERVICE_PROJECT_ID
Define the backend service with the
gcloud compute backend-services create
command.gcloud compute backend-services create l7-ilb-backend-service \ --load-balancing-scheme=INTERNAL_MANAGED \ --protocol=HTTP \ --health-checks=l7-ilb-basic-check \ --health-checks-region=us-west1 \ --region=us-west1 \ --project=SERVICE_PROJECT_ID
Add backends to the backend service with the
gcloud compute backend-services add-backend
command.gcloud compute backend-services add-backend l7-ilb-backend-service \ --balancing-mode=UTILIZATION \ --instance-group=l7-ilb-backend-example \ --instance-group-zone=us-west1-a \ --region=us-west1 \ --project=SERVICE_PROJECT_ID
Create the URL map with the
gcloud compute url-maps create
command.gcloud compute url-maps create l7-ilb-map \ --default-service=l7-ilb-backend-service \ --region=us-west1 \ --project=SERVICE_PROJECT_ID
Create the target proxy.
For HTTP:
For an internal HTTP load balancer, create the target proxy with the
gcloud compute target-http-proxies create
command.gcloud compute target-http-proxies create l7-ilb-proxy \ --url-map=l7-ilb-map \ --url-map-region=us-west1 \ --region=us-west1 \ --project=SERVICE_PROJECT_ID
For HTTPS:
For information about how to create SSL certificate resources, see SSL certificates. Google-managed certificates aren't currently supported with internal Application Load Balancers.
Assign your filepaths to variable names.
export LB_CERT=path to PEM-formatted file
export LB_PRIVATE_KEY=path to PEM-formatted file
Create a regional SSL certificate using the
gcloud compute ssl-certificates create
command.gcloud compute ssl-certificates create l7-ilb-cert \ --certificate=$LB_CERT \ --private-key=$LB_PRIVATE_KEY \ --region=us-west1
Use the regional SSL certificate to create a target proxy with the
gcloud compute target-https-proxies create
command.gcloud compute target-https-proxies create l7-ilb-proxy \ --url-map=l7-ilb-map \ --region=us-west1 \ --ssl-certificates=l7-ilb-cert \ --project=SERVICE_PROJECT_ID
Create the forwarding rule.
For custom networks, you must reference the subnet in the forwarding rule.
For the forwarding rule's IP address, use the
lb-frontend-and-backend-subnet
. If you try to use the proxy-only subnet, forwarding rule creation fails.For HTTP:
Use the
gcloud compute forwarding-rules create
command with the correct flags.gcloud compute forwarding-rules create l7-ilb-forwarding-rule \ --load-balancing-scheme=INTERNAL_MANAGED \ --network=projects/HOST_PROJECT_ID/global/networks/lb-network \ --subnet=projects/HOST_PROJECT_ID/regions/us-west1/subnetworks/lb-frontend-and-backend-subnet \ --address=IP_ADDRESS_NAME \ --ports=80 \ --region=us-west1 \ --target-http-proxy=l7-ilb-proxy \ --target-http-proxy-region=us-west1 \ --project=SERVICE_PROJECT_ID
For HTTPS:
Use the
gcloud compute forwarding-rules create
command with the correct flags.gcloud compute forwarding-rules create l7-ilb-forwarding-rule \ --load-balancing-scheme=INTERNAL_MANAGED \ --network=projects/HOST_PROJECT_ID/global/networks/lb-network \ --subnet=projects/HOST_PROJECT_ID/regions/us-west1/subnetworks/lb-frontend-and-backend-subnet \ --address=IP_ADDRESS_NAME \ --ports=443 \ --region=us-west1 \ --target-https-proxy=l7-ilb-proxy \ --target-https-proxy-region=us-west1 \ --project=SERVICE_PROJECT_ID
Terraform
Define the HTTP health check.
For HTTP:
For HTTPS:
Define the backend service.
Create the URL map.
Create the target proxy.
For HTTP:
For HTTPS: Create a regional SSL certificate
For information about how to create SSL certificate resources, see SSL certificates. Google-managed certificates aren't currently supported with internal Application Load Balancers.
Use the regional SSL certificate to create a target proxy
Create the forwarding rule.
For custom networks, you must reference the subnet in the forwarding rule.
For HTTP:
For HTTPS:
Test the load balancer
To test the load balancer, first create a sample client VM. Then establish an SSH session with the VM and send traffic from this VM to the load balancer.
Create a test VM instance
Clients can be located in either the host project or any connected service project. In this example, you test that the load balancer is working by deploying a client VM in a service project. The client must use the same Shared VPC network and be in the same region as the load balancer.
Console
In the Google Cloud console, go to the VM instances page.
Click Create instance.
Set the Name to
client-vm
.Set the Zone to us-west1-a.
Click Advanced options, and then click Networking.
Enter the following Network tags:
allow-ssh
,load-balanced-backend
.In the Network interfaces section, select Networks shared with me (from host project: HOST_PROJECT_ID).
Select the
lb-frontend-and-backend-subnet
subnet from thelb-network
network.Click Create.
gcloud
Create a test VM instance.
gcloud compute instances create client-vm \ --image-family=debian-12 \ --image-project=debian-cloud \ --subnet=projects/HOST_PROJECT_ID/regions/us-west1/subnetworks/lb-frontend-and-backend-subnet \ --zone=us-west1-a \ --tags=allow-ssh \ --project=SERVICE_PROJECT_ID
Terraform
Create a test VM instance.
Send traffic to the load balancer
Use SSH to connect to the instance that you just created and test that HTTP(S) services on the backends are reachable through the internal Application Load Balancer's forwarding rule IP address and that traffic is being load balanced across the backend instances.
Connect to the client instance with SSH.
gcloud compute ssh client-vm \ --zone=us-west1-a
Verify that the IP address is serving its hostname. Replace LB_IP_ADDRESS with the load balancer's IP address.
curl LB_IP_ADDRESS
For HTTPS testing, replace
curl
with the following:curl -k -s 'https://LB_IP_ADDRESS:443'
The
-k
flag causes curl to skip certificate validation.
Configure a load balancer with a cross-project backend service
The previous example on this page shows you how to set up a Shared VPC deployment where all the load balancer components and its backends are created in the service project.
Internal Application Load Balancers also let you configure Shared VPC deployments where a URL map in one host or service project can reference backend services (and backends) located across multiple service projects in Shared VPC environments. This is referred to as cross-project service referencing.
You can use the steps in this section as a reference to configure any of the supported combinations listed here:
- Forwarding rule, target proxy, and URL map in the host project, and backend service in a service project
- Forwarding rule, target proxy, and URL map in a service project, and backend service in another service project
Cross-project service referencing can be used with instance groups, serverless NEGs, or any other supported backend types. If you're using serverless NEGs, you need to create a VM in the VPC network where you intend to create the load balancer's frontend. For an example, see Create a VM instance in a specific subnet in Set up an internal Application Load Balancer with Cloud Run.
Set up requirements
This example configures a sample load balancer with its frontend and backend in two different service projects.
If you haven't already done so, you must complete all of the prerequisite steps to set up Shared VPC and configure the network, subnets, and firewall rules required for this example. For instructions, see the following:
Create the backends and backend service in service project B
All the steps in this section must be performed in service project B.
Console
Create an instance template. In the Google Cloud console, go to the Instance templates page.
- Click Create instance template.
- Enter a Name for the instance template:
cross-ref-backend-template
. - Ensure that the Boot disk is set to a Debian image, such as
Debian GNU/Linux 12 (bookworm). These instructions use commands that
are only available on Debian, such as
apt-get
. If you need to change the Boot disk, click Change.- For Operating System, select Debian.
- For Version, select one of the available Debian images such as Debian GNU/Linux 12 (bookworm).
- Click Select.
- Click Advanced options, and then click Networking.
- Enter the following Network
tags:
allow-ssh
,load-balanced-backend
. - In the Network interfaces section, select Networks shared with me (from host project: HOST_PROJECT_ID).
- Select the
lb-frontend-and-backend-subnet
subnet from thelb-network
network. - Click Management. For Management, insert the following
script into the Startup script field.
#! /bin/bash apt-get update apt-get install apache2 -y a2ensite default-ssl a2enmod ssl vm_hostname="$(curl -H "Metadata-Flavor:Google"
http://metadata.google.internal/computeMetadata/v1/instance/name)" echo "Page served from: $vm_hostname" |
tee /var/www/html/index.html systemctl restart apache2 - Click Create.
Create a managed instance group. In the Google Cloud console, go to the Instance groups page.
- Click Create instance group.
- Choose New managed instance group (stateless). For more information, see Stateless or stateful MIGs.
- Enter a Name for the instance group:
cross-ref-ig-backend
. - For Location, select Single zone.
- For Region, select
us-west1
. - For Zone, select
us-west1-a
. - For Instance template, select cross-ref-backend-template.
Specify the number of instances that you want to create in the group.
For this example, specify the following options for Autoscaling:
- For Autoscaling mode, select
Off:do not autoscale
. - For Maximum number of instances, enter
2
.
Optionally, in the Autoscaling section of the UI, you can configure the instance group to automatically add or remove instances based on instance CPU usage.
- For Autoscaling mode, select
Click Create.
Create a regional backend service. As a part of this step we'll also create the health check and add backends to the backend service. In the Google Cloud console, go to the Backends page.
- Click Create regional backend service.
- Enter a Name for the backend service:
cross-ref-backend-service
. - For Region, select us-west1.
- For Load balancer type, select Regional internal Application Load Balancer (INTERNAL_MANAGED).
- Set Backend type to Instance groups.
- In the Backends section, set Network to lb-network.
- Click Add backend and set the following fields:
- Set Instance group to cross-ref-ig-backend.
- Enter the Port numbers:
80
. - Set Balancing mode to Utilization.
- Click Done.
- In the Health check section, choose Create a health check with the
following parameters:
- Name:
cross-ref-http-health-check
- Protocol:
HTTP
- Port:
80
- Click Save.
- Name:
- Click Continue.
Optional: In the Add permissions section, enter the IAM principals (typically an email address) of Load Balancer Admins from other projects so that they can use this backend service for load balancers in their own projects. Without this permission, you cannot use cross-project service referencing.
If you don't have permission to set access control policies for backend services in this project, you can still create the backend service now, and an authorized user can perform this step later as described in the section, Grant permissions to the Load Balancer Admin to use the backend service. That section also describes how to grant access to all the backend services in this project, so that you don't have to grant access every time you create a new backend service.
Click Create.
gcloud
Create a VM instance template with an HTTP server with the
gcloud compute instance-templates create
command.gcloud compute instance-templates create BACKEND_IG_TEMPLATE \ --region=us-west1 \ --network=projects/HOST_PROJECT_ID/global/networks/lb-network \ --subnet=projects/HOST_PROJECT_ID/regions/us-west1/subnetworks/lb-frontend-and-backend-subnet \ --tags=allow-ssh,load-balanced-backend \ --image-family=debian-12 \ --image-project=debian-cloud \ --metadata=startup-script='#! /bin/bash apt-get update apt-get install apache2 -y a2ensite default-ssl a2enmod ssl vm_hostname="$(curl -H "Metadata-Flavor:Google" \ http://metadata.google.internal/computeMetadata/v1/instance/name)" echo "Page served from: $vm_hostname" | \ tee /var/www/html/index.html systemctl restart apache2' \ --project=SERVICE_PROJECT_B_ID
Replace the following:
BACKEND_IG_TEMPLATE
: the name for the instance group template.SERVICE_PROJECT_B_ID
: the project ID for service project B, where the load balancer's backends and the backend service are being created.HOST_PROJECT_ID
: the project ID for the Shared VPC host project.
Create a managed instance group in the zone with the
gcloud compute instance-groups managed create
command.gcloud compute instance-groups managed create BACKEND_MIG \ --zone=us-west1-a \ --size=2 \ --template=BACKEND_IG_TEMPLATE \ --project=SERVICE_PROJECT_B_ID
Replace the following:
BACKEND_MIG
: the name for the backend instance group.
Define the HTTP health check with the
gcloud compute health-checks create http
command.gcloud compute health-checks create http HTTP_HEALTH_CHECK_NAME \ --region=us-west1 \ --use-serving-port \ --project=SERVICE_PROJECT_B_ID
Replace the following:
HTTP_HEALTH_CHECK_NAME
: the name for the HTTP health check.
Define the backend service with the
gcloud compute backend-services create
command.gcloud compute backend-services create BACKEND_SERVICE_NAME \ --load-balancing-scheme=INTERNAL_MANAGED \ --protocol=HTTP \ --health-checks=HTTP_HEALTH_CHECK_NAME \ --health-checks-region=us-west1 \ --region=us-west1 \ --project=SERVICE_PROJECT_B_ID
Replace the following:
BACKEND_SERVICE_NAME
: the name for the backend service created in service project B.
Add backends to the backend service with the
gcloud compute backend-services add-backend
command.gcloud compute backend-services add-backend BACKEND_SERVICE_NAME \ --balancing-mode=UTILIZATION \ --instance-group=BACKEND_MIG \ --instance-group-zone=us-west1-a \ --region=us-west1 \ --project=SERVICE_PROJECT_B_ID
Terraform
Create an instance template.
Create a managed instance group.
For HTTP
For HTTPS
Create a health check for backend.
For HTTP
For HTTPS
Create a regional backend service.
Create the load balancer frontend and URL map in service project A
All the steps in this section must be performed in service project A.
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 Application Load Balancer (HTTP/HTTPS) and click Next.
- For Public facing or internal, select Internal and click Next.
- For Cross-region or single region deployment, select Best for regional workloads and click Next.
- Click Configure.
Basic configuration
- Enter a Name for the load balancer.
- For the Region, select
us-west1
. For the Network, select lb-network (from Project: HOST_PROJECT_NAME).
If you see a Proxy-only subnet required in Shared VPC network warning, confirm that the host project admin has created the
proxy-only-subnet
in theus-west1
region in thelb-network
Shared VPC network. Load balancer creation succeeds even if you do not have permission to view the proxy-only subnet on this page.Keep the window open to continue.
Configure the backend
- Click Backend configuration.
- Click Cross-project backend services.
- For Project ID, enter the project ID for service project B.
- For Backend service name, enter the name of the backend service from
service project B that you want to use. For this example, it's
cross-ref-backend-service
. - Click Add backend service.
Configure the routing rules
- Click Routing rules. Ensure that the cross-ref-backend-service is the only backend service for any unmatched host and any unmatched path.
For information about traffic management, see Setting up traffic management.
Configure the frontend
For cross-project service referencing to work, the frontend must use
the same network (lb-network
) from the Shared VPC host project
that was used to create the backend service.
For HTTP:
- Click Frontend configuration.
- Enter a Name for the forwarding rule:
cross-ref-http-forwarding-rule
. - Set the Protocol to
HTTP
. - Set the Subnetwork to
lb-frontend-and-backend-subnet
. Don't select the proxy-only subnet for the frontend even if it is an option in the list. - Set the Port to
80
. - Click the IP address menu, and then click Create IP address.
- In the Reserve a static internal IP address panel, provide the
following details:
- For the Name, enter
cross-ref-ip-address
. - For Static IP address, click Let me choose. For Custom IP
address, enter
10.1.2.98
. - (Optional) If you want to share this IP address with different frontends, for set Purpose to Shared.
- For the Name, enter
- Click Done.
For HTTPS:
If you are using HTTPS between the client and the load balancer, you need one or more SSL certificate resources to configure the proxy. For information about how to create SSL certificate resources, see SSL certificates. Google-managed certificates aren't currently supported with internal Application Load Balancers.
- Click Frontend configuration.
- Enter a Name for the forwarding rule:
cross-ref-https-forwarding-rule
. - In the Protocol field, select
HTTPS (includes HTTP/2)
. - Set the Subnetwork to
lb-frontend-and-backend-subnet
. Don't select the proxy-only subnet for the frontend even if it is an option in the list. - Ensure that the Port is set to
443
to allow HTTPS traffic. - Click the IP address menu, and then click Create IP address.
- In the Reserve a static internal IP address panel, provide the
following details:
- For the Name, enter
cross-ref-ip-address
. - For Static IP address, click Let me choose. For Custom IP
address, enter
10.1.2.98
. - (Optional) If you want to share this IP address with different frontends, for set Purpose to Shared.
- For the Name, enter
- Click the Certificate list.
- If you already have a self-managed SSL certificate resource you want to use as the primary SSL certificate, select it from the menu.
- Otherwise, select Create a new certificate.
- Enter a Name for the SSL certificate.
- In the appropriate fields, upload your PEM-formatted files:
- Public key certificate
- Certificate chain
- Private key
- Click Create.
- To add certificate resources in addition to
the primary SSL certificate resource:
- Click Add certificate.
- Select a certificate from the Certificates list or click Create a new certificate and follow the previous instructions.
- Click Done.
Review and finalize the configuration
- Click Create.
Test the load balancer
After the load balancer is created, test the load balancer by using the steps described in Test the load balancer.
gcloud
Optional: Before creating a load balancer with cross-referencing backend services, find out whether the backend services you want to refer to can be referenced using a URL map:
gcloud compute backend-services list-usable \ --region=us-west1 \ --project=SERVICE_PROJECT_B_ID
Create the URL map and set the default service to the backend service created in service project B.
gcloud compute url-maps create URL_MAP_NAME \ --default-service=projects/SERVICE_PROJECT_B_ID/regions/us-west1/backendServices/BACKEND_SERVICE_NAME \ --region=us-west1 \ --project=SERVICE_PROJECT_A_ID
Replace the following:
URL_MAP_NAME
: the name for the URL map.BACKEND_SERVICE_NAME
: the name for the backend service created in service project B.SERVICE_PROJECT_B_ID
: the project ID for service project B, where the load balancer's backends and the backend service are created.SERVICE_PROJECT_A_ID
: the project ID for service project A, where the load balancer's frontend is being created.
URL map creation fails if you don't have the
compute.backendServices.use
permission for the backend service in service project B.Create the target proxy.
For HTTP:
gcloud compute target-http-proxies create HTTP_TARGET_PROXY_NAME \ --url-map=URL_MAP_NAME \ --url-map-region=us-west1 \ --region=us-west1 \ --project=SERVICE_PROJECT_A_ID
Replace the following:
HTTP_TARGET_PROXY_NAME
: the name for the target HTTP proxy.
For HTTPS:
Create a regional SSL certificate using the
gcloud compute ssl-certificates create
command.gcloud compute ssl-certificates create SSL_CERTIFICATE_NAME \ --certificate=PATH_TO_CERTIFICATE \ --private-key=PATH_TO_PRIVATE_KEY \ --region=us-west1 \ --project=SERVICE_PROJECT_A_ID
Replace the following:
SSL_CERTIFICATE_NAME
: the name for the SSL certificate resource.PATH_TO_CERTIFICATE
: the path to the local SSL certificate file in PEM format.PATH_TO_PRIVATE_KEY
: the path to the local SSL certificate private key in PEM format.
Use the regional SSL certificate to create a target proxy with the
gcloud compute target-https-proxies create
command.gcloud compute target-https-proxies create HTTPS_TARGET_PROXY_NAME \ --url-map=URL_MAP_NAME \ --region=us-west1 \ --ssl-certificates=SSL_CERTIFICATE_NAME \ --project=SERVICE_PROJECT_A_ID
Replace the following:
HTTPS_TARGET_PROXY_NAME
: the name for the target HTTPS proxy.
Create the forwarding rule. For cross-project service referencing to work, the forwarding rule must use the same network (
lb-network
) from the Shared VPC host project that was used to create the backend service.For HTTP:
gcloud compute forwarding-rules create HTTP_FORWARDING_RULE_NAME \ --load-balancing-scheme=INTERNAL_MANAGED \ --network=projects/HOST_PROJECT_ID/global/networks/lb-network \ --subnet=projects/HOST_PROJECT_ID/regions/us-west1/subnetworks/lb-frontend-and-backend-subnet \ --address=IP_ADDRESS_CROSS_REF \ --ports=80 \ --region=us-west1 \ --target-http-proxy=HTTP_TARGET_PROXY_NAME \ --target-http-proxy-region=us-west1 \ --project=SERVICE_PROJECT_A_ID
Replace the following:
HTTP_FORWARDING_RULE_NAME
: the name for the forwarding rule that is used to handle HTTP traffic.
For HTTPS:
gcloud compute forwarding-rules create HTTPS_FORWARDING_RULE_NAME \ --load-balancing-scheme=INTERNAL_MANAGED \ --network=projects/HOST_PROJECT_ID/global/networks/lb-network \ --subnet=projects/HOST_PROJECT_ID/regions/us-west1/subnetworks/lb-frontend-and-backend-subnet \ --address=IP_ADDRESS_CROSS_REF \ --ports=443 \ --region=us-west1 \ --target-https-proxy=HTTPS_TARGET_PROXY_NAME \ --target-https-proxy-region=us-west1 \ --project=SERVICE_PROJECT_A_ID
Replace the following:
HTTPS_FORWARDING_RULE_NAME
: the name for the forwarding rule that is used to handle HTTPS traffic.
To test the load balancer, use the steps described in Test the load balancer.
Terraform
Create the URL map.
Create the target proxy.
For HTTP
For HTTPS
Create a regional SSL certificate
Use the regional SSL certificate to create a target proxy
Create the forwarding rule.
For HTTP
For HTTPS
To test the load balancer, use the steps described in Test the load balancer.
Grant permissions to the Load Balancer Admin to use the backend service
If you want load balancers to reference backend services in other service
projects, the Load Balancer Admin must have the compute.backendServices.use
permission. To grant this permission, you can use the predefined
IAM role called
Compute Load Balancer Services User (roles/compute.loadBalancerServiceUser
).
This role must be granted by the Service Project Admin and can be applied at
the project level or at the individual backend service level.
This step is not required if you already granted the required permissions at the backend service level while creating the backend service. You can either skip this section or continue reading to learn how to grant access to all the backend services in this project so that you don't have to grant access every time you create a new backend service.
In this example, a Service Project Admin from service project B must run one
of the following commands to grant the compute.backendServices.use
permission
to a Load Balancer Admin from service project A. This can be done either at the
project level (for all backend services in the project) or per backend service.
Console
Project-level permissions
Use the following steps to grant permissions to all backend services in your project.
You require the compute.regionBackendServices.setIamPolicy
and the
resourcemanager.projects.setIamPolicy
permissions to complete this step.
In the Google Cloud console, go to the Shared load balancing services page.
In the All backend service permissions (project-level permissions) section, select your project.
If the permissions panel is not visible, click Show permissions panel. The Project level permissions panel opens on the right.
Click
Add principal.For New principals, enter the principal's email address or other identifier.
For Role, select the Compute Load Balancer Services User role from the drop-down list.
Optional: Add a condition to the role.
Click Save.
Resource-level permissions for individual backend services
Use the following steps to grant permissions to individual backend services in your project.
You require the compute.regionBackendServices.setIamPolicy
permission to
complete this step.
In the Google Cloud console, go to the Shared load balancing services page.
In the Individual backend service permissions (resource-level permissions) section, select the backend service that you want to grant access to.
Click
Add principal.For New principals, enter the principal's email address or other identifier.
For Role, select the Compute Load Balancer Services User role from the drop-down list.
Click Save.
gcloud
Project-level permissions
Use the following steps to grant permissions to all backend services in your project.
You require the compute.regionBackendServices.setIamPolicy
and the
resourcemanager.projects.setIamPolicy
permissions to complete this step.
gcloud projects add-iam-policy-binding SERVICE_PROJECT_B_ID \ --member="user:LOAD_BALANCER_ADMIN" \ --role="roles/compute.loadBalancerServiceUser"
Resource-level permissions for individual backend services
At the backend service level, Service Project Admins can use either of the
following commands to grant the Compute Load Balancer Services User role
(roles/compute.loadBalancerServiceUser
).
You require the compute.regionBackendServices.setIamPolicy
permission to
complete this step.
gcloud projects add-iam-policy-binding SERVICE_PROJECT_B_ID \ --member="user:LOAD_BALANCER_ADMIN" \ --role="roles/compute.loadBalancerServiceUser" \ --condition='expression=resource.name=="projects/SERVICE_PROJECT_B_ID/regions/us-west1/backend-services/BACKEND_SERVICE_NAME",title=Shared VPC condition'
or
gcloud compute backend-services add-iam-policy-binding BACKEND_SERVICE_NAME \ --member="user:LOAD_BALANCER_ADMIN" \ --role="roles/compute.loadBalancerServiceUser" \ --project=SERVICE_PROJECT_B_ID \ --region=us-west1
To use these commands, replace LOAD_BALANCER_ADMIN
with the
user's principal—for
example, test-user@gmail.com
.
You can also configure IAM permissions so that they only apply to a subset of regional backend services by using conditions and specifying condition attributes.
To see URL maps referencing a particular Shared VPC backend service, follow these steps:
gcloud
To see resources referencing a regional Shared VPC backend service, run the following command:
gcloud compute backend-services describe BACKEND_SERVICE_NAME \ --region REGION
Replace the following:
BACKEND_SERVICE_NAME
: the name of the load balancer backend serviceREGION
: the region of the load balancer
In the command output, review the usedBy
field, which displays the
resources referencing the backend service, as shown in the following
example:
id: '123456789' kind: compute#backendService loadBalancingScheme: INTERNAL_MANAGED ... usedBy: - reference: https://www.googleapis.com/compute/v1/projects/my-project/region/us-central1/urlMaps/my-url-map
What's next
- You can restrict how Shared VPC features such as cross-project service referencing are used in your project by using organization policy constraints. For more information, see Organization policy constraints for Cloud Load Balancing.
- To manage the proxy-only subnet resource required by internal Application Load Balancers, see Proxy-only subnet for internal Application Load Balancers.
- To see how to troubleshoot issues with an internal Application Load Balancer, see Troubleshoot internal Application Load Balancers.
- Clean up the load balancer setup.