Merge pull request #552 from pweil-/router-admin

Customizing a router

Author: adellape

admin_guide/router.adoc

@@ -54,3 +54,91 @@ connecting to back-ends for re-encrypt terminated routes are stored in the
 namespace and name of the route. The key, certificate, and CA certificate are
 concatenated into a single file. You can use
 link:https://www.openssl.org/[OpenSSL] to view the contents of these files.
+
+== Customizing a Router
+
+The HAProxy router is based on a golang template.  This template generates the
+HAProxy configuration file.  If you would like to customize a router to meet
+your needs you are able to change the template file, build a new docker image,
+and run a customized router.
+
+One common case for this may be implementing new features withing the
+application backends.  For instance, it might be desirable in a highly available
+setup to use stick-tables that synchronizes between peers.  The router
+plugin provides all the facilities necessary to make this customization.
+
+.Using Stick Tables
+
+*Adding a Peer Section*
+
+In order to synchronize stick tables amongst peers you must a define a peers
+section in your HAProxy configuration.  This section determines how HAProxy
+will identify and connect to peers.  The plugin provides data to the template
+under the `.PeerEndpoints` variable to allow you to easily identify members
+of the router service.  You may add a peer section to the `haproxy-config.template`
+by adding
+
+[options="nowrap"]
+----
+{{ if (len .PeerEndpoints) gt 0 }}
+peers openshift_peers
+  {{ range $endpointID, $endpoint := .PeerEndpoints }}
+    peer {{$endpoint.TargetName}} {{$endpoint.IP}}:1937
+  {{ end }}
+{{ end }}
+----
+
+
+*Changing the Reload Script*
+
+When using stick tables you have the option of telling HAProxy what it should
+consider the name of the local host in the peer section.  When creating endpoints the
+plugin will attempt to set the `TargetName` to the value
+of the endpoint's `TargetRef.Name`.  If `TargetRef` is not set it will set the
+`TargetName` to the IP address.  Since the `TargetRef.Name` corresponds with the
+Kubernetes host name you can add the `-L` option to the `reload-haproxy` script
+to identify the local host in the peer section.
+
+[options="nowrap"]
+----
+# Must match an endpoint target name that is used in the peer section
+peer_name=$HOSTNAME
+
+if [ -n "$old_pid" ]; then
+  /usr/sbin/haproxy -f $config_file -p $pid_file -L $peer_name -sf $old_pid
+else
+  /usr/sbin/haproxy -f $config_file -p $pid_file -L $peer_name
+fi
+----
+
+*Modifying Backends*
+
+Finally, to use the stick tables within backends you may modify the HAProxy configuration
+to use the stick-tables and peer set.  Below is an example of changing the existing
+backend for TCP connections to use stick-tables.
+
+[options="nowrap"]
+----
+
+            {{ if eq $cfg.TLSTermination "passthrough" }}
+backend be_tcp_{{$cfgIdx}}
+  balance leastconn
+  timeout check 5000ms
+  stick-table type ip size 1m expire 5m{{ if (len $.PeerEndpoints) gt 0 }} peers openshift_peers {{ end }}
+  stick on src
+                {{ range $endpointID, $endpoint := $serviceUnit.EndpointTable }}
+  server {{$endpointID}} {{$endpoint.IP}}:{{$endpoint.Port}} check inter 5000ms
+                {{ end }}
+            {{ end }}
+----
+
+*Rebuilding Your Router*
+
+Once you have made modifications to the router you must rebuild the docker image and push
+it to your repository.  Then you may specify your new image when creating a router either
+in the pod's spec directly or by using the `oadm` command
+
+[options="nowrap"]
+----
+oadm router --credentials="$KUBECONFIG" --images=myrepo/myimage:mytag
+----