jobspec: add deprecation warnings for removal of HCLv1

In Nomad 1.9.0 we're removing support for HCLv1. This has been long deprecated,
but this changeset adds warnings to the command line and package documentation
to make it that much more obvious.

Ref: #23912
Ref: #20195

.changelog/23913.txt

@@ -0,0 +1,7 @@
+```release-note:deprecation
+api: the JobParseRequest.HCLv1 field will be removed in Nomad 1.9.0
+```
+
+```release-note:deprecation
+jobspec: using the -hcl1 flag for HCLv1 job specifications will now emit a warning at the command line. This feature will be removed in Nomad 1.9.0
+```

api/jobs.go

@@ -75,7 +75,10 @@ type JobsParseRequest struct {
 	// JobHCL is an hcl jobspec
 	JobHCL string
 
-	// HCLv1 indicates whether the JobHCL should be parsed with the hcl v1 parser
+	// HCLv1 indicates whether the JobHCL should be parsed with the hcl v1
+	// parser.
+	//
+	// DEPRECATION: Will be removed in Nomad 1.9.0
 	HCLv1 bool `json:"hclv1,omitempty"`
 
 	// Variables are HCL2 variables associated with the job. Only works with hcl2.

command/job_plan.go

@@ -91,6 +91,7 @@ Plan Options:
 
   -hcl1
     Parses the job file as HCLv1. Takes precedence over "-hcl2-strict".
+    HCLv1 is deprecated and will be removed in Nomad 1.9.0.
 
   -hcl2-strict
     Whether an error should be produced from the HCL2 parser where a variable
@@ -187,6 +188,7 @@ func (c *JobPlanCommand) Run(args []string) int {
 	}
 
 	if c.JobGetter.HCL1 {
+		c.Ui.Warn("HCLv1 is deprecated and will be removed in Nomad 1.9.0")
 		c.JobGetter.Strict = false
 	}
 

command/job_run.go

@@ -99,6 +99,7 @@ Run Options:
 
   -hcl1
     Parses the job file as HCLv1. Takes precedence over "-hcl2-strict".
+    HCLv1 is deprecated and will be removed in Nomad 1.9.0.
 
   -hcl2-strict
     Whether an error should be produced from the HCL2 parser where a variable
@@ -236,6 +237,7 @@ func (c *JobRunCommand) Run(args []string) int {
 	}
 
 	if c.JobGetter.HCL1 {
+		c.Ui.Warn("HCLv1 is deprecated and will be removed in Nomad 1.9.0")
 		c.JobGetter.Strict = false
 	}
 

command/job_validate.go

@@ -53,6 +53,7 @@ Validate Options:
 
   -hcl1
     Parses the job file as HCLv1. Takes precedence over "-hcl2-strict".
+    HCLv1 is deprecated and will be removed in Nomad 1.9.0.
 
   -hcl2-strict
     Whether an error should be produced from the HCL2 parser where a variable
@@ -135,6 +136,7 @@ func (c *JobValidateCommand) Run(args []string) int {
 	}
 
 	if c.JobGetter.HCL1 {
+		c.Ui.Warn("HCLv1 is deprecated and will be removed in Nomad 1.9.0")
 		c.JobGetter.Strict = false
 	}
 

jobspec/parse.go

@@ -26,6 +26,8 @@ var errPortLabel = fmt.Errorf("Port label does not conform to naming requirement
 //
 // Due to current internal limitations, the entire contents of the
 // io.Reader will be copied into memory first before parsing.
+//
+// DEPRECATED: will be removed in Nomad 1.9.0
 func Parse(r io.Reader) (*api.Job, error) {
 	// Copy the reader into an in-memory buffer first since HCL requires it.
 	var buf bytes.Buffer
@@ -69,6 +71,8 @@ func Parse(r io.Reader) (*api.Job, error) {
 }
 
 // ParseFile parses the given path as a job spec.
+//
+// DEPRECATED: will be removed in Nomad 1.9.0
 func ParseFile(path string) (*api.Job, error) {
 	path, err := filepath.Abs(path)
 	if err != nil {

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

@@ -72,7 +72,8 @@ capability for the job's namespace.
   field is used as the job.
 
 - `-hcl1`: If set, HCL1 parser is used for parsing the job spec. Takes
-  precedence over `-hcl2-strict`.
+  precedence over `-hcl2-strict`. HCLv1 is deprecated and will be removed in
+  Nomad 1.9.0.
 
 - `-hcl2-strict`: Whether an error should be produced from the HCL2 parser where
   a variable has been supplied which is not defined within the root variables.

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

@@ -79,7 +79,8 @@ that volume.
   field is used as the job. See [JSON Jobs] for details.
 
 - `-hcl1`: If set, HCL1 parser is used for parsing the job spec. Takes
-  precedence over `-hcl2-strict`.
+  precedence over `-hcl2-strict`. HCLv1 is deprecated and will be removed in
+  Nomad 1.9.0.
 
 - `-hcl2-strict`: Whether an error should be produced from the HCL2 parser where
   a variable has been supplied which is not defined within the root variables.

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

@@ -47,7 +47,8 @@ capability for the job's namespace.
   field is used as the job.
 
 - `-hcl1`: If set, HCL1 parser is used for parsing the job spec. Takes
-  precedence over `-hcl2-strict`.
+  precedence over `-hcl2-strict`. HCLv1 is deprecated and will be removed in
+  Nomad 1.9.0.
 
 - `-hcl2-strict`: Whether an error should be produced from the HCL2 parser where
   a variable has been supplied which is not defined within the root variables.