1. docker
  2. Commit dfd706e1a59c3830c87b8240c466489ae6cc9d15
Browse code

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>

Boaz Shuster authored on 2017/10/06 05:57:11
Showing 8 changed files
api/swagger.yaml
History View file @ dfd706e
... ... 
@@ -720,7 +720,15 @@ definitions:
720 720 
             description: "Gives the container full access to the host."
721 721 
           PublishAllPorts:
722 722 
             type: "boolean"
723 
-            description: "Allocates a random host port for all of a container's exposed ports."
723 
+            description: |
724 
+              Allocates an ephemeral host port for all of a container's
725 
+              exposed ports.
726 
+
727 
+              Ports are de-allocated when the container stops and allocated when the container starts.
728 
+              The allocated port might be changed when restarting the container.
729 
+
730 
+              The port is selected from the ephemeral port range that depends on the kernel.
731 
+              For example, on Linux the range is defined by `/proc/sys/net/ipv4/ip_local_port_range`.
724 732 
           ReadonlyRootfs:
725 733 
             type: "boolean"
726 734 
             description: "Mount the container's root filesystem as read only."
docs/api/v1.18.md
History View file @ dfd706e
... ... 
@@ -256,8 +256,14 @@ Create a container
256 256 
           should map to. A JSON object in the form
257 257 
           `{ <port>/<protocol>: [{ "HostPort": "<port>" }] }`
258 258 
           Take note that `port` is specified as a string and not an integer value.
259 
-    -   **PublishAllPorts** - Allocates a random host port for all of a container's
259 
+    -   **PublishAllPorts** - Allocates an ephemeral host port for all of a container's
260 260 
           exposed ports. Specified as a boolean value.
261 
+
262 
+          Ports are de-allocated when the container stops and allocated when the container starts.
263 
+          The allocated port might be changed when restarting the container.
264 
+
265 
+          The port is selected from the ephemeral port range that depends on the kernel.
266 
+          For example, on Linux the range is defined by `/proc/sys/net/ipv4/ip_local_port_range`.
261 267 
     -   **Privileged** - Gives the container full access to the host. Specified as
262 268 
           a boolean value.
263 269 
     -   **ReadonlyRootfs** - Mount the container's root filesystem as read only.
docs/api/v1.19.md
History View file @ dfd706e
... ... 
@@ -268,8 +268,14 @@ Create a container
268 268 
           should map to. A JSON object in the form
269 269 
           `{ <port>/<protocol>: [{ "HostPort": "<port>" }] }`
270 270 
           Take note that `port` is specified as a string and not an integer value.
271 
-    -   **PublishAllPorts** - Allocates a random host port for all of a container's
271 
+    -   **PublishAllPorts** - Allocates an ephemeral host port for all of a container's
272 272 
           exposed ports. Specified as a boolean value.
273 
+
274 
+          Ports are de-allocated when the container stops and allocated when the container starts.
275 
+          The allocated port might be changed when restarting the container.
276 
+
277 
+          The port is selected from the ephemeral port range that depends on the kernel.
278 
+          For example, on Linux the range is defined by `/proc/sys/net/ipv4/ip_local_port_range`.
273 279 
     -   **Privileged** - Gives the container full access to the host. Specified as
274 280 
           a boolean value.
275 281 
     -   **ReadonlyRootfs** - Mount the container's root filesystem as read only.
docs/api/v1.20.md
History View file @ dfd706e
... ... 
@@ -269,8 +269,14 @@ Create a container
269 269 
           should map to. A JSON object in the form
270 270 
           `{ <port>/<protocol>: [{ "HostPort": "<port>" }] }`
271 271 
           Take note that `port` is specified as a string and not an integer value.
272 
-    -   **PublishAllPorts** - Allocates a random host port for all of a container's
272 
+    -   **PublishAllPorts** - Allocates an ephemeral host port for all of a container's
273 273 
           exposed ports. Specified as a boolean value.
274 
+
275 
+          Ports are de-allocated when the container stops and allocated when the container starts.
276 
+          The allocated port might be changed when restarting the container.
277 
+
278 
+          The port is selected from the ephemeral port range that depends on the kernel.
279 
+          For example, on Linux the range is defined by `/proc/sys/net/ipv4/ip_local_port_range`.
274 280 
     -   **Privileged** - Gives the container full access to the host. Specified as
275 281 
           a boolean value.
276 282 
     -   **ReadonlyRootfs** - Mount the container's root filesystem as read only.
