HashiConf 2024 Now streaming live from Boston! Attend for free
Nomad
Nomad Home

You are viewing documentation for version v1.5.x. View latest version.

Jobs HTTP API

The /jobs endpoints are used to query for and interact with jobs.

List Jobs

This endpoint lists all known jobs in the system registered with Nomad.

MethodPathProduces
GET/v1/jobsapplication/json

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking QueriesACL Required
YESnamespace:list-jobs

Parameters

  • prefix (string: "") - Specifies a string to filter jobs on based on an index prefix. This is specified as a query string parameter.

  • next_token (string: "") - This endpoint supports paging. The next_token parameter accepts a string which identifies the next expected job. This value can be obtained from the X-Nomad-NextToken header from the previous response.

  • per_page (int: 0) - Specifies a maximum number of jobs to return for this request. If omitted, the response is not paginated. The value of the X-Nomad-NextToken header of the last response can be used as the next_token of the next request to fetch additional pages.

  • filter (string: "") - Specifies the expression used to filter the results. Consider using pagination or a query parameter to reduce resource used to serve the request.

  • namespace (string: "default") - Specifies the target namespace. Specifying * would return all jobs across all the authorized namespaces.

  • meta (bool: false) - If set, jobs returned will include a meta field containing key-value pairs provided in the job specification's meta block.

Sample Request

$ curl https://localhost:4646/v1/jobs

$ curl https://localhost:4646/v1/jobs?prefix=team

$ curl https://localhost:4646/v1/jobs?namespace=*&prefix=team

Sample Response

[
  {
    "ID": "example",
    "ParentID": "",
    "Name": "example",
    "Type": "service",
    "Priority": 50,
    "Status": "pending",
    "StatusDescription": "",
    "JobSummary": {
      "JobID": "example",
      "Namespace": "default",
      "Summary": {
        "cache": {
          "Queued": 1,
          "Complete": 1,
          "Failed": 0,
          "Running": 0,
          "Starting": 0,
          "Lost": 0
        }
      },
      "Children": {
        "Pending": 0,
        "Running": 0,
        "Dead": 0
      },
      "CreateIndex": 52,
      "ModifyIndex": 96
    },
    "CreateIndex": 52,
    "ModifyIndex": 93,
    "JobModifyIndex": 52
  }
]

Create Job

This endpoint creates (aka "registers") a new job in the system.

MethodPathProduces
POST/v1/jobsapplication/json

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking QueriesACL Required
NOnamespace:submit-job
namespace:sentinel-override if PolicyOverride set

Parameters

  • Job (Job: <required>) - Specifies the JSON definition of the job.

  • EnforceIndex (bool: false) - If set, the job will only be registered if the passed JobModifyIndex matches the current job's index. If the index is zero, the register only occurs if the job is new. This paradigm allows check-and-set style job updating.

  • EvalPriority (int: 0) - Override the priority of the evaluations produced as a result of this job registration. By default, this is set to the priority of the job.

  • JobModifyIndex (int: 0) - Specifies the JobModifyIndex to enforce the current job is at.

  • PolicyOverride (bool: false) - If set, any soft mandatory Sentinel policies will be overridden. This allows a job to be registered when it would be denied by policy.

  • PreserveCounts (bool: false) - If set, existing task group counts are preserved, over those specified in the new job spec.

Sample Payload

{
  "Job": {
    "Datacenters": ["dc1"],
    "ID": "cache",
    "TaskGroups": [
      {
        "Name": "cache",
        "Networks": [
          {
            "DynamicPorts": [
              {
                "Label": "db",
                "To": 6379
              }
            ]
          }
        ],
        "Services": [
          {
            "Name": "redis-cache",
            "PortLabel": "db"
          }
        ],
        "Tasks": [
          {
            "Config": {
              "image": "redis:7",
              "ports": ["db"]
            },
            "Driver": "docker",
            "Name": "redis"
          }
        ]
      }
    ]
  }
}

Sample Request

$ curl \
    --request POST \
    --data @payload.json \
    https://localhost:4646/v1/jobs

Sample Response

{
  "EvalID": "",
  "EvalCreateIndex": 0,
  "JobModifyIndex": 109,
  "Warnings": "",
  "Index": 0,
  "LastContact": 0,
  "KnownLeader": false
}

Parse Job

This endpoint will parse a HCL jobspec and produce the equivalent JSON encoded job.

MethodPathProduces
POST/v1/jobs/parseapplication/json

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking QueriesACL Required
NOnamespace:parse-job
namespace:submit-job

Parameters

  • namespace (string: "default") - Specifies the target namespace. If ACL is enabled, this value must match a namespace that the token is allowed to access. This is specified as a query string parameter.

  • JobHCL (string: <required>) - Specifies the HCL definition of the job encoded in a JSON string.

  • Canonicalize (bool: false) - Flag to enable setting any unset fields to their default values.

  • HCLv1 (bool: false) - Use the legacy v1 HCL parser.

Sample Payload

{
  "JobHCL": "job \"example\" {\n  type = \"service\"\n  group \"cache\" {}\n}",
  "Canonicalize": true
}

You can use a tool such as jq to generate the payload from a local HCL file:

$ jq -Rsc '{ JobHCL: ., Canonicalize: true }' example.nomad.hcl > payload.json

Sample Request

$ curl \
    --request POST \
    --data @payload.json \
    https://localhost:4646/v1/jobs/parse

Sample Response

{
  "AllAtOnce": false,
  "Constraints": null,
  "Affinities": null,
  "CreateIndex": 0,
  "Datacenters": null,
  "ID": "my-job",
  "JobModifyIndex": 0,
  "Meta": null,
  "Migrate": null,
  "ModifyIndex": 0,
  "Name": "my-job",
  "Namespace": "default",
  "ParameterizedJob": null,
  "ParentID": "",
  "Payload": null,
  "Periodic": null,
  "Priority": 50,
  "Region": "global",
  "Reschedule": null,
  "Stable": false,
  "Status": "",
  "StatusDescription": "",
  "Stop": false,
  "SubmitTime": null,
  "TaskGroups": null,
  "Type": "service",
  "Update": null,
  "VaultToken": "",
  "Version": 0
}

Read Job

This endpoint reads information about a single job for its specification and status.

MethodPathProduces
GET/v1/job/:job_idapplication/json

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking QueriesACL Required
YESnamespace:read-job

Parameters

  • :job_id (string: <required>) - Specifies the ID of the job (as specified in the job file during submission). This is specified as part of the path.
  • namespace (string: "default") - Specifies the namespace of the job. If not specified, defaults to "default". This is specified as a URL query parameter.

Sample Request

$ curl \
    https://localhost:4646/v1/job/my-job

$ curl \
    https://localhost:4646/v1/job/my-job?namespace=apps

Sample Response

