Merge pull request openshift#1987 from knobunc/syn-eater

Document how to use the SYN eater iptables change to protect router reloads

Author: ahardin-rh

install_config/install/deploy_router.adoc

@@ -1030,6 +1030,57 @@ $ echo "    router metrics at: http://<ip>:9090/consoles/haproxy.html "
 ====
 
 
+=== Preventing Connection Failures During Restarts
+
+If you connect to the router while the proxy is reloading, there is a
+small chance that your connection will end up in the wrong network
+queue and be dropped.  The issue is being addressed.  In the meantime,
+it is possible to work around the problem by installing *_iptables_*
+rules to prevent connections during the reload window.  However, doing
+so means that the router needs to run with elevated privilege so that
+it can manipulate *_iptables_* on the host.  It also means that
+connections that happen during the reload are temporarily ignored and
+will have to retransmit their connection start, lengthening the time
+it takes to connect, but preventing connection failure.
+
+Due to these issues, do not enable this option most of the time.
+However, if you decide you must try to prevent this case from
+happening, you can make the router use *_iptables_* by changing the
+service account, and setting an environment variable on the router.
+
+*Use a Privileged SCC*
+
+When creating the router, allow it to use the privileged SCC.  That
+this gives the router user the ability to create containers with root
+privileges on the nodes.
+----
+$ oadm policy add-scc-to-user privileged -z router
+----
+
+*Patch the Router Deployment Configuration to Create a Privileged Container*
+
+Now that the router use can create privileged containers, make the
+router deployment configuration use the power so that the router can
+set the iptables rules it needs.  This patch changes the router
+deployment configuration so that the containter that is created runs
+as root.
+----
+$ oc patch dc router -p '{"spec":{"template":{"spec":{"containers":[{"name":"router","securityContext":{"privileged":true}}]}}}}'
+----
+
+*Tell the Router to Use iptables*
+
+Set the option on the router deployment configuration.  If you used a
+non-default name for the router, you will have to change *_dc/router_*
+accordingly):
+
+====
+----
+oc set env dc/router -c router DROP_SYN_DURING_RESTART=true
+----
+====
+
+
 [[deploying-customized-router]]
 == Deploying a Customized HAProxy Router