Environment

Modified

November 10, 2023

Abstract

Container introduces an additional layer of indirection which does not inherit its host environment transparently. User will need to explicilty export environment varibales into the container environment. Furthermore management of the container images themselfs, as well as bind-mounting host file-systems into the container during run-time is under responsability of the user.

Variables

Apptainer provides multiple methods to set environment variables in the container, details are described in the Apptainer User Guide ¹. A container introduces an additional layer of indirection which does not inherit automatically environment variables set in the command execution environment used to launch the container. Hence it is up to the user to specify environment variables which require to be set in a container. There are two possible ways to do this, either by using command-line options for the apptainer command or by exporting environment variables with a specific prefix.

`APPTAINERENV_`

Env. Variable	Description
`APPTAINERENV_*`	Environment variables prefixed with `APPTAINERENV_` will be set in the container
`APPTAINERENV_APPEND_PATH`	Append (added to the end) a colon separated list of paths to the `PATH` variable in the container
`APPTAINERENV_PREPEND_PATH`	Prepended (added to the start) a colon separated list of paths to the `PATH` variable in the container

Apptainer reads environment variables prefixed with APPTAINERENV_ from the execution environment and exports these in the container. The generic prefix can be used to set any number of environment variables. Within the containerized environment the prefix is removed from the environment variable name. For example a variable specified with the name APPTAINERENV_LUSTRE_HOME will be called LUSTRE_HOME within the container.

# use the generic prefix to set an environment variable for the container
» export APPTAINERENV_LUSTRE_HOME=$LUSTRE_HOME

# run the container an read the ennvironment variables
» apptainer exec $APPTAINER_CONTAINERS/debian11.sif env | grep ^LUSTRE
LUSTRE_HOME=/lustre/hpc/vpenso

The PATH environment variable is a special case. Users have the option to overwrite the variable in the container using the generic prefix or to either append or prepend to the existing PATH.

Note that in particular when using virtual application environments the use if the generic prefix is very useful in order to export LD_LIBRARY_PATH to the container:

export APPTAINERENV_LD_LIBRARY_PATH=$LD_LIBRARY_PATH
export APPTAINERENV_PREPEND_PATH=$LUSTRE_HOME/bin

Command Options

Option	Description
`--env NAME=VALUE[,NAME=VALUE,...]`	Specify a comma separated list of environment variables as `NAME=VALUE` pairs
`--env-file <file>`	Provide a file that contains environment variables as `NAME=VALUE` pairs

The command-line options listed set environment variables in a container:

# Path to the container image...
container=$APPTAINER_CONTAINERS/debian.sif

# ...download the offical Debian container image
apptainer pull $container docker://debian:latest

# Set an environment variable LUSTRE_HOME...
apptainer exec --env LUSTRE_HOME=$LUSTRE_HOME $container env | grep ^LUSTRE
# ...check visibility of the variable during container execution

Users of an VAE can set the Slurm command line option --singulairty-args to to specify environment variables. (Note that this is supported with meta-commands in batch scripts as well.)

srun ... --singularity-args="--env-file job.env" ...

Bind Mounts

Option	Description
`--bind=src[:dest]`	Specify bind paths, where `src` and `dest` are paths outside and inside of the container respectively.

The container run-time allows to bind mount directories from the host system. The bind path and mounts section in the Apptainer User Guide ² describes this in detail. Paths like $HOME, $PWD, /tmp and /lustre are mounted by default. Users define additional mounts with the following option:

# download the official Debian 10 container
apptainer pull $APPTAINER_CONTAINERS/debian10.sif docker://debian:10

# bind-mount the CernVM-FS repositoires available on the cluster
apptainer exec --bind /cvmfs $APPTAINER_CONTAINERS/debian10.sif

This is particularly useful to access the CVMFS repositories available on the cluster.

Image Cache

Environment Variable	Description
`APPTAINER_CACHEDIR`	Cache folder for images from a container registry.
`APPTAINER_TMPDIR`	Temporary directory to build container file-systems.

By default the container build cache is located in $HOME/.apptainer. Details about the container build environment are available in the Apptainer User Guide ³. Pay attention to the storage consumed by the container cache, since the amount of available space is limited by a quota on your network home-directory.

# show storage capacity used by the cache
apptainercache list

# clean up everything
apptainer cache clean

The environment variable listed in the table on top are used to configure the paths to the container caches. Following example store all container artifacts on volatile storage in the /tmp directory by setting both variables:

# create a user specific directory in /tmp
tmp=$(mktemp -d /tmp/$USER-apptainer-XXXXXX)
export APPTAINER_TMPDIR=$tmp
export APPTAINER_CACHEDIR=$tmp

Footnotes

Apptainer User Guide - Environment and Metadata
http://apptainer.org/docs/user/main/environment_and_metadata.html ↩︎
Apptainer User Guide - Bind Paths and Mounts
http://apptainer.org/docs/user/main/bind_paths_and_mounts.html ↩︎
Apptainer User Guide - Build Environment
http://apptainer.org/docs/user/main/build_env.html#cache-folders ↩︎

