Route security management by end user

Openshift 3.6

Add a new route annotation "haproxy.router.openshift.io/ip_whitelist"
that specifies a space separated list of white listed source IP
addresses and/or CIDRs. Requests from IP addresses that are not in
the whitelist are dropped.

origin PR 14536
openshift/origin#14536

Trello: TbZPhHKE Route security management by end user
https://trello.com/c/TbZPhHKE/

Bug: 1426562
https://bugzilla.redhat.com/show_bug.cgi?id=1426562

architecture/core_concepts/routes.adoc

@@ -807,6 +807,7 @@ For all the items outlined in this section, you can set annotations on the
 |`*haproxy.router.openshift.io/rate-limit-connections.rate-tcp*`| Limits the rate at which an IP address can make TCP connections. |
 |`*haproxy.router.openshift.io/timeout*` | Sets a server-side timeout for the route. xref:time-units[(TimeUnits)] | `ROUTER_DEFAULT_SERVER_TIMEOUT`
 |`*router.openshift.io/haproxy.health.check.interval*`| Sets the interval for the back-end health checks. xref:time-units[(TimeUnits)] | `ROUTER_BACKEND_CHECK_INTERVAL`
+|`*haproxy.router.openshift.io/ip_whitelist*` | Sets a xref:whitelist[whitelist] for the route. | 
 |===
 
 .A Route Setting Custom Timeout
@@ -830,6 +831,50 @@ Setting a server-side timeout value for passthrough routes too low can cause
 WebSocket connections to timeout frequently on that route.
 ====
 
+[[whitelist]]
+== Route Specific IP Whitelists
+You can restrict access to a route to a select set of IP addresses by adding the 
+`haproxy.router.openshift.io/ip_whitelist` annotation on the route. The whitelist is a space
+separated list of IP addresses and/or CIDRs for the approved source addresses.  Requests from
+IP addresses that are not in the whitelist are dropped.
+
+Some examples:
+
+When editing a route add the following annotation to define the desired
+source IP's. Alternatively, `oc annotate route <name>` may be used.
+
+Allow only one specific IP address:
+
+----
+metadata:
+  annotations:
+    haproxy.router.openshift.io/ip_whitelist: 192.168.1.10
+----
+
+Allow several IP addresses:
+
+----
+metadata:
+  annotations:
+    haproxy.router.openshift.io/ip_whitelist: 192.168.1.10 192.168.1.11 192.168.1.12
+----
+
+Allow an IP CIDR network:
+
+----
+metadata:
+  annotations:
+    haproxy.router.openshift.io/ip_whitelist: 192.168.1.0/24
+----
+
+Allow mixed IP addresses and IP CIDR networks:
+
+----
+metadata:
+  annotations:
+    haproxy.router.openshift.io/ip_whitelist: 180.5.61.153 192.168.1.0/24 10.0.0.0/8
+----
+
 
 [[wildcard-subdomain-route-policy]]
 == Creating Routes Specifying a Wildcard Subdomain Policy