template: add RunOnFirstRender option to change_script

Add a RunOnFirstRender field to the ChangeScript configuration that
allows template change_script to fire after the initial template
render, not only on subsequent re-renders.

When enabled, the template manager waits for the task to reach
the running state after unblocking, then executes the configured
scripts. This is useful for initialization tasks that need to run
once the first template content is available.

Fixes #27429

Author: VedantMadane

api/tasks.go

@@ -916,10 +916,11 @@ func (wc *WaitConfig) Copy() *WaitConfig {
 }
 
 type ChangeScript struct {
-	Command     *string        `mapstructure:"command" hcl:"command"`
-	Args        []string       `mapstructure:"args" hcl:"args,optional"`
-	Timeout     *time.Duration `mapstructure:"timeout" hcl:"timeout,optional"`
-	FailOnError *bool          `mapstructure:"fail_on_error" hcl:"fail_on_error"`
+	Command          *string        `mapstructure:"command" hcl:"command"`
+	Args             []string       `mapstructure:"args" hcl:"args,optional"`
+	Timeout          *time.Duration `mapstructure:"timeout" hcl:"timeout,optional"`
+	FailOnError      *bool          `mapstructure:"fail_on_error" hcl:"fail_on_error"`
+	RunOnFirstRender *bool          `mapstructure:"run_on_first_render" hcl:"run_on_first_render,optional"`
 }
 
 func (ch *ChangeScript) Canonicalize() {
@@ -935,6 +936,9 @@ func (ch *ChangeScript) Canonicalize() {
 	if ch.FailOnError == nil {
 		ch.FailOnError = pointerOf(false)
 	}
+	if ch.RunOnFirstRender == nil {
+		ch.RunOnFirstRender = pointerOf(false)
+	}
 }
 
 type Template struct {

client/allocrunner/taskrunner/template/template.go

@@ -276,8 +276,16 @@ func (tm *TaskTemplateManager) Run() {
 	// Unblock the task
 	close(tm.config.UnblockCh)
 
+	// Collect any change_script templates that should fire on first render.
+	// These scripts are launched in a goroutine because they need the task
+	// to reach the running state before Exec can succeed.
+	firstRenderScripts := tm.collectFirstRenderScripts()
+	if len(firstRenderScripts) > 0 {
+		go tm.runFirstRenderScripts(firstRenderScripts)
+	}
+
 	// If all our templates are change mode no-op, then we can exit here
-	if tm.allTemplatesNoop() {
+	if tm.allTemplatesNoop() && len(firstRenderScripts) == 0 {
 		return
 	}
 
@@ -646,6 +654,46 @@ func (tm *TaskTemplateManager) allTemplatesNoop() bool {
 	return true
 }
 
+// collectFirstRenderScripts returns the set of ChangeScript objects from
+// templates that have change_mode "script" with RunOnFirstRender enabled.
+func (tm *TaskTemplateManager) collectFirstRenderScripts() []*structs.ChangeScript {
+	var scripts []*structs.ChangeScript
+	for _, tmpl := range tm.config.Templates {
+		if tmpl.ChangeMode == structs.TemplateChangeModeScript &&
+			tmpl.ChangeScript != nil &&
+			tmpl.ChangeScript.RunOnFirstRender {
+			scripts = append(scripts, tmpl.ChangeScript)
+		}
+	}
+	return scripts
+}
+
+// runFirstRenderScripts waits for the task to reach the running state and then
+// executes the given change_scripts. It respects the shutdown channel so it
+// will not block forever if the task is killed before reaching running.
+func (tm *TaskTemplateManager) runFirstRenderScripts(scripts []*structs.ChangeScript) {
+	const pollInterval = 500 * time.Millisecond
+	ticker := time.NewTicker(pollInterval)
+	defer ticker.Stop()
+
+	for {
+		select {
+		case <-tm.shutdownCh:
+			return
+		case <-ticker.C:
+			if tm.config.Lifecycle.IsRunning() {
+				var wg sync.WaitGroup
+				for _, script := range scripts {
+					wg.Add(1)
+					go tm.processScript(script, &wg)
+				}
+				wg.Wait()
+				return
+			}
+		}
+	}
+}
+
 // templateRunner returns a consul-template runner for the given templates and a
 // lookup by destination to the template. If no templates are in the config, a
 // nil template runner and lookup is returned.

command/agent/job_endpoint.go

@@ -1553,10 +1553,11 @@ func apiChangeScriptToStructsChangeScript(changeScript *api.ChangeScript) *struc
 	}
 
 	return &structs.ChangeScript{
-		Command:     *changeScript.Command,
-		Args:        changeScript.Args,
-		Timeout:     *changeScript.Timeout,
-		FailOnError: *changeScript.FailOnError,
+		Command:          *changeScript.Command,
+		Args:             changeScript.Args,
+		Timeout:          *changeScript.Timeout,
+		FailOnError:      *changeScript.FailOnError,
+		RunOnFirstRender: *changeScript.RunOnFirstRender,
 	}
 }
 

command/agent/job_endpoint_test.go

@@ -3097,12 +3097,13 @@ func TestJobs_ApiJobToStructsJob(t *testing.T) {
 								EmbeddedTmpl: pointer.Of("embedded"),
 								ChangeMode:   pointer.Of("change"),
 								ChangeSignal: pointer.Of("signal"),
-								ChangeScript: &api.ChangeScript{
-									Command:     pointer.Of("/bin/foo"),
-									Args:        []string{"-h"},
-									Timeout:     pointer.Of(5 * time.Second),
-									FailOnError: pointer.Of(false),
-								},
+							ChangeScript: &api.ChangeScript{
+								Command:          pointer.Of("/bin/foo"),
+								Args:             []string{"-h"},
+								Timeout:          pointer.Of(5 * time.Second),
+								FailOnError:      pointer.Of(false),
+								RunOnFirstRender: pointer.Of(false),
+							},
 								Splay:      pointer.Of(1 * time.Minute),
 								Perms:      pointer.Of("666"),
 								Uid:        pointer.Of(1000),

jobspec2/parse_job.go

@@ -163,4 +163,7 @@ func normalizeChangeScript(ch *api.ChangeScript) {
 	if ch.FailOnError == nil {
 		ch.FailOnError = pointerOf(false)
 	}
+	if ch.RunOnFirstRender == nil {
+		ch.RunOnFirstRender = pointerOf(false)
+	}
 }

nomad/structs/diff_test.go

@@ -8656,6 +8656,12 @@ func TestTaskDiff(t *testing.T) {
 										Old:  "",
 										New:  "false",
 									},
+									{
+										Type: DiffTypeAdded,
+										Name: "RunOnFirstRender",
+										Old:  "",
+										New:  "false",
+									},
 									{
 										Type: DiffTypeAdded,
 										Name: "Timeout",
@@ -8780,6 +8786,12 @@ func TestTaskDiff(t *testing.T) {
 										Old:  "false",
 										New:  "",
 									},
+									{
+										Type: DiffTypeDeleted,
+										Name: "RunOnFirstRender",
+										Old:  "false",
+										New:  "",
+									},
 									{
 										Type: DiffTypeDeleted,
 										Name: "Timeout",

nomad/structs/structs.go

@@ -8919,6 +8919,10 @@ type ChangeScript struct {
 	// FailOnError indicates whether a task should fail in case script execution
 	// fails or log script failure and don't interrupt the task
 	FailOnError bool
+	// RunOnFirstRender indicates that the script should also be triggered
+	// after the initial template render, not only on subsequent re-renders.
+	// The script will execute once the task reaches the running state.
+	RunOnFirstRender bool
 }
 
 func (cs *ChangeScript) Equal(o *ChangeScript) bool {
@@ -8934,6 +8938,8 @@ func (cs *ChangeScript) Equal(o *ChangeScript) bool {
 		return false
 	case cs.FailOnError != o.FailOnError:
 		return false
+	case cs.RunOnFirstRender != o.RunOnFirstRender:
+		return false
 	}
 	return true
 }
@@ -8943,10 +8949,11 @@ func (cs *ChangeScript) Copy() *ChangeScript {
 		return nil
 	}
 	return &ChangeScript{
-		Command:     cs.Command,
-		Args:        slices.Clone(cs.Args),
-		Timeout:     cs.Timeout,
-		FailOnError: cs.FailOnError,
+		Command:          cs.Command,
+		Args:             slices.Clone(cs.Args),
+		Timeout:          cs.Timeout,
+		FailOnError:      cs.FailOnError,
+		RunOnFirstRender: cs.RunOnFirstRender,
 	}
 }
 

nomad/structs/structs_test.go

@@ -7143,10 +7143,11 @@ func TestChangeScript_Equal(t *testing.T) {
 	must.NotEqual[*ChangeScript](t, nil, new(ChangeScript))
 
 	must.StructEqual(t, &ChangeScript{
-		Command:     "/bin/sleep",
-		Args:        []string{"infinity"},
-		Timeout:     1 * time.Second,
-		FailOnError: true,
+		Command:          "/bin/sleep",
+		Args:             []string{"infinity"},
+		Timeout:          1 * time.Second,
+		FailOnError:      true,
+		RunOnFirstRender: true,
 	}, []must.Tweak[*ChangeScript]{{
 		Field: "Command",
 		Apply: func(c *ChangeScript) { c.Command = "/bin/false" },
@@ -7159,6 +7160,9 @@ func TestChangeScript_Equal(t *testing.T) {
 	}, {
 		Field: "FailOnError",
 		Apply: func(c *ChangeScript) { c.FailOnError = false },
+	}, {
+		Field: "RunOnFirstRender",
+		Apply: func(c *ChangeScript) { c.RunOnFirstRender = false },
 	}})
 }