Using Protocol Forwarding

Google Compute Engine supports Protocol Forwarding, which lets you create forwarding rule objects that can send packets to a non-NAT’ed target instance. Each target instance contains a single virtual machine instance that receives and handles traffic from the corresponding forwarding rules.

Protocol forwarding can be used in a number of scenarios, including:

  • Virtual hosting by IPs

    You can set up multiple forwarding rules to point to a single target instance, allowing you to use multiple external IP addresses with one virtual machine instance. You can use this in scenarios where you may want to serve data from just one virtual machine instance, but through different external IP addresses. This is especially useful for setting up SSL virtual hosting.

  • Virtual private networks (VPN)

    See Compute Engine VPN for using forwarding rules with VPN.

  • Load balancing

    See Load Balancing for instructions on how to forward traffic to a load balancer.

Google Compute Engine supports protocol forwarding for the following protocols:

Protocol forwarding is charged at the same rates as the load balancing service. Read the pricing page for more information.

Quickstart

To create a forwarding rule that sends traffic to a single instance, you must:

  1. Create a target instance.

    Your target instance will contain a single virtual machine instance, but this virtual machine instance can exist at the time you create the target instance, or can be created afterwards.

  2. Create a forwarding rule.

    Your target instance must exist before you create a forwarding rule. If incoming packets match the IP, protocol, and (if applicable) the port range that is being served by your forwarding rule, the forwarding rule will direct that traffic to your target instance.

The rest of this quickstart demonstrates the above steps end-to-end by:

  1. Setting up an Apache server on a virtual machine instance.
  2. Creating a target instance and corresponding forwarding rules.
  3. Send traffic to a single target instance.

At the end of this quickstart, you should know how to set up protocol forwarding from multiple forwarding rules to a single target instance.

Set up a virtual machine instance and install Apache

To begin, let's create a single virtual machine instance with Apache installed.

  1. Create some startup scripts for your new instance.

    Depending on your operating system, your startup script contents might differ:

    • If you plan to use a Debian image on your instance, run the following command:

      me@local:~$ echo "sudo apt-get update && sudo apt-get -y install apache2 && mkdir -p /var/www1 &&
      mkdir -p /var/www2 && mkdir -p /var/www3 && hostname > /var/www/html/index.html &&
      echo w1 > /var/www1/index.html && echo w2 > /var/www2/index.html && echo w3 > /var/www3/index.html" > \
      $HOME/pf_startup.sh
      

    • If you plan to use a CentOS image on your instance, run the following command:

      me@local:~$ echo "sudo yum -y install httpd && sudo service httpd restart && mkdir -p /var/www1 &&
      mkdir -p /var/www2 && mkdir /var/www3 && hostname > /var/www/html/index.html &&
      echo w1 > /var/www1/index.html && echo w2 > /var/www2/index.html && echo w3 > /var/www3/index.html" > \
      $HOME/pf_startup.sh
      

  2. Create a tag for your future virtual machine, so we can apply a firewall to it later:

    me@local:~$ TAG="www-tag"
    

  3. Create a new virtual machine instance to handle traffic for your forwarding rules.

    gcloud compute instances create pf-instance \
        --image-project debian-cloud --image-family debian-9 --tags $TAG \
        --metadata-from-file startup-script=$HOME/pf_startup.sh
    
  4. Create a firewall rule to allow external traffic to this virtual machine instance:

    gcloud compute firewall-rules create www-firewall --target-tags $TAG --allow tcp
    

Great, you have successfully set up a virtual machine instance. Now, you can start settting up your protocol forwarding configuration.

Create a target instance and corresponding forwarding rules

  1. Create a target instance.

    Target instances contain a single virtual machine instance that receives and handles traffic from a forwarding rule. Target instances do not have a NAT policy, so you can use them to set up your own VPN connections using IPsec protocols directly.

    You must create a target instance before you can create a forwarding rule object because forwarding rules must reference an existing target resource. It is not possible to create a forwarding rule that directs traffic to a non-existing target resource. For this example, create a target instance as follows:

    gcloud compute target-instances create pf-target-instance --instance pf-instance
    
  2. Create your forwarding rule objects.

    A forwarding rule object directs traffic that matches the IP protocol and port to a specified target instance. For more details, review the forwarding rules documentation.

    For this example, the following commands will create three forwarding rules, each with an ephemeral IP address that forwards TCP traffic to your target instance. Optionally, if you have some static external IP addresses, you can use them with these forwarding rules by specifying the --address IP-ADDRESS flag.

    gcloud compute forwarding-rules create pf-rule1 --ip-protocol TCP \
        --ports 80 --target-instance pf-target-instance
    
    gcloud compute forwarding-rules create pf-rule2 --ip-protocol TCP \
        --ports 80 --target-instance pf-target-instance
    
    gcloud compute forwarding-rules create pf-rule3 --ip-protocol TCP \
        --ports 80 --target-instance pf-target-instance
    