{
  "Region": "global",
  "Namespace": "apps",
  "ID": "example",
  "ParentID": "",
  "Name": "example",
  "Type": "batch",
  "Priority": 50,
  "AllAtOnce": false,
  "Datacenters": ["dc1"],
  "Constraints": [
    {
      "LTarget": "${attr.kernel.name}",
      "RTarget": "linux",
      "Operand": "="
    }
  ],
  "TaskGroups": [
    {
      "Name": "cache",
      "Count": 1,
      "Constraints": [
        {
          "LTarget": "${attr.os.signals}",
          "RTarget": "SIGUSR1",
          "Operand": "set_contains"
        }
      ],
      "Affinities": [
        {
          "LTarget": "${meta.datacenter}",
          "RTarget": "dc1",
          "Operand": "=",
          "Weight": 50
        }
      ],
      "RestartPolicy": {
        "Attempts": 10,
        "Interval": 300000000000,
        "Delay": 25000000000,
        "Mode": "delay"
      },
      "Tasks": [
        {
          "Config": {
            "command": "env",
            "image": "alpine"
          },
          "Driver": "docker",
          "Lifecycle": {
            "Hook": "prestart",
            "Sidecar": false
          },
          "Name": "init",
          "Resources": {
            "CPU": 100,
            "MemoryMB": 300
          }
        },
        {
          "Name": "redis",
          "Driver": "docker",
          "User": "foo-user",
          "Config": {
            "image": "redis:latest",
            "port_map": [
              {
                "db": 6379
              }
            ]
          },
          "Env": {
            "foo": "bar",
            "baz": "pipe"
          },
          "Services": [
            {
              "Name": "cache-redis",
              "PortLabel": "db",
              "Tags": ["global", "cache"],
              "Checks": [
                {
                  "Name": "alive",
                  "Type": "tcp",
                  "Command": "",
                  "Args": null,
                  "Path": "",
                  "Protocol": "",
                  "PortLabel": "",
                  "Interval": 10000000000,
                  "Timeout": 2000000000,
                  "InitialStatus": ""
                }
              ]
            }
          ],
          "Vault": null,
          "Templates": [
            {
              "SourcePath": "local/config.conf.tpl",
              "DestPath": "local/config.conf",
              "EmbeddedTmpl": "",
              "ChangeMode": "signal",
              "ChangeSignal": "SIGUSR1",
              "Splay": 5000000000,
              "Perms": ""
            }
          ],
          "Constraints": null,
          "Affinities": null,
          "Resources": {
            "CPU": 500,
            "MemoryMB": 256,
            "DiskMB": 0,
            "Networks": [
              {
                "Device": "",
                "CIDR": "",
                "IP": "",
                "MBits": 10,
                "ReservedPorts": [
                  {
                    "Label": "rpc",
                    "Value": 25566
                  }
                ],
                "DynamicPorts": [
                  {
                    "Label": "db",
                    "Value": 0
                  }
                ]
              }
            ]
          },
          "DispatchPayload": {
            "File": "config.json"
          },
          "Meta": {
            "foo": "bar",
            "baz": "pipe"
          },
          "KillTimeout": 5000000000,
          "LogConfig": {
            "Disabled": false,
            "MaxFiles": 10,
            "MaxFileSizeMB": 10
          },
          "Artifacts": [
            {
              "GetterSource": "http://foo.com/artifact.tar.gz",
              "GetterOptions": {
                "checksum": "md5:c4aa853ad2215426eb7d70a21922e794"
              },
              "RelativeDest": "local/"
            }
          ],
          "Leader": false
        }
      ],
      "EphemeralDisk": {
        "Sticky": false,
        "SizeMB": 300,
        "Migrate": false
      },
      "Meta": {
        "foo": "bar",
        "baz": "pipe"
      }
    }
  ],
  "Update": {
    "Stagger": 10000000000,
    "MaxParallel": 1
  },
  "Periodic": {
    "Enabled": true,
    "Spec": "* * * * *",
    "SpecType": "cron",
    "ProhibitOverlap": true
  },
  "ParameterizedJob": {
    "Payload": "required",
    "MetaRequired": ["foo"],
    "MetaOptional": ["bar"]
  },
  "Payload": null,
  "Meta": {
    "foo": "bar",
    "baz": "pipe"
  },
  "VaultToken": "",
  "Status": "running",
  "StatusDescription": "",
  "CreateIndex": 7,
  "ModifyIndex": 7,
  "JobModifyIndex": 7
}

Field Reference

  • Status: The job's current state. It can have one of the following values:
    • pending: The job is currently waiting on scheduling.
    • running: The job has non-terminal allocations.
    • dead: All of the job's allocations and evaluations are terminal.
  • Type: The type of job in terms of scheduling. It can have one of the following values:
    • service: Allocations are intended to remain alive.
    • batch: Allocations are intended to exit.
    • system: Each client gets an allocation.

List Job Versions

This endpoint reads information about all versions of a job.

MethodPathProduces
GET/v1/job/:job_id/versionsapplication/json

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking QueriesACL Required
YESnamespace:read-job

Parameters

  • diffs (bool: false) - Specifies if the Diffs field should be populated, containing the structured diff between the current and last job version.

  • :job_id (string: <required>) - Specifies the ID of the job (as specified in the job file during submission). This is specified as part of the path.

  • namespace (string: "default") - Specifies the target namespace. If ACL is enabled, this value must match a namespace that the token is allowed to access. This is specified as a query string parameter.

Sample Request

$ curl \
    https://localhost:4646/v1/job/my-job/versions

Sample Response

