• Overview
    • Batch Processing Workloads
    • Edge Workload Management
    • Non-Containerized Application Orchestration
    • Simple Container Orchestration
  • Enterprise
  • Tutorials
  • Docs
  • API
  • Plugins
  • Tools
  • Community
GitHub—Stars on GitHub
Download
    • v1.3.x (latest)
    • v1.2.x
    • v1.1.x
    • v1.0.x
    • v0.12.x
    • v0.11.x
    • Overview
    • Quickstart
      • Overview
      • Requirements
      • Reference Architecture
      • Deployment Guide
    • Windows Service
    • Overview
    • Specific Version Details
    • Overview
    • Consul
    • Consul Service Mesh
    • Vault Integration

    • Overview
    • Architecture
      • Overview
      • Base
      • Task Drivers
      • Devices
      • Storage
      • Overview
      • Internals
      • Preemption
    • Consensus Protocol
    • Filesystem
    • Gossip Protocol
    • Security Model
    • Overview
    • acl
    • audit
    • autopilot
    • client
    • consul
    • plugin
    • sentinel
    • search
    • server
    • server_join
    • telemetry
    • tls
    • ui
    • vault
    • Overview
      • Overview
      • bootstrap
      • policy apply
      • policy delete
      • policy info
      • policy list
      • token create
      • token delete
      • token info
      • token list
      • token self
      • token update
    • agent
    • agent-info
      • Overview
      • exec
      • fs
      • logs
      • restart
      • signal
      • status
      • stop
      • Overview
      • validate
      • Overview
      • fail
      • list
      • pause
      • promote
      • resume
      • status
      • unblock
      • Overview
      • list
      • status
      • Overview
      • allocs
      • deployments
      • dispatch
      • eval
      • history
      • init
      • inspect
      • plan
      • periodic force
      • promote
      • revert
      • run
      • scale
      • scaling-events
      • status
      • stop
      • validate
      • Overview
      • get
    • monitor
      • Overview
      • apply
      • delete
      • inspect
      • list
      • status
      • Overview
      • config
      • drain
      • eligibility
      • status
      • Overview
      • api
      • autopilot get-config
      • autopilot set-config
      • debug
      • keygen
      • keyring
      • metrics
      • raft info
      • raft list-peers
      • raft logs
      • raft remove-peer
      • raft state
      • snapshot agent
      • snapshot inspect
      • snapshot restore
      • snapshot save
      • snapshot state
      • Overview
      • status
      • Overview
      • apply
      • delete
      • init
      • inspect
      • list
      • status
      • Overview
      • apply
      • dismiss
      • info
      • list
      • Overview
      • policy info
      • policy list
      • Overview
      • apply
      • delete
      • list
      • read
      • Overview
      • force-leave
      • join
      • members
      • Overview
      • service delete
      • service info
      • service list
    • status
      • Overview
      • gc
      • reconcile summaries
    • ui
    • version
      • Overview
      • create
      • delete
      • deregister
      • detach
      • init
      • register
      • snapshot create
      • snapshot delete
      • snapshot list
      • status

    • Overview
      • Overview
      • Expressions
        • Overview
          • chunklist
          • coalesce
          • coalescelist
          • compact
          • concat
          • contains
          • distinct
          • element
          • flatten
          • index
          • keys
          • length
          • lookup
          • merge
          • range
          • reverse
          • setintersection
          • setproduct
          • setunion
          • slice
          • sort
          • values
          • zipmap
          • can
          • convert
          • try
          • bcrypt
          • md5
          • rsadecrypt
          • sha1
          • sha256
          • sha512
          • formatdate
          • timeadd
          • base64decode
          • base64encode
          • csvdecode
          • jsondecode
          • jsonencode
          • urlencode
          • yamldecode
          • yamlencode
          • abspath
          • basename
          • dirname
          • file
          • fileexists
          • fileset
          • pathexpand
          • cidrhost
          • cidrnetmask
          • cidrsubnet
          • cidrsubnets
          • abs
          • ceil
          • floor
          • log
          • max
          • min
          • parseint
          • pow
          • signum
          • chomp
          • format
          • formatlist
          • indent
          • join
          • lower
          • regex_replace
          • replace
          • split
          • strrev
          • substr
          • title
          • trim
          • trimprefix
          • trimspace
          • trimsuffix
          • upper
          • uuidv4
          • uuidv5
      • Locals
      • Syntax
      • Variables
    • artifact
    • affinity
    • check_restart
    • connect
    • constraint
    • csi_plugin
    • device
    • dispatch_payload
    • env
    • ephemeral_disk
    • expose
    • gateway
    • group
    • job
    • lifecycle
    • logs
    • meta
    • migrate
    • multiregion
    • network
    • parameterized
    • periodic
    • proxy
    • reschedule
    • resources
    • restart
    • scaling
    • service
    • sidecar_service
    • sidecar_task
    • spread
    • task
    • template
    • update
    • upstreams
    • vault
    • volume
    • volume_mount
    • Overview
      • Overview
      • capability
      • mount_options
      • topology_request
    • Overview
    • Docker
    • Isolated Fork/Exec
    • Java
    • Podman
    • QEMU
    • Raw Fork/Exec
      • Overview
      • containerd
      • Firecracker driver
      • Jailtask driver
      • Lightrun
      • LXC
      • Pot
      • Rkt Deprecated
      • Rookout
      • Singularity
      • systemd-nspawn
      • Windows IIS
      • Overview
      • ECS
    • Overview
      • Overview
      • Nvidia
      • USB Beta
  • Schedulers
    • Overview
    • Runtime Environment
    • Variable Interpolation
    • Overview
      • Overview
      • apm
      • dynamic_application_sizing
      • http
      • nomad
      • policy
      • policy_eval
      • source
      • strategy
      • target
      • telemetry
    • API
    • CLI
    • Policy
    • Telemetry
      • Overview
        • Overview
        • Datadog
        • Nomad API
        • Prometheus
        • Overview
        • Dynamic Application Sizing Average
        • Dynamic Application Sizing Max
        • Dynamic Application Sizing Percentile
        • Fixed Value
        • Pass-Through
        • Target Value
        • Threshold
        • Overview
        • Amazon Web Services Autoscaling Group
        • Azure Virtual Machine Scale Set
        • Dynamic Application Sizing
        • Google Cloud Engine Managed Instance Group
        • Nomad Task Group
      • Community
      • Overview
      • Checks
      • Node Selector Strategy
        • Overview
        • Base
        • APM
        • Strategy
        • Target
    • Overview
    • Operating Nomad Agents
    • Monitoring Nomad
    • Metrics Reference
    • Cluster Management
    • Transport Security
    • Access Control

    • Overview
    • Alternative to Kubernetes
    • Supplement to Kubernetes
  • Nomad Ecosystem
  • Nomad Partnerships
  • Who Uses Nomad
    • Overview
      • Overview
      • FAQ
  • FAQ