That's it! You can start sending traffic to your target instance.

Send traffic to your instance

  1. Get the external IP addresses of your new forwarding rules.

    Run gcloud compute forwarding-rules list to get the external IP addresses of your forwarding rules. For example, the following table lists the ephemeral IP addresses that were allocated for the forwarding rules created earlier.

    If you opted to use reserved IP addresses, they will be listed here in place of the ephemeral IP addresses.

    gcloud compute forwarding-rules list
    

    NAME     REGION      IP_ADDRESS     IP_PROTOCOL TARGET
    pf-rule1 us-central1 [ADDRESS_1]    TCP         us-central1-a/targetInstances/pf-target-instance
    pf-rule2 us-central1 [ADDRESS_2]    TCP         us-central1-a/targetInstances/pf-target-instance
    pf-rule3 us-central1 [ADDRESS_3]    TCP         us-central1-a/targetInstances/pf-target-instance

    Make a note of the IP addresses for the next step.

  2. Configure the virtual machine instance's Apache virtual hosts to serve different information based on the destination URL.

    First, SSH into your instance:

    gcloud compute ssh pf-instance
    

    Then, edit the /etc/apache2/sites-enabled/000-default.conf file and add the following lines. For VirtualHostcd .. lines, use the IP addresses you saw when you ran the prior step.

    <VirtualHost [ADDRESS_1]>
     DocumentRoot /var/www1
     <Directory /var/www1>
      Require all granted
     </Directory>
    </VirtualHost>
    <VirtualHost [ADDRESS_2]>
     DocumentRoot /var/www2
     <Directory /var/www2>
      Require all granted
     </Directory>
    </VirtualHost>
    <VirtualHost [ADDRESS_3]>
     DocumentRoot /var/www3
     <Directory /var/www3>
      Require all granted
     </Directory>
    </VirtualHost>
    

    Lastly, restart Apache:

    user@myinst:~$ sudo /etc/init.d/apache2 restart
    

  3. Try sending some traffic to your instance.

    On your local machine, we are going to make a request to the external IP addresses served by the forwarding rules we created.

    Use curl to send traffic to the IP addresses. The response will return w1, w2, or w3 depending on the IP address.

    me@local:~$curl [ADDRESS_1]
    w1
    

    me@local:~$ curl [ADDRESS_2]
    w2
    

    me@local:~$ curl [ADDRESS_3]
    w3
    

    That's it! You have set up your first protocol forwarding configuration!

Forwarding rules

Forwarding rules work in conjunction with target pools and target instances to support load balancing and protocol forwarding features. To use load balancing and protocol forwarding, you must create a forwarding rule that directs traffic to specific target pools (for load balancing) or target instances (for protocol forwarding). It is not possible to use either of these features without a forwarding rule.

Forwarding Rule resources live in the Forwarding Rules collection. Each forwarding rule matches a particular IP address, protocol, and optionally, port range to a single target pool or target instance. When traffic is sent to an external IP address that is served by a forwarding rule, the forwarding rule directs that traffic to the corresponding target pool or target instances. You can create up to 50 forwarding rule objects per project.

Some points to keep in mind when working with forwarding rules:

  • The name of a forwarding rule must be unique in this project, from 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.

  • If you do not specify a forwarding rule protocol, the default TCP is used. Also note that certain protocols can only be used with target pools or target instances:

    • If you use ESP, AH, SCTP or ICMP, you must specify a target instance. It is not possible to specify a target pool when using these protocols.
    • If you use TCP or UDP, you can specify either a target pool or a target instance.
  • Port ranges can only be specified for TCP, UDP, and SCTP protocols.

Add a forwarding rule

To add a new forwarding rule, you can use the gcloud compute forwarding-rules create command or create a HTTP POST request to the Forwarding Rules collection. An example of creating a forwarding rule to a target instance using the gcloud comand-line tool is:

gcloud compute forwarding-rules create [FORWARDING_RULE] --region [REGION] \
    [--target-instance-zone [ZONE]] --ip-protocol TCP --ports 80 \
    --target-instance [TARGET_INSTANCE]

If you omit the --target-instance-zone flag, the gcloud comand-line tool prompts you to choose a zone if you did not set the compute/zone property with gcloud config set compute/zone. For more information, read Setting a default zone or region.

An example of creating a forwarding rule to a target pool is:

gcloud compute forwarding-rules create [FORWARDING_RULE] --target-pool [TARGET_POOL] [--region [REGION]]

If you omit the --region flag, the gcloud comand-line tool prompts you to choose a region if you did not set the compute/region property with gcloud config set compute/region. For more information, read Setting a default zone or region.

For a complete description of the flags you can use, see the forwarding rules create command, or type gcloud compute forwarding-rules create --help.

To add a forwarding rule using the API, perform a HTTP POST request to the following URI:

https://www.googleapis.com/compute/v1/projects/myproject/regions/us-central1/forwardingRules

Your request body should contain the following fields:

{
 "name": "example-forwarding-rule",
 "IPAddress": "`10.1.1.1",
 "IPProtocol": "TCP",
 "portRange": "80",
 "target": "zones/us-central1-f/targetInstances/example-target-instances"
}

List forwarding rules

To get a list of forwarding rules using the gcloud comand-line tool, use the list command:

gcloud compute forwarding-rules list

In the API, make an empty HTTP GET request to the following URI:

https://www.googleapis.com/compute/v1/project/myproject/regions/us-central1/forwardingRules

Get forwarding rules

To get information about a single forwarding rules using the gcloud comand-line tool, use the describe command:

gcloud compute forwarding-rules describe [FORWARDING_RULE] [--region [REGION] | --global]

If you omit the --region or --global flag, the gcloud comand-line tool assumes that you are operating on a regional forwarding rule and prompts you to choose a region if you did not set the compute/region property with gcloud config set compute/region. For more information, read Setting a default zone or region.

In the API, make an empty HTTP GET request to the following URI:

https://www.googleapis.com/compute/v1/project/myproject/regions/us-central1/forwardingRules/example-forwarding-rule

Update the forwarding rule target

If you have already created a forwarding rule but want to change the target pool that the forwarding rule is using, you can do so with the gcloud comand-line tool set-target command:

gcloud compute forwarding-rules set-target [FORWARDING_RULE] --target-pool [TARGET_POOL] \
    [--region [REGION] | --global]

In the API, make a HTTP POST request to the following URI:

https://www.googleapis.com/compute/v1/projects/myproject/regions/us-central1/forwardingRules/example-forwarding-rule/setTarget

Your request body should contain the URL to the target instance or target pool resource you want to set. For instance, for target pools, the URI format should be:

{
  "target": "https://www.googleapis.com/compute/v1/projects/myproject/regions/us-central1/targetPools/example-target-pool"
}

Delete forwarding rules

To delete a forwarding rule with the gcloud comand-line tool, use the delete command:

gcloud compute forwarding-rules delete [FORWARDING_RULE] [--region [REGION] | --global]

To delete a forwarding rule from the API, make a HTTP DELETE request to the following URI, with an empty request body:

https://www.googleapis.com/compute/v1/project/myproject/regions/us-central1/forwardingRules/example-forwarding-rule

Target instances

A Target Instance resource contains one virtual machine instance that handles traffic from one or more forwarding rules and is ideal for forwarding certain types of protocol traffic that should be managed by a single source (e.g. ESP and AH), but you can also use a target instance for TCP and UDP protocols. Target instances do not have a NAT policy applied to them, so they can be used for traffic that require non-NAT'ed IPsec traffic for virtual private networks (VPN).

Target instances must live in the same region as the forwarding rule. Target instances must also live in the same zone as the virtual machine instance. For example, if your forwarding rule lives in us-central1 and the instance you want to use lives in us-central1-a, the target instance must live in us-central1-a. If the instance lived in us-central1-b, the target instance must also live in us-central1-b.

Add a target instance

To add a new target instance, you can use the gcloud compute target-instances command or create a HTTP POST request to the targetInstances collection. An example of creating a target instance using the gcloud comand-line tool is:

gcloud compute target-instances create [TARGET_INSTANCE] --instance INSTANCE

If you omit the --zone flag, the gcloud comand-line tool prompts you to choose a zone if you did not set the compute/zone property with gcloud config set compute/zone. For more information, read Setting a default zone or region.

For a complete description of the flags you can use, see the create command, or type gcloud compute target-instances create --help.

In the API, make a HTTP POST request to the following URI:

https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f/targetInstances

With the following request body:

body = {
  "name": "example-target-instance",
  "instance": "zones/us-central1-f/instances/example-instance"
}

List target instances

To get a list of target instances with the gcloud comand-line tool, use the list command:

gcloud compute target-instances list

In the API, make an empty HTTP GET request to the following URI:

https://www.googleapis.com/compute/v1/projects/myproject/aggregatedList/targetInstances

Get a target instance

To get information about a single target instance with the gcloud comand-line tool, use the describe command:

gcloud compute target-instances describe [TARGET_INSTANCE]

In the API, make an empty HTTP GET request to the following URI:

https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f/targetInstances/<target-instance>

Delete a target instance

To delete a target instance, you must first make sure that it is not being referenced by any forwarding rules. If a forwarding rule is currently referencing the target instance you want to delete, you must delete the forwarding rule to remove the reference.

After you've removed a target instance from being referenced by any forwarding rules, you can delete it with the gcloud comand-line tool delete command:

gcloud compute target-instance delete [TARGET_INSTANCE]

In the API, make an empty HTTP DELETE request to the following URI:

https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f/targetInstances/<target-instance>

Send feedback about...

Compute Engine Documentation