add known issue
@@ -12,6 +12,8 @@ failures, the original reply is returned. Because *autopath* returns a reply for
the original question it will add a CNAME that points from the original name (with the search path
element in it) to the name of this answer.
+**Note**: There are several known issues. See section below.
+
## Syntax
~~~
@@ -50,6 +52,16 @@ Use the search path dynamically retrieved from the *kubernetes* plugin.
## Known Issues
-In Kubernetes, *autopath* is not compatible with pods running from Windows nodes.
+In Kubernetes, *autopath* can derive the wrong namespace of a client Pod (and therefore wrong search path)
+in the following case. To properly build the search path of a client *autopath* needs to
+know the namespace of the a Pod making a DNS request. To do this, it relies on the
+*kubernetes* plugin's Pod cache to resolve the client's IP address to a Pod. The Pod cache is maintained by
+an API watch on Pods. When Pod IP assignments change, the Kubernetes API notifies CoreDNS via the API watch.
+However, that notification is not instantaneous. In the case that a Pod is deleted, and it's IP is
+immediately provisioned to a Pod in another namespace, and that new Pod make a DNS lookup *before* the API watch
+can notify CoreDNS of the change, *autopath* will resolve the IP to the previous Pod's namespace.
+
+In Kubernetes, *autopath* is not compatible with Pods running from Windows nodes.
-If the server side search ultimately results in a negative answer (e.g. `NXDOMAIN`), then the client will fruitlessly search all paths manually, thus negating the *autopath* optimization.
+If the server side search ultimately results in a negative answer (e.g. `NXDOMAIN`), then the client will
+fruitlessly search all paths manually, thus negating the *autopath* optimization.
