From ba59ebdfa9188ecc22987cde14cbf7bb2e64d6e2 Mon Sep 17 00:00:00 2001 From: Chris Bednarski Date: Thu, 8 Oct 2015 00:02:46 -0700 Subject: [PATCH 1/4] Clarified package documentation for executor in response to #232 --- client/executor/exec.go | 25 ++++++++++++++----------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/client/executor/exec.go b/client/executor/exec.go index 483e1fdef..44cbe9f3d 100644 --- a/client/executor/exec.go +++ b/client/executor/exec.go @@ -1,20 +1,23 @@ -// Package exec is used to invoke child processes across various platforms to -// provide the following features: +s// Package executor is used to invoke child processes across various "platforms" +// in a way that provides the following features: // // - Least privilege // - Resource constraints // - Process isolation // -// A "platform" may be defined as coarsely as "Windows" or as specifically as -// "linux 3.20 with systemd". This allows Nomad to use best-effort, best- -// available capabilities of each platform to provide resource constraints, -// process isolation, and security features, or otherwise take advantage of -// features that are unique to that platform. +// A "platform" may something like "windows" or "linux with systemd". Executors +// allow drivers like `exec` and `java` to share a common implementation of the +// isolation capabilities on a particular operating system. // -// The `semantics of any particular instance are left up to the implementation. -// However, these should be completely transparent to the calling context. In -// other words, the Java driver should be able to call exec for any platform and -// just work. +// For example: +// +// - `exec` and `java` on Linux will use a cgroups executor +// - `exec` and `java` on FreeBSD will use a jails executor +// +// However, drivers that provide their own isolation should not use executors. +// For example, using an executor to start QEMU means that the QEMU call is +// run inside a chroot+cgroup, even though the VM already provides isolation for +// the task running inside it. That's not what we want. package executor import ( From c681ec1ba93a3386ceacd005397a368eb34d6b00 Mon Sep 17 00:00:00 2001 From: Chris Bednarski Date: Thu, 8 Oct 2015 00:04:45 -0700 Subject: [PATCH 2/4] Removed wayward 's' --- client/executor/exec.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/client/executor/exec.go b/client/executor/exec.go index 44cbe9f3d..59a601a7d 100644 --- a/client/executor/exec.go +++ b/client/executor/exec.go @@ -1,4 +1,4 @@ -s// Package executor is used to invoke child processes across various "platforms" +// Package executor is used to invoke child processes across various "platforms" // in a way that provides the following features: // // - Least privilege From 4a1ae3cd4a12cfdebdcc089a90b8bb7756511cfb Mon Sep 17 00:00:00 2001 From: Chris Bednarski Date: Thu, 8 Oct 2015 00:07:07 -0700 Subject: [PATCH 3/4] Tweak phrasing to be clearer *why* that's not what we want --- client/executor/exec.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/client/executor/exec.go b/client/executor/exec.go index 59a601a7d..140739214 100644 --- a/client/executor/exec.go +++ b/client/executor/exec.go @@ -17,7 +17,7 @@ // However, drivers that provide their own isolation should not use executors. // For example, using an executor to start QEMU means that the QEMU call is // run inside a chroot+cgroup, even though the VM already provides isolation for -// the task running inside it. That's not what we want. +// the task running inside it. This is an extraneous level of indirection package executor import ( From 7063c7146152a3e178e93da1202824375104f396 Mon Sep 17 00:00:00 2001 From: Chris Bednarski Date: Thu, 8 Oct 2015 01:38:39 -0700 Subject: [PATCH 4/4] Insert missing 'may be' and clean up some other formatting / phrasing --- client/executor/exec.go | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/client/executor/exec.go b/client/executor/exec.go index 140739214..ca104ca3e 100644 --- a/client/executor/exec.go +++ b/client/executor/exec.go @@ -1,23 +1,23 @@ -// Package executor is used to invoke child processes across various "platforms" -// in a way that provides the following features: +// Package executor is used to invoke child processes across various operating +// systems in a way that provides the following features: // // - Least privilege // - Resource constraints // - Process isolation // -// A "platform" may something like "windows" or "linux with systemd". Executors -// allow drivers like `exec` and `java` to share a common implementation of the -// isolation capabilities on a particular operating system. +// An operating system may be something like "windows" or "linux with systemd". +// Executors allow drivers like `exec` and `java` to share an implementation +// for isolation capabilities on a particular operating system. // // For example: // -// - `exec` and `java` on Linux will use a cgroups executor -// - `exec` and `java` on FreeBSD will use a jails executor +// - `exec` and `java` on Linux use a cgroups executor +// - `exec` and `java` on FreeBSD use a jails executor // // However, drivers that provide their own isolation should not use executors. // For example, using an executor to start QEMU means that the QEMU call is // run inside a chroot+cgroup, even though the VM already provides isolation for -// the task running inside it. This is an extraneous level of indirection +// the task running inside it. This is an extraneous level of indirection. package executor import (