docs/api/v1.21.md
History View file @ dfd706e
... ... 
@@ -288,8 +288,14 @@ Create a container
288 288 
           should map to. A JSON object in the form
289 289 
           `{ <port>/<protocol>: [{ "HostPort": "<port>" }] }`
290 290 
           Take note that `port` is specified as a string and not an integer value.
291 
-    -   **PublishAllPorts** - Allocates a random host port for all of a container's
291 
+    -   **PublishAllPorts** - Allocates an ephemeral host port for all of a container's
292 292 
           exposed ports. Specified as a boolean value.
293 
+
294 
+          Ports are de-allocated when the container stops and allocated when the container starts.
295 
+          The allocated port might be changed when restarting the container.
296 
+
297 
+          The port is selected from the ephemeral port range that depends on the kernel.
298 
+          For example, on Linux the range is defined by `/proc/sys/net/ipv4/ip_local_port_range`.
293 299 
     -   **Privileged** - Gives the container full access to the host. Specified as
294 300 
           a boolean value.
295 301 
     -   **ReadonlyRootfs** - Mount the container's root filesystem as read only.
docs/api/v1.22.md
History View file @ dfd706e
... ... 
@@ -400,8 +400,14 @@ Create a container
400 400 
           should map to. A JSON object in the form
401 401 
           `{ <port>/<protocol>: [{ "HostPort": "<port>" }] }`
402 402 
           Take note that `port` is specified as a string and not an integer value.
403 
-    -   **PublishAllPorts** - Allocates a random host port for all of a container's
403 
+    -   **PublishAllPorts** - Allocates an ephemeral host port for all of a container's
404 404 
           exposed ports. Specified as a boolean value.
405 
+
406 
+          Ports are de-allocated when the container stops and allocated when the container starts.
407 
+          The allocated port might be changed when restarting the container.
408 
+
409 
+          The port is selected from the ephemeral port range that depends on the kernel.
410 
+          For example, on Linux the range is defined by `/proc/sys/net/ipv4/ip_local_port_range`.
405 411 
     -   **Privileged** - Gives the container full access to the host. Specified as
406 412 
           a boolean value.
407 413 
     -   **ReadonlyRootfs** - Mount the container's root filesystem as read only.
docs/api/v1.23.md
History View file @ dfd706e
... ... 
@@ -426,8 +426,14 @@ Create a container
426 426 
           should map to. A JSON object in the form
427 427 
           `{ <port>/<protocol>: [{ "HostPort": "<port>" }] }`
428 428 
           Take note that `port` is specified as a string and not an integer value.
429 
-    -   **PublishAllPorts** - Allocates a random host port for all of a container's
429 
+    -   **PublishAllPorts** - Allocates an ephemeral host port for all of a container's
430 430 
           exposed ports. Specified as a boolean value.
431 
+
432 
+          Ports are de-allocated when the container stops and allocated when the container starts.
433 
+          The allocated port might be changed when restarting the container.
434 
+
435 
+          The port is selected from the ephemeral port range that depends on the kernel.
436 
+          For example, on Linux the range is defined by `/proc/sys/net/ipv4/ip_local_port_range`.
431 437 
     -   **Privileged** - Gives the container full access to the host. Specified as
432 438 
           a boolean value.
433 439 
     -   **ReadonlyRootfs** - Mount the container's root filesystem as read only.
docs/api/v1.24.md
History View file @ dfd706e
... ... 
@@ -461,8 +461,14 @@ Create a container
461 461 
           should map to. A JSON object in the form
462 462 
           `{ <port>/<protocol>: [{ "HostPort": "<port>" }] }`
463 463 
           Take note that `port` is specified as a string and not an integer value.
464 
-    -   **PublishAllPorts** - Allocates a random host port for all of a container's
464 
+    -   **PublishAllPorts** - Allocates an ephemeral host port for all of a container's
465 465 
           exposed ports. Specified as a boolean value.
466 
+
467 
+          Ports are de-allocated when the container stops and allocated when the container starts.
468 
+          The allocated port might be changed when restarting the container.
469 
+
470 
+          The port is selected from the ephemeral port range that depends on the kernel.
471 
+          For example, on Linux the range is defined by `/proc/sys/net/ipv4/ip_local_port_range`.
466 472 
     -   **Privileged** - Gives the container full access to the host. Specified as
467 473 
           a boolean value.
468 474 
     -   **ReadonlyRootfs** - Mount the container's root filesystem as read only.