Mapping Jobs to Destinations

Overview

question Questions
  • How can I configure job dependent resources, like cores, memory for my DRM?

  • How can I map jobs to resources and destinations

objectives Objectives
  • Know how to map tools to job destinations

  • Be able to use the dynamic job runner to make arbitrary destination mappings

  • Understand the job resource selector config and dynamic rule creation

  • The various ways in which tools can be mapped to destinations, both statically and dynamically

  • How to write a dynamic tool destination (DTD)

  • How to write a dynamic python function destination

  • How to use the job resource parameter selection feature

requirements Requirements

time Time estimation: 2 hours

Supporting Materials

last_modification Last modification: Mar 12, 2021

Mapping Jobs

Results may vary

Your results may be slightly different from the ones presented in this tutorial due to differing versions of tools, reference data, external databases, or because of stochastic processes in the algorithms.

This tutorial heavily builds on the Connecting Galaxy to a compute cluster and it’s expected you have completed this tutorial first.

Now that you have a working scheduler, we will start configuring which jobs are sent to which destinations.

Agenda

  1. Mapping Jobs
  2. Galaxy and Slurm - Statically Mapping a Job
    1. Writing a testing tool
    2. Running with more resources
  3. Dynamic Job Destinations
  4. Dynamically map a tool to a job destination
    1. Writing a Dynamic Tool Destination
    2. Testing the DTD
  5. Job Resource Selectors
    1. A dynamic destination
    2. Further Reading

Galaxy and Slurm - Statically Mapping a Job

We don’t want to overload our training VMs trying to run real tools, so to demonstrate how to map a multicore tool to a multicore destination, we’ll create a fake tool.

Writing a testing tool

hands_on Hands-on: Deploying a Tool

  1. Create the directory files/galaxy/tools/ if it doesn’t exist and edit a new file in files/galaxy/tools/testing.xml with the following contents:

    <tool id="testing" name="Testing Tool">
        <command>
            <![CDATA[echo "Running with '\${GALAXY_SLOTS:-1}' threads" > "$output1"]]>
        </command>
        <inputs>
            <param name="input1" type="data" format="txt" label="Input Dataset"/>
        </inputs>
        <outputs>
            <data name="output1" format="txt" />
        </outputs>
    </tool>
    
  2. Add the tool to the Galaxy group variables under the new item galaxy_local_tools :

    --- a/group_vars/galaxyservers.yml
    +++ b/group_vars/galaxyservers.yml
    @@ -71,6 +71,8 @@ galaxy_config_files:
     - src: files/galaxy/config/dependency_resolvers_conf.xml
       dest: ""
    
    +galaxy_local_tools:
    +- testing.xml
    
     # systemd
     galaxy_systemd_mode: mule
    
  3. Run the Galaxy playbook.

    code-in Input: Bash

    ansible-playbook galaxy.yml
    
  4. Reload Galaxy in your browser and the new tool should now appear in the tool panel. If you have not already created a dataset in your history, upload a random text dataset. Once you have a dataset, click the tool’s name in the tool panel, then click Execute.

    question Question

    What is the tool’s output?

    solution Solution

    Running with '1' threads
    

Of course, this tool doesn’t actually use the allocated number of cores. In a real tool, you would call the tools’s underlying command with whatever flag that tool provides to control the number of threads or processes it starts, such as samtools sort -@ \${GALAXY_SLOTS:-1}.

Running with more resources

We want our tool to run with more than one core. To do this, we need to instruct Slurm to allocate more cores for this job. This is done in the job configuration file.

