{"id":21397591,"url":"https://github.com/multani/nomad-pipeline","last_synced_at":"2025-07-13T20:32:19.293Z","repository":{"id":49487396,"uuid":"173946088","full_name":"multani/nomad-pipeline","owner":"multani","description":"A Jenkins plugin to declare and run Jenkins nodes via Nomad","archived":false,"fork":false,"pushed_at":"2021-06-16T17:32:30.000Z","size":227,"stargazers_count":6,"open_issues_count":4,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2023-03-10T19:41:39.073Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/multani.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-03-05T12:52:54.000Z","updated_at":"2022-02-01T21:52:46.000Z","dependencies_parsed_at":"2022-08-24T21:30:48.638Z","dependency_job_id":null,"html_url":"https://github.com/multani/nomad-pipeline","commit_stats":null,"previous_names":[],"tags_count":null,"template":null,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/multani%2Fnomad-pipeline","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/multani%2Fnomad-pipeline/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/multani%2Fnomad-pipeline/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/multani%2Fnomad-pipeline/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/multani","download_url":"https://codeload.github.com/multani/nomad-pipeline/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225916996,"owners_count":17544825,"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":[],"created_at":"2024-11-22T14:43:39.929Z","updated_at":"2024-11-22T14:43:40.450Z","avatar_url":"https://github.com/multani.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"**This is a very early release of this plugin!**\n\nThere are still plenty of bugs a non-implemented features that you may depend\non!\n\n# Nomad Pipeline plugin for Jenkins\n\n[![Build Status](https://travis-ci.org/multani/nomad-pipeline.svg?branch=master)](https://travis-ci.org/multani/nomad-pipeline)\n\nThis is a plugin for Jenkins that runs Jenkins job into the Nomad scheduler, and\nallow the configuration of the Nomad jobs from Jenkins pipelines.\n\nSample job:\n\n```groovy\n\n// Guarantee the node will use this template\ndef label = \"job-${UUID.randomUUID().toString()}\"\n\nnomadJobTemplate(label: label) {\n    node(label) {\n        stage(\"Run shell command\") {\n            echo \"Hello world!\"\n        }\n    }\n}\n```\n\n# How to use?\n\n## Jenkins master configuration\n\nYou first need to install the plugin.\n\nThen, follow the menu *Jenkins* → *Manage Jenkins* → *Configure System*.\n\nIn the *Cloud* section, click on *Add a new cloud* → *Nomad* to configure the\nNomad cloud entry.\n\n![Nomad Plugin configuration](./doc/configuration-screen.png \"Nomad Plugin configuration\")\n\nYou will need to set:\n\n* *Name*: this has to be set to `nomad` for now\n* *Nomad URL*: the URL to your Nomad cluster. It has to be reachable from the\n  Jenkins master\n* *Region*: the default Nomad region you want to launch your job in.\n  See [Regions and\n  Datacenters](https://www.nomadproject.io/docs/internals/architecture.html) in\n  the Nomad documentation.\n* *Datacenters*: the default Nomad datacenters you want to launch your job in.\n  See [Regions and\n  Datacenters](https://www.nomadproject.io/docs/internals/architecture.html) in\n  the Nomad documentation.\n\nYou will then be ready to configure and start a new Jenkins job!\n\n### Authentication Token\n\nIf your Nomad cluster has ACLs enabled, you can configure the plugin to\nauthenticate using a dedicated Nomad token.\n\n* The minimum policy needed by the authenticated persona once connected is:\n\n  ```hcl\n  namespace \"default\" {\n    capabilities = [\"list-jobs\", \"read-job\", \"submit-job\"]\n  }\n  ```\n\n* Once the token has been created and associated with this policy, it can be\n  saved as a new `Secret text` credentials in Jenkins. The credentials can\n  optionaly be associated to the domain of your Nomad cluster.\n\n* Finally, in the plugin configuration panel in *Jenkins* → *Manage Jenkins* →\n  *Configure System*, select the correct credentials in the *Nomad Token* select\n  box.\n\n\n## Jenkins jobs configuration\n\nThe plugin creates a new Nomad job for each agent started and stops it after each build.\n\nThe plugin expects that the agent launched by Nomad will automatically connect\nto the Jenkins master via JNLP (see [Distributed\nbuilds](https://wiki.jenkins.io/display/JENKINS/Distributed+builds)).\n\nFor that purpose, the following environment variables are automatically\ninjected:\n\n* `JENKINS_AGENT_NAME`: the name of the Jenkins agent\n* `JENKINS_JNLP_URL`: the URL for Jenkins agent JNLP configuration file\n* `JENKINS_SECRET`: the secret key for authentication\n* `JENKINS_URL`: the URL to Jenkins web interface\n\nBy default if not specified otherwise, the plugin launches the\n[jenkins/jnlp-slave](https://hub.docker.com/r/jenkins/jnlp-slave) Docker image.\n\nYou can set a more complex configuration, as shown below:\n\n```groovy\n// Guarantee the node will use this template\ndef label = \"job-${UUID.randomUUID().toString()}\"\n\nnomadJobTemplate(\n    label: label,\n    taskGroups: [\n      taskTemplate(\n        name: 'jnlp',\n        image: 'jenkins/jnlp-slave:alpine',\n        resourcesMemory: 2048,\n        resourcesCPU: 1000,\n        envVars: [\n            envVar(key: 'my-super-var', value: '1234'),\n            envVar(key: 'OTHER_VAR', value: 'foobar'),\n        ],\n        auth: auth(username: 'bob', password: '1234', serverAddress: 'my-private-repo:15432')\n    )\n  ]\n) {\n    node(label) {\n        stage(\"Run shell command\") {\n            echo \"Hello world!: ${env.OTHER_VAR}\"\n        }\n    }\n}\n```\n\n# Features\n\n* Specify the Docker image to run your job in your job definition\n* Adjust the resources needed in your job definition\n* Configure environment variables for your whole job\n* Optionally, automatically download the Jenkins agent from the Jenkins master\n\nCurrent limitations:\n\n* This is a very early version!\n* Although it's possible to define multiple tasks within a job, this has not\n  been tested yet\n* Although it's possible to define multiple Nomad jobs in the same Jenkins\n  pipeline, this has not been tested yet.\n* It's currently not possible to configure the agent to receive SSH connection\n  from the Jenkins master.\n* It's not possible to use the plugin using a declarative `Jenkinsfile`\n  configuration file (see #2)\n* Look at [the issues](https://github.com/multani/nomad-pipeline/issues)!\n\n\n## List of settings\n\nTODO: complete me!\n\n\n### `taskTemplate`\n\nThis specifies the values for the Nomad job that will be executed:\n\n* `name`: [name of Nomad task\n  group](https://nomadproject.io/docs/job-specification/group/) to run.\n\n* `image`: [Docker image identifier](https://nomadproject.io/docs/drivers/docker/#inlinecode-image-16) to start.\n\n  The value undergoes variable names expansion. Jenkins environment variables\n  can be specified like this:\n\n  ```groovy\n  image: 'img-repo:5003/repo/my-image:${env.BRANCH_NAME}_${env.BUILD_ID}'\n  ```\n\n  You can also specify container environment variables:\n\n  ```groovy\n  taskGroups: [\n    taskTemplate(\n      name: 'my-task-grp',\n      image: 'img-repo:5003/repo/my-image:${IMAGE_VERSION}'\n    )\n  ],\n  envVars: [\n      envVar(key: 'IMAGE_VERSION', value: '0.1')\n  ]\n  ```\n\n* `resourcesMemory`: [memory\n  resources](https://nomadproject.io/docs/job-specification/resources/#inlinecode-memory-4)\n  allocated for that task.\n\n* `resourcesCPU`: [CPU\n  resources](https://nomadproject.io/docs/job-specification/resources/#inlinecode-cpu-7)\n  allocated for that task.\n\n* `command`: [command to\n  execute](https://nomadproject.io/docs/drivers/docker/#inlinecode-command-9)\n  when running the Docker container.\n\n  The value undergoes the same variable names expansion as in the case of the\n  `image` setting.\n\n* `args`: [arguments to pass to the\n  command](https://nomadproject.io/docs/drivers/docker/#inlinecode-args-13)\n  running the Docker container.\n\n  Each argument list entry undergoes the same variable names expansion as in the\n  case of the `image` setting.\n\n* `downloadAgentJar`: default to `false`. If set, download the slave agent from\n  the Jenkins master at `/jnlpJars/slave.jar` into `/local/slave.jar`, prior to\n  start the Nomad job.\n\n  You can then start the worker using the following command:\n\n  ```\n  java -jar /local/slave.jar -jnlpUrl $JENKINS_JNLP_URL -secret $JENKINS_SECRET'\n  ```\n\n* `auth`: Provide [authentication](https://www.nomadproject.io/docs/drivers/docker/#auth)\n  for a private Docker repository.\n\n  `auth` undergoes the same variable names expansion as in the case of the\n  `image` setting.\n\n\n## Migrating from [Nomad Plugin](https://wiki.jenkins.io/display/JENKINS/Nomad+Plugin)\n\nThere's another [Jenkins plugin for\nNomad](https://wiki.jenkins.io/display/JENKINS/Nomad+Plugin) which has a very\ndifferent approach and doesn't support pipeline jobs defintion.\n\nYou can still use the same Docker image as you were using with the other\nplugin with a few adjustements:\n\n* The other plugin was downloading an agent `jar` file directly from the Jenkins\n  master. This is *not done* automatically by default so you need to set\n  `downloadAgentJar` to `true` to download it into `/local/slave.jar`.\n* The other plugin was starting the Jenkins agent on behalf of the Docker image.\n\n  You will now need to start this agent yourself by setting the right command\n  line in the Nomad job.\n\n```groovy\ndef label = \"job-${UUID.randomUUID().toString()}\"\nnomadJobTemplate(\n    label: label,\n    taskGroups: [\n      taskTemplate(\n        name: 'jnlp',\n        image: 'your/image', // Your previous Docker image\n        // Download the slave agent from the Jenkins master at\n        // http://jenkins-master/jnlpJars/slave.jar\n        downloadAgentJar: true,\n        command: 'sh',\n        args: [\n          '-c',\n          // Start the Jenkins agent:\n          //  * /local/slave.jar is automatically downloaded by Nomad from\n          //    the Jenkins master\n          //  * The JNLP URL and the Jenkins secret is injected by the Jenkins\n          //    Nomad plugin.\n          'java -jar /local/slave.jar -jnlpUrl $JENKINS_JNLP_URL -secret $JENKINS_SECRET',\n        ],\n      )\n    ]\n) {\n  // your build here\n}\n```\n\n\n# Contributing\n\n## How to build?\n\n```\nmvn package\n```\n\n\n## How to run a test environment?\n\nEasy way:\n\n* [download Nomad](https://releases.hashicorp.com/nomad/) and run `nomad agent\n  -dev` on your machine (you need Docker also).\n* then run: `mvn hpi:run -Djetty.consoleForceReload=false -Djava.util.logging.config.file=debug-plugin-logging.properties`\n* wait for Jenkins to start and connect on http://localhost:8080/jenkins/\n* create a new pipeline job with the code from `test-config/test.Jenkinsfile`\n* configure Jenkins, add a new Cloud Provider and set the Server URL to http://localhost:4646\n\n\n# See also\n\nThis plugin is heavily based on the\n[kubernetes-plugin](https://github.com/jenkinsci/kubernetes-plugin) - it actually\nstarted as a fork of the Kubernetes code, replaced by calls to the Nomad API.\n\nYou may also want to have a look at the\n[nomad-plugin](https://github.com/jenkinsci/nomad-plugin/):\n\n* `nomad-pipeline` allows to define how to run a Jenkins worker directly from a\n  `Jenkinsfile` build file, instead of referring to an external definition\n  (configured in the Jenkins master). This give much finer grained opportunities\n  to control the environment in which the build runs at the expense of\n  preventing to have long-running Jenkins worker.\n* https://github.com/jenkinsci/nomad-plugin/issues/20 is the initial issue which\n  prompted for the creation of `nomad-pipeline`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmultani%2Fnomad-pipeline","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmultani%2Fnomad-pipeline","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmultani%2Fnomad-pipeline/lists"}