From 305b61631eb2b0c46e3f9157f3bb1745d05fa9e2 Mon Sep 17 00:00:00 2001
From: Mahmood Ali <mahmood@hashicorp.com>
Date: Mon, 22 Jul 2019 18:34:59 +0800
Subject: [PATCH] Clarify script checks requiring shell

Closes https://github.com/hashicorp/nomad/issues/5981
---
 .../docs/job-specification/service.html.md    | 50 ++++++++-----------
 1 file changed, 22 insertions(+), 28 deletions(-)

diff --git a/website/source/docs/job-specification/service.html.md b/website/source/docs/job-specification/service.html.md
index 7ab763538..878f4ea05 100644
--- a/website/source/docs/job-specification/service.html.md
+++ b/website/source/docs/job-specification/service.html.md
@@ -268,45 +268,39 @@ resources {
 }
 ```
 
-### Check with Bash-isms
+### Script Checks with Shells
 
-This example shows a common mistake and correct behavior for custom checks.
-Suppose a health check like this:
-
-```shell
-$ test -f /tmp/file.txt
-```
-
-In this example `test` is not actually a command (binary) on the system; it is a
-built-in shell function to bash. Thus, the following **would not work**:
-
-```hcl
-service {
-  check {
-    type    = "script"
-    command = "test -f /tmp/file.txt" # THIS IS NOT CORRECT
-  }
-}
-```
-
-Nomad will attempt to find an executable named `test` on your system, but it
-does not exist. It is actually just a function of bash. Additionally, it is not
-possible to specify the arguments in a single string. Here is the correct
-solution:
+This example shows a service with a script check that is evaluated and interpolated in a shell; it
+tests whether a file is present at `${HEALTH_CHECK_FILE}` environment variable:
 
 ```hcl
 service {
   check {
     type    = "script"
     command = "/bin/bash"
-    args    = ["-c", "test -f /tmp/file.txt"]
+    args    = ["-c", "test -f ${HEALTH_CHECK_FILE}"]
   }
 }
 ```
 
-The `command` is actually `/bin/bash`, since that is the actual process we are
-running. The arguments to that command are the script itself, which each
-argument provided as a value to the `args` array.
+Using `/bin/bash` (or another shell) is required here to interpolate the `${HEALTH_CHECK_FILE}` value.
+
+The following examples of `command` fields **will not work**:
+
+```hcl
+# invalid because command is not a path
+check {
+  type    = "script"
+  command = "test -f /tmp/file.txt"
+}
+
+# invalid because path will not be interpolated
+check {
+  type    = "script"
+  command = "/bin/test"
+  args    = ["-f", "${HEALTH_CHECK_FILE}"]
+}
+```
 
 ### HTTP Health Check