hands_on Hands-on: Allocating more resources

  1. Edit your templates/galaxy/config/job_conf.xml.j2 and add the following destination. Then, map the new tool to the new destination using the tool ID (<tool id="testing">) and destination id (<destination id="slurm-2c">) by adding a new section to the job config, <tools>, below the destinations:

    --- a/templates/galaxy/config/job_conf.xml.j2
    +++ b/templates/galaxy/config/job_conf.xml.j2
    @@ -25,6 +25,13 @@
                 <!-- Singularity uses a temporary directory to build the squashfs filesystem. -->
                 <env id="SINGULARITY_TMPDIR">/tmp</env>
             </destination>
    +        <destination id="slurm-2c" runner="slurm">
    +            <param id="nativeSpecification">--nodes=1 --ntasks=1 --cpus-per-task=2</param>
    +            <param id="singularity_enabled">true</param>
    +            <env id="LC_ALL">C</env>
    +            <env id="SINGULARITY_CACHEDIR">/tmp/singularity</env>
    +            <env id="SINGULARITY_TMPDIR">/tmp</env>
    +        </destination>
             <destination id="pulsar" runner="pulsar_runner" >
                 <param id="default_file_action">remote_transfer</param>
                 <param id="dependency_resolution">remote</param>
    @@ -34,10 +41,10 @@
                 <param id="rewrite_parameters">True</param>
                 <param id="transport">curl</param>
             </destination>
         </destinations>
         <tools>
             <tool id="bwa" destination="pulsar"/>
             <tool id="bwa_mem" destination="pulsar"/>
    +        <tool id="testing" destination="slurm-2c"/>
         </tools>
     </job_conf>
    
  2. Run the Galaxy playbook. Because we modified job_conf.xml, Galaxy will be restarted to reread its config files.

    code-in Input: Bash

    ansible-playbook galaxy.yml
    
  3. Click the rerun button on the last history item, or click Testing Tool in the tool panel, and then click the tool’s Execute button.

    question Question

    What is the tool’s output?

    solution Solution

    Running with '2' threads
    

Dynamic Job Destinations

Dynamic destinations allow you to write custom python code to dispatch jobs based on whatever rules you like. For example, UseGalaxy.eu at one point used a very complex custom dispatching configuration to handle sorting jobs between multiple clusters. Galaxy has extensive documentation on how to write these sort of destinations.

hands_on Hands-on: Writing a dynamic job destination

  1. Create and open files/galaxy/dynamic_job_rules/my_rules.py

    from galaxy.jobs import JobDestination
    from galaxy.jobs.mapper import JobMappingException
    import os
    
    def admin_only(app, user_email):
        # Only allow the tool to be executed if the user is an admin
        admin_users = app.config.get( "admin_users", "" ).split( "," )
        if user_email not in admin_users:
            raise JobMappingException("Unauthorized.")
        return JobDestination(runner="slurm")
    

    This destination will check that the user_email is in the set of admin_users from your config file.

    tip Debugging dynamic destinations

    You can use pdb for more advanced debugging, but it requires some configuration. print() statements are usually sufficient and easier.

  2. As usual, we need to instruct Galaxy of where to find this file:

    Edit your group variables file and add the following:

    --- a/group_vars/galaxyservers.yml
    +++ b/group_vars/galaxyservers.yml
    @@ -73,6 +73,8 @@ galaxy_config_files:
    
     galaxy_local_tools:
     - testing.xml
    +galaxy_dynamic_job_rules:
    +- my_rules.py
    
     # systemd
     galaxy_systemd_mode: mule
    
  3. We next need to configure this plugin in our job configuration:

    --- a/templates/galaxy/config/job_conf.xml.j2
    +++ b/templates/galaxy/config/job_conf.xml.j2
    @@ -41,10 +41,15 @@
                 <param id="rewrite_parameters">True</param>
                 <param id="transport">curl</param>
             </destination>
    +        <destination id="dynamic_admin_only" runner="dynamic">
    +            <param id="type">python</param>
    +            <param id="function">admin_only</param>
    +        </destination>
         </destinations>
         <tools>
    

    This is a Python function dynamic destination. Galaxy will load all python files in the {{ galaxy_dynamic_rule_dir }}, and all functions defined in those will be available my_rules.py to be used in the job_conf.xml

  4. Finally, in job_conf.xml, update the <tool> definition and point it to this destination:

    --- a/templates/galaxy/config/job_conf.xml.j2
    +++ b/templates/galaxy/config/job_conf.xml.j2
    @@ -49,7 +52,6 @@
         <tools>
             <tool id="bwa" destination="pulsar"/>
             <tool id="bwa_mem" destination="pulsar"/>
    -        <tool id="testing" destination="slurm-2c"/>
    +        <tool id="testing" destination="dynamic_admin_only" />
         </tools>
     </job_conf>
    
  5. Run the Galaxy playbook.

    code-in Input: Bash

    ansible-playbook galaxy.yml
    
  6. Try running the tool as both an admin user and a non-admin user, non-admins should not be able to run it. You can start a private browsing session to test as a non-admin, anonymous user. Anonymous users were enabled in your Galaxy configuration.