{
  "Diffs": null,
  "Index": 51,
  "KnownLeader": true,
  "LastContact": 0,
  "Versions": [
    {
      "Affinities": null,
      "AllAtOnce": false,
      "Constraints": null,
      "ConsulToken": "",
      "CreateIndex": 44,
      "Datacenters": ["dc1"],
      "Dispatched": false,
      "ID": "example",
      "JobModifyIndex": 44,
      "Meta": null,
      "ModifyIndex": 51,
      "Multiregion": null,
      "Name": "example",
      "Namespace": "default",
      "NomadTokenID": "",
      "ParameterizedJob": null,
      "ParentID": "",
      "Payload": null,
      "Periodic": null,
      "Priority": 50,
      "Region": "global",
      "Spreads": null,
      "Stable": true,
      "Status": "running",
      "StatusDescription": "",
      "Stop": false,
      "SubmitTime": 1608304897537638400,
      "TaskGroups": [
        {
          "Affinities": null,
          "Constraints": null,
          "Count": 1,
          "EphemeralDisk": {
            "Migrate": false,
            "SizeMB": 300,
            "Sticky": false
          },
          "MaxClientDisconnect": 300000000000,
          "Meta": null,
          "Migrate": {
            "HealthCheck": "checks",
            "HealthyDeadline": 300000000000,
            "MaxParallel": 1,
            "MinHealthyTime": 10000000000
          },
          "Name": "cache",
          "Networks": [
            {
              "CIDR": "",
              "DNS": null,
              "Device": "",
              "DynamicPorts": [
                {
                  "HostNetwork": "default",
                  "Label": "db",
                  "To": 6379,
                  "Value": 0
                }
              ],
              "IP": "",
              "MBits": 0,
              "Mode": "",
              "ReservedPorts": null
            }
          ],
          "ReschedulePolicy": {
            "Attempts": 0,
            "Delay": 30000000000,
            "DelayFunction": "exponential",
            "Interval": 0,
            "MaxDelay": 3600000000000,
            "Unlimited": true
          },
          "RestartPolicy": {
            "Attempts": 2,
            "Delay": 15000000000,
            "Interval": 1800000000000,
            "Mode": "fail"
          },
          "Scaling": null,
          "Services": null,
          "ShutdownDelay": null,
          "Spreads": null,
          "StopAfterClientDisconnect": null,
          "Tasks": [
            {
              "Affinities": null,
              "Artifacts": null,
              "CSIPluginConfig": null,
              "Config": {
                "image": "redis:7",
                "ports": ["db"]
              },
              "Constraints": null,
              "DispatchPayload": null,
              "Driver": "docker",
              "Env": null,
              "KillSignal": "",
              "KillTimeout": 5000000000,
              "Kind": "",
              "Leader": false,
              "Lifecycle": null,
              "LogConfig": {
                "Disabled": false,
                "MaxFileSizeMB": 10,
                "MaxFiles": 10
              },
              "Meta": null,
              "Name": "redis",
              "Resources": {
                "CPU": 500,
                "Devices": null,
                "DiskMB": 0,
                "IOPS": 0,
                "MemoryMB": 256,
                "Networks": null
              },
              "RestartPolicy": {
                "Attempts": 2,
                "Delay": 15000000000,
                "Interval": 1800000000000,
                "Mode": "fail"
              },
              "ScalingPolicies": null,
              "Services": null,
              "ShutdownDelay": 0,
              "Templates": null,
              "User": "",
              "Vault": null,
              "VolumeMounts": null
            }
          ],
          "Update": {
            "AutoPromote": false,
            "AutoRevert": false,
            "Canary": 0,
            "HealthCheck": "checks",
            "HealthyDeadline": 300000000000,
            "MaxParallel": 1,
            "MinHealthyTime": 10000000000,
            "ProgressDeadline": 600000000000,
            "Stagger": 30000000000
          },
          "Volumes": null
        }
      ],
      "Type": "service",
      "Update": {
        "AutoPromote": false,
        "AutoRevert": false,
        "Canary": 0,
        "HealthCheck": "",
        "HealthyDeadline": 0,
        "MaxParallel": 1,
        "MinHealthyTime": 0,
        "ProgressDeadline": 0,
        "Stagger": 30000000000
      },
      "VaultNamespace": "",
      "VaultToken": "",
      "Version": 0
    }
  ]
}