Type '/' to Search

»constraint Stanza

Placementjob -> constraint
job -> group -> constraint
job -> group -> task -> constraint

The constraint allows restricting the set of eligible nodes. Constraints may filter on attributes or client metadata. Additionally constraints may be specified at the job, group, or task levels for ultimate flexibility.

It is possible to define irreconcilable constraints in a job. For example, because all tasks within a group are scheduled on the same client node, specifying different ${attr.unique.hostname} constraints at the task level will cause a job to be unplaceable.

job "docs" {
  # All tasks in this job must run on linux.
  constraint {
    attribute = "${attr.kernel.name}"
    value     = "linux"
  }

  group "example" {
    # All groups in this job should be scheduled on different hosts.
    constraint {
      operator  = "distinct_hosts"
      value     = "true"
    }

    task "server" {
      # All tasks must run where "my_custom_value" is greater than 3.
      constraint {
        attribute = "${meta.my_custom_value}"
        operator  = ">"
        value     = "3"
      }
    }
  }
}
job "docs" {
  # All tasks in this job must run on linux.
  constraint {
    attribute = "${attr.kernel.name}"
    value     = "linux"
  }

  group "example" {
    # All groups in this job should be scheduled on different hosts.
    constraint {
      operator  = "distinct_hosts"
      value     = "true"
    }

    task "server" {
      # All tasks must run where "my_custom_value" is greater than 3.
      constraint {
        attribute = "${meta.my_custom_value}"
        operator  = ">"
        value     = "3"
      }
    }
  }
}

