IPv6 termination for HTTP(S), SSL proxy, and TCP proxy Load Balancing

Google Cloud Platform (GCP) supports IPv6 clients with HTTP(S), SSL proxy, and TCP proxy load balancing. The load balancer accepts IPv6 connections from your users and proxies those connections to your instances.

Overview

You can configure both IPv4 and IPv6 addresses for HTTP(S), SSL proxy, and TCP proxy load balancers.

Global IPv6 load balancing (click to enlarge)
Global IPv6 load balancing (click to enlarge)

Proliferation of IPv6 clients is driven by the explosion of mobile traffic, scarcity of IPv4 addresses, and IPv6-related policy and compliance requirements. IPv6 termination for HTTP(S), SSL proxy, and TCP proxy load balancing enables you to handle IPv6 clients for these use cases. The load balancer services IPv6 requests from your users and proxies them over IPv4 to your backend instances.

This user guide describes capabilities for, and configuration of, IPv6 termination for HTTP(S), SSL proxy, and TCP proxy load balancing.

IPv6 termination and proxy

Configuring IPv6 termination for your load balancers lets your backend instances appear as IPv6 applications to your IPv6 clients.

IPv6 termination for load balancing (click to enlarge)
IPv6 termination for load balancing (click to enlarge)

When a user connects to the load balancer via IPv6, the following happens:

  1. Your load balancer, with its IPv6 address and forwarding rule, waits for user connections.
  2. An IPv6 client connects to the load balancer via IPv6.
  3. The load balancer acts as a reverse proxy and terminates the IPv6 client connection. It places the request into an IPv4 connection to a backend instance.
  4. On the reverse path, the load balancer receives the IPv4 response from the backend instance, then places it into the IPv6 connection back to the original client.

Configuring IPv6 and IPv4 load balancing IPs for same backend instances

If you need to serve both IPv6 and IPv4 clients with your IPv4 backend instances, you can create two forwarding rules, one with an IPv6 address and the other with an IPv4 address. You can then associate both forwarding rules with the same load balancer and backend instances.

Directing IPv4 and IPv6 traffic to the same backend instances (click to enlarge)
Directing IPv4 and IPv6 traffic to the same backend instances (click to enlarge)

IPv6 address allocation for load balancer forwarding rules

When you configure an HTTP(S), SSL proxy, or TCP proxy load balancer, you provide it with one or more global forwarding rules, each with an external, publicly routed IPv4 or IPv6 IP address. You can use this IP address in the DNS records for your site.

When you create a forwarding rule, you can either use a static IP address reserved for your project or you can have the forwarding rule automatically acquire an ephemeral IP address when you create the rule. A static IP address is reserved to your project, and you can keep it until you deliberately release it. An ephemeral address belongs to the forwarding rule as long as the forwarding rule exists. If you delete the forwarding rule, the ephemeral address is released back into the GCP pool.

If you need both an IPv4 and IPv6 address for your load balancer, you can create two forwarding rules, associating an IPv4 address with one and an IPv6 address with the other. You can then associate both rules with the same load balancer.

IPv6 termination features

All features supported for IPv4 load balancing are also supported with IPv6 load balancing. These include:

Client IP header with IPv6 termination for HTTP(S) load balancing

When the load balancer proxies the IPv6 connection from the client to an IPv4 connection to your instance, the original source IP address is replaced with the load balancer's IP address. However, backend instances often need to know the original source IP for logging, decision making, or for other purposes. GCP provides an HTTP header that is propagated to the backend instance which includes the original IPv6 client IP.

HTTP headers for IPv6 are similar to those for IPv4. The format for requests is:

  • X-Forwarded-For: <client IP(s)>, <global forwarding rule external IP>
  • The last element shows the load balancer IP. The second to last element shows the client IP as seen by the load balancer. There may be other elements in the X-Forwarded-For header in cases where the client or intervening proxies add other X-Forwarded-For headers before sending the request to the load balancer.

An example X-Forwarded-For header may look like this:

X-Forwarded-For: 2001:db8:abcd:1::1234, 2607:f8b0:4005:801::200e

The first (second-to-last) address is the client’s IPv6 address. The second address is the IPv6 address of the HTTP(S) load balancer.

REST API

Global Addresses

Represents a Global Address resource. Global addresses are only used for Global Forwarding Rule resources and cannot be used for other resources. Both global addresses and global forwarding rules can only be used for global load balancing, not Network load balancing. A new field, ipVersion, indicates if an IP address IPv4 or IPv6. It is used in the insert request.

You cannot change the IP address or IP version associated with an address resource. The update method cannot change these fields.

Resource representations

A reserved address resource.

