Document iptables interaction with Openshift

iptables, firewalls, Openshift, Docker all interact with the kernel
iptables. None of the packages knows about what the other packages
have done or need to do.

It is very easy to misconfigure iptables and break Openshift and/or
docker networking.  These changes document the risks and some of the
interactions between packages.

https://trello.com/c/k6TgLcXS/307-3-document-un-allowed-iptables-mucking-with-behavior-sdn-supportability
openshift/openshift-docs: Issue #1947

Signed-off-by: Phil Cameron <pcameron@redhat.com>

Continuation of PR#30000

admin_guide/iptables.adoc

@@ -1,5 +1,5 @@
 [[admin-guide-iptables]]
-= IPtables
+= iptables
 {product-author}
 {product-version}
 :data-uri:
@@ -11,18 +11,97 @@
 toc::[]
 
 == Overview
-This topic describes how administrators should work with iptables. openshift-sdn takes care of adding the
-necessary iptables rules to make it work. Kubernetes and Docker also manage iptables for port forwarding
-and services.
+There are many system components including {product-title}, containers, and
+software that manage local firewall policies that rely on the kernel iptables
+configuration for proper network operation. In addition, the iptables
+configuration of all nodes in the cluster must be correct for networking to
+work.
 
+All components independently work with iptables without knowledge of how other
+components are using them. This makes it very easy for one component to break
+another component's configuration. Further, {product-title} and the Docker service
+assume that iptables remains set up exactly as they have set it up. They may not
+detect changes introduced by other components and if they do there may be some
+lag in implementing the fix. In particular, {product-title} does monitor and fix
+problems. However, the Docker service does not.
 
-== Restarting
-Docker doesn't monitor the iptables rules that it adds for exposing ports from containers and hence if
-iptables service is restarted, then these rules are lost. So, to safely restart iptables, it is
-recommended that the rules are saved and restored. 
+[IMPORTANT]
+====
+You must ensure that changes you make to the iptables configuration on a node do
+not impact the operation of {product-title} and the Docker service. Also, changes
+will often need to be made on all nodes in the cluster. Use caution, as iptables
+is not designed to have multiple concurrent users and it is very easy to break
+{product-title} and Docker networking.
+====
+
+The chains, order of the chains, and rules in the kernel iptables must be
+properly set up on each node in the cluster for {product-title} and Docker
+networking to work properly. There are several tools and services that are
+commonly used in the system that interact with the kernel iptables and can
+accidentally impact {product-title} and the Docker service.
+
+[[iptables-tool]]
+== iptables
+
+The iptables tool can be used to set up, maintain, and inspect the tables of IPv4
+packet filter rules in the Linux kernel.
+
+Independent of other use, such as a firewall, {product-title} and the the Docker
+service manage chains in some of the tables. The chains are inserted in specific
+order and the rules are specific to their needs.
+
+[CAUTION]
+====
+`iptables --flush [chain]` can remove key required configuration. Do not
+ execute this command.
+====
+
+[[iptables-service]]
+== iptables.service
+
+The iptables service supports a local network firewall. It assumes total control
+of the iptables configuration. When it starts, it flushes and restores the
+complete iptables configuration. The restored rules are from its configuration
+file, *_/etc/sysconfig/iptables_*. The configuration file is not kept up to date
+during operation, so the dynamically added rules are lost during every restart.
+
+[WARNING]
+====
+Stopping and starting *iptables.service* will destroy configuration that is
+required by {product-title} and Docker. {product-title} and Docker are not
+notified of the change.
+====
+
+----
+# systemctl disable iptables.service
+# systemctl mask iptables.service
+----
+
+If you need to run *iptables.service*, keep a limited configuration in the
+configuration file and rely on {product-title} and Docker to install their
+needed rules.
+
+The *iptables.service* configuration is loaded from:
+
+----
+/etc/sysconfig/iptables
+----
+
+To make permanent rules changes, edit the changes into this file. Do not include
+Docker or {product-title} rules.
+
+After *iptables.service* is started or restarted on a node, the Docker service
+and *atomic-openshift-node.service* must be restarted to reconstruct the needed
+iptables configuration.
+
+[IMPORTANT]
+====
+Restarting the Docker service will cause all containers running on the node to
+be stopped and restarted.
+====
 
 ----
-$ iptables-save > /path/to/iptables.bkp
-$ systemctl restart iptables
-$ iptables-restore < /path/to/iptables.bkp
+# systemctl restart iptables.service
+# systemctl restart docker
+# systemctl restart atomic-openshift-node.service
 ----

admin_guide/sdn_troubleshooting.adoc

@@ -11,7 +11,6 @@
 toc::[]
 
 == Overview
-
 As described in the
 xref:../architecture/additional_concepts/sdn.adoc#architecture-additional-concepts-sdn[SDN documentation]
 there are multiple layers of interfaces that are created to correctly
@@ -395,13 +394,6 @@ Of course the opposite traffic flows are also possible.
 
 Check that `sysctl net.ipv4.ip_forward` is set to 1 (and check the host if this is a VM)
 
-==== Is `firewalld` Disabled?
-
-Check that `firewalld` is disabled using `systemctl status firewalld`.
-If it is running, you either need to disable it, or check
-that it is not blocking traffic.  That is outside the scope of this
-guide.
-
 ====  Are your routes correct?
 
 Check the route tables with `ip route`:

getting_started/administrators.adoc

@@ -39,6 +39,13 @@ Docker and {product-title} must run on the Linux operating system. If you wish t
 run the server from a Windows or Mac OS X host, you should download and run the
 Origin Vagrant image as described in xref:building-from-source[Method 3].
 
+[CAUTION]
+====
+{product-title} and Docker use xref:../admin_guide/iptables.adoc#[iptables] to
+manage networking. Ensure that local firewall rules and other software making
+iptable changes do not alter the {product-title} and Docker service setup.
+====
+
 [[installation-methods]]
 == Installation Methods