Change `job init` default to example`.nomad.hcl` and recommend in docs (#15997)

recommend .nomad.hcl for job files instead of .nomad (without .hcl)
* nomad job init -> example.nomad.hcl
* update docs

.changelog/15997.txt

@@ -0,0 +1,3 @@
+```release-note:improvement
+cli: we now recommend .nomad.hcl extension for job files, so `job init` creates example.nomad.hcl
+```

.gitignore

@@ -61,6 +61,7 @@ go.work.sum
 
 # init outputs
 example.nomad
+example.nomad.hcl
 spec.hcl
 volume.hcl
 nomad_linux_amd64

command/integration_test.go

@@ -27,11 +27,11 @@ func TestIntegration_Command_NomadInit(t *testing.T) {
 	}
 
 	{
-		cmd := exec.Command("nomad", "job", "validate", "example.nomad")
+		cmd := exec.Command("nomad", "job", "validate", "example.nomad.hcl")
 		cmd.Dir = tmpDir
 		cmd.Env = []string{`NOMAD_ADDR=http://127.0.0.1:0`}
 		if err := cmd.Run(); err != nil {
-			t.Fatalf("error validating example.nomad: %v", err)
+			t.Fatalf("error validating example.nomad.hcl: %v", err)
 		}
 	}
 }
@@ -54,12 +54,12 @@ func TestIntegration_Command_RoundTripJob(t *testing.T) {
 	}
 
 	{
-		cmd := exec.Command("nomad", "job", "run", "example.nomad")
+		cmd := exec.Command("nomad", "job", "run", "example.nomad.hcl")
 		cmd.Dir = tmpDir
 		cmd.Env = []string{fmt.Sprintf("NOMAD_ADDR=%s", url)}
 		err := cmd.Run()
 		if err != nil && !strings.Contains(err.Error(), "exit status 2") {
-			t.Fatalf("error running example.nomad: %v", err)
+			t.Fatalf("error running example.nomad.hcl: %v", err)
 		}
 	}
 

command/job_init.go