$ curl \
    https://localhost:4646/v1/job/my-job/versions?diffs=true

 
{
  "Diffs": [
    {
      "Fields": null,
      "ID": "example",
      "Objects": null,
      "TaskGroups": [
        {
          "Fields": null,
          "Name": "cache",
          "Objects": null,
          "Tasks": [
            {
              "Annotations": null,
              "Fields": [
                {
                  "Annotations": null,
                  "Name": "Env[foo]",
                  "New": "bar",
                  "Old": "",
                  "Type": "Added"
                }
              ],
              "Name": "redis",
              "Objects": null,
              "Type": "Edited"
            }
          ],
          "Type": "Edited",
          "Updates": null
        }
      ],
      "Type": "Edited"
    }
  ],
  "Index": 26,
  "KnownLeader": true,
  "LastContact": 0,
  "Versions": [
    {
      "Affinities": null,
      "AllAtOnce": false,
      "Constraints": null,
      "ConsulToken": "",
      "CreateIndex": 10,
      "Datacenters": [
        "dc1"
      ],
      "Dispatched": false,
      "ID": "example",
      "JobModifyIndex": 16,
      "Meta": null,
      "ModifyIndex": 26,
      "Multiregion": null,
      "Name": "example",
      "Namespace": "default",
      "NomadTokenID": "",
      "ParameterizedJob": null,
      "ParentID": "",
      "Payload": null,
      "Periodic": null,
      "Priority": 50,
      "Region": "global",
      "Spreads": null,
      "Stable": true,
      "Status": "running",
      "StatusDescription": "",
      "Stop": false,
      "SubmitTime": 1608316675000588800,
      "TaskGroups": [
        {
          "Affinities": null,
          "Constraints": null,
          "Count": 1,
          "EphemeralDisk": {
            "Migrate": false,
            "SizeMB": 300,
            "Sticky": false
          },
          "MaxClientDisconnect": null,
          "Meta": null,
          "Migrate": {
            "HealthCheck": "checks",
            "HealthyDeadline": 300000000000,
            "MaxParallel": 1,
            "MinHealthyTime": 10000000000
          },
          "Name": "cache",
          "Networks": [
            {
              "CIDR": "",
              "DNS": null,
              "Device": "",
              "DynamicPorts": [
                {
                  "HostNetwork": "default",
                  "Label": "db",
                  "To": 6379,
                  "Value": 0
                }
              ],
              "IP": "",
              "MBits": 0,
              "Mode": "",
              "ReservedPorts": null
            }
          ],
          "ReschedulePolicy": {
            "Attempts": 0,
            "Delay": 30000000000,
            "DelayFunction": "exponential",
            "Interval": 0,
            "MaxDelay": 3600000000000,
            "Unlimited": true
          },
          "RestartPolicy": {
            "Attempts": 2,
            "Delay": 15000000000,
            "Interval": 1800000000000,
            "Mode": "fail"
          },
          "Scaling": null,
          "Services": null,
          "ShutdownDelay": null,
          "Spreads": null,
          "StopAfterClientDisconnect": null,
          "Tasks": [
            {
              "Affinities": null,
              "Artifacts": null,
              "CSIPluginConfig": null,
              "Config": {
                "image": "redis:7",
                "ports": [
                  "db"
                ]
              },
              "Constraints": null,
              "DispatchPayload": null,
              "Driver": "docker",
              "Env": {
                "foo": "bar"
              },
              "KillSignal": "",
              "KillTimeout": 5000000000,
              "Kind": "",
              "Leader": false,
              "Lifecycle": null,
              "LogConfig": {
                "Disabled": false,
                "MaxFileSizeMB": 10,
                "MaxFiles": 10
              },
              "Meta": null,
              "Name": "redis",
              "Resources": {
                "CPU": 500,
                "Devices": null,
                "DiskMB": 0,
                "IOPS": 0,
                "MemoryMB": 256,
                "Networks": null
              },
              "RestartPolicy": {
                "Attempts": 2,
                "Delay": 15000000000,
                "Interval": 1800000000000,
                "Mode": "fail"
              },
              "ScalingPolicies": null,
              "Services": null,
              "ShutdownDelay": 0,
              "Templates": null,
              "User": "",
              "Vault": null,
              "VolumeMounts": null
            }
          ],
          "Update": {
            "AutoPromote": false,
            "AutoRevert": false,
            "Canary": 0,
            "HealthCheck": "checks",
            "HealthyDeadline": 300000000000,
            "MaxParallel": 1,
            "MinHealthyTime": 10000000000,
            "ProgressDeadline": 600000000000,
            "Stagger": 30000000000
          },
          "Volumes": null
        }
      ],
      "Type": "service",
      "Update": {
        "AutoPromote": false,
        "AutoRevert": false,
        "Canary": 0,
        "HealthCheck": "",
        "HealthyDeadline": 0,
        "MaxParallel": 1,
        "MinHealthyTime": 0,
        "ProgressDeadline": 0,
        "Stagger": 30000000000
      },
      "VaultNamespace": "",
      "VaultToken": "",
      "Version": 1
    },
    {
      "Affinities": null,
      "AllAtOnce": false,
      "Constraints": null,
      "ConsulToken": "",
      "CreateIndex": 10,
      "Datacenters": [
        "dc1"
      ],
      "Dispatched": false,
      "ID": "example",
      "JobModifyIndex": 10,
      "Meta": null,
      "ModifyIndex": 10,
      "Multiregion": null,
      "Name": "example",
      "Namespace": "default",
      "NomadTokenID": "",
      "ParameterizedJob": null,
      "ParentID": "",
      "Payload": null,
      "Periodic": null,
      "Priority": 50,
      "Region": "global",
      "Spreads": null,
      "Stable": false,
      "Status": "pending",
      "StatusDescription": "",
      "Stop": false,
      "SubmitTime": 1608316662268190500,
      "TaskGroups": [
        {
          "Affinities": null,
          "Constraints": null,
          "Count": 1,
          "EphemeralDisk": {
            "Migrate": false,
            "SizeMB": 300,
            "Sticky": false
          },
          "MaxClientDisconnect": null,
          "Meta": null,
          "Migrate": {
            "HealthCheck": "checks",
            "HealthyDeadline": 300000000000,
            "MaxParallel": 1,
            "MinHealthyTime": 10000000000
          },
          "Name": "cache",
          "Networks": [
            {
              "CIDR": "",
              "DNS": null,
              "Device": "",
              "DynamicPorts": [
                {
                  "HostNetwork": "default",
                  "Label": "db",
                  "To": 6379,
                  "Value": 0
                }
              ],
              "IP": "",
              "MBits": 0,
              "Mode": "",
              "ReservedPorts": null
            }
          ],
          "ReschedulePolicy": {
            "Attempts": 0,
            "Delay": 30000000000,
            "DelayFunction": "exponential",
            "Interval": 0,
            "MaxDelay": 3600000000000,
            "Unlimited": true
          },
          "RestartPolicy": {
            "Attempts": 2,
            "Delay": 15000000000,
            "Interval": 1800000000000,
            "Mode": "fail"
          },
          "Scaling": null,
          "Services": null,
          "ShutdownDelay": null,
          "Spreads": null,
          "StopAfterClientDisconnect": null,
          "Tasks": [
            {
              "Affinities": null,
              "Artifacts": null,
              "CSIPluginConfig": null,
              "Config": {
                "image": "redis:7",
                "ports": [
                  "db"
                ]
              },
              "Constraints": null,
              "DispatchPayload": null,
              "Driver": "docker",
              "Env": null,
              "KillSignal": "",
              "KillTimeout": 5000000000,
              "Kind": "",
              "Leader": false,
              "Lifecycle": null,
              "LogConfig": {
                "Disabled": false,
                "MaxFileSizeMB": 10,
                "MaxFiles": 10
              },
              "Meta": null,
              "Name": "redis",
              "Resources": {
                "CPU": 500,
                "Devices": null,
                "DiskMB": 0,
                "IOPS": 0,
                "MemoryMB": 256,
                "Networks": null
              },
              "RestartPolicy": {
                "Attempts": 2,
                "Delay": 15000000000,
                "Interval": 1800000000000,
                "Mode": "fail"
              },
              "ScalingPolicies": null,
              "Services": null,
              "ShutdownDelay": 0,
              "Templates": null,
              "User": "",
              "Vault": null,
              "VolumeMounts": null
            }
          ],
          "Update": {
            "AutoPromote": false,
            "AutoRevert": false,
            "Canary": 0,
            "HealthCheck": "checks",
            "HealthyDeadline": 300000000000,
            "MaxParallel": 1,
            "MinHealthyTime": 10000000000,
            "ProgressDeadline": 600000000000,
            "Stagger": 30000000000
          },
          "Volumes": null
        }
      ],
      "Type": "service",
      "Update": {
        "AutoPromote": false,
        "AutoRevert": false,
        "Canary": 0,
        "HealthCheck": "",
        "HealthyDeadline": 0,
        "MaxParallel": 1,
        "MinHealthyTime": 0,
        "ProgressDeadline": 0,
        "Stagger": 30000000000
      },
      "VaultNamespace": "",
      "VaultToken": "",
      "Version": 0
    }
  ]
}

List Job Allocations

This endpoint reads information about a single job's allocations.

MethodPathProduces
GET/v1/job/:job_id/allocationsapplication/json

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking QueriesACL Required
YESnamespace:read-job

Parameters

  • :job_id (string: <required>) - Specifies the ID of the job (as specified in the job file during submission). This is specified as part of the path.

  • all (bool: false) - Specifies whether the list of allocations should include allocations from a previously registered job with the same ID. This is possible if the job is deregistered and re-registered.

  • namespace (string: "default") - Specifies the target namespace. If ACL is enabled, this value must match a namespace that the token is allowed to access. This is specified as a query string parameter.

Sample Request

$ curl \
    https://localhost:4646/v1/job/my-job/allocations

Sample Response

