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
This commit is contained in:
Daniel Bennett 2023-02-02 11:47:47 -06:00 committed by GitHub
parent 971a286ea3
commit dc9c8d4e47
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
26 changed files with 97 additions and 94 deletions

3
.changelog/15997.txt Normal file
View File

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

1
.gitignore vendored
View File

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

View File

@ -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.Dir = tmpDir
cmd.Env = []string{`NOMAD_ADDR=http://127.0.0.1:0`} cmd.Env = []string{`NOMAD_ADDR=http://127.0.0.1:0`}
if err := cmd.Run(); err != nil { 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.Dir = tmpDir
cmd.Env = []string{fmt.Sprintf("NOMAD_ADDR=%s", url)} cmd.Env = []string{fmt.Sprintf("NOMAD_ADDR=%s", url)}
err := cmd.Run() err := cmd.Run()
if err != nil && !strings.Contains(err.Error(), "exit status 2") { 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)
} }
} }

File diff suppressed because one or more lines are too long

View File

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

View File

@ -53,7 +53,7 @@ func TestInitCommand_Run(t *testing.T) {
if err != nil { if err != nil {
t.Fatalf("err: %s", err) t.Fatalf("err: %s", err)
} }
defaultJob, _ := Asset("command/assets/example.nomad") defaultJob, _ := Asset("command/assets/example.nomad.hcl")
if string(content) != string(defaultJob) { if string(content) != string(defaultJob) {
t.Fatalf("unexpected file content\n\n%s", string(content)) 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) content, err = ioutil.ReadFile(DefaultInitName)
require.NoError(t, err) 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)) require.Equal(t, string(content), string(shortJob))
// Fails if the file exists // 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 // 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 // the default job file is embedded in the go file, it's easy for tabs to
// slip in. // slip in.
defaultJob, _ := Asset("command/assets/example.nomad") defaultJob, _ := Asset("command/assets/example.nomad.hcl")
if strings.Contains(string(defaultJob), "\t") { if strings.Contains(string(defaultJob), "\t") {
t.Error("default job contains tab character - please convert to spaces") 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)) must.Eq(t, string(content), string(tinyJob))
ui.ErrorWriter.Reset() 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) must.StrContains(t, ui.OutputWriter.String(), expectedOutput)
} }
@ -193,7 +193,7 @@ func TestInitCommand_customFilename(t *testing.T) {
if err != nil { if err != nil {
t.Fatalf("err: %s", err) t.Fatalf("err: %s", err)
} }
defaultJob, _ := Asset("command/assets/example.nomad") defaultJob, _ := Asset("command/assets/example.nomad.hcl")
if string(content) != string(defaultJob) { if string(content) != string(defaultJob) {
t.Fatalf("unexpected file content\n\n%s", string(content)) 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) content, err = ioutil.ReadFile(filename)
require.NoError(t, err) 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)) require.Equal(t, string(content), string(shortJob))
// Fails if the file exists // Fails if the file exists

View File

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

View File

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

View File

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

View File

@ -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: the payload from a local HCL file:
```shell-session ```shell-session
$ jq -Rsc '{ JobHCL: ., Canonicalize: true }' example.nomad > payload.json $ jq -Rsc '{ JobHCL: ., Canonicalize: true }' example.nomad.hcl > payload.json
``` ```
### Sample Request ### Sample Request

View File

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

View File

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

View File

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

View File

