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 configure an internal load balancer, you can optionally designate a service label for GCP to create a Compute Engine internal DNS name for the load balancer. This internal DNS name is constructed from your project ID, internal forwarding rule name, and a service label you choose.

Client VMs in the same project, VPC network, and region can use the internal DNS name (A record) instead of the forwarding rule's IP address to send traffic to the load balancer. In your code and scripts, you can substitute the DNS name in place of the IP address.

Specifications

• This feature is supported for internal load balancers:

  • Internal TCP/UDP load balancers

• See DNS record format for details about the format of the DNS name that GCP 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.

• Client VMs in any region in the same project and VPC network can perform DNS lookups for the load balancer's internal DNS name; however, client VMs must be located in the same region as the load balancer to send traffic to it.

• You can only specify a service label when you create an internal forwarding rule. You cannot add a service label to an existing internal 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 internal 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).

  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

The unique Compute Engine internal DNS A record for an internal TCP/UDP load balancer uses this format:

• Internal TCP/UDP Load Balancing:

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

where

• [SERVICE_LABEL] is the service label that you specify, in the following 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 your forwarding rule, which was set when you created it.
• [REGION] is the region where you created the forwarding rule.
• [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, GCP uses example-marketing-prod.example.com.

Creating an internal forwarding rule with a service label

This procedure shows the steps to assign a service label to an internal forwarding rule in an internal load balancer. Properties of the backend configuration and other properties of the frontend configuration are omitted. For a full example, see:

• Setting Up Internal TCP/UDP Load Balancing In the gcloud and API fields, replace the placeholders with appropriate values:

• [FORWARDING_RULE_NAME] is the name of your internal forwarding rule.

• [REGION] is the region in which your internal TCP/UDP load balancer is located.

• [BACKEND_SERVICE_NAME] is the name of the internal TCP/UDP load balancer's backend service.

• [NETWORK] is the name of the VPC network for the internal TCP/UDP load balancer.

• [SUBNET] is the name of a subnet in the specified VPC network in the same region as the load balancer's backend service.

• [INTERNAL_IP] is an internal IP address in the primary IP range of the chosen subnet. You can omit the --address flag to have GCP choose an available IP address for you.

• [PROTOCOL] is either TCP or UDP, matching the protcol of the backend service.

• [PORTS] is an array of up to five ports by number, or the word ALL. See forwarding rules and port specifications for more information.

• [SERVICE_LABEL] is your desired service label. It must follow the naming conventions.

For internal TCP/UDP load balancers, the loadBalancingScheme is INTERNAL.

Console

1. Go to the Load balancing page in the Google Cloud Platform Console.
   Go to the Load balancing page
2. Click Create load balancer.
3. Under TCP Load Balancing or UDP Load Balancing, click Start configuration.
4. Under Internet facing or internal only select Only between my VMs, 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

gcloud compute forwarding-rules create [FORWARDING_RULE_NAME] \
    --load-balancing-scheme=INTERNAL | --load-balancing-scheme=INTERNAL_MANAGED \
    --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]

api

Add a forwarding rule and service label with the forwardingRules.insert method

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

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

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 Platform 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

For internal TCP/UDP load balancers, the loadBalancingScheme is INTERNAL.

1. List all internal forwarding rules in your project. Note its name and region for the next step.

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

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://www.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",
  ...
}

Example

The following procedure demonstrates how to create a forwarding rule with a service label for the example internal TCP/UDP load balancer. On that page, the internal forwarding rule has no service label. If you followed that example, you can delete the forwarding rule and replace it with one that has a service label.

1. Delete the fr-ilb forwarding rule.

   gcloud compute forwarding-rules delete fr-ilb \
       --region=us-west1
   

2. Create a forwarding rule with the same name and a service label. The other parameters for this rule, including the IP address and backend service, are the same as in the original example.

   gcloud compute forwarding-rules create fr-ilb \
       --region=us-west1 \
       --load-balancing-scheme=INTERNAL_MANAGED \
       --network=lb-network \
       --subnet=lb-subnet \
       --address=10.1.2.99 \
       --ip-protocol=TCP \
       --ports=80 \
       --backend-service=be-ilb \
       --backend-service-region=us-west1 \
       --service-label=example
   

Now clients in the us-west1 region can access the load balancer using either its internal IP address, 10.1.2.99, or the following Compute Engine internal DNS name, where [PROJECT] is your project ID:

    example.fr-ilb.il4.us-west1.lb.[PROJECT].internal

What's next

• See Internal TCP/UDP Load Balancing Concepts for important fundamentals.
• See Failover concepts for Internal TCP/UDP Load Balancing for important information about failover.
• See Setting Up Internal TCP/UDP Load Balancing for an example internal load balancer configuration.
• See Configuring failover for Internal TCP/UDP Load Balancing for configuration steps and an example internal TCP/UDP load balancer failover configuration.
• See Internal TCP/UDP Load Balancing Logging and Monitoring for information on configuring Stackdriver logging and monitoring for Internal TCP/UDP Load Balancing.
• See Internal TCP/UDP Load Balancing and Connected Networks for information about accessing internal TCP/UDP load balancers from peer networks connected to your VPC network.
• See Troubleshooting Internal TCP/UDP Load Balancing for information on how to troubleshoot issues with your internal TCP/UDP load balancer.