[
  {
    "ID": "ed344e0a-7290-d117-41d3-a64f853ca3c2",
    "EvalID": "a9c5effc-2242-51b2-f1fe-054ee11ab189",
    "Name": "example.cache[0]",
    "NodeID": "cb1f6030-a220-4f92-57dc-7baaabdc3823",
    "PreviousAllocation": "516d2753-0513-cfc7-57ac-2d6fac18b9dc",
    "NextAllocation": "cd13d9b9-4f97-7184-c88b-7b451981616b",
    "RescheduleTracker": {
      "Events": [
        {
          "PrevAllocID": "516d2753-0513-cfc7-57ac-2d6fac18b9dc",
          "PrevNodeID": "9230cd3b-3bda-9a3f-82f9-b2ea8dedb20e",
          "RescheduleTime": 1517434161192946200,
          "Delay": 5000000000
        }
      ]
    },
    "JobID": "example",
    "TaskGroup": "cache",
    "DesiredStatus": "run",
    "DesiredDescription": "",
    "ClientStatus": "running",
    "ClientDescription": "",
    "TaskStates": {
      "redis": {
        "State": "running",
        "Failed": false,
        "StartedAt": "2017-05-25T23:41:23.240184101Z",
        "FinishedAt": "0001-01-01T00:00:00Z",
        "Events": [
          {
            "Type": "Received",
            "Time": 1495755675956923000,
            "FailsTask": false,
            "RestartReason": "",
            "SetupError": "",
            "DriverError": "",
            "ExitCode": 0,
            "Signal": 0,
            "Message": "",
            "KillTimeout": 0,
            "KillError": "",
            "KillReason": "",
            "StartDelay": 0,
            "DownloadError": "",
            "ValidationError": "",
            "DiskLimit": 0,
            "FailedSibling": "",
            "VaultError": "",
            "TaskSignalReason": "",
            "TaskSignal": "",
            "DriverMessage": ""
          },
          {
            "Type": "Task Setup",
            "Time": 1495755675957466400,
            "FailsTask": false,
            "RestartReason": "",
            "SetupError": "",
            "DriverError": "",
            "ExitCode": 0,
            "Signal": 0,
            "Message": "Building Task Directory",
            "KillTimeout": 0,
            "KillError": "",
            "KillReason": "",
            "StartDelay": 0,
            "DownloadError": "",
            "ValidationError": "",
            "DiskLimit": 0,
            "FailedSibling": "",
            "VaultError": "",
            "TaskSignalReason": "",
            "TaskSignal": "",
            "DriverMessage": ""
          },
          {
            "Type": "Driver",
            "Time": 1495755675970286800,
            "FailsTask": false,
            "RestartReason": "",
            "SetupError": "",
            "DriverError": "",
            "ExitCode": 0,
            "Signal": 0,
            "Message": "",
            "KillTimeout": 0,
            "KillError": "",
            "KillReason": "",
            "StartDelay": 0,
            "DownloadError": "",
            "ValidationError": "",
            "DiskLimit": 0,
            "FailedSibling": "",
            "VaultError": "",
            "TaskSignalReason": "",
            "TaskSignal": "",
            "DriverMessage": "Downloading image redis:7"
          },
          {
            "Type": "Started",
            "Time": 1495755683227522000,
            "FailsTask": false,
            "RestartReason": "",
            "SetupError": "",
            "DriverError": "",
            "ExitCode": 0,
            "Signal": 0,
            "Message": "",
            "KillTimeout": 0,
            "KillError": "",
            "KillReason": "",
            "StartDelay": 0,
            "DownloadError": "",
            "ValidationError": "",
            "DiskLimit": 0,
            "FailedSibling": "",
            "VaultError": "",
            "TaskSignalReason": "",
            "TaskSignal": "",
            "DriverMessage": ""
          }
        ]
      }
    },
    "CreateIndex": 9,
    "ModifyIndex": 13,
    "CreateTime": 1495755675944527600,
    "ModifyTime": 1495755675944527600
  }
]

List Job Evaluations

This endpoint reads information about a single job's evaluations

MethodPathProduces
GET/v1/job/:job_id/evaluationsapplication/json

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking QueriesACL Required
YESnamespace:read-job

Parameters

  • :job_id (string: <required>) - Specifies the ID of the job (as specified in the job file during submission). This is specified as part of the path.

  • namespace (string: "default") - Specifies the target namespace. If ACL is enabled, this value must match a namespace that the token is allowed to access. This is specified as a query string parameter.

Sample Request

$ curl \
    https://localhost:4646/v1/job/my-job/evaluations

Sample Response

[
  {
    "ID": "a9c5effc-2242-51b2-f1fe-054ee11ab189",
    "Priority": 50,
    "Type": "service",
    "TriggeredBy": "job-register",
    "JobID": "example",
    "JobModifyIndex": 7,
    "NodeID": "",
    "NodeModifyIndex": 0,
    "Status": "complete",
    "StatusDescription": "",
    "Wait": 0,
    "NextEval": "",
    "PreviousEval": "",
    "BlockedEval": "",
    "FailedTGAllocs": null,
    "ClassEligibility": null,
    "EscapedComputedClass": false,
    "AnnotatePlan": false,
    "QueuedAllocations": {
      "cache": 0
    },
    "SnapshotIndex": 8,
    "CreateIndex": 8,
    "ModifyIndex": 10
  }
]

List Job Deployments

This endpoint lists a single job's deployments

MethodPathProduces
GET/v1/job/:job_id/deploymentsapplication/json

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking QueriesACL Required
YESnamespace:read-job

Parameters

  • :job_id (string: <required>) - Specifies the ID of the job (as specified in the job file during submission). This is specified as part of the path.

  • all (bool: false) - Specifies whether the list of deployments should include deployments from a previously registered job with the same ID. This is possible if the job is deregistered and re-registered.

  • namespace (string: "default") - Specifies the target namespace. If ACL is enabled, this value must match a namespace that the token is allowed to access. This is specified as a query string parameter.

Sample Request

$ curl \
    https://localhost:4646/v1/job/my-job/deployments

Sample Response

[
  {
    "ID": "85ee4a9a-339f-a921-a9ef-0550d20b2c61",
    "JobID": "my-job",
    "JobVersion": 1,
    "JobModifyIndex": 19,
    "JobCreateIndex": 7,
    "TaskGroups": {
      "cache": {
        "AutoRevert": true,
        "Promoted": false,
        "PlacedCanaries": [
          "d0ad0808-2765-abf6-1e15-79fb7fe5a416",
          "38c70cd8-81f2-1489-a328-87bb29ec0e0f"
        ],
        "DesiredCanaries": 2,
        "DesiredTotal": 3,
        "PlacedAllocs": 2,
        "HealthyAllocs": 2,
        "UnhealthyAllocs": 0
      }
    },
    "Status": "running",
    "StatusDescription": "Deployment is running",
    "CreateIndex": 21,
    "ModifyIndex": 25
  },
  {
    "ID": "fb6070fb-4a44-e255-4e6f-8213eba3871a",
    "JobID": "my-job",
    "JobVersion": 0,
    "JobModifyIndex": 7,
    "JobCreateIndex": 7,
    "TaskGroups": {
      "cache": {
        "AutoRevert": true,
        "Promoted": false,
        "PlacedCanaries": null,
        "DesiredCanaries": 0,
        "DesiredTotal": 3,
        "PlacedAllocs": 3,
        "HealthyAllocs": 3,
        "UnhealthyAllocs": 0
      }
    },
    "Status": "successful",
    "StatusDescription": "Deployment completed successfully",
    "CreateIndex": 9,
    "ModifyIndex": 17
  }
]

