Add iptables-wrapper-installer.sh, update docs

CONTRIBUTING.md

@@ -8,10 +8,6 @@ _As contributors and maintainers of this project, and in the interest of fosteri
 
 We have full documentation on how to get started contributing here:
 
-<!---
-If your repo has certain guidelines for contribution, put them here ahead of the general k8s resources
--->
-
 - [Contributor License Agreement](https://git.k8s.io/community/CLA.md) Kubernetes projects require that you sign a Contributor License Agreement (CLA) before we can accept your pull requests
 - [Kubernetes Contributor Guide](https://git.k8s.io/community/contributors/guide) - Main contributor documentation, or you can just jump directly to the [contributing section](https://git.k8s.io/community/contributors/guide#contributing)
 - [Contributor Cheat Sheet](https://git.k8s.io/community/contributors/guide/contributor-cheatsheet.md) - Common resources for existing developers
@@ -20,12 +16,7 @@ If your repo has certain guidelines for contribution, put them here ahead of the
 
 - [Mentoring Initiatives](https://git.k8s.io/community/mentoring) - We have a diverse set of mentorship programs available that are always looking for volunteers!
 
-<!---
-Custom Information - if you're copying this template for the first time you can add custom content here, for example:
-
 ## Contact Information
 
-- [Slack channel](https://kubernetes.slack.com/messages/kubernetes-users) - Replace `kubernetes-users` with your slack channel string, this will send users directly to your channel. 
-- [Mailing list](URL)
-
--->
+- [sig-network slack channel](https://kubernetes.slack.com/messages/sig-network)
+- [kubernetes-sig-network mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-network)

README.md

@@ -1,29 +1,131 @@
-# Kubernetes Template Project
+# iptables-wrappers
 
-The Kubernetes Template Project is a template for starting new projects in the GitHub organizations owned by Kubernetes. All Kubernetes projects, at minimum, must have the following files:
+This repository consists of wrapper scripts to help with using
+iptables in containers.
 
-- a `README.md` outlining the project goals, sponsoring sig, and community contact information
-- an `OWNERS` with the project leads listed as approvers ([docs on `OWNERS` files][owners])
-- a `CONTRIBUTING.md` outlining how to contribute to the project
-- an unmodified copy of `code-of-conduct.md` from this repo, which outlines community behavior and the consequences of breaking the code
-- a `LICENSE` which must be Apache 2.0 for code projects, or [Creative Commons 4.0] for documentation repositories, without any custom content
-- a `SECURITY_CONTACTS` with the contact points for the Product Security Team 
-  to reach out to for triaging and handling of incoming issues. They must agree to abide by the
-  [Embargo Policy](https://git.k8s.io/security/private-distributors-list.md#embargo-policy)
-  and will be removed and replaced if they violate that agreement.
+Specifically, it provides a wrapper script to select between the two
+modes of iptables 1.8 ("legacy" and "nft") at runtime, so that
+hostNetwork containers that examine or modify iptables rules will work
+correctly regardless of which mode the underlying system is using.
 
-## Community, discussion, contribution, and support
+## Background
 
-Learn how to engage with the Kubernetes community on the [community page](http://kubernetes.io/community/).
+As of iptables 1.8, the iptables command line clients come in two
+different versions/modes: "legacy", which uses the kernel iptables API
+just like iptables 1.6 and earlier did, and "nft", which translates
+the iptables command-line API into the kernel nftables API.
 
-You can reach the maintainers of this project at:
+Because they connect to two different subsystems in the kernel, you
+cannot mix and match between them; in particular, if you are adding a
+new rule that needs to run either before or after some existing rules
+(such as the system firewall rules), then you need to create your rule
+with the same iptables mode as the other rules were created with,
+since otherwise the ordering may not be what you expect. (eg, if you
+*prepend* a rule using the nft-based client, it will still run *after*
+all rules that were added with the legacy iptables client.)
 
-- [Slack](http://slack.k8s.io/)
-- [Mailing List](https://groups.google.com/forum/#!forum/kubernetes-dev)
+In particular, this means that if you create a container image that
+will make changes to iptables rules in the host network namespace, and
+you want that container to be able to work on any host, then you need
+to figure out at run time which mode the host is using, and then also
+use that mode yourself. This wrapper is designed to do that for you.
 
-### Code of conduct
+### Additional iptables-nft 1.8.0-1.8.3 compatibility problems
 
-Participation in the Kubernetes community is governed by the [Kubernetes Code of Conduct](code-of-conduct.md).
+In addition to the general problem of needing to use the right mode,
+there is a second problem with iptables 1.8, which is that the first
+few releases (1.8.0, 1.8.1, and 1.8.2) had bugs in nft mode that made
+them not work with kubelet and some other programs. In particular:
 
-[owners]: https://git.k8s.io/community/contributors/guide/owners.md
-[Creative Commons 4.0]: https://git.k8s.io/website/LICENSE
+  - Some commands did not exit with success or failure in exactly the
+    same situations as the legacy clients. Eg, with the legacy
+    clients, `iptables -F CHAIN` would exit with an error if the chain
+    did not exist, but with the nft-based clients up to 1.8.2, it
+    would exit with success.
+
+  - In some cases it was possible to add a rule with `iptables -A` but
+    then have `iptables -C` claim that the rule did not exist. (This
+    led to kubelet repeatedly creating more and more copies of the
+    same rule, thinking it had not been created yet.)
+
+iptables 1.8.3 fixes these compatibility problems, but has a slightly
+different problem, which is that `iptables-nft` will get stuck in an
+infinite loop if it can't load the kernel `nf_tables` module. The
+wrapper script has code to deal with this.
+
+All currently-known problems are fixed in iptables 1.8.4.
+
+## iptables-wrapper
+
+The `iptables-wrapper-installer.sh` script in this repo will install
+an `iptables-wrapper` script alongside `iptables-legacy` and
+`iptables-nft` in `/usr/sbin` (or `/sbin`), and adjust the symlinks on
+`iptables`, `iptables-save`, etc, to point to the wrapper.
+
+(Because of the known bugs, `iptables-wrapper-installer.sh` will
+refuse to install the wrappers into a container with iptables earlier
+than 1.8.2. If you really know what you're doing you can pass
+`--no-sanity-check` to install anyway. Because it can work around the
+bugs in 1.8.3, the installer will allow you to install with iptables
+1.8.3.)
+
+The first time the wrapper is run, it will figure out which mode the
+system is using, update the `iptables`, `iptables-save`, etc, links to
+point to either the nft or legacy copies of iptables as appropriate,
+and then exec the appropriate binary. After that first call, the
+wrapper will not be used again; future calls to iptables will go
+directly to the correct underlying binary.
+
+## Building a container image that uses iptables
+
+When building a container image that needs to run iptables in the host
+network namespace, install iptables 1.8.3 or later in the container
+using whatever tools you normally would. Then copy the
+[`iptables-wrapper-installer.sh`](./iptables-wrapper-installer.sh)
+script into your container, and run it to have it set up run-time
+autodetection.
+
+Some distro-specific examples:
+
+- Alpine Linux
+
+      FROM alpine:3.10
+
+      RUN apk add --no-cache iptables
+      COPY iptables-wrapper-installer.sh /
+      RUN /iptables-wrapper-installer.sh
+
+- Debian GNU/Linux
+
+  Debian stable (buster) ships iptables 1.8.2, but iptables 1.8.3 is
+  available in buster-backports, so you should install it from there:
+
+      FROM debian:buster
+
+      RUN echo deb http://deb.debian.org/debian buster-backports main >> /etc/apt/sources.list; \
+          apt-get update; \
+          apt-get -t buster-backports -y --no-install-recommends install iptables
+
+      COPY iptables-wrapper-installer.sh /
+      RUN /iptables-wrapper-installer.sh
+
+- Fedora
+
+  Fedora 31 is the first release to include iptables 1.8.3. (Similarly
+  to the Debian example, you might be able to build an image based on
+  Fedora 30 or 29 if you use `dnf --releasever 31 ...` to install the
+  F31 iptables packages.)
+
+      FROM fedora:31
+
+      RUN dnf install -y iptables iptables-nft
+
+      COPY iptables-wrapper-installer.sh /
+      RUN /iptables-wrapper-installer.sh
+
+- RHEL / CentOS
+
+  RHEL/CentOS 7 ship iptables 1.4, which does not support nft mode.
+  RHEL/CentOS 8 ship a hacked version of iptables 1.8 that *only*
+  supports nft mode. Therefore, neither can be used as a basis for a
+  portable iptables-using container image.