Submitting Docker jobs to LSF

Use the Docker application profiles or queues to submit Docker jobs to LSF.

1. Submit a job to a Docker application profile or queue.
   • Use the bsub -app option to submit a job to a Docker application profile (that is, an application profile with a specified value for the CONTAINER parameter).

     For example, if CONTAINER is defined in the dockerapp application profile, run the following command to submit a Docker job:

     bsub -app dockerapp ./myjob.sh

   • Use the bsub -q option to submit a job to a Docker queue (that is, a queue with a specified value for the CONTAINER parameter).

     For example, if CONTAINER is defined in the dockerq queue, run the following command to submit a Docker job:

     bsub -q dockerq ./myjob.sh

   If you specify both the application profile and the queue in the same job submission, the CONTAINER, EXEC_DRIVER, and DOCKER_IMAGE_AFFINITY parameter settings in the application profile take precedence over the same parameter settings in the queue.

   For example, if you submit a job with the following command, the parameters in the dockerapp application profile override the corresponding parameters in the dockerq queue:

   bsub -app dockerapp -q dockerq ./myjob.sh

2. If users are allowed to specify image names for Docker container jobs at job submission time (that is, if the $LSB_CONTAINER_IMAGE environment variable is used as the image name when specifying the image keyword), set the LSB_CONTAINER_IMAGE environment variable at job submission time to specify the Docker image name.

   Specify a container image name (such as ubuntu) at the job submission time by setting the LSB_CONTAINER_IMAGE environment using one of the following methods:

   • Specify the LSB_CONTAINER_IMAGE environment variable according to your shell environment. For example, to specify the Docker image named ubuntu, set the environment variable as follows:
     • In csh or tcsh:

       setenv LSB_CONTAINER_IMAGE ubuntu

     • In sh, ksh, or bash:

       export LSB_CONTAINER_IMAGE=ubuntu

   • Use the bsub -env option. For example, to specify the Docker image named ubuntu

     bsub -env LSB_CONTAINER_IMAGE=ubuntu -app udocker a.out -in in.dat -out out.dat

   • Use an esub script to set the LSB_CONTAINER_IMAGE environment variable, then call the esub with the bsub command:
     For example, create an esub.docker script in the $LSF_SERVERDIR directory with the following contents:

     #!/bin/sh
     exec 1>&2
     echo "LSB_CONTAINER_IMAGE=\"$1\"" >> $LSB_SUB_MODIFY_ENVFILE

     Submit a job to call the esub.docker script by running the following command:

     bsub -a "docker(ubuntu)" -app udocker a.out -in in.dat -out out.dat

3. To submit a job with a Docker entry point image, but no command, use the LSB_DOCKER_PLACE_HOLDER keyword instead of the command.

   For example, run the following command to submit a Docker job with a Docker entry point image:

   bsub -app dockerapp LSB_DOCKER_PLACE_HOLDER

4. Optional: To override the Docker image affinity settings at the cluster, queue, or application level, define the LSB_DOCKER_IMAGE_AFFINITY environment variable with the -env option when submitting the Docker job.

   LSB_DOCKER_IMAGE_AFFINITY=Y | y | N | n

   The job level environment variable overrides application level, which overrides queue level, which overrides the cluster level configuration.

   bsub -env LSB_DOCKER_IMAGE_AFFINITY=N -app udocker a.out -in in.dat -out out.dat