@@ -13,7 +13,7 @@ import (
 const (
 	// DefaultInitName is the default name we use when
 	// initializing the example file
-	DefaultInitName = "example.nomad"
+	DefaultInitName = "example.nomad.hcl"
 )
 
 // JobInitCommand generates a new job template that you can customize to your
@@ -28,7 +28,7 @@ Usage: nomad job init <filename>
 Alias: nomad init <filename>
 
   Creates an example job file that can be used as a starting point to customize
-  further. If no filename is given, the default of "example.nomad" will be used.
+  further. If no filename is given, the default of "example.nomad.hcl" will be used.
 
 Init Options:
 
@@ -170,13 +170,13 @@ func (c *JobInitCommand) Run(args []string) int {
 	} else {
 		switch {
 		case connect && !short:
-			jobSpec, err = Asset("command/assets/connect.nomad")
+			jobSpec, err = Asset("command/assets/connect.nomad.hcl")
 		case connect && short:
-			jobSpec, err = Asset("command/assets/connect-short.nomad")
+			jobSpec, err = Asset("command/assets/connect-short.nomad.hcl")
 		case !connect && short:
-			jobSpec, err = Asset("command/assets/example-short.nomad")
+			jobSpec, err = Asset("command/assets/example-short.nomad.hcl")
 		default:
-			jobSpec, err = Asset("command/assets/example.nomad")
+			jobSpec, err = Asset("command/assets/example.nomad.hcl")
 		}
 		if err != nil {
 			// should never see this because we've precompiled the assets

command/job_init_test.go

@@ -53,7 +53,7 @@ func TestInitCommand_Run(t *testing.T) {
 	if err != nil {
 		t.Fatalf("err: %s", err)
 	}
-	defaultJob, _ := Asset("command/assets/example.nomad")
+	defaultJob, _ := Asset("command/assets/example.nomad.hcl")
 	if string(content) != string(defaultJob) {
 		t.Fatalf("unexpected file content\n\n%s", string(content))
 	}
@@ -65,7 +65,7 @@ func TestInitCommand_Run(t *testing.T) {
 	}
 	content, err = ioutil.ReadFile(DefaultInitName)
 	require.NoError(t, err)
-	shortJob, _ := Asset("command/assets/example-short.nomad")
+	shortJob, _ := Asset("command/assets/example-short.nomad.hcl")
 	require.Equal(t, string(content), string(shortJob))
 
 	// Fails if the file exists
@@ -82,7 +82,7 @@ func TestInitCommand_defaultJob(t *testing.T) {
 	// Ensure the job file is always written with spaces instead of tabs. Since
 	// the default job file is embedded in the go file, it's easy for tabs to
 	// slip in.
-	defaultJob, _ := Asset("command/assets/example.nomad")
+	defaultJob, _ := Asset("command/assets/example.nomad.hcl")
 	if strings.Contains(string(defaultJob), "\t") {
 		t.Error("default job contains tab character - please convert to spaces")
 	}
@@ -162,7 +162,7 @@ func TestInitCommand_fromJobTemplate(t *testing.T) {
 	must.Eq(t, string(content), string(tinyJob))
 
 	ui.ErrorWriter.Reset()
-	expectedOutput := "Initializing a job template from valid-template\nExample job file written to example.nomad\n"
+	expectedOutput := "Initializing a job template from valid-template\nExample job file written to example.nomad.hcl\n"
 	must.StrContains(t, ui.OutputWriter.String(), expectedOutput)
 }
 
@@ -193,7 +193,7 @@ func TestInitCommand_customFilename(t *testing.T) {
 	if err != nil {
 		t.Fatalf("err: %s", err)
 	}
-	defaultJob, _ := Asset("command/assets/example.nomad")
+	defaultJob, _ := Asset("command/assets/example.nomad.hcl")
 	if string(content) != string(defaultJob) {
 		t.Fatalf("unexpected file content\n\n%s", string(content))
 	}
@@ -205,7 +205,7 @@ func TestInitCommand_customFilename(t *testing.T) {
 	}
 	content, err = ioutil.ReadFile(filename)
 	require.NoError(t, err)
-	shortJob, _ := Asset("command/assets/example-short.nomad")
+	shortJob, _ := Asset("command/assets/example-short.nomad.hcl")
 	require.Equal(t, string(content), string(shortJob))
 
 	// Fails if the file exists

command/job_plan_test.go

@@ -125,7 +125,7 @@ func TestPlanCommand_hcl1_hcl2_strict(t *testing.T) {
 		got := cmd.Run([]string{
 			"-hcl1", "-hcl2-strict",
 			"-address", addr,
-			"assets/example-short.nomad",
+			"assets/example-short.nomad.hcl",
 		})
 		// Exit code 1 here means that an alloc will be created, which is
 		// expected.

command/job_run_test.go

@@ -66,7 +66,7 @@ func TestRunCommand_hcl1_hcl2_strict(t *testing.T) {
 			"-hcl1", "-hcl2-strict",
 			"-address", addr,
 			"-detach",
-			"assets/example-short.nomad",
+			"assets/example-short.nomad.hcl",
 		})
 		require.Equal(t, 0, got, ui.ErrorWriter.String())
 	})
@@ -258,7 +258,7 @@ func TestRunCommand_JSON(t *testing.T) {
 	}()
 
 	// First convert HCL -> JSON with -output
-	stdout, stderr, code := run("-output", "assets/example-short.nomad")
+	stdout, stderr, code := run("-output", "assets/example-short.nomad.hcl")
 	require.Zero(t, code, stderr)
 	require.Empty(t, stderr)
 	require.NotEmpty(t, stdout)

command/job_validate_test.go

@@ -79,7 +79,7 @@ func TestValidateCommand_hcl1_hcl2_strict(t *testing.T) {
 		got := cmd.Run([]string{
 			"-hcl1", "-hcl2-strict",
 			"-address", addr,
-			"assets/example-short.nomad",
+			"assets/example-short.nomad.hcl",
 		})
 		require.Equal(t, 0, got, ui.ErrorWriter.String())
 	})

website/content/api-docs/jobs.mdx

@@ -250,7 +250,7 @@ You can use a tool such as [`jq`](https://stedolan.github.io/jq/) to generate
 the payload from a local HCL file:
 
 ```shell-session
-$ jq -Rsc '{ JobHCL: ., Canonicalize: true }' example.nomad > payload.json
+$ jq -Rsc '{ JobHCL: ., Canonicalize: true }' example.nomad.hcl > payload.json
 ```
 
 ### Sample Request

website/content/api-docs/json-jobs.mdx

@@ -45,8 +45,8 @@ reproduce it:
 
 ```shell-session
 $ nomad init
-Example job file written to example.nomad
-$ nomad job run -output example.nomad
+Example job file written to example.nomad.hcl
+$ nomad job run -output example.nomad.hcl
 ```
 
 ```json

website/content/api-docs/validate.mdx

@@ -46,7 +46,7 @@ There are no parameters, but the request _body_ contains the entire job file.
 ```shell-session
 $ curl \
     --request POST \
-    --data @my-job.nomad \
+    --data @my-job.nomad.json \
     https://localhost:4646/v1/validate/job
 ```
 

website/content/docs/commands/job/init.mdx

@@ -20,7 +20,7 @@ nomad job init [options] [filename]
 ```
 
 You may optionally supply a filename for the example job to be written to. The
-default filename for the generated file is "example.nomad".
+default filename for the generated file is "example.nomad.hcl".
 
 Please refer to the [jobspec] and [drivers] pages to learn how to customize the
 template.
@@ -38,7 +38,7 @@ Generate an example job file:
 
 ```shell-session
 $ nomad job init
-Example job file written to example.nomad
+Example job file written to example.nomad.hcl
 ```
 
 [jobspec]: /nomad/docs/job-specification 'Nomad Job Specification'

website/content/docs/commands/job/plan.mdx

@@ -103,8 +103,7 @@ capability for the job's namespace.
 Plan a new job that has not been previously submitted:
 
 ```shell-session
-$ nomad job plan job1.nomad
-nomad job plan example.nomad
+$ nomad job plan example.nomad.hcl
 + Job: "example"
 + Task Group: "cache" (1 create)
   + Task: "redis" (forces create)
@@ -115,7 +114,7 @@ Scheduler dry-run:
 Job Modify Index: 0
 To submit the job with version verification run:
 
-nomad job run -check-index 0 example.nomad
+nomad job run -check-index 0 example.nomad.hcl
 
 When running the job with the check-index flag, the job will only be run if the
 job modify index given matches the server-side version. If the index has
@@ -126,7 +125,7 @@ potentially invalid.
 Increase the count of an existing without sufficient cluster capacity:
 
 ```shell-session
-$ nomad job plan example.nomad
+$ nomad job plan example.nomad.hcl
 +/- Job: "example"
 +/- Task Group: "cache" (7 create, 1 in-place update)
   +/- Count: "1" => "8" (forces create)
@@ -141,7 +140,7 @@ Scheduler dry-run:
 Job Modify Index: 15
 To submit the job with version verification run:
 
-nomad job run -check-index 15 example.nomad
+nomad job run -check-index 15 example.nomad.hcl
 
 When running the job with the check-index flag, the job will only be run if the
 job modify index given matches the server-side version. If the index has
@@ -152,7 +151,7 @@ potentially invalid.
 Update an existing job such that it would cause a rolling update:
 
 ```shell-session
-$ nomad job plan example.nomad
+$ nomad job plan example.nomad.hcl
 +/- Job: "example"
 +/- Task Group: "cache" (3 create/destroy update)
   +/- Task: "redis" (forces create/destroy update)
@@ -168,7 +167,7 @@ Scheduler dry-run:
 Job Modify Index: 7
 To submit the job with version verification run:
 
-nomad job run -check-index 7 example.nomad
+nomad job run -check-index 7 example.nomad.hcl
 
 When running the job with the check-index flag, the job will only be run if the
 job modify index given matches the server-side version. If the index has
@@ -179,7 +178,7 @@ potentially invalid.
 Add a task to the task group using verbose mode:
 
 ```shell-session
-$ nomad job plan -verbose example.nomad
+$ nomad job plan -verbose example.nomad.hcl
 +/- Job: "example"
 +/- Task Group: "cache" (3 create/destroy update)
   + Task: "my-website" (forces create/destroy update)
@@ -226,7 +225,7 @@ Scheduler dry-run:
 Job Modify Index: 7
 To submit the job with version verification run:
 
-nomad job run -check-index 7 example.nomad
+nomad job run -check-index 7 example.nomad.hcl
 
 When running the job with the check-index flag, the job will only be run if the
 job modify index given matches the server-side version. If the index has
@@ -245,7 +244,7 @@ file. For example, in Linux environments the [`tee`] command can be used for
 this purpose:
 
 ```console
-$ nomad job plan -no-color example.nomad | tee /dev/stderr | grep 'Job Modify Index:' | awk -F': ' '{ print $2 }' > check-index || true
+$ nomad job plan -no-color example.nomad.hcl | tee /dev/stderr | grep 'Job Modify Index:' | awk -F': ' '{ print $2 }' > check-index || true
 ```
 
 The [`-no-color`](#no-color) flag prevents style characters from impacting

website/content/docs/commands/job/run.mdx

@@ -128,10 +128,10 @@ that volume.
 
 ## Examples
 
-Schedule the job contained in the file `job1.nomad`, monitoring placement and deployment:
+Schedule the job contained in the file `example.nomad.hcl`, monitoring placement and deployment:
 
 ```shell-session
-$ nomad job run job1.nomad
+$ nomad job run example.nomad.hcl
 ==> 2021-06-09T15:22:58-07:00: Monitoring evaluation "52dee78a"
     2021-06-09T15:22:58-07:00: Evaluation triggered by job "example"
     2021-06-09T15:22:58-07:00: Allocation "5e0b39f0" created: node "3e84d3d2", group "group1"
@@ -159,11 +159,11 @@ $ nomad job run job1.nomad
 <a id="check-index"></a> Update the job using `check-index`:
 
 ```shell-session
-$ nomad job run -check-index 5 example.nomad
+$ nomad job run -check-index 5 example.nomad.hcl
 Enforcing job modify index 5: job exists with conflicting job modify index: 6
 Job not updated
 
-$ nomad job run -check-index 6 example.nomad
+$ nomad job run -check-index 6 example.nomad.hcl
 ==> 2021-06-09T16:57:29-07:00: Monitoring evaluation "5ef16dff"
     2021-06-09T16:57:29-07:00: Evaluation triggered by job "example"
     2021-06-09T16:57:29-07:00: Allocation "6ec7d16f" modified: node "6e1f9bf6", group "cache"
@@ -186,10 +186,10 @@ $ nomad job run -check-index 6 example.nomad
     cache       1        1       1        0          2021-06-09T17:07:00-07:00
 ```
 
-Schedule the job contained in `job1.nomad` and return immediately:
+Schedule the job contained in `example.nomad.hcl` and return immediately:
 
 ```shell-session
-$ nomad job run -detach job1.nomad
+$ nomad job run -detach example.nomad.hcl
 Job registration successful
 Evaluation ID: e18819c1-b83d-dc17-5e7b-b6f264990283
 ```
@@ -198,7 +198,7 @@ Schedule a job which cannot be successfully placed. This results in a scheduling
 failure and the specifics of the placement are printed:
 
 ```shell-session
-$ nomad job run failing.nomad
+$ nomad job run failing.nomad.hcl
 ==> 2021-06-09T16:49:00-07:00: Monitoring evaluation "2ae0e6a5"
     2021-06-09T16:49:00-07:00: Evaluation triggered by job "example"
 ==> 2021-06-09T16:49:01-07:00: Monitoring evaluation "2ae0e6a5"
@@ -227,7 +227,7 @@ $ nomad job run failing.nomad
 Sample output when scheduling a system job, which doesn't create a deployment:
 
 ```shell-session
-$ nomad job run example.nomad
+$ nomad job run example.nomad.hcl
 ==> 2021-06-14T09:25:08-07:00: Monitoring evaluation "88a91284"
     2021-06-14T09:25:08-07:00: Evaluation triggered by job "example"
     2021-06-14T09:25:08-07:00: Allocation "03501797" created: node "7849439f", group "cache"

website/content/docs/commands/job/validate.mdx

@@ -85,7 +85,7 @@ Job validation errors:
 Validate a job that has a configuration that causes warnings:
 
 ```shell-session
-$ nomad job validate example.nomad
+$ nomad job validate example.nomad.hcl
 Job Warnings:
 1 warning(s):
 

website/content/docs/concepts/scheduling/preemption.mdx

@@ -68,7 +68,7 @@ preemption is necessary to place the job, it shows additional information in the
 `nomad plan` as seen below.
 
 ```shell-session
-$ nomad plan example.nomad
+$ nomad plan example.nomad.hcl
 
 + Job: "test"
 + Task Group: "test" (1 create)

website/content/docs/integrations/consul-connect.mdx

@@ -181,8 +181,8 @@ net.bridge.bridge-nf-call-iptables = 1
 ## Run the Service Mesh-enabled Services
 
 Once Nomad and Consul are running, submit the following service mesh-enabled services
-to Nomad by copying the HCL into a file named `servicemesh.nomad` and running:
-`nomad job run servicemesh.nomad`
+to Nomad by copying the HCL into a file named `servicemesh.nomad.hcl` and running:
+`nomad job run servicemesh.nomad.hcl`
 
 ```hcl
 job "countdash" {

website/content/docs/job-specification/hcl2/index.mdx

@@ -44,7 +44,7 @@ $ # Generate an HCL formatted job
 $ nomad init
 
 $ # Convert HCL to API JSON format
-$ nomad job run -output example.nomad > example.json
+$ nomad job run -output example.nomad.hcl > example.json
 
 $ # Submit with the -json flag
 $ nomad job run -json example.json

website/content/docs/job-specification/hcl2/variables.mdx

@@ -199,7 +199,7 @@ To specify individual variables on the command line, use the `-var` option when
 running the `nomad job run` command:
 
 ```shell-session
-$ nomad job run -var="image_id=nginx:1.19" example.nomad
+$ nomad job run -var="image_id=nginx:1.19" example.nomad.hcl
 ```
 
 The `-var` option can be used any number of times in a single command.
@@ -216,7 +216,7 @@ _variable definitions file_ and then specify that file on the command line with
 `-var-file`:
 
 ```shell-session
-$ nomad job run -var-file="testing.vars" example.nomad
+$ nomad job run -var-file="testing.vars" example.nomad.hcl
 ```
 
 A variable definitions file uses the same HCL basic syntax, but consists only
@@ -252,7 +252,7 @@ at a `bash` prompt on a Unix system:
 
 ```shell-session
 $ export NOMAD_VAR_image_id=nginx:1.19
-$ nomad job run example.nomad
+$ nomad job run example.nomad.hcl
 ...
 ```
 

website/content/docs/job-specification/job.mdx

@@ -239,7 +239,7 @@ job "docs" {
 When submitting this job, you would run:
 
 ```shell-session
-$ VAULT_TOKEN="..." nomad job run example.nomad
+$ VAULT_TOKEN="..." nomad job run example.nomad.hcl
 ```
 
 [affinity]: /nomad/docs/job-specification/affinity 'Nomad affinity Job Specification'

website/content/plugins/devices/nvidia.mdx

@@ -229,7 +229,7 @@ job "gpu-test" {
 ```
 
 ```shell-session
-$ nomad run example.nomad
+$ nomad run example.nomad.hcl
 ==> Monitoring evaluation "21bd7584"
     Evaluation triggered by job "gpu-test"
     Allocation "d250baed" created: node "4d46e59f", group "smi"