Summary

This plugin implements a Nextflow executor for Hashicorp Nomad, enabling Nextflow pipelines to execute tasks on Nomad clusters. It is a community-contributed plugin developed collaboratively by Abhinav Sharma, Jorge Aguilera, Tomas, and the Center For Medical Genetics Ghent team.

Get Started

To use this plugin in your Nextflow pipeline, add the following to your nextflow.config file:

plugins {
    id 'nf-nomad'
}

process {
    executor = 'nomad'
}

nomad {
    client {
        address = 'http://your-nomad-server:4646'
    }
}

Unit Testing

Run the following command in the project root directory:

./gradlew check

Test Environment Selection

The Gradle test task supports selecting the target environment with -PtestEnv:

• ./gradlew test → unit tests only
• ./gradlew test -PtestEnv=mock → unit + mock tests
• ./gradlew test -PtestEnv=local → unit + local Nomad integration tests
• ./gradlew test -PtestEnv=oci → unit + OCI Nomad integration tests

For local integration tests with a custom endpoint:

./gradlew test -PtestEnv=local -PnomadAddr=http://<host>:4646

Development Environment Setup

1. Clone the Nextflow repository:

   git clone --depth 1 https://github.com/nextflow-io/nextflow _resources/nextflow
   

2. Generate the nextflow class path:

   cd _resources/nextflow && ./gradlew exportClasspath
   

3. Compile the plugin:

   cd ../../ && ./gradlew compileGroovy
   

4. Run Nextflow with the plugin:

   ./launch.sh run main.nf -plugins nf-nomad
   

Examples

Basic Process Configuration with Custom Resources

The following example demonstrates how to configure a Nextflow pipeline to target a specific process to run on Nomad with customized datacenters and resource limits:

// nextflow.config
plugins {
  id 'nf-nomad'
}

process {
  executor = 'nomad'
  
  withName: runAlignment {
    nomadOptions = [
      datacenters: ['dc-analytics'],
      priority: 'high',
      resources: [
        cores: 8,
        memoryMax: '32 GB'
      ]
    ]
  }
}

Advanced Process-Level Nomad Options

Process directives support map-based nomadOptions for comprehensive control:

process {
  withName: sayHello {
    nomadOptions = [
      datacenters: ['dc1', 'dc2'],
      namespace: 'bio',
      constraints: { node { unique = [name: params.RUN_IN_NODE] } },
      affinity: [attribute: '${meta.workload}', operator: '=', value: 'batch', weight: 25],
      meta: [owner: 'team-x', step: 'align'],
      shutdownDelay: '15s',
      failures: [
        restart: [attempts: 1, delay: '5s', mode: 'fail'],
        reschedule: [attempts: 2, delay: '10s']
      ],
      volumes: [[type: 'host', name: 'ref-data', path: '/ref', readOnly: true]],
      secretsPath: 'secret/projects/team-x',
      secrets: ['MY_ACCESS_KEY', 'MY_SECRET_KEY'],
      spread: [name: 'node.datacenter', weight: 50, targets: ['us-east1': 70, 'us-east2': 30]],
      priority: 'high',
      resources: [memoryMax: '64 GB', cores: 4, device: [[name: 'nvidia/gpu', count: 1]]]
    ]
  }
}

CPU Mode Configuration

Control task concurrency by setting the CPU mode:

nomad {
    jobs {
        cpuMode = 'cpu'     // oversubscribe; default is 'cores'
    }
}

Sizing Configuration for Large Runs

Configure executor queue size and placement failure handling:

executor {
    queueSize = 12          // e.g. one 48-core node, cpus = 4, cpuMode = 'cores'
}

nomad {
    jobs {
        failOnPlacementFailure = true
        placementFailureTimeout = '30m'
    }
}

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.