..
      Copyright (c) 2016 IBM

      Licensed under the Apache License, Version 2.0 (the "License"); you may
      not use this file except in compliance with the License. You may obtain
      a copy of the License at

          http://www.apache.org/licenses/LICENSE-2.0

      Unless required by applicable law or agreed to in writing, software
      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
      License for the specific language governing permissions and limitations
      under the License.

================
Layer 7 Cookbook
================

Introduction
============
This document gives several examples of common L7 load balancer usage. For a
description of L7 load balancing see: :doc:`l7`

For the puposes of this guide we assume that the neutron command-line interface
is going to be used to configure all features of Neutron LBaaS with an Octavia
back-end. Also, in order to keep these examples short, we assume that many
non-L7 configuration tasks (such as deploying loadbalancers, listeners, pools,
members, healthmonitors, etc.) have already been accomplished. A description
of the starting conditions is given in each example below.


Examples
========

.. _redirect-http-to-https:

Redirect http://www.example.com/ to https://www.example.com/
------------------------------------------------------------
**Scenario description**:

* Load balancer *lb1* has been set up with ``TERMINATED_HTTPS`` listener
  *tls_listener* on TCP port 443.
* *tls_listener* has been populated with a default pool, members, etc.
* *tls_listener* is available under the DNS name *https://www.example.com/*
* We want any regular HTTP requests to TCP port 80 on *lb1* to be redirected
  to *tls_listener* on TCP port 443.

**Solution**:

1. Create listener *http_listener* as an HTTP listener on *lb1* port 80.
2. Set up an L7 Policy *policy1* on *http_listener* with action
   ``REDIRECT_TO_URL`` pointed at the URL *https://www.example.com/*
3. Add an L7 Rule to *policy1* which matches all requests.


**CLI commands**:

::

    neutron lbaas-listener-create --name http_listener --loadbalancer lb1 --protocol HTTP --protocol-port 80
    neutron lbaas-l7policy-create --action REDIRECT_TO_URL --redirect-url https://www.example.com/ --listener http_listener --name policy1
    neutron lbaas-l7rule-create --type PATH --compare-type STARTS_WITH --value / policy1


.. _send-requests-to-static-pool:

Send requests starting with /js or /images to *static_pool*
-----------------------------------------------------------
**Scenario description**:

* Listener *listener1* on load balancer *lb1* is set up to send all requests to
  its default_pool *pool1*.
* We are introducing static content servers 10.0.0.10 and 10.0.0.11 on subnet
  *private-subnet*, and want any HTTP requests with a URL that starts with
  either "/js" or "/images" to be sent to those two servers instead of *pool1*.

**Solution**:

1. Create pool *static_pool* on *lb1*.
2. Populate *static_pool* with the new back-end members.
3. Create L7 Policy *policy1* with action ``REDIRECT_TO_POOL`` pointed at
   *static_pool*.
4. Create an L7 Rule on *policy1* which looks for "/js" at the start of
   the request path.
5. Create L7 Policy *policy2* with action ``REDIRECT_TO_POOL`` pointed at
   *static_pool*.
6. Create an L7 Rule on *policy2* which looks for "/images" at the start
   of the request path.

**CLI commands**:

::

    neutron lbaas-pool-create --name static_pool --lb-algorithm ROUND_ROBIN --loadbalancer lb1 --protocol HTTP
    neutron lbaas-member-create --subnet private-subnet --address 10.0.0.10 --protocol-port 80 static_pool
    neutron lbaas-member-create --subnet private-subnet --address 10.0.0.11 --protocol-port 80 static_pool
    neutron lbaas-l7policy-create --action REDIRECT_TO_POOL --redirect-pool static_pool --listener listener1 --name policy1
    neutron lbaas-l7rule-create --type PATH --compare-type STARTS_WITH --value /js policy1
    neutron lbaas-l7policy-create --action REDIRECT_TO_POOL --redirect-pool static_pool --listener listener1 --name policy2
    neutron lbaas-l7rule-create --type PATH --compare-type STARTS_WITH --value /images policy2

**Alternate solution** (using regular expressions):

