From 73e6e2ac4026d3ea748fbfdeaf61358fd55a8a79 Mon Sep 17 00:00:00 2001
From: Mahmood Ali <mahmood@hashicorp.com>
Date: Mon, 20 May 2019 10:06:15 -0400
Subject: [PATCH] elaborate on shell interpolation and examples

---
 .../docs/commands/alloc/exec.html.md.erb      | 64 +++++++++++++++----
 1 file changed, 50 insertions(+), 14 deletions(-)

diff --git a/website/source/docs/commands/alloc/exec.html.md.erb b/website/source/docs/commands/alloc/exec.html.md.erb
index 4ebddbf06..cc825f08d 100644
--- a/website/source/docs/commands/alloc/exec.html.md.erb
+++ b/website/source/docs/commands/alloc/exec.html.md.erb
@@ -3,7 +3,7 @@ layout: "docs"
 page_title: "Commands: alloc exec"
 sidebar_current: "docs-commands-alloc-exec"
 description: >
-Stream the exec of a task.
+  Runs a command in a container.
 ---
 
 # Command: alloc exec
@@ -15,7 +15,7 @@ The `alloc exec` command runs a command in a running allocation.
 
 ```
 nomad alloc exec [options] <allocation> <command> [<args>...]
-    ```
+```
 
 
 The nomad exec command can be use to run commands inside a running task/allocation.
@@ -23,11 +23,11 @@ The nomad exec command can be use to run commands inside a running task/allocati
 Use cases are for inspecting container state, debugging a failed application
 without needing ssh access into the node that's running the allocation.
 
-This command streams the execution of command in the given task in the allocation.  If the
+This command executes the command in the given task in the allocation.  If the
 allocation is only running a single task, the task name can be omitted.
 Optionally, the `-job` option may be used in which case a random allocation from
 the given job will be chosen.
-#
+
 ## General Options
 
 <%= partial "docs/commands/_general_options" %>
@@ -53,21 +53,57 @@ transparent.
 
 ## Examples
 
-```
-$ # interactive debugging
-$ nomad alloc exec eb17e557 /bin/sh
-/ # ps -ef
-...
+To start an interactive debugging session in a particular alloc, invoke exec
+command with your desired shell available inside the task:
 
+```
+$ nomad alloc exec eb17e557 /bin/bash
+root@eb17e557:/data# # now run any debugging commands inside container
+root@eb17e557:/data# # ps -ef
+```
+
+To run a command and stream results without starting an interactive shell, you
+can pass the command and its arguments to exec directly:
+
+```
 $ # run commands without starting an interactive session
 $ nomad alloc exec eb17e557 cat /etc/resolv.conf
-...
-
-$ # run commands on an arbitrary alloc of a job
-$ nomad alloc exec -job example printenv NOMAD_CPU_LIMIT
-...
 ```
 
+When passing command arguments to be evaluated in task, you may need to ensure
+that your host shell doesn't interpolate values before invoking `exec` command.
+For example, the following command would return the environment variable on
+operator shell rather than task containers:
+
+```
+$ nomad alloc exec eb17e557 echo $NOMAD_ALLOC_ID # wrong
+```
+
+Here, we must start a shell in task to interpolate `$NOMAD_ALLOC_ID`, and quote
+command or use the [heredoc syntax][heredoc]
+
+```
+$ # by quoting argument
+$ nomad alloc exec eb17e557 /bin/sh -c 'echo $NOMAD_ALLOC_ID'
+eb17e557-443e-4c51-c049-5bba7a9850bc
+
+$ # by using heredoc and passing command in stdin
+$ nomad alloc exec eb17e557 /bin/sh <<'EOF'
+> echo $NOMAD_ALLOC_ID
+> EOF
+eb17e557-443e-4c51-c049-5bba7a9850bc
+```
+
+This technique applies when aiming to run a shell pipeline without streaming
+intermediate command output across the network:
+
+```
+$ # e.g. find top appearing lines in some output
+$ nomad alloc exec eb17e557 /bin/sh -c 'cat /output | sort | uniq -c | sort -rn | head -n 5'
+```
+
+[heredoc]: http://tldp.org/LDP/abs/html/here-docs.html
+
 ## Using Job ID instead of Allocation ID
 
 Setting the `-job` flag causes a random allocation of the specified job to be