Using Gridware with Docker¶
Gridware can now be transported within a docker container which can be shared with the nodes in a Flight environment. This allows applications to be packaged within in a container for distribution between nodes or even to systems outside of the Flight environment.
To install docker support, apply the feature profile (for more info on features see Feature Profiles):
alces customize apply feature/configure-docker
Note
The feature profile will install the required docker dependencies and perform Flight specific configuration changes. Any systems within the cluster that are to use docker will need to apply the profile as well
Viewing Images¶
The alces gridware docker
command can be used to interact with docker images & containers once the feature has been applied to the system.
To show available docker images:
alces gridware docker list
On a fresh build there won’t be any Local
images but once the first build is run, the base
image along with whatever apps have been built into containers will appear in the list.
Building Images¶
The image base
from docker.io/alces
will be used to build new images with the chosen gridware application.
To build a gridware application as a docker image:
alces gridware docker build apps/memtester/4.3.0
Note
Unlike standard gridware, this requires the version number to be specified even if there aren’t multiple versions available
This will download the base image & run the additional commands required to install the application into the image. Once this has completed then the image will be visible in the Local
image list.:
Local:
apps-memtester-4.3.0
base
Multiple Apps in Image¶
Multiple gridware apps can be packaged into a docker image, this is done by simply appending the rest of the apps to the build command (--name
is specified to reduce the length and complexity of the output image name):
alces gridware docker build --name my-super-apps apps/memtester/4.3.0 mpi/openmpi/1.10.2 apps/gnuplot/5.0.2
The resulting image can be interacted with in the same way as a single app gridware container.
Running Containers¶
When an image has been created it will only get started when it is interacted with using alces gridware docker run
which launches a container built from the image. The containers can be interacted with in a couple of ways using this command, these methods are outlined below.
Running a Single Command¶
Provide a single command as an argument to the run command after specifying the container to launch:
[alces@login1(scooby) ~]$ alces gridware docker run apps-memtester-4.3.0 uptime
Executing 'alces/gridware-apps-memtester-4.3.0' with arguments 'uptime'...
>>> 15:46:02 up 1:40, 0 users, load average: 0.20, 0.26, 0.23
Job completed successfu8lly.
Output summary:
/home/alces/apps-memtester-4.3.0/work.6ff32278-2f4e-11e7-b988-0a6424937e45/output
total 0
drwx------ 2 alces alces 6 May 2 15:45 .
drwx------ 3 alces alces 36 May 2 15:45 ..
Note
Any input files will need to be copied to ~/app-memtester-4.3.0/input/
to appear at /job/input/
within the container. (Replace app-memtester-4.3.0 with the name of the container that gridware created)
Running a Script¶
Local scripts can be passed through to the container which allows for multiple commands to be ran at a time. Take the below script, ~/script.sh
, which runs a few quick commands:
#!/bin/bash
uptime
free -m
echo $HOSTNAME
This can be passed to a container using docker run as follows:
[alces@login1(scooby) ~]$ alces gridware docker run apps-paraview-4.3.1 --script script.sh
Executing script 'script.sh' in 'alces/gridware-apps-paraview-4.3.1'...
>>> 16:02:02 up 1:56, 0 users, load average: 3.11, 2.40, 1.39
>>> total used free shared buff/cache available
>>> Mem: 7565 728 159 17 6676 6466
>>> Swap: 0 0 0
>>> 7ea913ce82a3
Job completed successfully.
Output summary:
/home/alces/apps-paraview-4.3.1/work.ab7a1250-2f50-11e7-85da-0a6424937e45/output
total 0
drwx------ 2 alces alces 6 May 2 16:01 .
drwx------ 3 alces alces 54 May 2 16:01 ..
Running in Parallel¶
The argument --mpi=X
can be appended to the run command to distribute the container across X processors. A 4 core example script is below:
[alces@login1(scooby) ~]$ alces gridware docker run --mpi=4 apps-memtester-4.3.0 memtester 1G 1
Additionally, the following files are created within the container:
/job/work/hosts
- This contains a hosts file with entries for each slave container that is running as part of the job./job/work/hostlist
- As above but containing the IP addresses of the slave containers.
The MPI argument can only be used from the master (login) node. It will then act as the master and allocate cores on any client nodes that have the ‘configure-docker’ feature installed.
Other Running Options¶
Without Gridware Entrypoint¶
The Gridware entrypoint is used as a standard for executing commands inside the container. The script loads the modules for the applications installed within the container and handles running the applications. In the event of wanting to run a command without using the Gridware launched, run it as follows:
alces gridware docker run apps-memtester-4.3.0 --command uptime
Interactively¶
Instead of running the container ephemerally for a single command/script, an interactive session can be launched:
alces gridware docker run apps-memtester-4.3.0 --interactive
Data Storage and Images¶
Gridware docker creates ~/CONTAINER-NAME/
when a container is launched with alces gridware docker run
, this directory contains:
input/
- Any files in here are mapped to/job/input/
in the container instancework.CONTAINER-UUID
- This directory is unique to the container instance and contains:
Dockerfile
- The recipe file used to build the containerdocker.log
- Output from the building of the containeroutput/
- Any files saved to/job/output/
within the container will appear here- Any files written to
/job/work/
will appear in this directory
The working directory can be changed from ~/CONTAINER-NAME
to a user-specified directory with the workdir
flag when launching the container. The directory will be created if not present and the hierarchy of the directory will be the same as listed above:
alces gridware docker run --workdir ~/my_container_directory/ apps-memtester-4.3.0 touch /job/output/testfile
Adding Extra Mountpoints¶
Directories from the host system can be mounted within the container by using the mount
option when running a container:
alces gridware docker run apps-memtester-4.3.0 --mount ~/my_local_directory/:/container_mnt ls /container_mnt
Sharing Images¶
In order for nodes to be able to use the same container that was built on the login node it will need to be shared, this can be done either through the share feature or a local registry.
Local Registry¶
A local docker registry allows for the pushing and pulling of docker images. Much like docker.io images but without the requirement of upstream connections for sharing. To start the local registry:
alces gridware docker start-registry
Once the registry is running it can then be interacted with with docker push
and docker pull
as per the docker documentation
Note
Any other systems that are to use the docker containers will need the docker feature enabled with alces customize apply feature/configure-docker