Internal load balancing and DNS names

A DNS address record, known as an A record, is used to map a DNS name to an IP address. When you create the forwarding rule for an internal load balancer, you can optionally designate a service label so that Google Cloud creates a unique Compute Engine internal DNS name for the load balancer. This internal DNS name is constructed from your project ID, forwarding rule name, and a service label you specify.

Note: This page describes how to create a specific load balancer component before or after you've already created a load balancer. Working with specific components is useful for advanced configurations and necessary for some configuration options. Before using the information on this page, know the type of Google Cloud load balancer that you need.

Specifications

• This feature is supported by forwarding rules for these load balancers:

  • Internal TCP/UDP load balancer
  • Internal HTTP(S) load balancer

• See DNS record format for details about the format of the DNS name that Google Cloud creates for your load balancer. Because the DNS name contains the forwarding rule's name, each DNS name is unique, even if you use the same service label for multiple forwarding rules.

• Unless an alternative name server is configured, client VMs in any region in the same project and VPC network can perform DNS lookups for the load balancer's internal DNS name. To access the load balancer, client VMs must be located in the same region, unless global access is available and enabled. If you enable global access for an internal TCP/UDP load balancer, a client in any region can access the load balancer.

• You can only specify a service label when you create a forwarding rule. You cannot add a service label to an existing forwarding rule. However, you can replace an existing forwarding rule with a new forwarding rule that has a service label. The replacement can use the same internal IP address as the original if you delete the original forwarding rule first.

• The internal DNS names created from service labels have the following restrictions:

  • No corresponding reverse (PTR) records are created.
  • Each forwarding rule can have only one service label.
  • Other than the service label and forwarding rule's name, you cannot change any other part of the internal DNS name. This includes its format and its domain name (.internal).
  • You cannot define a service label on an internal forwarding rule that uses IPv6 addresses.

  If you need more flexible DNS names for your internal load balancer, you can create custom records in a Cloud DNS managed private zone.

DNS record format

When you add a service label to a forwarding rule, Google Cloud creates a Compute Engine internal DNS A record using one of these formats:

• For internal TCP/UDP load balancers:

  SERVICE_LABEL.FORWARDING_RULE_NAME.il4.REGION.lb.PROJECT_ID.internal

• For internal HTTP(S) load balancers:

  SERVICE_LABEL.FORWARDING_RULE_NAME.il7.REGION.lb.PROJECT_ID.internal

SERVICE_LABEL is the forwarding rule's service label that you specify. It must follow this format:

• You can use up to 63 lower case letters (a to z), numbers (0 to 9), or dashes (-).
• The service label must start with a lowercase letter.
• The service label must end with a lowercase letter or number.

FORWARDING_RULE_NAME is the name of the forwarding rule you're creating.

REGION is the load balancer's region.

PROJECT_ID is your project ID. Project IDs that have the form organization:project-id are converted to project-id.organization. For example, if your project ID is example.com:example-marketing-prod, Google Cloud uses example-marketing-prod.example.com.

Creating a forwarding rule with a service label

This procedure shows how to create a forwarding rule with a service label for either an internal TCP/UDP load balancer or an internal HTTP(S) load balancer.

This procedure only focuses on how to create a forwarding rule with a service label. Properties of the load balancer's backend configuration and other properties of its frontend configuration are omitted. If you're new to internal TCP/UDP load balancers or internal HTTP(S) load balancers, see these pages for complete examples:

• Set up an internal TCP/UDP load balancer

• Set up an internal HTTP(S) load balancer

Console

1. Go to the Load balancing page in the Google Cloud console.
   Go to the Load balancing page
2. Click Create load balancer.
3. Under HTTP(S) Load Balancing, TCP Load Balancing, or UDP Load Balancing, click Start configuration.
4. Under Internet facing or internal only, select Only between my VMs, and then click Continue.
5. Specify a Name for the load balancer.
6. Complete the Backend configuration.
7. Click Frontend configuration. Complete the frontend configuration, specifying a Service label at the bottom of that section.
8. Click Done, and then Review and finalize.

gcloud

To create a forwarding rule with a service label for an internal TCP/UDP load balancer:

gcloud compute forwarding-rules create FORWARDING_RULE_NAME \
    --load-balancing-scheme=INTERNAL \
    --region=REGION \
    --backend-service-region=REGION \
    --backend-service=BACKEND_SERVICE_NAME \
    --network=NETWORK \
    --subnet=SUBNET \
    --address=INTERNAL_IP \
    --ip-protocol=PROTOCOL \
    --ports=PORTS \
    --service-label=SERVICE_LABEL

To create a forwarding rule with a service label for an internal HTTPS load balancer:

