Note port publishing needs in pods for create/run

Add notes to the podman-create and podman-run man pages
to note that ports do not need to be published and should not
be, for containers that will be part of a pod.

Addresses: #6769

Signed-off-by: TomSweeneyRedHat <tsweeney@redhat.com>

3 files changed, 50 insertions, 0 deletions

diff --git a/docs/source/markdown/podman-create.1.md b/docs/source/markdown/podman-create.1.md
index 976a1e681..cbf51dd2e 100644
--- a/docs/source/markdown/podman-create.1.md
+++ b/docs/source/markdown/podman-create.1.md
@@ -648,6 +648,14 @@ Host port does not have to be specified (e.g. `podman run -p 127.0.0.1::80`).
 If it is not, the container port will be randomly assigned a port on the host.
 Use `podman port` to see the actual mapping: `podman port CONTAINER $CONTAINERPORT`
 
+**Note:** if a container will be run within a pod, it is not necessary to publish the port for
+the containers in the pod. The port must only be published by the pod itself.  Pod network
+stacks act like the network stack on the host - you have a variety of containers in the pod,
+and programs in the container, all sharing a single interface and IP address, and
+associated ports. If one container binds to a port, no other container can use that port
+within the pod while it is in use. Containers in the pod can also communicate over localhost
+by having one container bind to localhost in the pod, and another connect to that port.
+
 **--publish-all**, **-P**=*true|false*
 
 Publish all exposed ports to random ports on the host interfaces. The default is *false*.
diff --git a/docs/source/markdown/podman-run.1.md b/docs/source/markdown/podman-run.1.md
index b6c1fab17..09df87b2b 100644
--- a/docs/source/markdown/podman-run.1.md
+++ b/docs/source/markdown/podman-run.1.md
@@ -662,6 +662,14 @@ If it is not, the container port will be randomly assigned a port on the host.
 
 Use **podman port** to see the actual mapping: **podman port $CONTAINER $CONTAINERPORT**.
 
+**Note:** if a container will be run within a pod, it is not necessary to publish the port for
+the containers in the pod. The port must only be published by the pod itself.  Pod network
+stacks act like the network stack on the host - you have a variety of containers in the pod,
+and programs in the container, all sharing a single interface and IP address, and
+associated ports. If one container binds to a port, no other container can use that port
+within the pod while it is in use. Containers in the pod can also communicate over localhost
+by having one container bind to localhost in the pod, and another connect to that port.
+
 **--publish-all**, **-P**=**true**|**false**
 
 Publish all exposed ports to random ports on the host interfaces. The default is **false**.
diff --git a/troubleshooting.md b/troubleshooting.md
index 4c452404c..7e8f9bcb0 100644
--- a/troubleshooting.md
+++ b/troubleshooting.md
@@ -558,3 +558,37 @@ _eof
 
 In order to effect root running containers and all users, modify the system
 wide defaults in /etc/containers/containers.conf
+
+
+### 23) Container with exposed ports won't run in a pod
+
+A container with ports that have been published with the `--publish` or `-p` option
+can not be run within a pod.
+
+#### Symptom
+
+```
+$ podman pod create --name srcview -p 127.0.0.1:3434:3434 -p 127.0.0.1:7080:7080 -p 127.0.0.1:3370:3370                        4b2f4611fa2cbd60b3899b936368c2b3f4f0f68bc8e6593416e0ab8ecb0a3f1d
+
+$ podman run --pod srcview --name src-expose -p 3434:3434 -v "${PWD}:/var/opt/localrepo":Z,ro sourcegraph/src-expose:latest serve /var/opt/localrepo
+Error: cannot set port bindings on an existing container network namespace
+```
+
+#### Solution
+
+This is a known limitation.  If a container will be run within a pod, it is not necessary
+to publish the port for the containers in the pod. The port must only be published by the
+pod itself.  Pod network stacks act like the network stack on the host - you have a
+variety of containers in the pod, and programs in the container, all sharing a single
+interface and IP address, and associated ports. If one container binds to a port, no other
+container can use that port within the pod while it is in use. Containers in the pod can
+also communicate over localhost by having one container bind to localhost in the pod, and
+another connect to that port.
+
+In the example from the symptom section, dropping the `-p 3434:3434` would allow the
+`podman run` command to complete, and the container as part of the pod would still have
+access to that port.  For example:
+
+```
+$ podman run --pod srcview --name src-expose -v "${PWD}:/var/opt/localrepo":Z,ro sourcegraph/src-expose:latest serve /var/opt/localrepo
+```