Placing constraints at both the job level and at the group level is redundant since constraints are applied hierarchically. The job constraints will affect all groups (and tasks) in the job.

»constraint Parameters

  • attribute (string: "") - Specifies the name or reference of the attribute to examine for the constraint. This can be any of the Nomad interpolated values.

  • operator (string: "=") - Specifies the comparison operator. The ordering is compared lexically. Possible values include:

    =
    !=
    >
    >=
    <
    <=
    distinct_hosts
    distinct_property
    regexp
    set_contains
    set_contains_any
    version
    semver
    is_set
    is_not_set
    
    =
    !=
    >
    >=
    <
    <=
    distinct_hosts
    distinct_property
    regexp
    set_contains
    set_contains_any
    version
    semver
    is_set
    is_not_set
    

    For a detailed explanation of these values and their behavior, please see the operator values section.

  • value (string: "") - Specifies the value to compare the attribute against using the specified operation. This can be a literal value, another attribute, or any Nomad interpolated values.

»operator Values

This section details the specific values for the "operator" parameter in the Nomad job specification for constraints. The operator is always specified as a string, but the string can take on different values which change the behavior of the overall constraint evaluation.

constraint {
  operator = "..."
}
constraint {
  operator = "..."
}
  • "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. This constraint can not be specified at the task level. Note that the attribute parameter should be omitted when using this constraint.

    constraint {
      operator  = "distinct_hosts"
      value     = "true"
    }
    
    constraint {
      operator  = "distinct_hosts"
      value     = "true"
    }
    

    The constraint may also be specified as follows for a more compact representation:

    constraint {
        distinct_hosts = true
    }
    
    constraint {
        distinct_hosts = true
    }
    
  • "distinct_property" - Instructs the scheduler to select nodes that have a distinct value of the specified property. The value parameter specifies how many allocations are allowed to share the value of a property. The value must be 1 or greater and if omitted, defaults to 1. 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.

    constraint {
      operator  = "distinct_property"
      attribute = "${meta.rack}"
      value     = "3"
    }
    
    constraint {
      operator  = "distinct_property"
      attribute = "${meta.rack}"
      value     = "3"
    }
    

    The constraint may also be specified as follows for a more compact representation:

    constraint {
      distinct_property = "${meta.rack}"
      value     = "3"
    }
    
    constraint {
      distinct_property = "${meta.rack}"
      value     = "3"
    }
    
  • "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 accepted by RE2 and described at in the Google RE2 syntax.

    constraint {
      attribute = "..."
      operator  = "regexp"
      value     = "[a-z0-9]"
    }
    
    constraint {
      attribute = "..."
      operator  = "regexp"
      value     = "[a-z0-9]"
    }
    
  • "set_contains" - Specifies a contains constraint against the attribute. The attribute and the list being checked are split using commas. This will check that the given attribute contains all of the specified elements.

    constraint {
      attribute = "..."
      operator  = "set_contains"
      value     = "a,b,c"
    }
    
    constraint {
      attribute = "..."
      operator  = "set_contains"
      value     = "a,b,c"
    }
    
  • "set_contains_any" - Specifies a contains constraint against the attribute. The attribute and the list being checked are split using commas. This will check that the given attribute contains any of the specified elements.

    constraint {
      attribute = "..."
      operator  = "set_contains_any"
      value     = "a,b,c"
    }
    
    constraint {
      attribute = "..."
      operator  = "set_contains_any"
      value     = "a,b,c"
    }
    
  • "version" - Specifies a version constraint against the attribute. This supports a comma-separated list of constraints, including the pessimistic operator. version will not consider a prerelease (eg 1.6.0-beta) sufficient to match a non-prerelease constraint (eg >= 1.0). Use the semver constraint for strict Semantic Versioning 2.0 ordering. For more examples please see the go-version repository for more specific examples.

    constraint {
      attribute = "..."
      operator  = "version"
      value     = ">= 0.1.0, < 0.2"
    }
    
    constraint {
      attribute = "..."
      operator  = "version"
      value     = ">= 0.1.0, < 0.2"
    }
    
  • "semver" - Specifies a version constraint against the attribute. Only Semantic Versioning 2.0 compliant versions and comparison operators are supported, so there is no pessimistic operator. Unlike version, this operator considers prereleases (eg 1.6.0-beta) sufficient to satisfy non-prerelease constraints (eg >= 1.0). Added in Nomad v0.10.2.

    constraint {
      attribute = "..."
      operator  = "semver"
      value     = ">= 0.1.0, < 0.2"
    }
    
    constraint {
      attribute = "..."
      operator  = "semver"
      value     = ">= 0.1.0, < 0.2"
    }
    
  • "is_set" - Specifies that a given attribute must be present. This can be combined with the "!=" operator to require that an attribute has been set before checking for equality. The default behavior for "!=" is to include nodes that don't have that attribute set.

  • "is_not_set" - Specifies that a given attribute must not be present.