gcloud compute forwarding-rules create FORWARDING_RULE_NAME \
    --load-balancing-scheme=INTERNAL_MANAGED \
    --region=REGION \
    --target-https-proxy-region=REGION \
    --target-https-proxy=TARGET_PROXY_NAME \
    --network=NETWORK \
    --subnet=SUBNET \
    --address=INTERNAL_IP \
    --ip-protocol=TCP \
    --ports=443 \
    --service-label=SERVICE_LABEL

To create a forwarding rule with a service label for an internal HTTP load balancer:

gcloud compute forwarding-rules create FORWARDING_RULE_NAME \
    --load-balancing-scheme=INTERNAL_MANAGED \
    --region=REGION \
    --target-http-proxy-region=REGION \
    --target-http-proxy=TARGET_PROXY_NAME \
    --network=NETWORK \
    --subnet=SUBNET \
    --address=INTERNAL_IP \
    --ip-protocol=TCP \
    --ports=PORT \
    --service-label=SERVICE_LABEL

Replace the placeholders with appropriate values:

• FORWARDING_RULE_NAME is the name of the load balancer's forwarding rule.
• REGION is the load balancer's region.
• BACKEND_SERVICE_NAME is the name of the load balancer's backend service.
• TARGET_PROXY_NAME is the name of the target HTTPS proxy (for an internal HTTPS load balancer) or the target HTTP proxy (for an internal HTTP load balancer).
• NETWORK is the name of the VPC network where the load balancer is created.
• SUBNET is the name of a subnet in the VPC network. The subnet must be in the same region as the load balancer's backend service or target proxy.
• INTERNAL_IP is an internal IP address in the primary IP range of the chosen subnet. You can omit the --address flag to have Google Cloud choose an available IP address for you.
• For internal TCP/UDP load balancers, PROTOCOL is either TCP or UDP, matching the protcol of the load balancer's backend service. For internal HTTP(S) load balancers, the protocol must be TCP.
• For internal TCP/UDP load balancers, PORTS is an array of up to five ports by number, or the word ALL. For internal HTTPS load balancers, you must use 443 for the port; for internal HTTP load balancers, you can use either 80 or 8080 for PORT. See Port specifications in forwarding rules concepts for more details.
• SERVICE_LABEL is your desired service label. It must follow the naming conventions.

api

The following examples create forwarding rules using the forwardingRules.insert method

To create a forwarding rule with a service label for an internal TCP/UDP load balancer:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT/regions/REGION/forwardingRules

{
  "name": "FORWARDING_RULE_NAME",
  "loadBalancingScheme": "INTERNAL",
  "backendService": "https://www.googleapis.com/compute/v1/projects/PROJECT/regions/REGION/backendServices/BACKEND_SERVICE_NAME",
  "network": "https://www.googleapis.com/compute/v1/projects/PROJECT/global/networks/NETWORK",
  "subnetwork": "https://www.googleapis.com/compute/v1/projects/PROJECT/regions/REGION/subnetworks/SUBNET",
  "IPAddress": "INTERNAL_IP",
  "IPProtocol": "PROTOCOL",
  "ports": PORTS,
  "serviceLabel": "SERVICE_LABEL"
}

To create a forwarding rule with a service label for an internal HTTPS load balancer:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT/regions/REGION/forwardingRules

{
  "name": "FORWARDING_RULE_NAME",
  "loadBalancingScheme": "INTERNAL_MANAGED",
  "target": "https://www.googleapis.com/compute/v1/projects/PROJECT/regions/REGION/targetHttpsProxies/TARGET_PROXY_NAME",
  "network": "https://www.googleapis.com/compute/v1/projects/PROJECT/global/networks/NETWORK",
  "subnetwork": "https://www.googleapis.com/compute/v1/projects/PROJECT/regions/REGION/subnetworks/SUBNET",
  "IPAddress": "INTERNAL_IP",
  "IPProtocol": "TCP",
  "ports": 443,
  "serviceLabel": "SERVICE_LABEL"
}

To create a forwarding rule with a service label for an internal HTTP load balancer:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT/regions/REGION/forwardingRules

{
  "name": "FORWARDING_RULE_NAME",
  "loadBalancingScheme": "INTERNAL_MANAGED",
  "target": "https://www.googleapis.com/compute/v1/projects/PROJECT/regions/REGION/targetHttpProxies/TARGET_PROXY_NAME",
  "network": "https://www.googleapis.com/compute/v1/projects/PROJECT/global/networks/NETWORK",
  "subnetwork": "https://www.googleapis.com/compute/v1/projects/PROJECT/regions/REGION/subnetworks/SUBNET",
  "IPAddress": "INTERNAL_IP",
  "IPProtocol": "TCP",
  "ports": PORT,
  "serviceLabel": "SERVICE_LABEL"
}

Replace the placeholders with appropriate values:

