From b1f062f1b010494b0c2afc2d9d205b2a02b0f463 Mon Sep 17 00:00:00 2001
From: Alex Dadgar <alex.dadgar@gmail.com>
Date: Mon, 13 Feb 2017 10:18:34 -0800
Subject: [PATCH] Documentation

---
 website/source/docs/http/json-jobs.html.md     |  7 +++++++
 .../source/docs/job-specification/task.html.md |  4 ++++
 .../operating-a-job/accessing-logs.html.md     | 18 +++++++++++++++---
 3 files changed, 26 insertions(+), 3 deletions(-)

diff --git a/website/source/docs/http/json-jobs.html.md b/website/source/docs/http/json-jobs.html.md
index 7d8cc3bbe..48f600925 100644
--- a/website/source/docs/http/json-jobs.html.md
+++ b/website/source/docs/http/json-jobs.html.md
@@ -358,6 +358,10 @@ The `Task` object supports the following keys:
   sends `SIGTERM` if the task doesn't die after the `KillTimeout` duration has
   elapsed. The default `KillTimeout` is 5 seconds.
 
+* `leader` - Specifies whether the task is the leader task of the task group. If
+  set to true, when the leader task completes, all other tasks within the task
+  group will be gracefully shutdown.
+
 * `LogConfig` - This allows configuring log rotation for the `stdout` and `stderr`
   buffers of a Task. See the log rotation reference below for more details.
 
@@ -681,6 +685,9 @@ README][ct].
   "SIGUSR1" or "SIGINT". This option is required if the `ChangeMode` is
   `signal`.
 
+* `perms` - Specifies the rendered template's permissions. File permissions are
+  given as octal of the unix file permissions rwxrwxrwx.
+
 * `Splay` - Specifies a random amount of time to wait between 0ms and the given
   splay value before invoking the change mode. Should be specified in
   nanoseconds.
diff --git a/website/source/docs/job-specification/task.html.md b/website/source/docs/job-specification/task.html.md
index 0bc47c42c..76be98ca1 100644
--- a/website/source/docs/job-specification/task.html.md
+++ b/website/source/docs/job-specification/task.html.md
@@ -52,6 +52,10 @@ job "docs" {
   If the task does not exit before the configured timeout, `SIGKILL` is sent to
   the task.
 
+- `leader` `(bool: false)` - Specifies whether the task is the leader task of
+  the task group. If set to true, when the leader task completes, all other
+  tasks within the task group will be gracefully shutdown.
+
 - `logs` <code>([Logs][]: nil)</code> - Specifies logging configuration for the
   `stdout` and `stderr` of the task.
 
diff --git a/website/source/docs/operating-a-job/accessing-logs.html.md b/website/source/docs/operating-a-job/accessing-logs.html.md
index e0daf7520..c006bada1 100644
--- a/website/source/docs/operating-a-job/accessing-logs.html.md
+++ b/website/source/docs/operating-a-job/accessing-logs.html.md
@@ -79,9 +79,9 @@ $ nomad logs -stderr 04d9627d
 
 While the logs command works well for quickly accessing application logs, it
 generally does not scale to large systems or systems that produce a lot of log
-output, especially for the long-term storage of logs. Nomad only retains log
-files for a configurable period of time, so chatty applications should use a
-better log retention strategy.
+output, especially for the long-term storage of logs. Nomad's retention of log
+files is best effort, so chatty applications should use a better log retention
+strategy.
 
 Since applications log to the `alloc/` directory, all tasks within the same task
 group have access to each others logs. Thus it is possible to have a task group
@@ -91,6 +91,10 @@ as follows:
 group "my-group" {
   task "server" {
     # ...
+
+    # Setting the server task as the leader of the task group allows us to
+    # signal the log shipper task to gracefully shutdown when the server exits.
+    leader = true
   }
 
   task "log-shipper" {
@@ -103,3 +107,11 @@ In the above example, the `server` task is the application that should be run
 and will be producing the logs. The `log-shipper` reads those logs from the
 `alloc/logs/` directory and sends them to a longer-term storage solution such as
 Amazon S3 or an internal log aggregation system.
+
+When using the log shipper pattern, especially for batch jobs, the main task
+should be marked as the [leader task](/docs/job-specification/task.html#leader).
+By marking the main task as a leader, when the task completes all other tasks
+within the group will be gracefully shutdown. This allows the log shipper to
+finish sending any logs and then exiting itself. The log shipper should set a
+high enough [`kill_timeout`](/docs/job-specification/task.html#kill_timeout)
+such that it can ship any remaining logs before exiting.