cli: add -task flag to alloc signal, restart (#10859)

Alloc exec only works when task is passed as a flag and not an arg.
Alloc logs currently accepts either, but alloc signal and restart only
accept task as an arg. This adds -task as a flag to the other alloc
commands to make the cli UX consistent. If task is passed as a flag and
an arg, it ignores the arg.

.changelog/10859.txt

@@ -0,0 +1,3 @@
+```release-note:improvement
+cli: Added a `-task` flag to `alloc restart` and `alloc signal` for consistent UX with `alloc exec` and `alloc logs`
+```

command/alloc_logs.go

@@ -42,7 +42,8 @@ Logs Specific Options:
     Show full information.
 
   -task <task-name>
-    Sets the task to view the logs.
+    Sets the task to view the logs. If task name is given with both an argument 
+	and the '-task' option, preference is given to the '-task' option.
 
   -job <job-id>
     Use a random allocation from the specified job ID.

command/alloc_restart.go

@@ -31,6 +31,10 @@ General Options:
 
 Restart Specific Options:
 
+  -task <task-name>
+	Specify the individual task to restart. If task name is given with both an 
+	argument and the '-task' option, preference is given to the '-task' option.
+
   -verbose
     Show full information.
 `
@@ -41,10 +45,12 @@ func (c *AllocRestartCommand) Name() string { return "alloc restart" }
 
 func (c *AllocRestartCommand) Run(args []string) int {
 	var verbose bool
+	var task string
 
 	flags := c.Meta.FlagSet(c.Name(), FlagSetClient)
 	flags.Usage = func() { c.Ui.Output(c.Help()) }
 	flags.BoolVar(&verbose, "verbose", false, "")
+	flags.StringVar(&task, "task", "", "")
 
 	if err := flags.Parse(args); err != nil {
 		return 1
@@ -107,18 +113,21 @@ func (c *AllocRestartCommand) Run(args []string) int {
 		return 1
 	}
 
-	var taskName string
-	if len(args) == 2 {
-		// Validate Task
-		taskName = args[1]
-		err := validateTaskExistsInAllocation(taskName, alloc)
+	// If -task isn't provided fallback to reading the task name
+	// from args.
+	if task == "" && len(args) >= 2 {
+		task = args[1]
+	}
+
+	if task != "" {
+		err := validateTaskExistsInAllocation(task, alloc)
 		if err != nil {
 			c.Ui.Error(err.Error())
 			return 1
 		}
 	}
 
-	err = client.Allocations().Restart(alloc, taskName, nil)
+	err = client.Allocations().Restart(alloc, task, nil)
 	if err != nil {
 		c.Ui.Error(fmt.Sprintf("Failed to restart allocation:\n\n%s", err.Error()))
 		return 1

command/alloc_signal.go

@@ -34,6 +34,11 @@ Signal Specific Options:
   -s
     Specify the signal that the selected tasks should receive.
 
+  -task <task-name>
+	Specify the individual task that will receive the signal. If task name is given 
+	with both an argument and the '-task' option, preference is given to the '-task' 
+	option.
+
   -verbose
     Show full information.
 `
@@ -44,12 +49,13 @@ func (c *AllocSignalCommand) Name() string { return "alloc signal" }
 
 func (c *AllocSignalCommand) Run(args []string) int {
 	var verbose bool
-	var signal string
+	var signal, task string
 
 	flags := c.Meta.FlagSet(c.Name(), FlagSetClient)
 	flags.Usage = func() { c.Ui.Output(c.Help()) }
 	flags.BoolVar(&verbose, "verbose", false, "")
 	flags.StringVar(&signal, "s", "SIGKILL", "")
+	flags.StringVar(&task, "task", "", "")
 
 	if err := flags.Parse(args); err != nil {
 		return 1
@@ -112,18 +118,21 @@ func (c *AllocSignalCommand) Run(args []string) int {
 		return 1
 	}
 
-	var taskName string
-	if len(args) == 2 {
-		// Validate Task
-		taskName = args[1]
-		err := validateTaskExistsInAllocation(taskName, alloc)
+	// If -task isn't provided fallback to reading the task name
+	// from args.
+	if task == "" && len(args) >= 2 {
+		task = args[1]
+	}
+
+	if task != "" {
+		err := validateTaskExistsInAllocation(task, alloc)
 		if err != nil {
 			c.Ui.Error(err.Error())
 			return 1
 		}
 	}
 
-	err = client.Allocations().Signal(alloc, nil, taskName, signal)
+	err = client.Allocations().Signal(alloc, nil, task, signal)
 	if err != nil {
 		c.Ui.Error(fmt.Sprintf("Error signalling allocation: %s", err))
 		return 1

website/content/docs/commands/alloc/logs.mdx

@@ -22,6 +22,10 @@ allocation is only running a single task, the task name can be omitted.
 Optionally, the `-job` option may be used in which case a random allocation from
 the given job will be chosen.
 
+Task name may also be specified using the `-task`  option rather than a command 
+argument. If task name is given with both an argument and the `-task` option, 
+preference is given to the `-task` option.
+
 When ACLs are enabled, this command requires a token with the `read-logs`,
 `read-job`, and `list-jobs` capabilities for the allocation's namespace.
 
@@ -38,6 +42,8 @@ When ACLs are enabled, this command requires a token with the `read-logs`,
 - `-job`: Use a random allocation from the specified job, preferring a running
   allocation.
 
+- `-task`: Specify the task to view the logs.
+
 - `-f`: Causes the output to not stop when the end of the logs are reached, but
   rather to wait for additional output.
 
@@ -81,6 +87,19 @@ bam
 <blocking>
 ```
 
+Specifying task name with the `-task` option:
+
+```shell-session
+$ nomad alloc logs -task redis eb17e557
+```
+
+If task name is specified using both options, the command argument is ignored.
+The following will output the logs from the "redis" task only, not the "api" task:
+
+```shell-session
+$ nomad alloc logs -task redis eb17e557 api
+```
+
 ## Using Job ID instead of Allocation ID
 
 Setting the `-job` flag causes a random allocation of the specified job to be

website/content/docs/commands/alloc/restart.mdx

@@ -20,6 +20,10 @@ This command accepts a single allocation ID and a task name. The task name must
 be part of the allocation and the task must be currently running. The task name
 is optional and if omitted every task in the allocation will be restarted.
 
+Task name may also be specified using the `-task` option rather than a command 
+argument. If task name is given with both an argument and the `-task` option, 
+preference is given to the `-task` option.
+
 When ACLs are enabled, this command requires a token with the
 `alloc-lifecycle`, `read-job`, and `list-jobs` capabilities for the
 allocation's namespace.
@@ -30,6 +34,8 @@ allocation's namespace.
 
 ## Restart Options
 
+- `-task`: Specify the individual task to restart.
+
 - `-verbose`: Display verbose output.
 
 ## Examples
@@ -42,3 +48,16 @@ Could not find task named: foo, found:
 * test
 <blocking>
 ```
+
+Specifying task name with the `-task` option:
+
+```shell-session
+$ nomad alloc restart -task redis eb17e557
+```
+
+If task name is specified using both options, the command argument is ignored.
+The following will restart the "redis" task only, not the "api" task:
+
+```shell-session
+$ nomad alloc restart -task redis eb17e557 api
+```

website/content/docs/commands/alloc/signal.mdx

@@ -20,6 +20,10 @@ This command accepts a single allocation ID and a task name. The task name must
 be part of the allocation and the task must be currently running. The task name
 is optional and if omitted every task in the allocation will be signaled.
 
+Task name may also be specified using the `-task`  option rather than a command 
+argument. If task name is given with both an argument and the `-task` option, 
+preference is given to the `-task` option.
+
 When ACLs are enabled, this command requires a token with the
 `alloc-lifecycle`, `read-job`, and `list-jobs` capabilities for the
 allocation's namespace.
@@ -31,6 +35,9 @@ allocation's namespace.
 ## Signal Options
 
 - `-s`: Signal to send to the tasks. Valid options depend on the driver.
+
+- `-task`: Specify the individual task that will receive the signal.
+
 - `-verbose`: Display verbose output.
 
 ## Examples
@@ -38,8 +45,21 @@ allocation's namespace.
 ```shell-session
 $ nomad alloc signal eb17e557
 
-$ nomad alloc signal eb17e557 foo
-Could not find task named: foo, found:
+$ nomad alloc signal eb17e557 redis
+Could not find task named: redis, found:
 * test
 <blocking>
 ```
+
+Specifying task name with the `-task` option:
+
+```shell-session
+$ nomad alloc signal -task redis eb17e557
+```
+
+If task name is specified using both options, the command argument is ignored.
+The following will signal the "redis" task only, not the "api" task:
+
+```shell-session
+$ nomad alloc signal -task redis eb17e557 api
+```