jobspec: fixup vault_grace deprecation

Followup to #7170

- Moved canonicalization of VaultGrace back into `api/` package.
- Fixed tests.
- Made docs styling consistent.

api/jobs_test.go

@@ -531,6 +531,7 @@ func TestJobs_Canonicalize(t *testing.T) {
 										LeftDelim:    stringToPtr("{{"),
 										RightDelim:   stringToPtr("}}"),
 										Envvars:      boolToPtr(false),
+										VaultGrace:   timeToPtr(0),
 									},
 									{
 										SourcePath:   stringToPtr(""),
@@ -543,6 +544,7 @@ func TestJobs_Canonicalize(t *testing.T) {
 										LeftDelim:    stringToPtr("{{"),
 										RightDelim:   stringToPtr("}}"),
 										Envvars:      boolToPtr(true),
+										VaultGrace:   timeToPtr(0),
 									},
 								},
 							},

api/tasks.go

@@ -750,6 +750,11 @@ func (tmpl *Template) Canonicalize() {
 	if tmpl.Envvars == nil {
 		tmpl.Envvars = boolToPtr(false)
 	}
+
+	//COMPAT(0.12) VaultGrace is deprecated and unused as of Vault 0.5
+	if tmpl.VaultGrace == nil {
+		tmpl.VaultGrace = timeToPtr(0)
+	}
 }
 
 type Vault struct {

jobspec/parse_task.go

@@ -374,7 +374,6 @@ func parseTemplates(result *[]*api.Template, list *ast.ObjectList) error {
 			ChangeMode: helper.StringToPtr("restart"),
 			Splay:      helper.TimeToPtr(5 * time.Second),
 			Perms:      helper.StringToPtr("0644"),
-			VaultGrace: helper.TimeToPtr(0),
 		}
 
 		dec, err := mapstructure.NewDecoder(&mapstructure.DecoderConfig{

jobspec/parse_test.go

@@ -320,6 +320,7 @@ func TestParse(t *testing.T) {
 										Splay:        helper.TimeToPtr(10 * time.Second),
 										Perms:        helper.StringToPtr("0644"),
 										Envvars:      helper.BoolToPtr(true),
+										VaultGrace:   helper.TimeToPtr(33 * time.Second),
 									},
 									{
 										SourcePath: helper.StringToPtr("bar"),

nomad/structs/diff_test.go

@@ -5756,6 +5756,12 @@ func TestTaskDiff(t *testing.T) {
 								Old:  "",
 								New:  "3",
 							},
+							{
+								Type: DiffTypeAdded,
+								Name: "VaultGrace",
+								Old:  "",
+								New:  "0",
+							},
 						},
 					},
 					{
@@ -5810,6 +5816,12 @@ func TestTaskDiff(t *testing.T) {
 								Old:  "2",
 								New:  "",
 							},
+							{
+								Type: DiffTypeDeleted,
+								Name: "VaultGrace",
+								Old:  "0",
+								New:  "",
+							},
 						},
 					},
 				},

nomad/structs/structs.go

@@ -5839,17 +5839,6 @@ func (t *Task) Warnings() error {
 	return mErr.ErrorOrNil()
 }
 
-func (t *Template) Warnings() error {
-	var mErr multierror.Error
-
-	// Deprecation notice for vault_grace
-	if t.VaultGrace > 0 {
-		mErr.Errors = append(mErr.Errors, fmt.Errorf("VaultGrace has been deprecated as of Nomad 0.11 and ignored since Vault 0.5. Please remove VaultGrace / vault_grace from template stanza."))
-	}
-
-	return mErr.ErrorOrNil()
-}
-
 // TaskKind identifies the special kinds of tasks using the following format:
 // '<kind_name>(:<identifier>)`. The TaskKind can optionally include an identifier that
 // is opaque to the Task. This identifier can be used to relate the task to some
@@ -6060,6 +6049,17 @@ func (t *Template) Validate() error {
 	return mErr.ErrorOrNil()
 }
 
+func (t *Template) Warnings() error {
+	var mErr multierror.Error
+
+	// Deprecation notice for vault_grace
+	if t.VaultGrace != 0 {
+		mErr.Errors = append(mErr.Errors, fmt.Errorf("VaultGrace has been deprecated as of Nomad 0.11 and ignored since Vault 0.5. Please remove VaultGrace / vault_grace from template stanza."))
+	}
+
+	return mErr.ErrorOrNil()
+}
+
 // Set of possible states for a task.
 const (
 	TaskStatePending = "pending" // The task is waiting to be run.

nomad/structs/structs_test.go

@@ -163,6 +163,26 @@ func TestJob_Warnings(t *testing.T) {
 				},
 			},
 		},
+		{
+			Name:     "Template.VaultGrace Deprecated",
+			Expected: []string{"VaultGrace has been deprecated as of Nomad 0.11 and ignored since Vault 0.5. Please remove VaultGrace / vault_grace from template stanza."},
+			Job: &Job{
+				Type: JobTypeService,
+				TaskGroups: []*TaskGroup{
+					{
+						Tasks: []*Task{
+							{
+								Templates: []*Template{
+									{
+										VaultGrace: 1,
+									},
+								},
+							},
+						},
+					},
+				},
+			},
+		},
 	}
 
 	for _, c := range cases {

website/pages/guides/upgrade/upgrade-specific.mdx

@@ -19,11 +19,12 @@ standard upgrade flow.
 
 ### client.template: `vault_grace` deprecation
 
-Nomad 0.11.0 includes an update to [consul-template](https://github.com/hashicorp/consul-template) v0.24.1.
-This library deprecates the `vault_grace` option for templating included in nomad.
-The feature has been ignored since vault 0.5 and as long as you are running
-a more recent version of vault, you can safely remove vault_grace from your
-nomad jobs.
+Nomad 0.11.0 updates
+[consul-template](https://github.com/hashicorp/consul-template) to v0.24.1.
+This library deprecates the [`vault_grace`][vault_grace] option for templating
+included in Nomad. The feature has been ignored since Vault 0.5 and as long as
+you are running a more recent version of Vault, you can safely remove
+`vault_grace` from your Nomad jobs.
 
 ## Nomad 0.10.4
 
@@ -470,6 +471,7 @@ deleted and then Nomad 0.3.0 can be launched.
 [preemption-api]: /api/operator#update-scheduler-configuration
 [task-config]: /docs/job-specification/task#config
 [validate]: /docs/commands/job/validate
+[vault_grace]: /docs/job-specification/template
 [update]: /docs/job-specification/update
 [tls-guide]: /guides/security/securing-nomad
 [tls-vault-guide]: /guides/security/vault-pki-integration