You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mesos.apache.org by jp...@apache.org on 2017/11/01 16:32:19 UTC
mesos git commit: Added documentation for the `network/ports`
isolator.
Repository: mesos
Updated Branches:
refs/heads/master c5c1debb1 -> d578dc7cd
Added documentation for the `network/ports` isolator.
Added documentation for the `network/ports` isolator to the Mesos
containerizer documentation. Updated the agent flags documentation with
the new isolator flags. Added changelog information to note the new
isolator, the new agent flags and new fields in the TaskStatus message.
Review: https://reviews.apache.org/r/63331/
Project: http://git-wip-us.apache.org/repos/asf/mesos/repo
Commit: http://git-wip-us.apache.org/repos/asf/mesos/commit/d578dc7c
Tree: http://git-wip-us.apache.org/repos/asf/mesos/tree/d578dc7c
Diff: http://git-wip-us.apache.org/repos/asf/mesos/diff/d578dc7c
Branch: refs/heads/master
Commit: d578dc7cd838f65b05f41b47aa2d2d8dd0f71865
Parents: c5c1deb
Author: James Peach <jp...@apache.org>
Authored: Wed Nov 1 09:31:37 2017 -0700
Committer: James Peach <jp...@apache.org>
Committed: Wed Nov 1 09:31:37 2017 -0700
----------------------------------------------------------------------
docs/configuration/agent.md | 22 ++++++++++++
docs/isolators/network-ports.md | 67 ++++++++++++++++++++++++++++++++++++
docs/mesos-containerizer.md | 3 +-
docs/upgrades.md | 18 +++++++++-
4 files changed, 108 insertions(+), 2 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/mesos/blob/d578dc7c/docs/configuration/agent.md
----------------------------------------------------------------------
diff --git a/docs/configuration/agent.md b/docs/configuration/agent.md
index 5c1b469..116e7c6 100644
--- a/docs/configuration/agent.md
+++ b/docs/configuration/agent.md
@@ -333,6 +333,18 @@ Name of the root cgroup. (default: mesos)
</tr>
<tr>
<td>
+ --[no-]check_agent_port_range_only
+ </td>
+ <td>
+When this is true, the `network/ports` isolator allows tasks to
+listen on additional ports provided they fall outside the range
+published by the agent's resources. Otherwise tasks are restricted
+to only listen on ports for which they have been assigned resources.
+(default: false)
+ </td>
+</tr>
+<tr>
+ <td>
--container_disk_watch_interval=VALUE
</td>
<td>
@@ -353,6 +365,16 @@ in the sandbox directory.
</tr>
<tr>
<td>
+ --container_ports_watch_interval=VALUE
+ </td>
+Interval at which the `network/ports` isolator should check for
+containers listening on ports they don't have resources for.
+(default: 30secs)
+ <td>
+ </td>
+</tr>
+<tr>
+ <td>
--containerizers=VALUE
</td>
<td>
http://git-wip-us.apache.org/repos/asf/mesos/blob/d578dc7c/docs/isolators/network-ports.md
----------------------------------------------------------------------
diff --git a/docs/isolators/network-ports.md b/docs/isolators/network-ports.md
new file mode 100644
index 0000000..ea63968
--- /dev/null
+++ b/docs/isolators/network-ports.md
@@ -0,0 +1,67 @@
+---
+title: Apache Mesos - Network Ports Isolator in Mesos Containerizer
+layout: documentation
+---
+
+# Network Ports Isolator in Mesos Containerizer
+
+When tasks run in the host network namespace, a scheduler typically
+assigns ports resources to them and they must only listen on the network
+ports they have been assigned. If a task listens on the wrong ports,
+the resulting failures can be hard to diagnose.
+
+The network ports isolator enforces task port assignments by periodically
+scanning the set of ports every task is listening on and reconciling that
+information against the corresponding ports resources. If a task is found
+to be listening on a port that has not been allocated to it, the task
+will be killed and the its framework will receive a status update with
+the reason `REASON_CONTAINER_LIMITATION`. The port(s) that triggered the
+limitation will be reported as resources in the status update. If the task
+is a member of a [task group](../nested-container-and-task-group.md),
+the limitation is raised against the root of the task group (i.e. the
+executor's container). This behavior is consistent across all the Mesos
+resource isolators.
+
+## Installation
+
+The network ports isolator is not compiled into Mesos by default. To
+enable it in build, specify the `--enable-network-ports-isolator`
+configuration option.
+
+[libnl3](https://github.com/thom311/libnl/releases) version 3.2.26 or
+higher is required at both build and deployment time.
+
+## Configuration
+
+To enable the network ports isolator, append `network/ports` to the
+`--isolation` flag when starting the agent.
+
+The network ports isolator requires that the Mesos agent is configured
+to use the Linux launcher (i.e. the agent has the `--launcher=linux`
+flag), because it uses Linux cgroups to track the processes belonging
+to a Mesos task.
+
+The `--container_ports_watch_interval` flag specifies the interval
+between task port reconciliations.
+
+If the `--check_agent_port_range_only` flag is specified, the isolator
+will not kill tasks that listen on unallocated ports outside the range
+of port resources the agent offers to tasks. This flag is required when
+using the default Mesos executors or any custom executor that uses the
+native Mesos Java or Python bindings since the native Mesos libraries
+will always implicity listen on a socket. This flag should not be
+required for custom executors that use the HTTP executor API.
+
+The network ports isolator ignores tasks that belong to a [CNI](../cni.md)
+network since these tasks do not share the host network namespace.
+
+## Security Considerations
+
+The network ports isolator is not a secure mechanism for enforcing
+port assignments. Since it periodically reconciles port assignments,
+it is possible for a sufficiently malicious task to only listen
+on unassigned ports between reconciliations. The reconciliation is
+performed by the Mesos agent, so if the agent has been stopped, no
+port assignments are enforced. Depending on the configuration, the
+`--check_agent_port_range_only` flag could allow a malicious task to
+intercept network requests.
http://git-wip-us.apache.org/repos/asf/mesos/blob/d578dc7c/docs/mesos-containerizer.md
----------------------------------------------------------------------
diff --git a/docs/mesos-containerizer.md b/docs/mesos-containerizer.md
index 9cb0712..a194eb0 100644
--- a/docs/mesos-containerizer.md
+++ b/docs/mesos-containerizer.md
@@ -26,7 +26,6 @@ can write modules that implement custom isolators.
Mesos supports the following built-in isolators.
-- [environment\_secret](secrets.md#environment-based-secrets)
- appc/runtime
- [cgroups/blkio](isolators/cgroups-blkio.md)
- [cgroups/cpu](isolators/cgroups-cpu.md)
@@ -42,6 +41,7 @@ Mesos supports the following built-in isolators.
- [disk/xfs](isolators/disk-xfs.md)
- [docker/runtime](isolators/docker-runtime.md)
- [docker/volume](isolators/docker-volume.md)
+- [environment\_secret](secrets.md#environment-based-secrets)
- filesystem/linux
- filesystem/posix
- [filesystem/shared](isolators/filesystem-shared.md)
@@ -52,6 +52,7 @@ Mesos supports the following built-in isolators.
- [namespaces/pid](isolators/namespaces-pid.md)
- [network/cni](cni.md)
- [network/port_mapping](isolators/network-port-mapping.md)
+- [network/ports](isolators/network-ports.md)
- posix/cpu
- posix/mem
- [posix/rlimits](isolators/posix-rlimits.md)
http://git-wip-us.apache.org/repos/asf/mesos/blob/d578dc7c/docs/upgrades.md
----------------------------------------------------------------------
diff --git a/docs/upgrades.md b/docs/upgrades.md
index 6370c06..b65a350 100644
--- a/docs/upgrades.md
+++ b/docs/upgrades.md
@@ -48,17 +48,21 @@ We categorize the changes as follows:
<td style="word-wrap: break-word; overflow-wrap: break-word;"><!--Mesos Core-->
<ul style="padding-left:10px;">
- <li>C <a href="#1-5-x-task-starting">Built-int executors send a TASK_STARTING update</a></li>
+ <li>C <a href="#1-5-x-task-starting">Built-in executors send a TASK_STARTING update</a></li>
+ <li>A <a href="#1-5-x-network-ports-isolator">Network ports isolator</a></li>
</ul>
</td>
<td style="word-wrap: break-word; overflow-wrap: break-word;"><!--Flags-->
<ul style="padding-left:10px;">
+ <li>A <a href="#1-5-x-network-ports-isolator">container_ports_watch_interval</a></li>
+ <li>A <a href="#1-5-x-network-ports-isolator">check_agent_port_range_only</a></li>
</ul>
</td>
<td style="word-wrap: break-word; overflow-wrap: break-word;"><!--Framework API-->
<ul style="padding-left:10px;">
+ <li>A <a href="#1-5-x-task-resource-limitation">Added the TaskStatus.limitation message</a></li>
</ul>
</td>
@@ -361,6 +365,18 @@ We categorize the changes as follows:
executors must be upgraded to expect `TASK_STARTING` updates before upgrading
Mesos itself.
+<a name="1-5-x-task-resource-limitation"></a>
+
+* A new field, `limitation`, was added to the `TaskStatus` message. This
+ field is a `TaskResourceLimitation` message that describes the resources
+ that caused a task to fail with a resource limitation reason.
+
+<a name="1-5-x-network-ports-isolator"></a>
+
+* A new [`network/ports`](isolators/network-ports.md) isolator has been added. The isolator supports the following new agent flags:
+ * `--container_ports_watch_interval` specifies the interval at which the isolator reconciles port assignments.
+ * `--check_agent_port_range_only` excludes ports outside the agent's range from port reconcilation.
+
## Upgrading from 1.3.x to 1.4.x ##
<a name="1-4-x-ambient-capabilities"></a>