From bef9c0bdddf50f34b54d5a7ca38ea43633ee890d Mon Sep 17 00:00:00 2001
From: Mitchell Hashimoto <mitchell.hashimoto@gmail.com>
Date: Tue, 6 Apr 2021 08:54:24 -0700
Subject: [PATCH] builtin/nomad-jobspec: better docs

---
 builtin/nomad/jobspec/platform.go | 50 ++++++++++++++++++++++++++++++-
 1 file changed, 49 insertions(+), 1 deletion(-)

diff --git a/builtin/nomad/jobspec/platform.go b/builtin/nomad/jobspec/platform.go
index cd204d7f959..c2b3aec9857 100644
--- a/builtin/nomad/jobspec/platform.go
+++ b/builtin/nomad/jobspec/platform.go
@@ -187,9 +187,35 @@ Deploy to a Nomad cluster from a pre-existing Nomad job specification file.
 
 This plugin lets you use any pre-existing Nomad job specification file to
 deploy to Nomad. This deployment is able to support all the features of Waypoint.
-You may use Waypoint's [templating features](https://www.waypointproject.io/docs/waypoint-hcl/functions/template)
+You may use Waypoint's [templating features](/docs/waypoint-hcl/functions/template)
 to template the Nomad jobspec with information such as the artifact from
 a previous build step, entrypoint environment variables, etc.
+
+### Artifact Access
+
+You may use Waypoint's [templating features](/docs/waypoint-hcl/functions/template)
+to access information such as the artifact from the build or push stages.
+An example below shows this by using ` + "`templatefile`" + ` mixed with
+variables such as ` + "`artifact.image`" + ` to dynamically configure the
+Docker image within the Nomad job specification.
+
+### Entrypoint Functionality
+
+Waypoint [entrypoint functionality](/docs/entrypoint#functionality) such
+as logs, exec, app configuration, and more require two properties to be true:
+
+1. The running image must already have the Waypoint entrypoint installed
+  and configured as the entrypoint. This should happen in the build stage.
+
+2. Proper environment variables must be set so the entrypoint knows how
+  to communicate to the Waypoint server. **This step happens in this
+  deployment stage.**
+
+**Step 2 does not happen automatically.** You must manually set the entrypoint
+environment variables using the [templating feature](/docs/waypoint-hcl/functions/template).
+One of the examples below shows the entrypoint environment variables being
+injected.
+
 `)
 
 	doc.Example(`
@@ -201,6 +227,7 @@ deploy {
 `)
 
 	doc.Example(`
+// The waypoint.hcl file
 deploy {
   use "nomad-jobspec" {
     // Templated to perhaps bring in the artifact from a previous
@@ -208,6 +235,27 @@ deploy {
     jobspec = templatefile("${path.app}/app.nomad.tpl")
   }
 }
+
+// The app.nomad.tpl file
+job "web" {
+  datacenters = ["dc1"]
+
+  group "app" {
+    task "app" {
+      driver = "docker"
+
+      config {
+        image = "${artifact.image}:${artifact.tag}"
+      }
+
+      env {
+        %{ for k,v in entrypoint.env ~}
+        ${k} = "${v}"
+        %{ endfor ~}
+      }
+    }
+  }
+}
 `)
 
 	doc.SetField(