Alliance Doc

Singularity: Difference between revisions

Page Discussion

Singularity (view source)

Revision as of 21:43, 1 March 2018

9,020 bytes added ,  6 years ago
Initial draft of comprehensive Singularity v2.4 usage instructions.
No edit summary
(Initial draft of comprehensive Singularity v2.4 usage instructions.)
Line 1: Line 1:
{{Draft}}
{{Draft}}
Singularity is an application containerization solution for High-Performance Computing (HPC). The goal of Singularity is to allow for "mobility of computing": an application containerized on one Linux system should be able to run on another system, as it is, and without the need to reconcile software dependencies and Linux version differences between the source and target systems. One of the main benefits of Singularity is that containers are executed as user and can have access to local and network filesystems.
=Overview=
Singularity<ref>http://singularity.lbl.gov/</ref> is open source software created by Berkeley Lab:
* as a '''secure way''' to use Linux containers on Linux multi-user clusters,
* as a way to enable users to have '''full control of their environment,''' and,
* as a way to '''package scientific software''' and deploy such to ''different'' clusters having the ''same'' architecture.
i.e., it provides '''operating-system-level virtualization''' commonly called ''containers''.


You can create containers and install and setup software in them on systems where you have root access (e.g. your laptop or a cloud VM). Once you have created your singularity container, you can copy it to an HPC cluster such as [[Cedar]] or [[Graham]] and run your container as a user on that system. For more information about singularity see [http://singularity.lbl.gov/ singularity main page]
A ''container'' is different from a ''virtual machine'' in that a container:
* likely has less overhead, and,
* can only run programs capable of running in the same operating system (i.e., Linux when using Singularity) for the same hardware architecture.
(Virtual machines can run different operating systems and sometimes support running software designed for foreign CPU architectures.)


=Using=
Containers use Linux '''control groups''' (cgroups), kernel '''namespaces''', and an '''overlay filesystem''' where:
* cgroups '''limit, control, and isolate''' resource usage (e.g., RAM, disk I/O, CPU access)
* kernel namespaces '''virtualize and isolate''' operating system resources of a '''group of processes''', e.g., process and user IDs, filesystems, network access; and,
* overlay filesystems can be used to enable the '''appearance''' of writing to otherwise read-only filesystems.


Singularity has been installed via modules. To see which versions are available, execute:
Singularity is similar to other container solutions such as Docker<ref>https://www.docker.com/</ref> except Singularity was specifically designed to enable containers to be used securely without requiring any special permissions especially on multi-user compute clusters.<ref>http://singularity.lbl.gov/docs-security</ref>


<source lang="console">
=Singularity Availability=
$ module avail singularity
</source>


To load and use one of the modules, in this example version 2.3, execute:
Singularity is available on Compute Canada clusters (e.g., [[Cedar]] and [[Graham]]) and some legacy cluster systems run by various Compute Canada involved members/consortia across Canada.


<source lang="console">
Should you wish to use Singularity on your own computer systems, you will need to download and install Singularity per its documentation.<ref>http://singularity.lbl.gov/all-releases</ref> You should be using a relatively recent version of some Linux distribution (e.g., ideally your kernel ideally is v3.10.0 or newer).
$ module load singularity/2.3
</source>


A good place to find more images to use with singularity is: [https://hub.docker.com/ docker hub] e.g. search for ubuntu, and then you can create a new singularity container with a given Ubuntu image with:
=Using Singularity On Compute Canada Systems=


<source lang="console">
==Module Loading==
$ module load singularity/2.3
$ singularity create my-container.img
$ singularity import my-container.img docker://ubuntu:16.10
</source>
or in fewer steps
<source lang="console">
$ module load singularity/2.3
$ singularity pull -n my-container.img docker://ubuntu:16.10
</source>


To start a shell inside this newly created container, execute:
To use Singularity, first load the specific module you would like to use, e.g.,
<source lang="console">
<source lang="console">$ module load singularity/2.4</source>
$ singularity shell my-container.img
</source>


Should you need to see all versions of Singularity modules that are available then run:
<source lang="console">$ module spider singularity</source>


if the docker image name and tag are <code>ubuntu</code> and <code>16.10</code> for example. It is also likely if installing software that you will want larger than the default image. The size of the image can be specified with the <code>-s</code> option, e.g. <code>-s 4096</code> to specify that the image should be 4096 MB or 4G.
==Creating Images==


See also:
'''Before''' using Singularity, you will first need to '''create a (container) image'''. A Singularity image is either a file or a directory '''containing an installation of Linux'''. One can create a Singularity image by any of the following:
* downloading a container from '''Singularity Hub'''<ref>https://singularityhub.com/</ref>
* downloading a container from '''Docker Hub'''<ref>https://hub.docker.com/</ref>
* from a container you already have,
* from a '''tarball''' or a '''directory''' containing an installation of Linux, or,
* from a '''Singularity recipe file'''.


* [http://singularity.lbl.gov/ singularity main page]
===Creating an Image Using Singularity Hub===
* [https://www.westgrid.ca/support/software/singularity westgrid docs on singularity]
 
* [http://www.hpc.mcgill.ca/downloads/user_meetings/McGillHPC-UsersMeeting-Singularity-20161215.pdf slides about singularity]
Suppose the Singularity Hub URL for a container you want to use is:
<pre>shub://singularityhub/ubuntu</pre>
then you would download the container by running:
<source lang="console">$ singularity pull shub://singularityhub/ubuntu</source>
 
[https://singularityhub.com/ Singularity Hub] allows one to search for images.
 
===Creating an Image Using Docker Hub===
 
Suppose the Docker Hub URL for a container you want to use is:
<pre>docker://ubuntu</pre>
then you would download the container by running:
<source lang="console">$ singularity pull docker://ubuntu</source>
 
[https://hub.docker.com/ Docker Hub] allows one to search for images.
 
===Creating a Tarball of Your Own Linux System===
 
If you already have a configured Intel-CPU-based 64-bit version of Linux installed, then you can create a tarball of your system using the <code>tar</code> similar to this:
<source lang="console">$ sudo tar -cvpf -C / my-system.tar --exclude=/dev --exclude=/proc --exclude=/sys</source>
although you may probably want to exclude additional directories.
 
The created tarball will need to be converted into a Singularity image which is discussed [[#Creating an Image From a Tarball|later on this page]].
 
===Creating an Image From a Tarball===
 
If you have a tarball or a gzip-compressed tarball, a Singularity image can be made from it by using the Singularity '''build''' command:
<source lang="console">$ sudo singularity build my-image.simg my-system.tar</source>
if you are using your own system, or,
<source lang="console">$ singularity build my-image.simg my-system.tar</source>
if you are using a Compute Canada system.
 
The structure of the build command used to build an image from a tarball can be any one of the following:
<pre>singularity build IMAGE_FILE_NAME TARBALL_FILE_NAME
singularity build [OPTIONS] IMAGE_FILE_NAME TARBALL_FILE_NAME</pre>
 
The full syntax of the build command can be obtained by running:
<source lang="console">$ singularity build --help</source>
 
Singularity single-file images filenames typically have a <code>.simg</code> extension.
 
===Creating an Image From a Singularity Recipe===
 
If the following:
<pre>Bootstrap: self
Exclude: /boot /dev /home /lost+found /media /mnt /opt /proc /run /sys</pre>
is placed in a file, e.g., <code>copy-drive-into-container-recipe</code> then it can be used to copy one's Linux system directly into a container (except for the excluded directories listed) by running:
<source lang="console">$ sudo singularity build self.simg copy-drive-into-container-recipe</source>
(Clearly such has to be run on your own Linux system and Singularity must already be installed on that system.)
 
If you had the need to periodically re-generate your Singularity image from a script, then you might write a Singularity recipe such as this:
<pre>Bootstrap: localimage
From: ubuntu-16.04-x86_64.simg
 
%help
This is a modified Ubuntu 16.06 x86_64 Singularity container image.
 
%post
  sudo apt-get -y update
  sudo apt-get -y upgrade
  sudo apt-get -y install build-essential git
  sudo apt-get -y install python-dev python-pip python-virtualenv python-numpy python-matplotlib
  sudo apt-get -y install vim
  sudo apt-get clean</pre>
The above recipe allows one to update-regenerate a Singularity image from an existing Singularity image. In the above example, the recipe ensures all security updates are applied and that certain software programs are installed. If this script was in a file called <code>update-existing-container-recipe</code> ''and'' the image <code>ubuntu-16.04-x86_64.simg</code> already exists in the current directory, then the image can be updated by running:
<source lang="console">$ sudo singularity build new-ubuntu-image.simg update-existing-container-recipe</source>
 
===Creating/Updating an Image Interactively and Manually===
 
This section is incomplete and will be completed later.
 
===Is sudo Needed or Not Needed?===
 
Notice the different between the two commands is whether or not <code>'''sudo'''</code> appears. The <code>sudo</code> command runs the command after it as the '''root''' user (i.e., superuser) of that system. On Compute Canada systems, no users have such access so the '''sudo''' command cannot be used there. Presumably you do have '''root''' access on your own computer so you can use '''sudo''' on it.
 
It is entirely possible that you will not need to use the '''sudo''' command with your image. If <code>sudo</code> is not used, then the following will happen when you '''build''' the image:
* Singularity will output a warning that such may result in an image that does not work. This message is only a warning though --the image will still be created.
* All filesystem permissions will be collapsed to be the permissions of the Linux user and group that is running '''singularity build'''. (This is normally the user and group you are logged in as.)
If <code>sudo</code> is used, then all filesystem permissions will be kept as they are in the tarball.
 
Typically one will not need to be concerned with retaining all filesystem permissions unless:
* one needs to regularly update/reconfigure the contents of the image, and,
* tools used to update/reconfigure the contents of the image '''require''' those permissions to be retained.
For example, many Linux distributions make it easy to update or install new software using commands such as:
* <code>apt-get update && apt-get upgrade</code>
* <code>apt-get install some-software-package</code>
* <code>yum install some-software-package</code>
* <code>dnf install some-software-package</code>
* etc.
It is possible that these and other commands may not run successfully unless filesystem permissions are retained. If this is of concern, then:
# Install Singularity on your own computer.
# Always build the Singularity image on your own computer using '''sudo'''.
If this is not a concern, then you may be able to build the Singularity image on a Compute Canada system without '''sudo''', however, be aware that such might fail for any of the following reasons:
* When using Lustre filesystems, e.g., <code>/project</code>, you may run out of quota. If this occurs, it is likely because there are too many small files causing all of your quota to be used. (Lustre is excellent for large files but stores small files very inefficiently.)
* Sometimes image creation will fail due to various user restrictions placed on the node you are using. The login nodes, in particular, have a number of restrictions which may prevent one from successfully building an image.
If such occurs, then you will need to create your image using your own computer. If this is an issue, then request assistance to create the Singularity image you want by creating a Compute Canada ticket by sending an email to [mailto:support@computecanada.ca].
 
==Using Singularity==
 
'''NOTE:''' The discussion below does not describe how to use Slurm to run interactive or batch jobs --it only describes how to use Singularity. For interactive and batch job information see the [[Running jobs]] page.
 
Unlike perhaps when you created your Singularity image, you will never use, don't need to use, and cannot use <code>sudo</code> to run programs in your image on Compute Canada systems. There are a number of ways to run programs in your image:
# Running '''commands''' interactively in one Singularity session.
# Run a '''single command''' which executes and then stops running.
# Run a container instance in order to run '''daemons''' which may have '''backgrounded processes'''.
 
===Running Commands Interactively===
 
This section is incomplete and will be completed later.
 
===Running a Single Command===
 
This section is incomplete and will be completed later.
 
===Running Container Instances===
 
This section is incomplete and will be completed later.
 
===Bind Mounts===
 
This section is incomplete and will be completed later.
 
==HPC Issues With Singularity==
 
This section is incomplete and will be completed later.
 
=See Also=
* SHARCNET General Interest Webinar, "Singularity", presented by Paul Preney on Feb. 14, 2018. See this [https://www.youtube.com/watch?v=C4va7d7GxjM YouTube Video] as well as the [https://www.sharcnet.ca/help/index.php/Online_Seminars SHARCNET Online Seminars] page for slides.
 
=References=
<references/>
Preney
cc_staff
156

edits

Retrieved from "https://docs.alliancecan.ca/wiki/Special:MobileDiff/47698"