@ -103,8 +103,7 @@ capability for the job's namespace.
Plan a new job that has not been previously submitted: Plan a new job that has not been previously submitted:
```shell-session ```shell-session
$ nomad job plan job1.nomad $ nomad job plan example.nomad.hcl
nomad job plan example.nomad
+ Job: "example" + Job: "example"
+ Task Group: "cache" (1 create) + Task Group: "cache" (1 create)
+ Task: "redis" (forces create) + Task: "redis" (forces create)
@ -115,7 +114,7 @@ Scheduler dry-run:
Job Modify Index: 0 Job Modify Index: 0
To submit the job with version verification run: 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 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 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: Increase the count of an existing without sufficient cluster capacity:
```shell-session ```shell-session
$ nomad job plan example.nomad $ nomad job plan example.nomad.hcl
+/- Job: "example" +/- Job: "example"
+/- Task Group: "cache" (7 create, 1 in-place update) +/- Task Group: "cache" (7 create, 1 in-place update)
+/- Count: "1" => "8" (forces create) +/- Count: "1" => "8" (forces create)
@ -141,7 +140,7 @@ Scheduler dry-run:
Job Modify Index: 15 Job Modify Index: 15
To submit the job with version verification run: 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 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 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: Update an existing job such that it would cause a rolling update:
```shell-session ```shell-session
$ nomad job plan example.nomad $ nomad job plan example.nomad.hcl
+/- Job: "example" +/- Job: "example"
+/- Task Group: "cache" (3 create/destroy update) +/- Task Group: "cache" (3 create/destroy update)
+/- Task: "redis" (forces create/destroy update) +/- Task: "redis" (forces create/destroy update)
@ -168,7 +167,7 @@ Scheduler dry-run:
Job Modify Index: 7 Job Modify Index: 7
To submit the job with version verification run: 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 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 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: Add a task to the task group using verbose mode:
```shell-session ```shell-session
$ nomad job plan -verbose example.nomad $ nomad job plan -verbose example.nomad.hcl
+/- Job: "example" +/- Job: "example"
+/- Task Group: "cache" (3 create/destroy update) +/- Task Group: "cache" (3 create/destroy update)
+ Task: "my-website" (forces create/destroy update) + Task: "my-website" (forces create/destroy update)
@ -226,7 +225,7 @@ Scheduler dry-run:
Job Modify Index: 7 Job Modify Index: 7
To submit the job with version verification run: 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 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 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: this purpose:
```console ```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 The [`-no-color`](#no-color) flag prevents style characters from impacting

View File

@ -128,10 +128,10 @@ that volume.
## Examples ## 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 ```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: Monitoring evaluation "52dee78a"
2021-06-09T15:22:58-07:00: Evaluation triggered by job "example" 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" 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`: <a id="check-index"></a> Update the job using `check-index`:
```shell-session ```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 Enforcing job modify index 5: job exists with conflicting job modify index: 6
Job not updated 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: Monitoring evaluation "5ef16dff"
2021-06-09T16:57:29-07:00: Evaluation triggered by job "example" 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" 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 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 ```shell-session
$ nomad job run -detach job1.nomad $ nomad job run -detach example.nomad.hcl
Job registration successful Job registration successful
Evaluation ID: e18819c1-b83d-dc17-5e7b-b6f264990283 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: failure and the specifics of the placement are printed:
```shell-session ```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: Monitoring evaluation "2ae0e6a5"
2021-06-09T16:49:00-07:00: Evaluation triggered by job "example" 2021-06-09T16:49:00-07:00: Evaluation triggered by job "example"
==> 2021-06-09T16:49:01-07:00: Monitoring evaluation "2ae0e6a5" ==> 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: Sample output when scheduling a system job, which doesn't create a deployment:
```shell-session ```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: Monitoring evaluation "88a91284"
2021-06-14T09:25:08-07:00: Evaluation triggered by job "example" 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" 2021-06-14T09:25:08-07:00: Allocation "03501797" created: node "7849439f", group "cache"

View File

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

View File

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

View File

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

View File

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

View File

@ -199,7 +199,7 @@ To specify individual variables on the command line, use the `-var` option when
running the `nomad job run` command: running the `nomad job run` command:
```shell-session ```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. 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`: `-var-file`:
```shell-session ```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 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 ```shell-session
$ export NOMAD_VAR_image_id=nginx:1.19 $ export NOMAD_VAR_image_id=nginx:1.19
$ nomad job run example.nomad $ nomad job run example.nomad.hcl
... ...
``` ```

View File

@ -239,7 +239,7 @@ job "docs" {
When submitting this job, you would run: When submitting this job, you would run:
```shell-session ```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' [affinity]: /nomad/docs/job-specification/affinity 'Nomad affinity Job Specification'

View File

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