Read Job's Most Recent Deployment

This endpoint returns a single job's most recent deployment.

MethodPathProduces
GET/v1/job/:job_id/deploymentapplication/json

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking QueriesACL Required
YESnamespace:read-job

Parameters

  • :job_id (string: <required>) - Specifies the ID of the job (as specified in the job file during submission). This is specified as part of the path.

  • namespace (string: "default") - Specifies the target namespace. If ACL is enabled, this value must match a namespace that the token is allowed to access. This is specified as a query string parameter.

Sample Request

$ curl \
    https://localhost:4646/v1/job/my-job/deployment

Sample Response

{
  "ID": "85ee4a9a-339f-a921-a9ef-0550d20b2c61",
  "JobID": "my-job",
  "JobVersion": 1,
  "JobModifyIndex": 19,
  "JobCreateIndex": 7,
  "TaskGroups": {
    "cache": {
      "AutoRevert": true,
      "Promoted": false,
      "PlacedCanaries": [
        "d0ad0808-2765-abf6-1e15-79fb7fe5a416",
        "38c70cd8-81f2-1489-a328-87bb29ec0e0f"
      ],
      "DesiredCanaries": 2,
      "DesiredTotal": 3,
      "PlacedAllocs": 2,
      "HealthyAllocs": 2,
      "UnhealthyAllocs": 0
    }
  },
  "Status": "running",
  "StatusDescription": "Deployment is running",
  "CreateIndex": 21,
  "ModifyIndex": 25
}

Read Job Summary

This endpoint reads summary information about a job.

MethodPathProduces
GET/v1/job/:job_id/summaryapplication/json

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking QueriesACL Required
YESnamespace:read-job

Parameters

  • :job_id (string: <required>) - Specifies the ID of the job (as specified in the job file during submission). This is specified as part of the path.

  • namespace (string: "default") - Specifies the target namespace. If ACL is enabled, this value must match a namespace that the token is allowed to access. This is specified as a query string parameter.

Sample Request

$ curl \
    https://localhost:4646/v1/job/my-job/summary

Sample Response

{
  "JobID": "example",
  "Summary": {
    "cache": {
      "Queued": 0,
      "Complete": 0,
      "Failed": 0,
      "Running": 1,
      "Starting": 0,
      "Lost": 0
    }
  },
  "Children": {
    "Pending": 0,
    "Running": 0,
    "Dead": 0
  },
  "CreateIndex": 7,
  "ModifyIndex": 13
}

Update Existing Job

This endpoint registers a new job or updates an existing job.

MethodPathProduces
POST/v1/job/:job_idapplication/json

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking QueriesACL Required
NOnamespace:submit-job
namespace:sentinel-override if PolicyOverride set

Parameters

  • :job_id (string: <required>) - Specifies the ID of the job (as specified in the job file during submission). This is specified as part of the path.

  • Job (Job: <required>) - Specifies the JSON definition of the job.

  • EnforceIndex (bool: false) - If set, the job will only be registered if the passed JobModifyIndex matches the current job's index. If the index is zero, the register only occurs if the job is new. This paradigm allows check-and-set style job updating.

  • EvalPriority (int: 0) - Override the priority of the evaluations produced as a result of this job update. By default, this is set to the priority of the job.

  • JobModifyIndex (int: 0) - Specifies the JobModifyIndex to enforce the current job is at.

  • PolicyOverride (bool: false) - If set, any soft mandatory Sentinel policies will be overridden. This allows a job to be registered when it would be denied by policy.

  • namespace (string: "default") - Specifies the target namespace. If ACL is enabled, this value must match a namespace that the token is allowed to access. This is specified as a query string parameter.

Sample Payload

{
  "Job": {
    // ...
  },
  "EnforceIndex": true,
  "JobModifyIndex": 4
}

Sample Request

$ curl \
    --request POST \
    --data @payload.json \
    https://localhost:4646/v1/job/my-job

Sample Response

{
  "EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac",
  "EvalCreateIndex": 35,
  "JobModifyIndex": 34
}

Dispatch Job

This endpoint dispatches a new instance of a parameterized job.

MethodPathProduces
POST/v1/job/:job_id/dispatchapplication/json

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking QueriesACL Required
NOnamespace:dispatch-job

Parameters

  • :job_id (string: <required>) - Specifies the ID of the job (as specified in the job file during submission). This is specified as part of the path.

  • IdempotencyToken (string: "") - Optional identifier used to prevent more than one instance of the job from being dispatched. This is specified as a URL query parameter.

  • IdPrefixTemplate (string: "") - Optional prefix added to dispatched job IDs.

  • Payload (string: "") - Specifies a base64 encoded string containing the payload. This is limited to 16384 bytes (16KiB).

  • Meta (meta<string|string>: nil) - Specifies arbitrary metadata to pass to the job.

  • namespace (string: "default") - Specifies the target namespace. If ACL is enabled, this value must match a namespace that the token is allowed to access. This is specified as a query string parameter.

Sample Payload

{
  "Payload": "A28C3==",
  "Meta": {
    "key": "Value"
  }
}

Sample Request

$ curl \
    --request POST \
    --data @payload.json \
    https://localhost:4646/v1/job/my-job/dispatch

Sample Response

{
  "Index": 13,
  "JobCreateIndex": 12,
  "EvalCreateIndex": 13,
  "EvalID": "e5f55fac-bc69-119d-528a-1fc7ade5e02c",
  "DispatchedJobID": "example/dispatch-1485408778-81644024"
}

Revert to older Job Version

This endpoint reverts the job to an older version.

MethodPathProduces
POST/v1/job/:job_id/revertapplication/json

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking QueriesACL Required
NOnamespace:submit-job

Parameters

  • JobID (string: <required>) - Specifies the ID of the job (as specified in the job file during submission). This is specified as part of the path.

  • JobVersion (integer: 0) - Specifies the job version to revert to.

  • EnforcePriorVersion (integer: nil) - Optional value specifying the current job's version. This is checked and acts as a check-and-set value before reverting to the specified job.

  • ConsulToken (string:"") - Optional value specifying the consul token used for Consul service identity polity authentication checking.

  • VaultToken (string: "") - Optional value specifying the vault token used for Vault policy authentication checking.

  • namespace (string: "default") - Specifies the target namespace. If ACL is enabled, this value must match a namespace that the token is allowed to access. This is specified as a query string parameter.

Sample Payload

{
  "JobID": "my-job",
  "JobVersion": 2
}

Sample Request

$ curl \
    --request POST \
    --data @payload.json \
    https://localhost:4646/v1/job/my-job/revert

Sample Response

{
  "EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac",
  "EvalCreateIndex": 35,
  "JobModifyIndex": 34
}

Set Job Stability

This endpoint sets the job's stability.