• FORWARDING_RULE_NAME is the name of the load balancer's forwarding rule.
• REGION is the load balancer's region.
• BACKEND_SERVICE_NAME is the name of the internal TCP/UDP load balancer's backend service.
• TARGET_PROXY_NAME is the name of the target HTTPS proxy (for an internal HTTPS load balancer) or the target HTTP proxy (for an internal HTTP load balancer).
• NETWORK is the name of the VPC network where the load balancer is created.
• SUBNET is the name of a subnet in the VPC network. The subnet must be in the same region as the load balancer's backend service or target proxy.
• INTERNAL_IP is an internal IP address in the primary IP range of the chosen subnet. You can omit the IPAddress key to have Google Cloud choose an available IP address for you.
• For internal TCP/UDP load balancers, PROTOCOL is either TCP or UDP, matching the protcol of the load balancer's backend service. For internal HTTP(S) load balancers, the protocol must be TCP.
• For internal TCP/UDP load balancers, PORTS is an array of up to five ports by number, or the word ALL. For internal HTTPS load balancers, you must use 443 for the port; for internal HTTP load balancers, you can use either 80 or 8080 for PORT. See Port specifications in forwarding rules concepts for more details.
• SERVICE_LABEL is your desired service label. It must follow the naming conventions.

Viewing service labels

Console

You can view the Compute Engine internal DNS name (created from the service label) for each internal forwarding rule of an internal load balancer:

1. Go to the Load balancing page in the Google Cloud console.
   Go to the Load balancing page
2. Click the name of the internal load balancer to view its details page.
3. The internal forwarding rules assigned to the load balancer are listed in the Frontend section. The DNS name column shows you the Compute Engine internal DNS name that's assigned to each forwarding rule. The service label is the first part of that name (before the first dot). If no name is shown, the forwarding rule has no service label defined.

gcloud

1. List forwarding rules in your project used by either internal TCP/UDP load balancers or internal HTTP(S) load balancers. Locate the one you need, and note its name and region for the next step.

   gcloud compute forwarding-rules list \
       --filter="loadBalancingScheme=SCHEME"
   

   The value of SCHEME depends on the forwarding rules you need to list:

   • For internal TCP/UDP load balancers, use INTERNAL.
   • For internal HTTP(S) load balancers, use INTERNAL_MANAGED.

2. Describe the forwarding rule, replacing FORWARDING_RULE_NAME with its name and REGION with its region:

   gcloud compute forwarding-rules describe FORWARDING_RULE_NAME \
       --region=REGION \
       --format="get(serviceLabel)"
   

api

View the forwarding rule and service label with the forwardingRules.get method

The response to the API request includes the service label (serviceLabel) and Compute Engine internal DNS name (serviceName).

GET https://compute.googleapis.com/compute/v1/projects/PROJECT/regions/REGION/forwardingRules/FORWARDING_RULE_NAME

TCP/UDP response:

{
  ...
  "serviceLabel": "SERVICE_LABEL",
  "serviceName": "SERVICE_LABEL.FORWARDING_RULE_NAME.il4.REGION.lb.PROJECT.internal",
  ...
}

HTTP(S) response:

{
  ...
  "serviceLabel": "SERVICE_LABEL",
  "serviceName": "SERVICE_LABEL.FORWARDING_RULE_NAME.il7.REGION.lb.PROJECT.internal",
  ...
}

Example

The following procedure demonstrates how to replace a forwarding rule with one that has a service label. This procedure works for both internal TCP/UDP load balancers and internal HTTP(S) load balancers.

If you haven't created a forwarding rule for your internal load balancer yet, skip this example and refer to Creating a forwarding rule with a service label instead.

1. Describe your load balancer's existing forwarding rule, noting the forwarding rule's internal IP address:

   gcloud compute forwarding-rules describe FORWARDING_RULE_NAME \
       --region=REGION \
       --format="get(IPAddress)"
   

2. Delete the forwarding rule:

   gcloud compute forwarding-rules delete FORWARDING_RULE_NAME \
       --region=REGION
   

3. Create a replacement forwarding rule with the same name and internal IP address with a service label. Refer to Creating a forwarding rule with a service label for directions.

What's next

• See Internal TCP/UDP load balancer overview and Internal HTTP(S) load balancer overview for important fundamentals.
• See Set up an internal TCP/UDP load balancer and Set up an internal HTTP(S) load balancer for example internal load balancer configurations.
• See Failover for internal TCP/UDP load balancers for important information about failover.
• See Configure failover for internal TCP/UDP load balancers for configuration steps and an example internal TCP/UDP load balancer failover configuration.
• See Internal TCP/UDP load balancer logging and monitoring for information on configuring Logging and Monitoring for internal TCP/UDP load balancers.
• See Internal load balancing and connected networks for information about accessing internal load balancers from peer networks connected to your VPC network.
• See Troubleshooting internal TCP/UDP load balancers for information about how to troubleshoot issues with your internal TCP/UDP load balancer.