1. Create pool *static_pool* on *lb1*.
2. Populate *static_pool* with the new back-end members.
3. Create L7 Policy *policy1* with action ``REDIRECT_TO_POOL`` pointed at
   *static_pool*.
4. Create an L7 Rule on *policy1* which uses a regular expression to match
   either "/js" or "/images" at the start of the request path.

**CLI commands**:

::

    neutron lbaas-pool-create --name static_pool --lb-algorithm ROUND_ROBIN --loadbalancer lb1 --protocol HTTP
    neutron lbaas-member-create --subnet private-subnet --address 10.0.0.10 --protocol-port 80 static_pool
    neutron lbaas-member-create --subnet private-subnet --address 10.0.0.11 --protocol-port 80 static_pool
    neutron lbaas-l7policy-create --action REDIRECT_TO_POOL --redirect-pool static_pool --listener listener1 --name policy1
    neutron lbaas-l7rule-create --type PATH --compare-type REGEX --value '^/(js|images)' policy1


Send requests for http://www2.example.com/ to *pool2*
-----------------------------------------------------
**Scenario description**:

* Listener *listener1* on load balancer *lb1* is set up to send all requests to
  its default_pool *pool1*.
* We have set up a new pool *pool2* on *lb1* and want any requests using the
  HTTP/1.1 hostname *www2.example.com* to be sent to *pool2* instead.

**Solution**:

1. Create L7 Policy *policy1* with action ``REDIRECT_TO_POOL`` pointed at
   *pool2*.
2. Create an L7 Rule on *policy1* which matches the hostname
   *www2.example.com*.

**CLI commands**:

::

    neutron lbaas-l7policy-create --action REDIRECT_TO_POOL --redirect-pool pool2 --listener listener1 --name policy1
    neutron lbaas-l7rule-create --type HOST_NAME --compare-type EQUAL_TO --value www2.example.com policy1


Send requests for *\*.example.com* to *pool2*
---------------------------------------------
**Scenario description**:

* Listener *listener1* on load balancer *lb1* is set up to send all requests to
  its default_pool *pool1*.
* We have set up a new pool *pool2* on *lb1* and want any requests using any
  HTTP/1.1 hostname like *\*.example.com* to be sent to *pool2* instead.

**Solution**:

1. Create L7 Policy *policy1* with action ``REDIRECT_TO_POOL`` pointed at
   *pool2*.
2. Create an L7 Rule on *policy1* which matches any hostname that ends with
   *example.com*.

**CLI commands**:

::

    neutron lbaas-l7policy-create --action REDIRECT_TO_POOL --redirect-pool pool2 --listener listener1 --name policy1
    neutron lbaas-l7rule-create --type HOST_NAME --compare-type ENDS_WITH --value example.com policy1


Send unauthenticated users to *login_pool* (scenario 1)
-------------------------------------------------------
**Scenario description**:

* ``TERMINATED_HTTPS`` listener *listener1* on load balancer *lb1* is set up
  to send all requests to its default_pool *pool1*.
* The site behind *listener1* requires all web users to authenticate, after
  which a browser cookie *auth_token* will be set.
* When web users log out, or if the *auth_token* is invalid, the application
  servers in *pool1* clear the *auth_token*.
* We want to introduce new secure authentication server 10.0.1.10 on Neutron
  subnet *secure_subnet* (a different Neutron subnet from the default
  application servers) which handles authenticating web users and sets the
  *auth_token*.

*Note:* Obviously, to have a more secure authentication system that is less
vulnerable to attacks like XSS, the new secure authentication server will need
to set session variables to which the default_pool servers will have access
outside the data path with the web client. There may be other security concerns
as well. This example is not meant to address how these are to be
accomplished--it's mainly meant to show how L7 application routing can be done
based on a browser cookie.

**Solution**:

1. Create pool *login_pool* on *lb1*.
2. Add member 10.0.1.10 on *secure_subnet* to *login_pool*.
3. Create L7 Policy *policy1* with action ``REDIRECT_TO_POOL`` pointed at
   *login_pool*.
4. Create an L7 Rule on *policy1* which looks for browser cookie *auth_token*
   (with any value) and matches if it is *NOT* present.