Unauthorized

You can imagine extending this to complex logic for permissions, or for destination mapping depending on numerous factors. We did not cover it, but in the documentation you can add additional variables to your function signature, and they will be automatically supplied. Some useful variables are tool, user, job, and app if you need to load configuration information, and more can be found in the documentation.

Dynamically map a tool to a job destination

If you don’t want to write dynamic destinations yourself, Dynamic Tool Destinations (DTDs) utilize the dynamic job runner to provide dynamic job mapping functionality without having to explicitly write code to perform the mapping. The mapping functionality is mostly limited to input sizes, but often input size is the most important factor in deciding what resources to allocate for a job.

Writing a Dynamic Tool Destination

hands_on Hands-on: Writing a DTD

  1. Dynamic tool destinations are configured via a YAML file. As before, we’ll use a fake example but this is extremely useful in real-life scenarios. Create the file files/galaxy/config/tool_destinations.yml with the following contents:

    ---
    tools:
      testing:
        rules:
          - rule_type: file_size
            lower_bound: 16
            upper_bound: Infinity
            destination: slurm-2c
        default_destination: slurm
    default_destination: slurm
    verbose: True
    

    The rule says:

    • If the tool has ID testing:
      • If the input dataset is >=16 bytes, run on the destination slurm-2c
      • If the input dataset is <16 bytes, run on the destination slurm
    • Else, run on the destination slurm
  2. We also need to inform Galaxy of the path to the file we’ve just created, which is done using the tool_destinations_config_file in galaxy_config > galaxy. Additionally we need to add a galaxy_config_files entry to ensure it is deployed.

    --- a/group_vars/galaxyservers.yml
    +++ b/group_vars/galaxyservers.yml
    @@ -28,6 +28,7 @@ miniconda_manage_dependencies: false
    
     galaxy_config:
       galaxy:
    +    tool_destinations_config_file: "{{ galaxy_config_dir }}/tool_destinations.yml"
         dependency_resolvers_config_file: "{{ galaxy_config_dir }}/dependency_resolvers_conf.xml"
         brand: "🧬🔬🚀"
         admin_users: admin@example.org,admin@example.com
    @@ -68,6 +69,8 @@ galaxy_config_templates:
         dest: "{{ galaxy_config.galaxy.job_config_file }}"
    
     galaxy_config_files:
    +- src: files/galaxy/config/tool_destinations.yml
    +  dest: "{{ galaxy_config.galaxy.tool_destinations_config_file }}"
     - src: files/galaxy/config/dependency_resolvers_conf.xml
       dest: "{{ galaxy_config.galaxy.dependency_resolvers_config_file }}"
    
  3. We need to update Galaxy’s job configuration to use this rule. Open templates/galaxy/config/job_conf.xml.j2 and add a DTD destination. Also, comment out or remove the previous <tool> definition for the testing tool, and replace it with a mapping to the dtd destination like so:

    --- a/templates/galaxy/config/job_conf.xml.j2
    +++ b/templates/galaxy/config/job_conf.xml.j2
    @@ -45,10 +45,13 @@
                 <param id="type">python</param>
                 <param id="function">admin_only</param>
             </destination>
    +        <destination id="dtd" runner="dynamic">
    +            <param id="type">dtd</param>
    +        </destination>
         </destinations>
         <tools>
             <tool id="bwa" destination="pulsar"/>
             <tool id="bwa_mem" destination="pulsar"/>
    -        <tool id="testing" destination="dynamic_admin_only" />
    +        <tool id="testing" destination="dtd" />
         </tools>
     </job_conf>
    
  4. Run the Galaxy playbook.

    code-in Input: Bash

    ansible-playbook galaxy.yml
    

Testing the DTD

Our rule specified that any invocation of the testing tool with an input dataset with size <16 bytes would run on the 1 core destination, whereas any with >= 16 bytes would run on the 2 core destination.

hands_on Hands-on: Testing the DTD

  1. Create a dataset using the upload paste tool with a few (<16) characters

  2. Create a dataset using the upload paste tool with >16 characters

  3. Run the Testing Tool on both datasets.