--- title: Environment date-modified: 2023/11/10 abstract: > Container introduces an additional layer of indirection which does not inherit its host environment transparently. User will need to explicilty export environment varibales into the container environment. Furthermore management of the container images themselfs, as well as bind-mounting host file-systems into the container during run-time is under responsability of the user. --- ## Variables Apptainer provides multiple methods to set environment variables in the container, details are described in the _Apptainer User Guide_ [^sudem]. A container introduces an additional layer of indirection which does not inherit automatically environment variables set in the command execution environment used to launch the container. Hence it is up to the user to specify environment variables which require to be set in a container. There are two possible ways to do this, either by using command-line options for the `apptainer` command or by exporting environment variables with a specific prefix. ### `APPTAINERENV_` Env. Variable | Description --------------|-------------------------------------- `APPTAINERENV_*` | Environment variables prefixed with `APPTAINERENV_` will be set in the container `APPTAINERENV_APPEND_PATH` | Append (added to the end) a colon separated list of paths to the `PATH` variable in the container `APPTAINERENV_PREPEND_PATH` | Prepended (added to the start) a colon separated list of paths to the `PATH` variable in the container Apptainer reads environment variables prefixed with `APPTAINERENV_` from the execution environment and exports these in the container. The generic prefix can be used to set any number of environment variables. Within the containerized environment the prefix is removed from the environment variable name. For example a variable specified with the name `APPTAINERENV_LUSTRE_HOME` will be called `LUSTRE_HOME` within the container. ```sh # use the generic prefix to set an environment variable for the container » export APPTAINERENV_LUSTRE_HOME=$LUSTRE_HOME # run the container an read the ennvironment variables » apptainer exec $APPTAINER_CONTAINERS/debian11.sif env | grep ^LUSTRE LUSTRE_HOME=/lustre/hpc/vpenso ``` The `PATH` environment variable is a special case. Users have the option to overwrite the variable in the container using the generic prefix or to either append or prepend to the existing `PATH`. Note that in particular when using [virtual application environments][SReGT] the use if the generic prefix is very useful in order to export `LD_LIBRARY_PATH` to the container: [SReGT]: ../overview/software.html#vae ```sh export APPTAINERENV_LD_LIBRARY_PATH=$LD_LIBRARY_PATH export APPTAINERENV_PREPEND_PATH=$LUSTRE_HOME/bin ``` ### Command Options Option |Description -------|-------------------------------------- `--env NAME=VALUE[,NAME=VALUE,...]` | Specify a comma separated list of environment variables as `NAME=VALUE` pairs `--env-file <file>` | Provide a file that contains environment variables as `NAME=VALUE` pairs The command-line options listed set environment variables in a container: ```sh # Path to the container image... container=$APPTAINER_CONTAINERS/debian.sif # ...download the offical Debian container image apptainer pull $container docker://debian:latest # Set an environment variable LUSTRE_HOME... apptainer exec --env LUSTRE_HOME=$LUSTRE_HOME $container env | grep ^LUSTRE # ...check visibility of the variable during container execution ``` Users of an VAE can set the Slurm command line option `--singulairty-args` to to specify environment variables. (Note that this is supported with [meta-commands][dO2H2] in batch scripts as well.) ```sh srun ... --singularity-args="--env-file job.env" ... ``` [dO2H2]: ../cluster/environment.html#meta-commands [^sudem]: Apptainer User Guide - Environment and Metadata <http://apptainer.org/docs/user/main/environment_and_metadata.html> ## Bind Mounts Option | Description -------|--------------------------------------- `--bind=src[:dest]` | Specify bind paths, where `src` and `dest` are paths outside and inside of the container respectively. The container run-time allows to bind mount directories from the host system. The bind path and mounts section in the _Apptainer User Guide_ [^sugbm] describes this in detail. **Paths like `$HOME`, `$PWD`, `/tmp` and `/lustre` are mounted by default.** Users define additional mounts with the following option: [^sugbm]: Apptainer User Guide - Bind Paths and Mounts <http://apptainer.org/docs/user/main/bind_paths_and_mounts.html> ```sh # download the official Debian 10 container apptainer pull $APPTAINER_CONTAINERS/debian10.sif docker://debian:10 # bind-mount the CernVM-FS repositoires available on the cluster apptainer exec --bind /cvmfs $APPTAINER_CONTAINERS/debian10.sif ``` This is particularly useful to access the [CVMFS][7Tld2] repositories available on the cluster. [7Tld2]: ../storage/cvmfs.html ## Image Cache Environment Variable | Description ---------------------|---------------------------------- `APPTAINER_CACHEDIR` | Cache folder for images from a container registry. `APPTAINER_TMPDIR` | Temporary directory to build container file-systems. By default the container build cache is located in `$HOME/.apptainer`. Details about the container build environment are available in the Apptainer User Guide [^sugbe]. Pay attention to the storage consumed by the container cache, since the amount of available space is limited by a quota on your network [home-directory][cH9kK]. [cH9kK]: ../storage.html#home-directory [^sugbe]: Apptainer User Guide - Build Environment <http://apptainer.org/docs/user/main/build_env.html#cache-folders> ```sh # show storage capacity used by the cache apptainercache list # clean up everything apptainer cache clean ``` The environment variable listed in the table on top are used to configure the paths to the container caches. Following example store all container artifacts on volatile storage in the `/tmp` directory by setting both variables: ```sh # create a user specific directory in /tmp tmp=$(mktemp -d /tmp/$USER-apptainer-XXXXXX) export APPTAINER_TMPDIR=$tmp export APPTAINER_CACHEDIR=$tmp ```