singularity

README

Tracker for Singularity Containers

Please consider to use the process based backend (default tracker) as it can spawn any process, i.e. also singularity

This is work in progress...ideas welcome!

Introduction

Singularity tracker implements the JobTracker interface used by the Go DRMAA2 implementation in order to use Singularity containers as a backend for managing jobs as containers from the DRMAA2 interface on the same host.

Functionality

Basically the Singularity tracker wraps the OS process tracker adding the required Singularity calls for creating the singularity process.

Basic Usage

A JobTemplate requires at least:

• RemoteCommand -> which is path to the executable which is started in the container
• JobCategory -> which is the Singularity image (like vsoch-hello-world-master.simg)

If you want to see any output it makes sense to set OutputPath and ErrorPath to /dev/stdout in the JobTemplate.

JobTemplate extensions can be used to inject Singularity exec arguments like "--pid" (see command.go).

	jt := drmaa2interface.JobTemplate{
	   RemoteCommand: "/bin/sleep",
		  Args:          []string{"600"},
		  JobCategory:   "shub://GodloveD/lolcow",
		  OutputPath:    "/dev/stdout",
		  ErrorPath:     "/dev/stderr",
	}
	// set Singularity specific arguments and options
	jt.ExtensionList = map[string]string{
		  "debug": "true",
		  "pid":   "true",
 }

In the ExtensionList following arguments are evaluated as global singularity options:

• debug
• silent
• quite
• verbose

Boolean options are (which are injected after singularity exec):

• writable
• keep-privs
• net
• nv
• overlay
• pid
• ipc
• app
• contain
• containAll
• userns
• workdir
• pwd
• cleanenv
• disable-cache
• fakeroot
• no-home
• no-init
• no-nv
• no-privs
• nohttps
• nonet
• rocm
• writeable
• writable-tmpf
• vm
• vm-err

Note that boolean options which are set to "false" or "FALSE" are not evaluated.

Options with values are:

• bind
• add-caps
• drop-cap
• security
• hostname
• network
• network-args
• apply-cgroups
• scatch
• home
• vm-cpu
• vm-ip
• vm-ram
• allow-setuid
• app
• drop-caps
• app
• pem-path

If some are missing open an issue.

Examples

For an example please check out singularity.go in the examples directory.

Documentation

Index

• func NewAllocator() *allocator
• type Tracker
  • func New(jobsession string) (*Tracker, error)
  • func (dt *Tracker) AddArrayJob(jt drmaa2interface.JobTemplate, begin, end, step, maxParallel int) (string, error)
  • func (dt *Tracker) AddJob(jt drmaa2interface.JobTemplate) (string, error)
  • func (dt *Tracker) DeleteJob(jobid string) error
  • func (dt *Tracker) JobControl(jobid, state string) error
  • func (dt *Tracker) JobInfo(jobid string) (drmaa2interface.JobInfo, error)
  • func (dt *Tracker) JobState(jobid string) (drmaa2interface.JobState, string, error)
  • func (dt *Tracker) ListArrayJobs(ID string) ([]string, error)
  • func (dt *Tracker) ListJobCategories() ([]string, error)
  • func (dt *Tracker) ListJobs() ([]string, error)
  • func (dt *Tracker) Wait(jobid string, timeout time.Duration, state ...drmaa2interface.JobState) error

Functions

func NewAllocator

func NewAllocator() *allocator

Types

type Tracker

type Tracker struct {
	// contains filtered or unexported fields
}

Tracker tracks singularity container.

func New

func New(jobsession string) (*Tracker, error)

New creates a new Tracker for Singularity containers.

func (*Tracker) AddArrayJob

func (dt *Tracker) AddArrayJob(jt drmaa2interface.JobTemplate, begin, end, step, maxParallel int) (string, error)

AddArrayJob creates ~(end - begin)/step Singularity containers.

func (*Tracker) AddJob

func (dt *Tracker) AddJob(jt drmaa2interface.JobTemplate) (string, error)

AddJob creates a new Singularity container.

func (*Tracker) DeleteJob

func (dt *Tracker) DeleteJob(jobid string) error

DeleteJob removes the job from the internal storage. It errors when the job is not yet in any end state.

func (*Tracker) JobControl

func (dt *Tracker) JobControl(jobid, state string) error

JobControl suspends, resumes, or stops a Singularity container.

func (*Tracker) JobInfo

func (dt *Tracker) JobInfo(jobid string) (drmaa2interface.JobInfo, error)

JobInfo returns detailed information about the job.

func (*Tracker) JobState

func (dt *Tracker) JobState(jobid string) (drmaa2interface.JobState, string, error)

JobState returns the state of the Singularity container.

func (*Tracker) ListArrayJobs

func (dt *Tracker) ListArrayJobs(ID string) ([]string, error)

ListArrayJobs shows all containers which belong to a certain job array.

func (*Tracker) ListJobCategories

func (dt *Tracker) ListJobCategories() ([]string, error)

ListJobCategories returns nothing.

func (*Tracker) ListJobs

func (dt *Tracker) ListJobs() ([]string, error)

ListJobs shows all Singularity containers running.

func (*Tracker) Wait

func (dt *Tracker) Wait(jobid string, timeout time.Duration, state ...drmaa2interface.JobState) error

Wait blocks until either one of the given states is reached or when the timeout occurs.