You can imagine using this to run large blast jobs on compute hardware with more resources, or giving them more CPU cores. Some tools require more memory as job inputs increase, you can use this to run tools with a larger memory limit, if you know it will need it to process a certain size of inputs.

Job Resource Selectors

You may find that certain tools can benefit from having form elements added to them to allow for controlling certain job parameters, so that users can select based on their own knowledge. For example, a user might know that a particular set of parameters and inputs to a certain tool needs a larger memory allocation than the standard amount for a given tool. This of course assumes that your users are well behaved enough not to choose the maximum whenever available, although such concerns can be mitigated somewhat by the use of concurrency limits on larger memory destinations.

Such form elements can be added to tools without modifying each tool’s configuration file through the use of the job resource parameters configuration file

hands_on Hands-on: Configuring a Resource Selector

  1. Create and open templates/galaxy/config/job_resource_params_conf.xml.j2

    <parameters>
        <param label="Cores" name="cores" type="select" help="Number of cores to run job on.">
            <option value="1">1 (default)</option>
            <option value="2">2</option>
        </param>
      <param label="Time" name="time" type="integer" size="3" min="1" max="24" value="1" help="Maximum job time in hours, 'walltime' value (1-24). Leave blank to use default value." />
    </parameters>
    

    This defines two resource fields, a select box where users can choose between 1 and 2 cores, and a text entry field where users can input an integer value from 1-24 to set the walltime for a job.

  2. As usual, we need to instruct Galaxy of where to find this file:

    --- a/group_vars/galaxyservers.yml
    +++ b/group_vars/galaxyservers.yml
    @@ -28,6 +28,7 @@ miniconda_manage_dependencies: false
    
     galaxy_config:
       galaxy:
    +    job_resource_params_file: "{{ galaxy_config_dir }}/job_resource_params_conf.xml"
         tool_destinations_config_file: "{{ galaxy_config_dir }}/tool_destinations.yml"
         dependency_resolvers_config_file: "{{ galaxy_config_dir }}/dependency_resolvers_conf.xml"
         brand: "🧬🔬🚀"
    @@ -65,6 +66,8 @@ galaxy_config:
         farm: job-handlers:1,2
    
     galaxy_config_templates:
    +- src: templates/galaxy/config/job_resource_params_conf.xml.j2
    +  dest: "{{ galaxy_config.galaxy.job_resource_params_file }}"
     - src: templates/galaxy/config/job_conf.xml.j2
       dest: "{{ galaxy_config.galaxy.job_config_file }}"
    
  3. Next, we define a new section in job_conf.xml: <resources>. This groups together parameters that should appear together on a tool form. Add the following section to your templates/galaxy/config/job_conf.xml.j2:

    --- a/templates/galaxy/config/job_conf.xml.j2
    +++ b/templates/galaxy/config/job_conf.xml.j2
    @@ -55,6 +55,9 @@
                 <param id="type">dtd</param>
             </destination>
         </destinations>
    +    <resources>
    +        <group id="testing">cores,time</group>
    +    </resources>
         <tools>
             <tool id="bwa" destination="pulsar"/>
             <tool id="bwa_mem" destination="pulsar"/>
    

    The group ID will be used to map a tool to job resource parameters, and the text value of the <group> tag is a comma-separated list of names from job_resource_params_conf.xml to include on the form of any tool that is mapped to the defined <group>.

  4. Finally, in job_conf.xml, move the previous <tool> definition for the testing tool into the comment and define a new <tool> that defines the resources for the tool:

    --- a/templates/galaxy/config/job_conf.xml.j2
    +++ b/templates/galaxy/config/job_conf.xml.j2
    @@ -61,6 +61,6 @@
         <tools>
             <tool id="bwa" destination="pulsar"/>
             <tool id="bwa_mem" destination="pulsar"/>
    -        <tool id="testing" destination="dtd" />
    +        <tool id="testing" destination="dynamic_cores_time" resources="testing"/>
         </tools>
     </job_conf>
    
  5. We have assigned the testing tool to a new destination: dynamic_cores_time, but this destination does not exist. We need to create it. Add the following destination in your job conf:

    --- a/templates/galaxy/config/job_conf.xml.j2
    +++ b/templates/galaxy/config/job_conf.xml.j2
    @@ -54,6 +54,10 @@
             <destination id="dtd" runner="dynamic">
                 <param id="type">dtd</param>
             </destination>
    +        <destination id="dynamic_cores_time" runner="dynamic">
    +            <param id="type">python</param>
    +            <param id="function">dynamic_cores_time</param>
    +        </destination>
         </destinations>
         <resources>
             <group id="testing">cores,time</group>
    

    This will be another dynamic destination. Galaxy will load all python files in the {{ galaxy_dynamic_rule_dir }}, and all functions defined in those will be available dynamic_cores_time to be used in the job_conf.xml

