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

This documents the steps needed to enable the SYN eater to prevent
connection drops when the haproxy used by the router reloads.  In
order to work its magic it needs to use iptables, which entails all
sorts of fussing to get the router user to have the needed
permissions, and to patch the deployment config to make it request a
privileged container.

Author: knobunc

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