builtin/nomad-jobspec: better docs

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,13 +227,35 @@ deploy {
 `)
 
  doc.Example(`
+// The waypoint.hcl file
 deploy {
  use "nomad-jobspec" {
  // Templated to perhaps bring in the artifact from a previous
  // build/registry, entrypoint env vars, etc.
  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(