This will set everything up to use the function. We have:

  • A set of “job resources” defined which will let the user select the number of cores and walltime.
  • A job configuration which says:
    • that our testing tool should allow selection of the cores and time parameters
    • directs it to use a new, dynamic_cores_time destination
    • and a has a new destination, dynamic_cores_time, which is defined as a dynamic destination which will call a python function we will load.

This is a lot but we’re still missing the last piece for it to work:

A dynamic destination

Lastly, we need to write the rule that will read the value of the job resource parameter form fields and decide how to submit the job.

hands_on Hands-on: Writing a dynamic destination

  1. Create and edit files/galaxy/dynamic_job_rules/map_resources.py. Create it with the following contents:

    import logging
    from galaxy.jobs.mapper import JobMappingException
    
    log = logging.getLogger(__name__)
    
    DESTINATION_IDS = {
        1 : 'slurm',
        2 : 'slurm-2c'
    }
    FAILURE_MESSAGE = 'This tool could not be run because of a misconfiguration in the Galaxy job running system, please report this error'
    
    
    def dynamic_cores_time(app, tool, job, user_email):
        destination = None
        destination_id = 'slurm'
    
        # build the param dictionary
        param_dict = job.get_param_values(app)
    
        if param_dict.get('__job_resource', {}).get('__job_resource__select') != 'yes':
            log.info("Job resource parameters not seleted, returning default destination")
            return destination_id
    
        # handle job resource parameters
        try:
            # validate params
            cores = int(param_dict['__job_resource']['cores'])
            time = int(param_dict['__job_resource']['time'])
            destination_id = DESTINATION_IDS[cores]
            destination = app.job_config.get_destination(destination_id)
            # set walltime
            if 'nativeSpecification' not in destination.params:
                destination.params['nativeSpecification'] = ''
            destination.params['nativeSpecification'] += ' --time=%s:00:00' % time
        except:
            # resource param selector not sent with tool form, job_conf.xml misconfigured
            log.warning('(%s) error, keys were: %s', job.id, param_dict.keys())
            raise JobMappingException(FAILURE_MESSAGE)
    
        log.info('returning destination: %s', destination_id)
        log.info('native specification: %s', destination.params.get('nativeSpecification'))
        return destination or destination_id
    

    It is important to note that you are responsible for parameter validation, including the job resource selector. This function only handles the job resource parameter fields, but it could do many other things - examine inputs, job queues, other tool parameters, etc.

  2. As usual, we need to instruct Galaxy of where to find this file:

    --- a/group_vars/galaxyservers.yml
    +++ b/group_vars/galaxyservers.yml
    @@ -81,6 +81,7 @@ galaxy_local_tools:
     - testing.xml
     galaxy_dynamic_job_rules:
     - my_rules.py
    +- map_resources.py
    
     # systemd
     galaxy_systemd_mode: mule
    
  3. Run the Galaxy playbook.

    code-in Input: Bash

    ansible-playbook galaxy.yml
    
  4. Run the Testing Tool with various resource parameter selections

    • Use default job resource parameters
    • Specify job resource parameters:
      • 1 core
      • 2 cores
      • Some value for walltime from 1-24

The cores parameter can be verified from the output of the tool. The walltime can be verified with scontrol:

code-in Input: Bash

Your job number may be different.

scontrol show job 24

code-out Output

Your output may look slightly different. Note that the TimeLimit for this job (which I gave a 12 hour time limit) was set to 12:00:00.