"kind": "compute#address",
  "id": unsigned long,
  "creationTimestamp": string,
  "status": string,
  "region": string,
  "name": string,
  "description": string,
  "address": string,
  "selfLink": string,
  "users": [
    string
  ],
  “ipVersion”: string,  // Valid values are “IPV4” and “IPV6”
}
Property name Value Description
address string [Output Only] The static external IP address represented by this resource.
creationTimestamp string [Output Only] Creation timestamp in RFC3339 text format.
description string An optional description of this resource. Provide this property when you create the resource.
id unsigned long [Output Only] The unique identifier for the resource. This identifier is defined by the server.
kind string [Output Only] Type of the resource. Always “compute#address” for addresses.
name string Name of the resource. Provided by the client when the resource is created. The name must be 1-63 characters long, and comply with RFC1035. Specifically, the name must be 1-63 characters long and match the regular expression [a-z]([-a-z0-9]*[a-z0-9])? which means the first character must be a lowercase letter, and all following characters must be a dash, lowercase letter, or digit, except the last character, which cannot be a dash.
region string [Output Only] URL of the region where the regional address resides. This field is not applicable to global addresses.
selfLink string [Output Only] Server-defined URL for the resource.
status string [Output Only] The status of the address, which can be either IN_USE or RESERVED. An address that is RESERVED is currently reserved and available to use. An IN_USE address is currently being used by another resource and is not available.
users[] list [Output Only] The URLs of the resources that are using this address.
ipVersion string Valid values are “IPV4” and “IPV6”. This field is optional. When not specified, the default value is “IPV4”. When included in a request, this field indicates the version of IP address to allocate. When returned in a response, it is the value specified when allocating the address.

delete

Deletes the specified address resource. This method does not change for IPv6.

get

Returns the specified address resource. Get a list of available addresses by making a list() request. For example, an request like the following returns an IPv6 address in colon notation in the address portion of the response.

GET /compute/v1/projects/[PROJECT_ID]/global/addresses/[IP_ADDRESS]
{
 "kind": "compute#address",
 "id": "2524574447380838367",
 "creationTimestamp": "2016-07-11T14:01:37.817-07:00",
 "status": "IN_USE",
 "name": "lb-ip-cr",
 "description": "",
 "address": "2001:db8:2000:1::",
 "selfLink": "https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/global/addresses/[IP_ADDRESS]",
 "users": [ "https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/global/forwardingRules/[RULE_NAME]"
 ],
 “ipVersion” : “IPV6”
}

insert

Creates an address resource in the specified project using the data included in the request. To create an IPv6 address, include the ipVersion in the GlobalAddress resource. For example, to create an IPv6 address, send an HTTP POST request like the one shown here:

POST /compute/v1/projects/[PROJECT_ID]/global/addresses

{
  "name": "ip-v6-proj",
  “ipVersion”: “IPV6”
}

list

Retrieves a list of global addresses. For example, this request returns an IPv6 address in colon notation:

GET /compute/v1/projects/[PROJECT_ID]/global/addresses
{
 "kind": "compute#address",
 "id": "2524574447380838367",
 "creationTimestamp": "2016-07-11T14:01:37.817-07:00",
 "status": "IN_USE",
 "name": "lb-ip-cr",
 "description": "",
 "address": "2001:db8:2000:1::",
 "selfLink": "https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/global/addresses/[IP_ADDRESS]",
 "users": [
  "https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/global/forwardingRules/[RULE_NAME]”
 ],
 “ipVersion” : “IPV6”
}

Global Forwarding Rules

Resource representations

Represents a GlobalForwardingRule resource. Global forwarding rules are used to forward traffic to the correct load balancer for HTTP load balancing. Global forwarding rules can only be used for HTTP load balancing. A new field, ipVersion, indicates if an IP address is IPv4 or IPv6. It is used in the insert request. Note that you cannot update the ipVersion in an existing Global Forwarding Rule.

