{"id":13785578,"url":"https://github.com/seatgeek/nomad-helper","last_synced_at":"2025-06-23T01:05:33.801Z","repository":{"id":22154438,"uuid":"95240965","full_name":"seatgeek/nomad-helper","owner":"seatgeek","description":"Useful tools for working with @hashicorp Nomad at scale","archived":false,"fork":false,"pushed_at":"2023-05-08T10:14:36.000Z","size":457,"stargazers_count":157,"open_issues_count":5,"forks_count":15,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-04-02T06:43:14.248Z","etag":null,"topics":["hashicorp","hashicorp-nomad","nomad"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/seatgeek.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2017-06-23T17:17:51.000Z","updated_at":"2025-03-14T17:03:57.000Z","dependencies_parsed_at":"2024-01-08T01:44:53.095Z","dependency_job_id":"83a8eed4-e142-4a09-bae6-877585ac9c91","html_url":"https://github.com/seatgeek/nomad-helper","commit_stats":null,"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/seatgeek/nomad-helper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seatgeek%2Fnomad-helper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seatgeek%2Fnomad-helper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seatgeek%2Fnomad-helper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seatgeek%2Fnomad-helper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/seatgeek","download_url":"https://codeload.github.com/seatgeek/nomad-helper/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seatgeek%2Fnomad-helper/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261392004,"owners_count":23151708,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hashicorp","hashicorp-nomad","nomad"],"created_at":"2024-08-03T19:01:02.035Z","updated_at":"2025-06-23T01:05:28.784Z","avatar_url":"https://github.com/seatgeek.png","language":"Go","funding_links":[],"categories":["Infrastructure setup"],"sub_categories":["Automation and Infrastructure Management"],"readme":"# nomad-helper\n\n- [nomad-helper](#nomad-helper)\n- [Running](#running)\n- [Requirements](#requirements)\n- [Building](#building)\n- [Configuration](#configuration)\n- [Installation](#installation)\n    - [Binary](#binary)\n    - [Source](#source)\n- [Usage](#usage)\n    - [attach](#attach)\n    - [tail](#tail)\n    - [namespace](#namespace)\n        - [gc](#gc)\n    - [node](#node)\n        - [Filter examples](#filter-examples)\n        - [drain](#drain)\n            - [Examples](#examples)\n        - [eligibility](#eligibility)\n            - [Examples](#examples-1)\n        - [breakdown](#breakdown)\n        - [list](#list)\n        - [discover](#discover)\n    - [job](#job)\n        - [stop](#stop)\n        - [move](#move)\n        - [hunt](#hunt)\n    - [scale](#scale)\n        - [export](#export)\n        - [import](#import)\n        - [Example Scale config](#example-scale-config)\n    - [server](#server)\n    - [reevaluate-all](#reevaluate-all)\n    - [gc](#gc)\n\n`nomad-helper` is a tool meant to enable teams to quickly onboard themselves with nomad, by exposing scaling functionality in a simple to use and share yaml format.\n\n# Running\n\nThe project has build artifacts for linux, darwin and windows in the [GitHub releases tab](https://github.com/seatgeek/nomad-helper/releases).\n\nA docker container is also provided at [seatgeek/nomad-helper](https://hub.docker.com/r/seatgeek/nomad-helper/tags/)\n\n# Requirements\n\n- Go 1.13.1\n\n# Building\n\nRecommend environment variables\n\n```sh\nexport GO111MODULE=on\nexport GOPROXY=https://proxy.golang.org\n```\n\nTo build a binary, run the following\n\n```shell\n# get this repo\ngo get github.com/seatgeek/nomad-helper\n\n# go to the repo directory\ncd $GOPATH/src/github.com/seatgeek/nomad-helper\n\n# install the `nomad-helper` binary into $GOPATH/bin\nmake install\n\n# install the `nomad-helper` binary ./build/nomad-helper-${GOOS}-${GOARCH}\nmake install\n```\n\nThis will create a `nomad-helper` binary in your `$GOPATH/bin` directory.\n\n# Configuration\n\nAny `NOMAD_*` env that the native `nomad` CLI tool supports are supported by this tool.\n\nThe most basic requirement is `export NOMAD_ADDR=http://\u003cip\u003e:4646`.\n\n# Installation\n\n## Binary\n\n- Download the binary from [the release page](https://github.com/seatgeek/nomad-helper/releases)\n- Use docker (`seatgeek/nomad-helper`)\n\n## Source\n\n- make sure Go 1.10+ is installed (`brew install go`)\n- clone the repo into `$GOPATH/src/github.com/seatgeek/nomad-helper`\n- make install\n- `go install` / `go build` / `make build`\n\n# Usage\n\nThe `nomad-helper` binary has several helper subcommands.\n\n## attach\n\nAutomatically handle discovery of allocation host IP by CLI filters or interactive shell and ssh + attach to the running container.\n\nThe tool assume you can SSH to the instance and your `~/.ssh/config` is configured with the right configuration for doing so.\n\n```\nNAME:\n   nomad-helper attach - attach to a specific allocation\n\nUSAGE:\n   nomad-helper attach [command options] [arguments...]\n\nOPTIONS:\n   --job value      List allocations for the job and attach to the selected allocation\n   --alloc value    Partial UUID or the full 36 char UUID to attach to\n   --task value     Task name to auto-select if the allocation has multiple tasks in the allocation group\n   --host           Connect to the host directly instead of attaching to a container\n   --command value  Command to run when attaching to the container (default: \"bash\")\n```\n\n## tail\n\nAutomatically handle discovery of allocation and tail both `stdout` and `stderr` at the same time\n\n```\nNAME:\n   nomad-helper tail - tail stdout/stderr from nomad alloc\n\nUSAGE:\n   nomad-helper tail [command options] [arguments...]\n\nOPTIONS:\n   --job value    (optional) list allocations for the job and attach to the selected allocation\n   --alloc value  (optional) partial UUID or the full 36 char UUID to attach to\n   --task value   (optional) the task name to auto-select if the allocation has multiple tasks in the allocation group\n   --stderr       (optional, default: true) tail stderr from nomad\n   --stdout       (optional, default: true) tail stdout from nomad\n```\n\n## namespace\n\nnamespace specific commands\n\n### gc\n\n```\nNAME:\n   nomad-helper namespace gc - Cleans up empty namespaces\n\nUSAGE:\n   nomad-helper namespace gc [command options] [arguments...]\n\nOPTIONS:\n   --dry  Dry run, just print actions\n   --ignore-job value  Ignore a job ID when marking a namespace as empty. Can be provided multiple times.\n```\n\nIf jobs are ignored when removing a namespace, those jobs will be deleted _prior to_ the namespace being removed. A Nomad GC call will be run after any ignored jobs are removed to ensure that the removed state is synced to the cluster.\n\n## node\n\nnode specific commands that act on all Nomad clients that match the filters provided, rather than a single node\n\n```\nNAME:\n   nomad-helper node - node specific commands that act on all Nomad clients that match the filters provided, rather than a single node\n\nUSAGE:\n   nomad-helper node command [command options] [arguments...]\n\nCOMMANDS:\n     drain                  The node drain command is used to toggle drain mode on a given node. Drain mode prevents any new tasks from being allocated to the node, and begins migrating all existing allocations away\n     eligibility, eligible  The eligibility command is used to toggle scheduling eligibility for a given node. By default node's are eligible for scheduling meaning they can receive placements and run new allocations. Node's that have their scheduling eligibility disabled are ineligible for new placements.\n\nOPTIONS:\n   --filter-prefix ef30d57c                                   Filter nodes by their ID with prefix matching ef30d57c\n   --filter-class batch-jobs                                  Filter nodes by their node class batch-jobs\n   --filter-version 0.8.4                                     Filter nodes by their Nomad version 0.8.4\n   --filter-eligibility                                       Filter nodes by their scheduling eligibility\n   --percent                                                  Filter only specific percent of nodes\n   --filter-meta 'aws.instance.availability-zone=us-east-1e'  Filter nodes by their meta key/value like 'aws.instance.availability-zone=us-east-1e'. Can be provided multiple times.\n   --filter-attribute 'driver.docker.version=17.09.0-ce'      Filter nodes by their attribute key/value like 'driver.docker.version=17.09.0-ce'. Can be provided multiple times.\n   --noop                                                     Only output nodes that would be drained, don't do any modifications\n   --help, -h                                                 show help\n```\n\n### Filter examples\n\n- `nomad-helper node \u003ccommand\u003e \u003cargs\u003e`\n- `nomad-helper node --noop --filter-meta 'aws.instance.availability-zone=us-east-1e'  --filter-attribute 'driver.docker.version=17.09.0-ce' \u003ccommand\u003e \u003cargs\u003e`\n\n### drain\n\nFiltering options can be found in the main `node` command help above\n\n```\nUSAGE:\n   nomad-helper node [filter options] drain [command options] [arguments...]\n\nOPTIONS:\n   --enable           Enable node drain mode\n   --disable          Disable node drain mode\n   --deadline value   Set the deadline by which all allocations must be moved off the node. Remaining allocations after the deadline are force removed from the node. Defaults to 1 hour (default: 1h0m0s)\n   --no-deadline      No deadline allows the allocations to drain off the node without being force stopped after a certain deadline\n   --monitor          Enter monitor mode directly without modifying the drain status\n   --force            Force remove allocations off the node immediately\n   --detach           Return immediately instead of entering monitor mode\n   --ignore-system    Ignore system allows the drain to complete without stopping system job allocations. By default system jobs are stopped last.\n   --keep-ineligible  Keep ineligible will maintain the node's scheduling ineligibility even if the drain is being disabled. This is useful when an existing drain is being cancelled but additional scheduling on the node is not desired.\n   --with-benefits    Instead of flipping the regular drain flag it will make instance ineligible and will add a desired constraint to the task groups found on the node\n        --constraint\n        --operand\n        --value\n        --wait-for-pending  will wait for all the moved jobs to reach running state\n```\n\n#### Examples\n\n- `nomad-helper node drain --enable`\n- `nomad-helper node --filter-class wrecker --filter-meta 'aws.ami-version=2.0.0-alpha14' --filter-meta 'aws.instance.availability-zone=us-east-1e' drain --noop --enable`\n- `node --filter-meta \"aws.ami-version=1.9.6\" drain --enable --with-benefits --constraint meta.aws.ami-version --operand '=' --value 1.9.8 --wait-for-pending`\n\n### eligibility\n\nFiltering options can be found in the main `node` command help above\n\n```\nNAME:\n   nomad-helper node eligibility - The eligibility command is used to toggle scheduling eligibility for a given node. By default node's are eligible for scheduling meaning they can receive placements and run new allocations. Node's that have their scheduling eligibility disabled are ineligible for new placements.\n\nUSAGE:\n   nomad-helper node [filter options] eligibility [command options] [arguments...]\n\nOPTIONS:\n   --enable   Enable scheduling eligibility\n   --disable  Disable scheduling eligibility\n```\n\n#### Examples\n\n- `nomad-helper node eligibility --enable`\n- `nomad-helper node --filter-class wrecker --filter-meta 'aws.ami-version=2.0.0-alpha14' --filter-meta 'aws.instance.availability-zone=us-east-1e' eligibility --enable`\n\n### Breakdown\n\n```\nNAME:\n   nomad-helper node breakdown - Break down (count) how many Nomad clients that match a list of key properties\n\nUSAGE:\n   nomad-helper node [filters...] breakdown [command options] [keys...]\n\nDESCRIPTION:\n\n  ** Arguments **\n\n    * attribute.key will look up key in the \"Attributes\" Nomad client property\n    * hostname is an alias for attribute.unique.hostname\n    * ip / address / ip-address is alias for attribute.unique.network.ip-address\n    * meta.key will look up key in the \"Meta\" Nomad client configuration\n    * class / nodeclass for the Nomad client \"NodeClass\" property\n    * id for the Nomad client \"ID\" property\n    * datacenter / dc for the Nomad client \"Datacenter\" property\n    * drain for the Nomad client \"Drain\" property\n    * status for the Nomad client \"Status\" property\n    * eligibility / schedulingeligibility for the Nomad client \"SchedulingEligibility\" property\n\n  ** Filters **\n\n    --filter-prefix ef30d57c                                   Filter nodes by their ID with prefix matching ef30d57c\n    --filter-class batch-jobs                                  Filter nodes by their node class batch-jobs\n    --filter-version 0.8.4                                     Filter nodes by their Nomad version 0.8.4\n    --filter-eligibility eligible/ineligible                   Filter nodes by their eligibility status eligible/ineligible\n    --filter-meta 'aws.instance.availability-zone=us-east-1e'  Filter nodes by their meta key/value like 'aws.instance.availability-zone=us-east-1e'. Flag can be repeated.\n    --filter-attribute 'driver.docker.version=17.09.0-ce'      Filter nodes by their attribute key/value like 'driver.docker.version=17.09.0-ce'. Flag can be repeated.\n\n  ** Examples **\n\n    * nomad-helper node breakdown class status\n    * nomad-helper node breakdown attribute.nomad.version attribute.driver.docker\n    * nomad-helper node breakdown meta.aws.instance.region attribute.nomad.version\n\n\nOPTIONS:\n   --output-format value  Either \"table\", \"json\" or \"json-pretty\" (default: \"table\")\n```\n\n### List\n\n```\nNAME:\n   nomad-helper node list - Output list of key properties for a Nomad client\n\nUSAGE:\n   nomad-helper node [filters...] list [command options] [keys...]\n\nDESCRIPTION:\n\n  ** Arguments **\n\n    * attribute.key will look up key in the \"Attributes\" Nomad client property\n    * hostname is an alias for attribute.unique.hostname\n    * ip / address / ip-address is alias for attribute.unique.network.ip-address\n    * meta.key will look up key in the \"Meta\" Nomad client configuration\n    * class / nodeclass for the Nomad client \"NodeClass\" property\n    * id for the Nomad client \"ID\" property\n    * datacenter / dc for the Nomad client \"Datacenter\" property\n    * drain for the Nomad client \"Drain\" property\n    * status for the Nomad client \"Status\" property\n    * eligibility / schedulingeligibility for the Nomad client \"SchedulingEligibility\" property\n\n  ** Filters **\n\n    --filter-prefix ef30d57c                                   Filter nodes by their ID with prefix matching ef30d57c\n    --filter-class batch-jobs                                  Filter nodes by their node class batch-jobs\n    --filter-version 0.8.4                                     Filter nodes by their Nomad version 0.8.4\n    --filter-eligibility eligible/ineligible                   Filter nodes by their eligibility status eligible/ineligible\n    --filter-meta 'aws.instance.availability-zone=us-east-1e'  Filter nodes by their meta key/value like 'aws.instance.availability-zone=us-east-1e'. Flag can be repeated.\n    --filter-attribute 'driver.docker.version=17.09.0-ce'      Filter nodes by their attribute key/value like 'driver.docker.version=17.09.0-ce'. Flag can be repeated.\n\n  ** Examples **\n\n    * nomad-helper node list class status\n    * nomad-helper node list attribute.nomad.version attribute.driver.docker\n    * nomad-helper node list meta.aws.instance.region attribute.nomad.version\n\n\nOPTIONS:\n   --output-format table, json or json-pretty  Either table, json or json-pretty (default: \"table\")\n```\n\n### Discover\n\n```\nNAME:\n   nomad-helper node discover - Output the Nomad client Meta and Attribute fields present in your cluster\n\nUSAGE:\n   nomad-helper node [filters...] discover [command options]\n\nOPTIONS:\n   --output-format value  Either \"table\", \"json\" or \"json-pretty\" (default: \"table\")\n```\n\n\n## job\n\njob specific commands\n\n```\nNAME:\n   nomad-helper job - job specific commands with a twist\n\nUSAGE:\n   nomad-helper job stop [command options] [arguments...]\n\nCOMMANDS:\n     stop   Stop will stop the job with the ability to purge the job from the nomad cluster\n     move   Move will add/append a constraint to the job that will resolve to moving the job\n     hunt   Hunt will look for the jobs with discrepancy in job version between allocations\n\nOPTIONS:\n   --help, -h                                                 show help\n```\n\n### stop\n\n```\nUSAGE:\n   nomad-helper job stop [job_name] [command options]\n\nOPTIONS:\n   --as-prefix  Filter jobs by their name with prefix matching api-\n   --dry        Only output jobs that would be stopped, don't do any modifications\n```\n\n#### Examples\n\n- `nomad-helper job stop api`\n- `nomad-helper job stop api --as-prefix`\n- `nomad-helper job stop api --as-prefix --dry`\n\n\n### move\n\n```\nUSAGE:\n   nomad-helper job stop [job_name] [command options]\n\nOPTIONS:\n   --as-prefix  Filter jobs by their name with prefix matching api-\n   --constraint Constraint attribute\n   --operand    Constraint operator\n   --value      Constraint value\n   --dry        Only output jobs that would be stopped, don't do any modifications\n```\n\n#### Examples\n\n- `job move api --constraint meta.aws.ami-version --operand = --value 1.9.1 --exclude core`\n- `job move api --as-prefix --constraint meta.aws.ami-version --operand = --value 1.9.1 --exclude core`\n\n### hunt\n\n```\nUSAGE:\n   nomad-helper job hunt\n```\n\n#### Examples\n\n- `job hunt`\n\n## scale\n\n```\nNAME:\n   nomad-helper scale - Import / Export job -\u003e group -\u003e count values\n\nUSAGE:\n   nomad-helper scale command [command options] [arguments...]\n\nCOMMANDS:\n     export  Export nomad job scale config to a local file from Nomad cluster\n     import  Import nomad job scale config from a local file to Nomad cluster\n\nOPTIONS:\n   --help, -h  show help\n```\n\n### export\n\n`nomad-helper scale export production.yml` will read the Nomad cluster `job  + group + count` values and write them to a local `production.yml` file.\n\n```\nNAME:\n   nomad-helper scale export - Export nomad job scale config to a local file from Nomad cluster\n\nUSAGE:\n   nomad-helper scale export [arguments...]\n```\n\n### import\n\n`nomad-helper scale import production.yml` will update the Nomad cluster `job + group + count` values according to the values in a local `production.yaml` file.\n\n```\nNAME:\n   nomad-helper scale import - Import nomad job scale config from a local file to Nomad cluster\n\nUSAGE:\n   nomad-helper scale import [arguments...]\n```\n\n### Example Scale config\n\n```yml\ninfo:\n  exported_at: Thu, 29 Jun 2017 13:11:19 +0000\n  exported_by: jippi\n  nomad_addr: http://nomad.service.consul:4646\njobs:\n  nginx:\n    server: 10\n  api-es:\n    api-es-1: 1\n    api-es-2: 1\n    api-es-3: 1\n```\n\n## Server\n\n```\nNAME:\n   nomad-helper server - Run a webserver exposing various endpoints\n\nUSAGE:\n   nomad-helper server [command options] [arguments...]\n\nDESCRIPTION:\n\n  ** Arguments **\n\n    * attribute.key will look up key in the \"Attributes\" Nomad client property\n    * class / nodeclass for the Nomad client \"NodeClass\" property\n    * datacenter / dc for the Nomad client \"Datacenter\" property\n    * drain for the Nomad client \"Drain\" property\n    * eligibility / schedulingeligibility for the Nomad client \"SchedulingEligibility\" property\n    * hostname is an alias for attribute.unique.hostname\n    * id for the Nomad client \"ID\" property\n    * ip / address / ip-address is alias for attribute.unique.network.ip-address\n    * meta.key will look up key in the \"Meta\" Nomad client configuration\n    * name for the Nomad client \"Name\" property\n    * status for the Nomad client \"Status\" property\n\n  ** Filters **\n\n  Filters are always passed as HTTP query arguments, order doesn't matter\n\n    /?filter-attribute=driver.docker.version=17.09.0-ce        Filter nodes by their attribute key/value like 'driver.docker.version=17.09.0-ce'.\n    /?filter-class=batch-jobs                                  Filter nodes by their node class batch-jobs\n    /?filter-eligibility=eligible/ineligible                   Filter nodes by their eligibility status eligible/ineligible\n    /?filter-meta=aws.instance.availability-zone=us-east-1e    Filter nodes by their meta key/value like 'aws.instance.availability-zone=us-east-1e'.\n    /?filter-prefix=ef30d57c                                   Filter nodes by their ID with prefix matching ef30d57c\n    /?filter-version=0.8.4                                     Filter nodes by their Nomad version 0.8.4\n\n  ** Examples **\n\n  Fields are always passed as HTTP path, and processed in order\n\n    * /help\n    * /help/node/breakdown\n    * /help/node/list\n    * /help/node/discover\n    * /help/[command]/[subcommand]\n    * /node/[breakdown|list]/class/status\n    * /node/[breakdown|list]/meta.aws.instance.region/attribute.nomad.version\n    * /node/[breakdown|list]/attribute.nomad.version/attribute.driver.docker\n\n\nOPTIONS:\n   --listen value  (default: \"0.0.0.0:8000\") [$LISTEN]\n```\n\n## reevaluate-all\n\n```\nNAME:\n   nomad-helper reevaluate-all - Force re-evaluate all jobs\n\nUSAGE:\n   nomad-helper reevaluate-all [arguments...]\n```\n\n## gc\n\n```\nNAME:\n   nomad-helper gc - Force a cluster GC\n\nUSAGE:\n   nomad-helper gc [arguments...]\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseatgeek%2Fnomad-helper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fseatgeek%2Fnomad-helper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseatgeek%2Fnomad-helper/lists"}