package require containers
container::exists db name
container::add db name image initfile mountpoints
container::replace db oldname newname image initfile mountpoints
container::remove db name
set fd [container::activate db name host]
set fd [container::run name host command]
container::deactivate host name
set dictlist [container::listDefinitions db ?name?]
This package provides an API for the database schema that defines containers to the manager. It is used by the manager code itself. The API is roughly divided into database manipulations and procs that allow containers to be activated and applications run in those containers.
The API makes use of singularity's ability to create persistent containers. A persistent container is a container image process that also provides a new Linux namespace. These containers have a script that can be run with parameters passed from the command line. This provides the possibility of running programs within those persistent containers.
Container definitions have the following attributes:
Each container definition has a unqique name. This name is used to identify the container definition throughout the API.
Each container has an image fie. This is a singularity image that, when activated produces a containerized environment within which programs can run.
Each container definition can have an initialization script. This is a shell script that is run prior to running any program in the container. One common use for this script is to source an appropriate daqsetup.bash into the shell that runs programs in the container.
Each conatainer definition has a possibly empty list of mount points. A mount point is a host file or directory and where it should appear inthe containerized environment. The term for these in singularity's documentation are bindpoints.
The singularity configuration provides a set of default mount points that meet most needs, however some mount points depend on the container. For example a containerized environment for Debian 10 will probably need a directory tree of the NSCL software compiled for that software while one for Debian 8 will need a different directory tree.
For all entry points with a db parameter,
this parameter should be an SQLite3 command that is connected to the
configuration database you wish to manipulate.
Returns a boolean value that is true if the container
name has been defined in the
configuration database whose SQLite3 database command
is db
Adds a new container definition. The name of the new container
will be name, the container image is
given by the filename path in image.
The path must be valid in the host system(s) in which the
container will be activated.
If the initfile parameter is a non-empty
string it is the path to the initialization script to be
run prior to each program run in an activation of this container.
The path must be valid in the host
filesystem. The contents of this
file at the time the container is added is sucked into the
database. If you modify this file and want the modifications
to be reflected you must recreate the container definition.
The mountpoints parameter is a
list of desired mount points. Each mount point is
a one or two element sublist. If one element, the element
is a filesystem point in the native filesystem that's mounted
to the same position in the container (e.g. equivalent to
--bind point
). If a two element list, the first element is the
native file system point to bind and the second is where to bind
it in the container (e.g.
--bind point:where).
Replaces the container named oldname
with a container named newname and
the definition described by the subsequent parameters
that have the same meaning as for
container::add above.
The resulting container is referenced everywhere in the database
that the old container was referenced. This is accomplished because
the new container definition retains the primary key of the
root record of the container oldname.
Removes the definition of the container name
from the database.
Activates the container name in
the system with the DNS name host.
This proc, if successful, returns a Tcl file descriptor.
The container is activated using ssh the user's public key must, therefore be in the ~/.ssh/authorized_keys file. The file descriptor returned is the output/error end of the pipeline used to run ssh and therefore can capture the messages and errors this ssh command output.
Runs the command in the container
instance of name that must already
have been activated in a system with the DNS name
host.
On success, a file descriptor connected to the output/error of the program. This allows you to capture messages and
Deactivates the container name in the
system host. The container must already
have been activated. Deactivating a container will also kill
any programs that are running in that container.
Returns a list of dicts that describe the containers that
have been defined. If the optional name
parameter is provided, the list will be filtered to only
include that container but is still a list.
If no containers are defined or name
is provided but there is no container named
name, the result is an empty list.
Each elementof the list is a dict which describes one container definition. THe dict contains the following key/values:
This is the primary key of the root record for the container description in the database. For the most part it does not help your code to know this value but it is provided for internal use.
Name of the container described by this dict.
The file path (in the host filesystem) of the container image that will be run when this container is activated in a host.
The contents of the initialization script. If no initialization script was provided, this key will not be present.
A list of one or two element sublists describing the mountpoints. The first element (element 0) of each list is a host file or directory. If there is no second element, this file or directory will appear in the same place in the container as it does in the host filesystem. If there is a second element, it describes where the file or directory will appear in the container filesystem.
This second form is needed to provide for e.g. mapping /usr/opt/opt-buster in the host filesystem to /usr/opt in the container, as is usually done at the FRIB.
Container activation and their associated initialization
scripts require that the package write shell scripts. These
are stored in a hidden directory ~/.daqmanager.
The path to this directory is stored in the variable
::container::tempdir.
Two sorts of scripts are stored there:
Where nn is an integer is the script needed by singluarity to run programs inside the activated, persistent container.
Where again nn is an integer is an initialization script provided for the user run prior to running any program within the activated container.
Note these scripts are a property of the container not of an activation of the container in a host. That is all container activations use the same script filename although the current implementation writes the script each time it's needed to allow for changes in a container's definition between activations.