Merge pull request #3919 from BenTheElder/doc-local

clarify local registry address

site/content/docs/user/local-registry.md

@@ -28,4 +28,29 @@ The registry can be used like this.
 4. And now we can use the image `kubectl create deployment hello-server --image=localhost:5001/hello-app:1.0`
 
 If you build your own image and tag it like `localhost:5001/image:foo` and then use
-it in kubernetes as `localhost:5001/image:foo`. And use it from inside of your cluster application as `kind-registry:5000`.
+it in kubernetes as `localhost:5001/image:foo`. 
+
+If for some reason you have code running *inside* of a pod within the cluster that
+needs to use this registry directly (e.g. to build and push an image) then that
+code will need to use the `kind-registry:5000` HTTP endpoint directly, as the
+code running inside your pod will not see the containerd config.
+
+Pod manifests / pod specs / pod YAML should use `localhost:5001`,
+which will be rerouted to match the same name as the host via the containerd config.
+
+<!--TODO: consider a shared guide for this which we can use across the docs-->
+> **NOTE**: A bit about "localhost" and containers ...
+> "localhost" resolves to a loopback IP, which are network-namespace local.
+> Network-namespace local means that the `127.0.0.1` / `localhost` / `::1`
+> inside your container is NOT the same as the one on your host
+> (unless using `hostNetwork: true` / `--net=host`).
+>
+> KIND nodes are *not* `--net=host` and most pods are not, so really these
+> "`localhost`s" are local to your pod container, to your kind node, and to your
+> host machine in most cases.
+>
+> However we can tell containerd that `localhost:5001` should route to the
+> registry container such that the same name works on both the host and your machine.
+>
+> We do this so you can conveniently push and pull from a "local"
+> address on your host and in your pod YAML.