»constraint Examples

The following examples only show the constraint stanzas. Remember that the constraint stanza is only valid in the placements listed above.

»Kernel Data

This example restricts the task to running on nodes which have a kernel version higher than "3.19".

constraint {
  attribute = "${attr.kernel.version}"
  operator  = "version"
  value     = "> 3.19"
}
constraint {
  attribute = "${attr.kernel.version}"
  operator  = "version"
  value     = "> 3.19"
}

»Distinct 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 custom client metadata with values such as "rack-12-1", "rack-12-2", etc. The following constraint would assure that an individual rack is not running more than 2 instances of the task group.

constraint {
  distinct_property = "${meta.rack}"
  value = "2"
}
constraint {
  distinct_property = "${meta.rack}"
  value = "2"
}

»Operating Systems

This example restricts the task to running on nodes that are running Ubuntu 14.04

constraint {
  attribute = "${attr.os.name}"
  value     = "ubuntu"
}

constraint {
  attribute = "${attr.os.version}"
  value     = "14.04"
}
constraint {
  attribute = "${attr.os.name}"
  value     = "ubuntu"
}

constraint {
  attribute = "${attr.os.version}"
  value     = "14.04"
}

»Cloud Metadata

When possible, Nomad populates node attributes from the cloud environment. These values are accessible as filters in constraints. This example constrains this task to only run on nodes that are memory-optimized on AWS.

constraint {
  attribute = "${attr.platform.aws.instance-type}"
  value     = "m4.xlarge"
}
constraint {
  attribute = "${attr.platform.aws.instance-type}"
  value     = "m4.xlarge"
}

»User-Specified Metadata

This example restricts the task to running on nodes where the binaries for redis, cypress, and nginx are all cached locally. This particular example is utilizing custom client metadata.

constraint {
  attribute    = "${meta.cached_binaries}"
  set_contains = "redis,cypress,nginx"
}
constraint {
  attribute    = "${meta.cached_binaries}"
  set_contains = "redis,cypress,nginx"
}
github logoEdit this page
DocsAPIResourcesPrivacySecurityPress KitConsent Manager