MethodPathProduces
POST/v1/job/:job_id/stableapplication/json

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking QueriesACL Required
NOnamespace:submit-job

Parameters

  • JobID (string: <required>) - Specifies the ID of the job (as specified in the job file during submission). This is specified as part of the path.

  • JobVersion (integer: 0) - Specifies the job version to set the stability on.

  • Stable (bool: false) - Specifies whether the job should be marked as stable or not.

  • namespace (string: "default") - Specifies the target namespace. If ACL is enabled, this value must match a namespace that the token is allowed to access. This is specified as a query string parameter.

Sample Payload

{
  "JobID": "my-job",
  "JobVersion": 2,
  "Stable": true
}

Sample Request

$ curl \
    --request POST \
    --data @payload.json \
    https://localhost:4646/v1/job/my-job/stable

Sample Response

{
  "JobModifyIndex": 34
}

Create Job Evaluation

This endpoint creates a new evaluation for the given job. This can be used to force run the scheduling logic if necessary. Since Nomad 0.8.4, this endpoint supports a JSON payload with additional options. Support for calling this end point without a JSON payload will be removed in Nomad 0.9.

MethodPathProduces
POST/v1/job/:job_id/evaluateapplication/json

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking QueriesACL Required
NOnamespace:read-job

Parameters

  • :job_id (string: <required>) - Specifies the ID of the job (as specified in the job file during submission). This is specified as part of the path.

  • JobID (string: <required>) - Specify the ID of the job in the JSON payload

  • EvalOptions (<optional>) - Specify additional options to be used during the forced evaluation.

    • ForceReschedule (bool: false) - If set, failed allocations of the job are rescheduled immediately. This is useful for operators to force immediate placement even if the failed allocations are past their rescheduling limit, or are delayed by several hours because the allocation's reschedule policy has exponential delay.

  • namespace (string: "default") - Specifies the target namespace. If ACL is enabled, this value must match a namespace that the token is allowed to access. This is specified as a query string parameter.

Sample Payload

{
  "JobID": "my-job",
  "EvalOptions": {
    "ForceReschedule": true
  }
}

Sample Request

$ curl \
    --request POST \
    -d @sample.json \
    https://localhost:4646/v1/job/my-job/evaluate

Sample Response

{
  "EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac",
  "EvalCreateIndex": 35,
  "JobModifyIndex": 34
}

Create Job Plan

This endpoint invokes a dry-run of the scheduler for the job.

MethodPathProduces
POST/v1/job/:job_id/planapplication/json

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking QueriesACL Required
NOnamespace:submit-job
namespace:sentinel-override if PolicyOverride set

Parameters

  • :job_id (string: <required>) - Specifies the ID of the job (as specified in

  • the job file during submission). This is specified as part of the path.

  • Job (string: <required>) - Specifies the JSON definition of the job.

  • Diff (bool: false) - Specifies whether the diff structure between the submitted and server side version of the job should be included in the response.

  • PolicyOverride (bool: false) - If set, any soft mandatory Sentinel policies will be overridden. This allows a job to be registered when it would be denied by policy.

  • namespace (string: "default") - Specifies the target namespace. If ACL is enabled, this value must match a namespace that the token is allowed to access. This is specified as a query string parameter.

Sample Payload

{
  "Job": {
    // ...
  },
  "Diff": true,
  "PolicyOverride": false
}

Sample Request

$ curl \
    --request POST \
    --data @payload.json \
    https://localhost:4646/v1/job/my-job/plan

Sample Response

{
  "Index": 0,
  "NextPeriodicLaunch": "0001-01-01T00:00:00Z",
  "Warnings": "",
  "Diff": {
    "Type": "Added",
    "TaskGroups": [
      {
        "Updates": {
          "create": 1
        },
        "Type": "Added",
        "Tasks": [
          {
            "Type": "Added",
            "Objects": ["..."],
            "Name": "redis",
            "Fields": [
              {
                "Type": "Added",
                "Old": "",
                "New": "docker",
                "Name": "Driver",
                "Annotations": null
              },
              {
                "Type": "Added",
                "Old": "",
                "New": "5000000000",
                "Name": "KillTimeout",
                "Annotations": null
              }
            ],
            "Annotations": ["forces create"]
          }
        ],
        "Objects": ["..."],
        "Name": "cache",
        "Fields": ["..."]
      }
    ],
    "Objects": [
      {
        "Type": "Added",
        "Objects": null,
        "Name": "Datacenters",
        "Fields": ["..."]
      },
      {
        "Type": "Added",
        "Objects": null,
        "Name": "Constraint",
        "Fields": ["..."]
      },
      {
        "Type": "Added",
        "Objects": null,
        "Name": "Update",
        "Fields": ["..."]
      }
    ],
    "ID": "example",
    "Fields": ["..."]
  },
  "CreatedEvals": [
    {
      "ModifyIndex": 0,
      "CreateIndex": 0,
      "SnapshotIndex": 0,
      "AnnotatePlan": false,
      "EscapedComputedClass": false,
      "NodeModifyIndex": 0,
      "NodeID": "",
      "JobModifyIndex": 0,
      "JobID": "example",
      "TriggeredBy": "job-register",
      "Type": "batch",
      "Priority": 50,
      "ID": "312e6a6d-8d01-0daf-9105-14919a66dba3",
      "Status": "blocked",
      "StatusDescription": "created to place remaining allocations",
      "Wait": 0,
      "NextEval": "",
      "PreviousEval": "80318ae4-7eda-e570-e59d-bc11df134817",
      "BlockedEval": "",
      "FailedTGAllocs": null,
      "ClassEligibility": {
        "v1:7968290453076422024": true
      }
    }
  ],
  "JobModifyIndex": 0,
  "FailedTGAllocs": {
    "cache": {
      "CoalescedFailures": 3,
      "AllocationTime": 46415,
      "Scores": null,
      "NodesEvaluated": 1,
      "NodesFiltered": 0,
      "NodesAvailable": {
        "dc1": 1
      },
      "ClassFiltered": null,
      "ConstraintFiltered": null,
      "NodesExhausted": 1,
      "ClassExhausted": null,
      "DimensionExhausted": {
        "cpu": 1
      }
    }
  },
  "Annotations": {
    "DesiredTGUpdates": {
      "cache": {
        "DestructiveUpdate": 0,
        "InPlaceUpdate": 0,
        "Stop": 0,
        "Migrate": 0,
        "Place": 11,
        "Ignore": 0
      }
    }
  }
}

Field Reference

  • Diff - A diff structure between the submitted job and the server side version. The top-level object is a Job Diff which contains Task Group Diffs, which in turn contain Task Diffs. Each of these objects then has Object and Field Diff structures embedded.

  • NextPeriodicLaunch - If the job being planned is periodic, this field will include the next launch time for the job.

  • CreatedEvals - A set of evaluations that were created as a result of the dry-run. These evaluations can signify a follow-up rolling update evaluation or a blocked evaluation.

  • JobModifyIndex - The JobModifyIndex of the server side version of this job.

  • FailedTGAllocs - A set of metrics to understand any allocation failures that occurred for the Task Group.

  • Annotations - Annotations include the DesiredTGUpdates, which tracks what

  • the scheduler would do given enough resources for each Task Group.