{
  "kind": "compute#forwardingRule",
  "region": string,
  "id": unsigned long,
  "creationTimestamp": string,
  "name": string,
  "description": string,
  "IPAddress": string,
  "IPProtocol": string,
  "portRange": string,
  "target": string,
  "selfLink": string,
  “ipVersion”: string
}
Property name Value Description
IPAddress string [Output Only] Value of the reserved IP address that this forwarding rule is serving on behalf of. For global forwarding rules, the address must be a global IP; for regional forwarding rules, the address must live in the same region as the forwarding rule. If left empty (default value), an ephemeral IP from the same scope (global or regional) will be assigned.
IPProtocol string The IP protocol to which this rule applies. Valid options are TCP, UDP, ESP, AH, SCTP or ICMP.
creationTimestamp string [Output Only] Creation timestamp in RFC3339 text format.
description string An optional description of this resource. Provide this property when you create the resource.
id unsigned long [Output Only] The unique identifier for the resource. This identifier is defined by the server.
kind string [Output Only] Type of the resource. Always “compute#forwardingRule” for Forwarding Rule resources.
name string Name of the resource; provided by the client when the resource is created. The name must be 1-63 characters long, and comply with RFC1035. Specifically, the name must be 1-63 characters long and match the regular expression [a-z]([-a-z0-9]*[a-z0-9])? which means the first character must be a lowercase letter, and all following characters must be a dash, lowercase letter, or digit, except the last character, which cannot be a dash.
portRange string Applicable only when IPProtocol is TCP, UDP, or SCTP, only packets addressed to ports in the specified range will be forwarded to target. Forwarding rules with the same [IPAddress, IPProtocol] pair must have disjoint port ranges.
region string [Output Only] URL of the region where the regional forwarding rule resides. This field is not applicable to global forwarding rules.
selfLink string [Output Only] Server-defined URL for the resource.
target string The URL of the target resource to receive the matched traffic. For regional forwarding rules, this target must live in the same region as the forwarding rule. For global forwarding rules, this target must be a globalTargetHttpProxy or TargetHttpsProxyresource. The forwarded traffic must be of a type appropriate to the target object. For example, TargetHttpProxy requires HTTP traffic, and TargetHttpsProxy requires HTTPS traffic.
ipVersion string Indicates the IP version for an ephemeral IP address. Valid values are “IPV4” and “IPV6”. This field is allowed only when IPAddress is empty. When not specified, the default value is “IPV4”. When included in a request, this field indicates the version of IP address to allocate. When returned in a response, it is the value specified when allocating the address. Valid for GlobalForwardingRule only.

delete

Deletes the specified ForwardingRule resource. This method does not change for IPv6.

get

Returns the specified ForwardingRule resource. Get a list of available forwarding rules by making a list() request. For example:

GET /compute/v1/projects/[PROJECT_ID]/global/forwardingRules/web-map-forwarding-rule
{
 "kind": "compute#forwardingRule",
 "id": "3874344572430168157",
 "creationTimestamp": "2016-07-11T14:25:07.020-07:00",
 "name": "web-map-forwarding-rule",
 "description": "",
 "IPAddress": "2607:f8b0:4005:801::",
 "IPProtocol": "TCP",
 "portRange": "80-80",
 "target": "https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/global/targetHttpProxies/web-map-target-proxy",
  "selfLink": "https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/global/forwardingRules/web-map-forwarding-rule",
 “ipVersion” : “IPV6”
}

insert

Creates a ForwardingRule resource in the specified project and region using the data included in the request. The following example creates a forwarding rule with an ephemeral IPv6 address:

POST /compute/v1/projects/[PROJECT_ID]/global/forwardingRules
{
 "name": "fr2",
 "portRange": "80",
 "target":  "https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/global/targetHttpProxies/web-map-target-proxy",
 "ipVersion": "IPV6"
}

list

Retrieves a list of ForwardingRule resources available to the specified project. For example, this request returns a structure like the following:

GET /compute/v1/projects/[PROJECT_ID]/global/forwardingRules
{
 "kind": "compute#forwardingRuleList",
 "id": "projects/[PROJECT_ID]/global/forwardingRules",
 "items": [
  {
   "kind": "compute#forwardingRule",
   "id": "3874344572430168157",
   "creationTimestamp": "2016-07-11T14:25:07.020-07:00",
   "name": "web-map-forwarding-rule",
   "description": "",
   "IPAddress": "2001:db8:2a:1::",
   "IPProtocol": "TCP",
   "portRange": "80-80",
   "target": "https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/global/targetHttpProxies/web-map-target-proxy",
   "selfLink": "https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/global/forwardingRules/web-map-forwarding-rule"
  }
 ],
 "selfLink": "https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/global/forwardingRules",
 “ipVersion” : “IPV6”
}

setTarget

Changes target URL for forwarding rule. This method does not change for IPv6.

gcloud command-line tool

Global Addresses

Read and manipulate Google Compute Engine addresses.

create

Reserves a new IP address or promotes an ephemeral IP address to reserved.

gcloud alpha compute addresses create [ADDRESS_NAME] \
    [--addresses [IP_ADDRESS]] \
    [--description DESCRIPTION] \
     --global \
    --ip-version [IP_VERSION]
  • --ip-version [IP VERSION]
    Valid values are IPV4 and IPV6. Allowed only when --addresses is not included. If not provided, then a value of IPV4 is used. Requires the --global flag. If provided, an ephemeral IP address of the specified IP version will be created.

To reserve a global IPv6 address, run:

gcloud alpha compute addresses create [IP_ADDRESS] --global --ip-version IPV6
address: 2001:db8:2a:1::
creationTimestamp: '2016-08-22T14:55:58.391-07:00'
description: ''
id: '3806558258942364167'
kind: compute#address
name: ADDRESS
selfLink: https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/global/addresses/[IP_ADDRESS]
status: RESERVED
ipVersion: IPV6