**CLI commands**:

::

    neutron lbaas-pool-create --name login_pool --lb-algorithm ROUND_ROBIN --loadbalancer lb1 --protocol HTTP
    neutron lbaas-member-create --subnet secure_subnet --address 10.0.1.10 --protocol-port 80 login_pool
    neutron lbaas-l7policy-create --action REDIRECT_TO_POOL --redirect-pool login_pool --listener listener1 --name policy1
    neutron lbaas-l7rule-create --type COOKIE --key auth_token --compare-type REGEX --value '.*' --invert policy1


Send unauthenticated users to *login_pool* (scenario 2)
--------------------------------------------------------
**Scenario description**:

* ``TERMINATED_HTTPS`` listener *listener1* on load balancer *lb1* is set up
  to send all requests to its default_pool *pool1*.
* The site behind *listener1* requires all web users to authenticate, after
  which a browser cookie *auth_token* will be set.
* When web users log out, or if the *auth_token* is invalid, the application
  servers in *pool1* set *auth_token* to the literal string "INVALID".
* We want to introduce new secure authentication server 10.0.1.10 on Neutron
  subnet *secure_subnet* (a different Neutron subnet from the default
  application servers) which handles authenticating web users and sets the
  *auth_token*.

*Note:* Obviously, to have a more secure authentication system that is less
vulnerable to attacks like XSS, the new secure authentication server will need
to set session variables to which the default_pool servers will have access
outside the data path with the web client. There may be other security concerns
as well. This example is not meant to address how these are to be
accomplished-- it's mainly meant to show how L7 application routing can be done
based on a browser cookie.

**Solution**:

1. Create pool *login_pool* on *lb1*.
2. Add member 10.0.1.10 on *secure_subnet* to *login_pool*.
3. Create L7 Policy *policy1* with action ``REDIRECT_TO_POOL`` pointed at
   *login_pool*.
4. Create an L7 Rule on *policy1* which looks for browser cookie *auth_token*
   (with any value) and matches if it is *NOT* present.
5. Create L7 Policy *policy2* with action ``REDIRECT_TO_POOL`` pointed at
   *login_pool*.
6. Create an L7 Rule on *policy2* which looks for browser cookie *auth_token*
   and matches if it is equal to the literal string "INVALID".

**CLI commands**:

::

    neutron lbaas-pool-create --name login_pool --lb-algorithm ROUND_ROBIN --loadbalancer lb1 --protocol HTTP
    neutron lbaas-member-create --subnet secure_subnet --address 10.0.1.10 --protocol-port 80 login_pool
    neutron lbaas-l7policy-create --action REDIRECT_TO_POOL --redirect-pool login_pool --listener listener1 --name policy1
    neutron lbaas-l7rule-create --type COOKIE --key auth_token --compare-type REGEX --value '.*' --invert policy1
    neutron lbaas-l7policy-create --action REDIRECT_TO_POOL --redirect-pool login_pool --listener listener1 --name policy2
    neutron lbaas-l7rule-create --type COOKIE --key auth_token --compare-type EQUAL_TO --value INVALID policy2


Send requests for *http://api.example.com/api* to *api_pool*
------------------------------------------------------------
**Scenario description**:

* Listener *listener1* on load balancer *lb1* is set up to send all requests
  to its default_pool *pool1*.
* We have created pool *api_pool* on *lb1*, however, for legacy business logic
  reasons, we only want requests sent to this pool if they match the hostname
  *api.example.com* AND the request path starts with */api*.

**Solution**:

1. Create L7 Policy *policy1* with action ``REDIRECT_TO_POOL`` pointed at
   *api_pool*.
2. Create an L7 Rule on *policy1* which matches the hostname *api.example.com*.
3. Create an L7 Rule on *policy1* which matches */api* at the start of the
   request path. (This rule will be logically ANDed with the previous rule.)

**CLI commands**:

::

    neutron lbaas-l7policy-create --action REDIRECT_TO_POOL --redirect-pool api_pool --listener listener1 --name policy1
    neutron lbaas-l7rule-create --type HOST_NAME --compare-type EQUAL_TO --value api.example.com policy1
    neutron lbaas-l7rule-create --type PATH --compare-type STARTS_WITH --value /api policy1