Force New Periodic Instance

This endpoint forces a new instance of the periodic job. A new instance will be created even if it violates the job's prohibit_overlap settings. As such, this should be only used to immediately run a periodic job.

MethodPathProduces
POST/v1/job/:job_id/periodic/forceapplication/json

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking QueriesACL Required
NOnamespace:dispatch-job or namespace:submit-job

Parameters

  • :job_id (string: <required>) - Specifies the ID of the job (as specified in the job file during submission). This is specified as part of the path.

Sample Request

$ curl \
    --request POST \
    https://localhost:4646/v1/job/my-job/periodic/force

Sample Response

{
  "EvalCreateIndex": 7,
  "EvalID": "57983ddd-7fcf-3e3a-fd24-f699ccfb36f4"
}

Stop a Job

This endpoint deregisters a job, and stops all allocations part of it.

MethodPathProduces
DELETE/v1/job/:job_idapplication/json

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking QueriesACL Required
NOnamespace:submit-job

Parameters

  • :job_id (string: <required>) - Specifies the ID of the job (as specified in the job file during submission). This is specified as part of the path.

  • eval_priority (int: 0) - Override the priority of the evaluations produced as a result of this job deregistration. By default, this is set to the priority of the job.

  • global (bool: false) - Stop a multi-region job in all its regions. By default, job stop will stop only a single region at a time. Ignored for single-region jobs.

  • purge (bool: false) - Specifies that the job should be stopped and purged immediately. This means the job will not be queryable after being stopped. If not set, the job will be purged by the garbage collector.

  • namespace (string: "default") - Specifies the target namespace. If ACL is enabled, this value must match a namespace that the token is allowed to access. This is specified as a query string parameter.

  • no_shutdown_delay (bool: false) - Ignore the group and task shutdown_delay configuration so that there is no delay between service deregistration and task shutdown. Note that using this flag will result in failed network connections to the allocations being stopped.

Sample Request

$ curl \
    --request DELETE \
    https://localhost:4646/v1/job/my-job?purge=true

Sample Response

{
  "EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac",
  "EvalCreateIndex": 35,
  "JobModifyIndex": 34
}

Read Job Scale Status

This endpoint reads scale information about a job.

MethodPathProduces
GET/v1/job/:job_id/scaleapplication/json

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking QueriesACL Required
YESnamespace:read-job-scaling or namespace:read-job

Parameters

  • :job_id (string: <required>) - Specifies the ID of the job (as specified in the job file during submission). This is specified as part of the path.

  • namespace (string: "default") - Specifies the target namespace. If ACL is enabled, this value must match a namespace that the token is allowed to access. This is specified as a query string parameter.

Sample Request

$ curl \
    https://localhost:4646/v1/job/my-job/scale

Sample Response

{
  "JobCreateIndex": 10,
  "JobID": "example",
  "Namespace": "default",
  "JobModifyIndex": 18,
  "JobStopped": false,
  "TaskGroups": {
    "cache": {
      "Desired": 1,
      "Events": null,
      "Healthy": 1,
      "Placed": 1,
      "Running": 0,
      "Unhealthy": 0
    }
  }
}

Scale Task Group

This endpoint performs a scaling action against a job. Currently, this endpoint supports scaling the count for a task group. This will return a 400 error if the job has an active deployment.

MethodPathProduces
POST/v1/job/:job_id/scaleapplication/json

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking QueriesACL Required
NOnamespace:scale-job or namespace:submit-job
namespace:sentinel-override if PolicyOverride set

Parameters

  • :job_id (string: <required>) - Specifies the ID of the job (as specified in the job file during submission). This is specified as part of the path.

  • Count (int: <optional>) - Specifies the new task group count.

  • Target (json: required) - JSON map containing the target of the scaling operation. Must contain a field Group with the name of the task group that is the target of this scaling action.

  • Message (string: <optional>) - Description of the scale action, persisted as part of the scaling event. Indicates information or reason for scaling; one of Message or Error must be provided.

  • Error (string: <optional>) - Description of the scale action, persisted as part of the scaling event. Indicates an error state preventing scaling; one of Message or Error must be provided.

  • Meta (json: <optional>) - JSON block that is persisted as part of the scaling event.

  • PolicyOverride (bool: false) - If set, any soft mandatory Sentinel policies will be overridden. This allows a job to be scaled when it would be denied by policy.

  • namespace (string: "default") - Specifies the target namespace. If ACL is enabled, this value must match a namespace that the token is allowed to access. This is specified as a query string parameter.

Sample Payload

{
    "Count": 5,
    "Meta": {
        "metrics": [
            "cpu",
            "memory"
        ]
    },
    "Message": "metric did not satisfy SLA",
    "Target": {
        "Group": "cache"
    }
}

Sample Request

$ curl \
    --request POST \
    --data @payload.json \
    https://localhost:4646/v1/job/example/scale

Sample Response

This is the same payload as returned by job update. EvalCreateIndex and EvalID will only be present if the scaling operation resulted in the creation of an evaluation.

{
  "EvalCreateIndex": 45,
  "EvalID": "116f3ede-f6a5-f6e7-2d0e-1fda136390f0",
  "Index": 45,
  "JobModifyIndex": 44,
  "KnownLeader": false,
  "LastContact": 0,
  "Warnings": ""
}

Job Services

The endpoint is used to read all services registered within Nomad belonging to the passed job ID.

MethodPathProduces
GET/job/:job_id/servicesapplication/json

The table below shows this endpoint's support for blocking queries, consistency modes and required ACLs.

Blocking QueriesConsistency ModesACL Required
YESallnamespace:read-job

Parameters

  • :job_id (string: <required>) - Specifies the ID of the job (as specified in the job file during submission). This is specified as part of the path.

  • namespace (string: "default") - Specifies the target namespace.

Sample Request

$ curl \
    https://localhost:4646/v1/job/example/services

Sample Response

[
  {
    "Address": "127.0.0.1",
    "AllocID": "177160af-26f6-619f-9c9f-5e46d1104395",
    "CreateIndex": 14,
    "Datacenter": "dc1",
    "ID": "_nomad-task-177160af-26f6-619f-9c9f-5e46d1104395-redis-example-cache-redis-db",
    "JobID": "example",
    "ModifyIndex": 24,
    "Namespace": "default",
    "NodeID": "7406e90b-de16-d118-80fe-60d0f2730cb3",
    "Port": 29702,
    "ServiceName": "example-cache-redis",
    "Tags": [
      "db",
      "cache"
    ]
  }
]