Merge pull request #2433 from hashicorp/f-distinct-property-misc

Distinct Property Docs and Validation

nomad/structs/structs.go

@@ -2515,6 +2515,12 @@ func (t *Task) Validate(ephemeralDisk *EphemeralDisk) error {
 			outer := fmt.Errorf("Constraint %d validation failed: %s", idx+1, err)
 			mErr.Errors = append(mErr.Errors, outer)
 		}
+
+		switch constr.Operand {
+		case ConstraintDistinctHosts, ConstraintDistinctProperty:
+			outer := fmt.Errorf("Constraint %d has disallowed Operand at task level: %s", idx+1, constr.Operand)
+			mErr.Errors = append(mErr.Errors, outer)
+		}
 	}
 
 	// Validate Services

nomad/structs/structs_test.go

@@ -487,6 +487,24 @@ func TestTask_Validate(t *testing.T) {
 	if err != nil {
 		t.Fatalf("err: %s", err)
 	}
+
+	task.Constraints = append(task.Constraints,
+		&Constraint{
+			Operand: ConstraintDistinctHosts,
+		},
+		&Constraint{
+			Operand: ConstraintDistinctProperty,
+			LTarget: "${meta.rack}",
+		})
+
+	err = task.Validate(ephemeralDisk)
+	mErr = err.(*multierror.Error)
+	if !strings.Contains(mErr.Errors[0].Error(), "task level: distinct_hosts") {
+		t.Fatalf("err: %s", err)
+	}
+	if !strings.Contains(mErr.Errors[1].Error(), "task level: distinct_property") {
+		t.Fatalf("err: %s", err)
+	}
 }
 
 func TestTask_Validate_Services(t *testing.T) {

website/source/docs/http/json-jobs.html.md

@@ -516,13 +516,26 @@ The `Constraint` object supports the following keys:
   * `distinct_host` - If set, the scheduler will not co-locate any task groups on the same
         machine. This can be specified as a job constraint which applies the
         constraint to all task groups in the job, or as a task group constraint which
-        scopes the effect to just that group.
+        scopes the effect to just that group. The constraint may not be
+        specified at the task level.
 
         Placing the constraint at both the job level and at the task group level is
         redundant since when placed at the job level, the constraint will be applied
         to all task groups. When specified, `LTarget` and `RTarget` should be
         omitted.
 
+  * `distinct_property` - If set, the scheduler selects nodes that have a
+        distinct value of the specified property for each allocation. This can
+        be specified as a job constraint which applies the constraint to all
+        task groups in the job, or as a task group constraint which scopes the
+        effect to just that group. The constraint may not be specified at the
+        task level.
+
+        Placing the constraint at both the job level and at the task group level is
+        redundant since when placed at the job level, the constraint will be applied
+        to all task groups. When specified, `LTarget` should be the property
+        that should be distinct and and `RTarget` should be omitted.
+
   * Comparison Operators - `=`, `==`, `is`, `!=`, `not`, `>`, `>=`, `<`, `<=`. The
     ordering is compared lexically.
 

website/source/docs/job-specification/constraint.html.md

@@ -104,8 +104,8 @@ constraint {
 - `"distinct_hosts"` - Instructs the scheduler to not co-locate any groups on
   the same machine. When specified as a job constraint, it applies to all groups
   in the job. When specified as a group constraint, the effect is constrained to
-  that group. Note that the `attribute` parameter should be omitted when using
-  this constraint.
+  that group. This constraint can not be specified at the task level. Note that
+  the `attribute` parameter should be omitted when using this constraint.
 
     ```hcl
     constraint {
@@ -114,6 +114,38 @@ constraint {
     }
     ```
 
+    The constraint may also be specified as follows for a more compact
+    representation:
+
+    ```hcl
+    constraint {
+        distinct_hosts = true
+    }
+    ```
+
+- `"distinct_property"` - Instructs the scheduler to select nodes that have a
+  distinct value of the specified property for each allocation. When specified
+  as a job constraint, it applies to all groups in the job. When specified as a
+  group constraint, the effect is constrained to that group. This constraint can
+  not be specified at the task level. Note that the `value` parameter should be
+  omitted when using this constraint.
+
+    ```hcl
+    constraint {
+      operator  = "distinct_property"
+      attribute = "${meta.rack"}
+    }
+    ```
+
+    The constraint may also be specified as follows for a more compact
+    representation:
+
+    ```hcl
+    constraint {
+        distinct_property = "${meta.rack}"
+    }
+    ```
+
 - `"regexp"` - Specifies a regular expression constraint against the attribute.
   The syntax of the regular expressions accepted is the same general syntax used
   by Perl, Python, and many other languages. More precisely, it is the syntax
@@ -172,6 +204,21 @@ constraint {
 }
 ```
 
+### Distint Property
+
+A potential use case of the `distinct_property` constraint is to spread a
+service with `count > 1` across racks to minimize correlated failure. Nodes can
+be annotated with which rack they are on using [client
+metadata][client-metadata] with values
+such as "rack-12-1", "rack-12-2", etc. The following constraint would then
+assure no two instances of the task group existed on the same rack.
+
+```hcl
+constraint {
+  distinct_property = "${meta.rack}"
+}
+```
+
 ### Operating Systems
 
 This example restricts the task to running on nodes that are running Ubuntu