Set up A/B testing on an existing production site using a cookie
----------------------------------------------------------------
**Scenario description**:

* Listener *listener1* on load balancer *lb1* is a production site set up as
  described under :ref:`send-requests-to-static-pool` (alternate solution)
  above. Specifically:

  * HTTP requests with a URL that starts with either "/js" or "/images" are
    sent to pool *static_pool*.
  * All other requests are sent to *listener1's* default_pool *pool1*.

* We are introducing a "B" version of the production site, complete with its
  own default_pool and static_pool. We will call these *pool_B* and
  *static_pool_B* respectively.
* The *pool_B* members should be 10.0.0.50 and 10.0.0.51, and the
  *static_pool_B* members should be 10.0.0.100 and 10.0.0.101 on subnet
  *private-subnet*.
* Web clients which should be routed to the "B" version of the site get a
  cookie set by the member servers in *pool1*. This cookie is called
  "site_version" and should have the value "B".

**Solution**:

1. Create pool *pool_B* on *lb1*.
2. Populate *pool_B* with its new back-end members.
3. Create pool *static_pool_B* on *lb1*.
4. Populate *static_pool_B* with its new back-end members.
5. Create L7 Policy *policy2* with action ``REDIRECT_TO_POOL`` pointed at
   *static_pool_B*. This should be inserted at position 1.
6. Create an L7 Rule on *policy2* which uses a regular expression to match
   either "/js" or "/images" at the start of the request path.
7. Create an L7 Rule on *policy2* which matches the cookie "site_version" to
   the exact string "B".
8. Create L7 Policy *policy3* with action ``REDIRECT_TO_POOL`` pointed at
   *pool_B*. This should be inserted at position 2.
9. Create an L7 Rule on *policy3* which matches the cookie "site_version" to
   the exact string "B".

*A word about L7 Policy position*: Since L7 Policies are evaluated in order
according to their position parameter, and since the first L7 Policy whose L7
Rules all evaluate to True is the one whose action is followed, it is important
that L7 Policies with the most specific rules get evaluated first.

For example, in this solution, if *policy3* were to appear in the listener's L7
Policy list before *policy2* (that is, if *policy3* were to have a lower
position number than *policy2*), then if a web client were to request the URL
http://www.example.com/images/a.jpg with the cookie "site_version:B", then
*policy3* would match, and the load balancer would send the request to
*pool_B*. From the scenario description, this request clearly was meant to be
sent to *static_pool_B*, which is why *policy2* needs to be evaluated before
*policy3*.

**CLI commands**:

::

    neutron lbaas-pool-create --name pool_B --lb-algorithm ROUND_ROBIN --loadbalancer lb1 --protocol HTTP
    neutron lbaas-member-create --subnet private-subnet --address 10.0.0.50 --protocol-port 80 pool_B
    neutron lbaas-member-create --subnet private-subnet --address 10.0.0.51 --protocol-port 80 pool_B
    neutron lbaas-pool-create --name static_pool_B --lb-algorithm ROUND_ROBIN --loadbalancer lb1 --protocol HTTP
    neutron lbaas-member-create --subnet private-subnet --address 10.0.0.100 --protocol-port 80 static_pool_B
    neutron lbaas-member-create --subnet private-subnet --address 10.0.0.101 --protocol-port 80 static_pool_B
    neutron lbaas-l7policy-create --action REDIRECT_TO_POOL --redirect-pool static_pool_B --listener listener1 --name policy2 --position 1
    neutron lbaas-l7rule-create --type PATH --compare-type REGEX --value '^/(js|images)' policy2
    neutron lbaas-l7rule-create --type COOKIE --key site_version --compare-type EQUAL_TO --value B policy2
    neutron lbaas-l7policy-create --action REDIRECT_TO_POOL --redirect-pool pool_B --listener listener1 --name policy3 --position 2
    neutron lbaas-l7rule-create --type COOKIE --key site_version --compare-type EQUAL_TO --value B policy3
