Elaborate more about port allocation in docs

Describe more how host port allocation is done when
container is stopped/started in "PublishAllPorts".

Signed-off-by: Boaz Shuster <ripcurld.github@gmail.com>
Upstream-commit: dfd706e1a59c3830c87b8240c466489ae6cc9d15
Component: engine

components/engine/api/swagger.yaml

@@ -720,7 +720,15 @@ definitions:
             description: "Gives the container full access to the host."
           PublishAllPorts:
             type: "boolean"
-            description: "Allocates a random host port for all of a container's exposed ports."
+            description: |
+              Allocates an ephemeral host port for all of a container's
+              exposed ports.
+
+              Ports are de-allocated when the container stops and allocated when the container starts.
+              The allocated port might be changed when restarting the container.
+
+              The port is selected from the ephemeral port range that depends on the kernel.
+              For example, on Linux the range is defined by `/proc/sys/net/ipv4/ip_local_port_range`.
           ReadonlyRootfs:
             type: "boolean"
             description: "Mount the container's root filesystem as read only."

components/engine/docs/api/v1.18.md

@@ -256,8 +256,14 @@ Create a container
           should map to. A JSON object in the form
           `{ <port>/<protocol>: [{ "HostPort": "<port>" }] }`
           Take note that `port` is specified as a string and not an integer value.
-    -   **PublishAllPorts** - Allocates a random host port for all of a container's
+    -   **PublishAllPorts** - Allocates an ephemeral host port for all of a container's
           exposed ports. Specified as a boolean value.
+
+          Ports are de-allocated when the container stops and allocated when the container starts.
+          The allocated port might be changed when restarting the container.
+
+          The port is selected from the ephemeral port range that depends on the kernel.
+          For example, on Linux the range is defined by `/proc/sys/net/ipv4/ip_local_port_range`.
     -   **Privileged** - Gives the container full access to the host. Specified as
           a boolean value.
     -   **ReadonlyRootfs** - Mount the container's root filesystem as read only.

components/engine/docs/api/v1.19.md

@@ -268,8 +268,14 @@ Create a container
           should map to. A JSON object in the form
           `{ <port>/<protocol>: [{ "HostPort": "<port>" }] }`
           Take note that `port` is specified as a string and not an integer value.
-    -   **PublishAllPorts** - Allocates a random host port for all of a container's
+    -   **PublishAllPorts** - Allocates an ephemeral host port for all of a container's
           exposed ports. Specified as a boolean value.
+
+          Ports are de-allocated when the container stops and allocated when the container starts.
+          The allocated port might be changed when restarting the container.
+
+          The port is selected from the ephemeral port range that depends on the kernel.
+          For example, on Linux the range is defined by `/proc/sys/net/ipv4/ip_local_port_range`.
     -   **Privileged** - Gives the container full access to the host. Specified as
           a boolean value.
     -   **ReadonlyRootfs** - Mount the container's root filesystem as read only.

components/engine/docs/api/v1.20.md

@@ -269,8 +269,14 @@ Create a container
           should map to. A JSON object in the form
           `{ <port>/<protocol>: [{ "HostPort": "<port>" }] }`
           Take note that `port` is specified as a string and not an integer value.
-    -   **PublishAllPorts** - Allocates a random host port for all of a container's
+    -   **PublishAllPorts** - Allocates an ephemeral host port for all of a container's
           exposed ports. Specified as a boolean value.
+
+          Ports are de-allocated when the container stops and allocated when the container starts.
+          The allocated port might be changed when restarting the container.
+
+          The port is selected from the ephemeral port range that depends on the kernel.
+          For example, on Linux the range is defined by `/proc/sys/net/ipv4/ip_local_port_range`.
     -   **Privileged** - Gives the container full access to the host. Specified as
           a boolean value.
     -   **ReadonlyRootfs** - Mount the container's root filesystem as read only.

components/engine/docs/api/v1.21.md

@@ -288,8 +288,14 @@ Create a container
           should map to. A JSON object in the form
           `{ <port>/<protocol>: [{ "HostPort": "<port>" }] }`
           Take note that `port` is specified as a string and not an integer value.
-    -   **PublishAllPorts** - Allocates a random host port for all of a container's
+    -   **PublishAllPorts** - Allocates an ephemeral host port for all of a container's
           exposed ports. Specified as a boolean value.
+
+          Ports are de-allocated when the container stops and allocated when the container starts.
+          The allocated port might be changed when restarting the container.
+
+          The port is selected from the ephemeral port range that depends on the kernel.
+          For example, on Linux the range is defined by `/proc/sys/net/ipv4/ip_local_port_range`.
     -   **Privileged** - Gives the container full access to the host. Specified as
           a boolean value.
     -   **ReadonlyRootfs** - Mount the container's root filesystem as read only.

components/engine/docs/api/v1.22.md

@@ -400,8 +400,14 @@ Create a container
           should map to. A JSON object in the form
           `{ <port>/<protocol>: [{ "HostPort": "<port>" }] }`
           Take note that `port` is specified as a string and not an integer value.
-    -   **PublishAllPorts** - Allocates a random host port for all of a container's
+    -   **PublishAllPorts** - Allocates an ephemeral host port for all of a container's
           exposed ports. Specified as a boolean value.
+
+          Ports are de-allocated when the container stops and allocated when the container starts.
+          The allocated port might be changed when restarting the container.
+
+          The port is selected from the ephemeral port range that depends on the kernel.
+          For example, on Linux the range is defined by `/proc/sys/net/ipv4/ip_local_port_range`.
     -   **Privileged** - Gives the container full access to the host. Specified as
           a boolean value.
     -   **ReadonlyRootfs** - Mount the container's root filesystem as read only.

components/engine/docs/api/v1.23.md

@@ -426,8 +426,14 @@ Create a container
           should map to. A JSON object in the form
           `{ <port>/<protocol>: [{ "HostPort": "<port>" }] }`
           Take note that `port` is specified as a string and not an integer value.
-    -   **PublishAllPorts** - Allocates a random host port for all of a container's
+    -   **PublishAllPorts** - Allocates an ephemeral host port for all of a container's
           exposed ports. Specified as a boolean value.
+
+          Ports are de-allocated when the container stops and allocated when the container starts.
+          The allocated port might be changed when restarting the container.
+
+          The port is selected from the ephemeral port range that depends on the kernel.
+          For example, on Linux the range is defined by `/proc/sys/net/ipv4/ip_local_port_range`.
     -   **Privileged** - Gives the container full access to the host. Specified as
           a boolean value.
     -   **ReadonlyRootfs** - Mount the container's root filesystem as read only.

components/engine/docs/api/v1.24.md

@@ -461,8 +461,14 @@ Create a container
           should map to. A JSON object in the form
           `{ <port>/<protocol>: [{ "HostPort": "<port>" }] }`
           Take note that `port` is specified as a string and not an integer value.
-    -   **PublishAllPorts** - Allocates a random host port for all of a container's
+    -   **PublishAllPorts** - Allocates an ephemeral host port for all of a container's
           exposed ports. Specified as a boolean value.
+
+          Ports are de-allocated when the container stops and allocated when the container starts.
+          The allocated port might be changed when restarting the container.
+
+          The port is selected from the ephemeral port range that depends on the kernel.
+          For example, on Linux the range is defined by `/proc/sys/net/ipv4/ip_local_port_range`.
     -   **Privileged** - Gives the container full access to the host. Specified as
           a boolean value.
     -   **ReadonlyRootfs** - Mount the container's root filesystem as read only.