diff options
Diffstat (limited to 'lib/spack/docs/containers.rst')
| -rw-r--r-- | lib/spack/docs/containers.rst | 151 |
1 files changed, 106 insertions, 45 deletions
diff --git a/lib/spack/docs/containers.rst b/lib/spack/docs/containers.rst index acf48e3eae..0033a081d3 100644 --- a/lib/spack/docs/containers.rst +++ b/lib/spack/docs/containers.rst @@ -9,34 +9,95 @@ Container Images ================ -Spack :ref:`environments` are a great tool to create container images, but -preparing one that is suitable for production requires some more boilerplate -than just: +Spack :ref:`environments` can easily be turned into container images. This page +outlines two ways in which this can be done: -.. code-block:: docker +1. By installing the environment on the host system, and copying the installations + into the container image. This approach does not require any tools like Docker + or Singularity to be installed. +2. By generating a Docker or Singularity recipe that can be used to build the + container image. In this approach, Spack builds the software inside the + container runtime, not on the host system. - COPY spack.yaml /environment - RUN spack -e /environment install +The first approach is easiest if you already have an installed environment, +the second approach gives more control over the container image. + +--------------------------- +From existing installations +--------------------------- + +If you already have a Spack environment installed on your system, you can +share the binaries as an OCI compatible container image. To get started you +just have to configure and OCI registry and run ``spack buildcache push``. + +.. code-block:: console + + # Create and install an environment in the current directory + spack env create -d . + spack -e . add pkg-a pkg-b + spack -e . install -Additional actions may be needed to minimize the size of the -container, or to update the system software that is installed in the base -image, or to set up a proper entrypoint to run the image. These tasks are -usually both necessary and repetitive, so Spack comes with a command -to generate recipes for container images starting from a ``spack.yaml``. + # Configure the registry + spack -e . mirror add --oci-username ... --oci-password ... container-registry oci://example.com/name/image -.. seealso:: + # Push the image + spack -e . buildcache push --base-image ubuntu:22.04 --tag my_env container-registry + +The resulting container image can then be run as follows: + +.. code-block:: console + + $ docker run -it example.com/name/image:my_env + +The image generated by Spack consists of the specified base image with each package from the +environment as a separate layer on top. The image is minimal by construction, it only contains the +environment roots and its runtime dependencies. + +.. note:: - This page is a reference for generating recipes to build container images. - It means that your environment is built from scratch inside the container - runtime. + When using registries like GHCR and Docker Hub, the ``--oci-password`` flag is not + the password for your account, but a personal access token you need to generate separately. + +The specified ``--base-image`` should have a libc that is compatible with the host system. +For example if your host system is Ubuntu 20.04, you can use ``ubuntu:20.04``, ``ubuntu:22.04`` +or newer: the libc in the container image must be at least the version of the host system, +assuming ABI compatibility. It is also perfectly fine to use a completely different +Linux distribution as long as the libc is compatible. + +For convenience, Spack also turns the OCI registry into a :ref:`build cache <binary_caches_oci>`, +so that future ``spack install`` of the environment will simply pull the binaries from the +registry instead of doing source builds. + +.. note:: + + When generating container images in CI, the approach above is recommended when CI jobs + already run in a sandboxed environment. You can simply use ``spack`` directly + in the CI job and push the resulting image to a registry. Subsequent CI jobs should + run faster because Spack can install from the same registry instead of rebuilding from + sources. + +--------------------------------------------- +Generating recipes for Docker and Singularity +--------------------------------------------- + +Apart from copying existing installations into container images, Spack can also +generate recipes for container images. This is useful if you want to run Spack +itself in a sandboxed environment instead of on the host system. + +Since recipes need a little bit more boilerplate than + +.. code-block:: docker + + COPY spack.yaml /environment + RUN spack -e /environment install - Since v0.21, Spack can also create container images from existing package installations - on your host system. See :ref:`binary_caches_oci` for more information on - that topic. +Spack provides a command to generate customizable recipes for container images. Customizations +include minimizing the size of the image, installing packages in the base image using the system +package manager, and setting up a proper entrypoint to run the image. --------------------- +~~~~~~~~~~~~~~~~~~~~ A Quick Introduction --------------------- +~~~~~~~~~~~~~~~~~~~~ Consider having a Spack environment like the following: @@ -47,8 +108,8 @@ Consider having a Spack environment like the following: - gromacs+mpi - mpich -Producing a ``Dockerfile`` from it is as simple as moving to the directory -where the ``spack.yaml`` file is stored and giving the following command: +Producing a ``Dockerfile`` from it is as simple as changing directories to +where the ``spack.yaml`` file is stored and running the following command: .. code-block:: console @@ -114,9 +175,9 @@ configuration are discussed in details in the sections below. .. _container_spack_images: --------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~ Spack Images on Docker Hub --------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~ Docker images with Spack preinstalled and ready to be used are built when a release is tagged, or nightly on ``develop``. The images @@ -186,9 +247,9 @@ by Spack use them as default base images for their ``build`` stage, even though handles to use custom base images provided by users are available to accommodate complex use cases. ---------------------------------- -Creating Images From Environments ---------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Configuring the Container Recipe +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Any Spack Environment can be used for the automatic generation of container recipes. Sensible defaults are provided for things like the base image or the @@ -229,18 +290,18 @@ under the ``container`` attribute of environments: A detailed description of the options available can be found in the :ref:`container_config_options` section. -------------------- +~~~~~~~~~~~~~~~~~~~ Setting Base Images -------------------- +~~~~~~~~~~~~~~~~~~~ The ``images`` subsection is used to select both the image where Spack builds the software and the image where the built software is installed. This attribute can be set in different ways and which one to use depends on the use case at hand. -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +"""""""""""""""""""""""""""""""""""""""" Use Official Spack Images From Dockerhub -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +"""""""""""""""""""""""""""""""""""""""" To generate a recipe that uses an official Docker image from the Spack organization to build the software and the corresponding official OS image @@ -445,9 +506,9 @@ responsibility to ensure that: Therefore we don't recommend its use in cases that can be otherwise covered by the simplified mode shown first. ----------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Singularity Definition Files ----------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In addition to producing recipes in ``Dockerfile`` format Spack can produce Singularity Definition Files by just changing the value of the ``format`` @@ -468,9 +529,9 @@ attribute: The minimum version of Singularity required to build a SIF (Singularity Image Format) image from the recipes generated by Spack is ``3.5.3``. ------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Extending the Jinja2 Templates ------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The Dockerfile and the Singularity definition file that Spack can generate are based on a few Jinja2 templates that are rendered according to the environment being containerized. @@ -591,9 +652,9 @@ The recipe that gets generated contains the two extra instruction that we added .. _container_config_options: ------------------------ +~~~~~~~~~~~~~~~~~~~~~~~ Configuration Reference ------------------------ +~~~~~~~~~~~~~~~~~~~~~~~ The tables below describe all the configuration options that are currently supported to customize the generation of container recipes: @@ -690,13 +751,13 @@ to customize the generation of container recipes: - Description string - No --------------- +~~~~~~~~~~~~~~ Best Practices --------------- +~~~~~~~~~~~~~~ -^^^ +""" MPI -^^^ +""" Due to the dependency on Fortran for OpenMPI, which is the spack default implementation, consider adding ``gfortran`` to the ``apt-get install`` list. @@ -707,9 +768,9 @@ For execution on HPC clusters, it can be helpful to import the docker image into Singularity in order to start a program with an *external* MPI. Otherwise, also add ``openssh-server`` to the ``apt-get install`` list. -^^^^ +"""" CUDA -^^^^ +"""" Starting from CUDA 9.0, Nvidia provides minimal CUDA images based on Ubuntu. Please see `their instructions <https://hub.docker.com/r/nvidia/cuda/>`_. Avoid double-installing CUDA by adding, e.g. @@ -728,9 +789,9 @@ to your ``spack.yaml``. Users will either need ``nvidia-docker`` or e.g. Singularity to *execute* device kernels. -^^^^^^^^^^^^^^^^^^^^^^^^^ +""""""""""""""""""""""""" Docker on Windows and OSX -^^^^^^^^^^^^^^^^^^^^^^^^^ +""""""""""""""""""""""""" On Mac OS and Windows, docker runs on a hypervisor that is not allocated much memory by default, and some spack packages may fail to build due to lack of |