JobId=24 JobName=g24_multi_anonymous_10_0_2_2
   UserId=galaxy(999) GroupId=galaxy(999)
   Priority=4294901747 Nice=0 Account=(null) QOS=(null)
   JobState=COMPLETED Reason=None Dependency=(null)
   Requeue=1 Restarts=0 BatchFlag=1 Reboot=0 ExitCode=0:0
   RunTime=00:00:05 TimeLimit=12:00:00 TimeMin=N/A
   SubmitTime=2016-11-05T22:01:09 EligibleTime=2016-11-05T22:01:09
   StartTime=2016-11-05T22:01:09 EndTime=2016-11-05T22:01:14
   PreemptTime=None SuspendTime=None SecsPreSuspend=0
   Partition=debug AllocNode:Sid=gat2016:1860
   ReqNodeList=(null) ExcNodeList=(null)
   NodeList=localhost
   BatchHost=localhost
   NumNodes=1 NumCPUs=1 CPUs/Task=1 ReqB:S:C:T=0:0:*:*
   TRES=cpu=1,node=1
   Socks/Node=* NtasksPerN:B:S:C=0:0:*:* CoreSpec=*
   MinCPUsNode=1 MinMemoryNode=0 MinTmpDiskNode=0
   Features=(null) Gres=(null) Reservation=(null)
   Shared=OK Contiguous=0 Licenses=(null) Network=(null)
   Command=(null)
   WorkDir=/srv/galaxy/server/database/jobs/000/24
   StdErr=/srv/galaxy/server/database/jobs/000/24/galaxy_24.e
   StdIn=StdIn=/dev/null
   StdOut=/srv/galaxy/server/database/jobs/000/24/galaxy_24.o
   Power= SICP=0

Further Reading

keypoints Key points

  • Dynamic Tool Destinations are a convenient way to map

  • Job resource parameters can allow you to give your users control over job resource requirements, if they are knowledgeable about the tools and compute resources available to them.

Frequently Asked Questions

Have questions about this tutorial? Check out the FAQ page for the Galaxy Server administration topic to see if your question is listed there. If not, please ask your question on the GTN Gitter Channel or the Galaxy Help Forum

Feedback

Did you use this material as an instructor? Feel free to give us feedback on how it went.

Click here to load Google feedback frame

Citing this Tutorial

  1. Nate Coraor, Björn Grüning, Helena Rasche, 2021 Mapping Jobs to Destinations (Galaxy Training Materials). /archive/2021-05-01/topics/admin/tutorials/job-destinations/tutorial.html Online; accessed TODAY
  2. Batut et al., 2018 Community-Driven Data Analysis Training for Biology Cell Systems 10.1016/j.cels.2018.05.012

details BibTeX

@misc{admin-job-destinations,
    author = "Nate Coraor and Björn Grüning and Helena Rasche",
    title = "Mapping Jobs to Destinations (Galaxy Training Materials)",
    year = "2021",
    month = "03",
    day = "12"
    url = "\url{/archive/2021-05-01/topics/admin/tutorials/job-destinations/tutorial.html}",
    note = "[Online; accessed TODAY]"
}
@article{Batut_2018,
        doi = {10.1016/j.cels.2018.05.012},
        url = {https://doi.org/10.1016%2Fj.cels.2018.05.012},
        year = 2018,
        month = {jun},
        publisher = {Elsevier {BV}},
        volume = {6},
        number = {6},
        pages = {752--758.e1},
        author = {B{\'{e}}r{\'{e}}nice Batut and Saskia Hiltemann and Andrea Bagnacani and Dannon Baker and Vivek Bhardwaj and Clemens Blank and Anthony Bretaudeau and Loraine Brillet-Gu{\'{e}}guen and Martin {\v{C}}ech and John Chilton and Dave Clements and Olivia Doppelt-Azeroual and Anika Erxleben and Mallory Ann Freeberg and Simon Gladman and Youri Hoogstrate and Hans-Rudolf Hotz and Torsten Houwaart and Pratik Jagtap and Delphine Larivi{\`{e}}re and Gildas Le Corguill{\'{e}} and Thomas Manke and Fabien Mareuil and Fidel Ram{\'{\i}}rez and Devon Ryan and Florian Christoph Sigloch and Nicola Soranzo and Joachim Wolff and Pavankumar Videm and Markus Wolfien and Aisanjiang Wubuli and Dilmurat Yusuf and James Taylor and Rolf Backofen and Anton Nekrutenko and Björn Grüning},
        title = {Community-Driven Data Analysis Training for Biology},
        journal = {Cell Systems}
}
                    

congratulations Congratulations on successfully completing this tutorial!