delete

Deletes the specified address resource. This method does not change for IPv6.

describe

IPv6 addresses will be displayed using colon notation. For example:

gcloud compute addresses describe [IP_ADDRESS] --global
address: 2001:db8:2a:1::
creationTimestamp: '2016-08-22T14:55:58.391-07:00'
description: ''
id: '3806558258942364167' kind: compute#address name: ADDRESS ipVersion: IPV6

list

IPv6 addresses will be displayed using colon notation. For example:

gcloud compute addresses list --global
NAME        REGION  ADDRESS                STATUS    IP VERSION
ADDRESS1            2001:db8:2a:1::        RESERVED  IPv6
ADDRESS2            2001:db8:abcd:1234::   IN_USE    IPv6

Global Forwarding Rules

Create and modify global forwarding rules.

create

gcloud alpha compute forwarding-rules create [RULE_NAME] \
    [--address [IP_ADDRESS]] \
    [--ip-protocol [IP_PROTOCOL]] \
    [--ports=[PORT | PORT-PORT],[[PORT | PORT-PORT],…]] \
    --global \
    [--ip-version [IP_VERSION]] \
    [--target-http-proxy [HTTP_PROXY]
      | --target-https-proxy [HTTPS_PROXY]
      | --target-ssl-proxy [SSL_PROXY]
      | --target-tcp-proxy [TCP_PROXY]]
  • --ip-version [IP_VERSION]
    Valid values are IPV4 and IPV6. Allowed only when --address is not included. If not provided, then a value of IPV4 is used. Requires the --global flag. If provided, an ephemeral IP address of the specified IP version will be created.

To create a global forwarding rule with an ephemeral IPv6 address, run:

gcloud alpha compute forwarding-rules create [RULE_NAME] \
    --global \
    --ip-version IPV6 \
    --target_https_proxy [PROXY_NAME] \
    --ports [PORT]

This command returns something like the following:

IPAddress: 2607:f8b0:4005:801::
IPProtocol: TCP
creationTimestamp: '2016-08-26T15:00:12.579-07:00'
description: ''
id: '7746473729712784647'
kind: compute#forwardingRule
name: NAME
portRange: [PORT]-[PORT]
selfLink: https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/global/forwardingRules/[RULE_NAME]
target: [PROXY_NAME]
ipVersion: IPV6

delete

Deletes the specified ForwardingRule resource. This command does not change for IPv6.

describe

IPv6 addresses will be displayed using colon notation.

gcloud compute forwarding-rules describe [RULE_NAME] --global
IPAddress: 2001:db8:4f:7::
IPProtocol: TCP
creationTimestamp: '2016-08-26T14:25:08.225-07:00'
description: ''
id: '5458687325652192607'
kind: compute#forwardingRule
name: [RULE_NAME]
portRange: [PORT-PORT]
selfLink: https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/global/forwardingRules/[RULE_NAME]
target: https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/global/targetHttpProxies/[HTTP_PROXY]
ipVersion: IPV6

list

IPv6 addresses will be displayed using colon notation.

gcloud compute forwarding-rules list --global
NAME     REGION  IP_ADDRESS            PORT  IP_PROTOCOL  TARGET   IP VERSION
NAME1            [IPV4_ADDRESS]        80    TCP          TARGET1  IPv4
NAME2            [IPV6_ADDRESS]        80    TCP          TARGET2  IPv6
NAME3            [IPV6_ADDRESS]        8080  TCP          TARGET3  IPv6

set-target

Sets a target proxy for the forwarding rule. This method does not change for IPv6.

Restrictions

  • IPv6 global forwarding rules are supported with HTTP(S),SSL (TLS) proxy, and TCP proxy load balancers only.

Limits for Alpha release

The quota for forwarding rules is the limit for all forwarding rules both IPv4 and IPv6.

Pricing

Forwarding rules for IPv6 termination are provided at no additional cost. Pricing for reserved but unused IPv6 addresses is the same as for IPv4 addresses. The rest of the pricing is the same as that for all other load balancing flavors. View load balancing pricing details here.

FAQ

What load balancing flavors is IPv6 termination supported with?

  • IPv6 termination is supported for HTTP(S), SSL (TLS) proxy, and TCP proxy load balancing.

Can my backend instances be IPv6?

  • Currently we support IPv6 termination for your incoming clients only. Your backend instances remain IPv4. The connection between the clients and the load balancer will be IPv6, and the connection between the load balancer and your instances will be IPv4.

Can my forwarding rule have both an IPv4 and IPv6 address?

  • A single forwarding rule can have only one IP address, but you can create multiple forwarding rules, each with a different IP address, that point to the same load balancer. If you want your service to have both an IPv4 and IPv6 address, create two forwarding rules and give one an IPv4 address and the other an IPv6 address.

Send feedback about...

Compute Engine Documentation