From 6bfaa3dd46fab9c416a89af55777408ddb782837 Mon Sep 17 00:00:00 2001 From: Boaz Shuster Date: Thu, 5 Oct 2017 23:57:11 +0300 Subject: [PATCH] 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 Upstream-commit: dfd706e1a59c3830c87b8240c466489ae6cc9d15 Component: engine --- components/engine/api/swagger.yaml | 10 +++++++++- components/engine/docs/api/v1.18.md | 8 +++++++- components/engine/docs/api/v1.19.md | 8 +++++++- components/engine/docs/api/v1.20.md | 8 +++++++- components/engine/docs/api/v1.21.md | 8 +++++++- components/engine/docs/api/v1.22.md | 8 +++++++- components/engine/docs/api/v1.23.md | 8 +++++++- components/engine/docs/api/v1.24.md | 8 +++++++- 8 files changed, 58 insertions(+), 8 deletions(-) diff --git a/components/engine/api/swagger.yaml b/components/engine/api/swagger.yaml index 1e300e7b40..3e2ead8425 100644 --- a/components/engine/api/swagger.yaml +++ b/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." diff --git a/components/engine/docs/api/v1.18.md b/components/engine/docs/api/v1.18.md index 973dca9f92..d3d97be08a 100644 --- a/components/engine/docs/api/v1.18.md +++ b/components/engine/docs/api/v1.18.md @@ -256,8 +256,14 @@ Create a container should map to. A JSON object in the form `{ /: [{ "HostPort": "" }] }` 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. diff --git a/components/engine/docs/api/v1.19.md b/components/engine/docs/api/v1.19.md index 3bcf7668f9..f82a5124fc 100644 --- a/components/engine/docs/api/v1.19.md +++ b/components/engine/docs/api/v1.19.md @@ -268,8 +268,14 @@ Create a container should map to. A JSON object in the form `{ /: [{ "HostPort": "" }] }` 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. diff --git a/components/engine/docs/api/v1.20.md b/components/engine/docs/api/v1.20.md index e5b8f32fce..91551815d5 100644 --- a/components/engine/docs/api/v1.20.md +++ b/components/engine/docs/api/v1.20.md @@ -269,8 +269,14 @@ Create a container should map to. A JSON object in the form `{ /: [{ "HostPort": "" }] }` 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. diff --git a/components/engine/docs/api/v1.21.md b/components/engine/docs/api/v1.21.md index f1863b8c11..57290e628f 100644 --- a/components/engine/docs/api/v1.21.md +++ b/components/engine/docs/api/v1.21.md @@ -288,8 +288,14 @@ Create a container should map to. A JSON object in the form `{ /: [{ "HostPort": "" }] }` 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. diff --git a/components/engine/docs/api/v1.22.md b/components/engine/docs/api/v1.22.md index 473ffd3c91..3253a68dba 100644 --- a/components/engine/docs/api/v1.22.md +++ b/components/engine/docs/api/v1.22.md @@ -400,8 +400,14 @@ Create a container should map to. A JSON object in the form `{ /: [{ "HostPort": "" }] }` 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. diff --git a/components/engine/docs/api/v1.23.md b/components/engine/docs/api/v1.23.md index c040d2460a..8a955ce93b 100644 --- a/components/engine/docs/api/v1.23.md +++ b/components/engine/docs/api/v1.23.md @@ -426,8 +426,14 @@ Create a container should map to. A JSON object in the form `{ /: [{ "HostPort": "" }] }` 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. diff --git a/components/engine/docs/api/v1.24.md b/components/engine/docs/api/v1.24.md index 29fed46a22..13d592b41c 100644 --- a/components/engine/docs/api/v1.24.md +++ b/components/engine/docs/api/v1.24.md @@ -461,8 +461,14 @@ Create a container should map to. A JSON object in the form `{ /: [{ "HostPort": "" }] }` 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.