Difference between revisions of "Singularity4"

From VeRLab Wiki
Jump to: navigation, search
m (→‎7) Montar /homeLocal/usuario dentro container para salvar resultados (opção --bind ))
(→‎Singularity CE 4.x (Community Edition))
 
(20 intermediate revisions by the same user not shown)
Line 13: Line 13:
 
** '''Exemplos de ''Definition Files'' ''': https://github.com/sylabs/examples
 
** '''Exemplos de ''Definition Files'' ''': https://github.com/sylabs/examples
 
** '''Singularity ''Definition Files'' vs. ''Docker file'' ''': https://docs.sylabs.io/guides/4.1/user-guide/singularity_and_docker.html#sec-deffile-vs-dockerfile
 
** '''Singularity ''Definition Files'' vs. ''Docker file'' ''': https://docs.sylabs.io/guides/4.1/user-guide/singularity_and_docker.html#sec-deffile-vs-dockerfile
 +
** '''Singularity ''Definition File Catalog'': https://singularityhub.github.io/singularity-catalog/
 +
 +
<br>
 
<br>
 
<br>
 +
{| class="wikitable"
 +
|-
 +
! Exemplo de Definition File - miniconda-pytorch.def
 +
|-
 +
|<pre>
 +
# Origem da imagem inicial
 +
# https://hub.docker.com/r/continuumio/miniconda3/tags
 +
# https://hub.docker.com/r/continuumio/miniconda3/dockerfile
 +
BootStrap: docker
 +
From: continuumio/miniconda3:latest
 +
 +
# Informação  impressa com comando "singularity inspect.."
 +
%labels
 +
    Author mauferrari
 +
    Maintainer Equipe de Infraestrutura da rede VeRLab/JLab
 +
    Version 1.0
 +
    Date ago/2024
 +
 +
 +
# Informação  impressa com comando "singularity inspect --helpfile..."
 +
%help
 +
    Container with:
 +
        continuumio/miniconda3:latest
 +
        https://hub.docker.com/r/continuumio/miniconda3
 +
            debian
 +
            miniconda (latest) instalado em /opt/conda
 +
            conda create --name env-torch pytorch torchvision torchaudio pytorch-cuda=12.1 -c pytorch -c nvidia
 +
 +
 +
# Environment Variables para o container em tempo de execução (runtime)
 +
%environment
 +
    export LC_ALL=C
 +
 +
 +
# Copiar arquivos para o container
 +
%files
 +
    # <path_origem>  <path_destino>
 +
    #env-conda.yml /opt/env-conda.yml
 +
 +
 +
# Instalar pacotes e fazer configurações
 +
%post
 +
 +
    # Conferir conda e configurar
 +
    conda --version
 +
    which conda
 +
   
 +
    # Cria arquivo de configurações do conda/opt/conda/.condarc
 +
    # Configurações do conda
 +
    export CONDA_ROOT=/opt/conda
 +
    conda config --file $CONDA_ROOT/.condarc --add channels conda-forge
 +
    conda config --file $CONDA_ROOT/.condarc --set auto_update_conda False
 +
    conda config --file $CONDA_ROOT/.condarc --set auto_activate_base True
 +
    conda config --file $CONDA_ROOT/.condarc --set show_channel_urls True
 +
 +
    # Install conda bash completion
 +
    # https://github.com/tartansandal/conda-bash-completion
 +
    conda install --yes --name base --channel conda-forge conda-bash-completion
 +
 +
    # Criar um novo environmet a partir do env-conda.yml
 +
    #conda env create --file /opt/env-conda.yml
 +
 +
    # Cria arquivo de inicialização do bash para seção de %runscript
 +
    cd /opt
 +
    pwd
 +
    touch .bashrc
 +
    echo 'source /opt/conda/etc/profile.d/conda.sh' >> .bashrc
 +
    echo 'source /opt/conda/etc/profile.d/bash_completion.sh' >> .bashrc
 +
 +
 +
    # Criar un novo enviroment com pacotes desejados do pytorch
 +
    # https://pytorch.org/get-started/locally/
 +
    # Opções: pytorch stable 2.4.0, linux, conda, cuda 12.1
 +
    conda create --name env-torch pytorch torchvision torchaudio pytorch-cuda=12.1 -c pytorch -c nvidia
 +
 +
 +
    # Clear files and downloaded data
 +
    conda clean --all --yes
 +
    #rm -v /opt/env-conda.yml
 +
    rm -rf /var/lib/apt/lists/*
 +
    apt-get clean
 +
 +
 +
# O que é executado com o comando "singularity run..."
 +
%runscript
 +
    echo "Informação do container..."
 +
    cat /etc/os-release
 +
    conda --version
 +
    echo "Inicia bash com source dos comandos do conda: activate, deactivate e etc"
 +
    bash --rcfile /opt/.bashrc
 +
 +
 +
# Comando para criar o container
 +
# $ singularity build --fakeroot --fix-perms stress-pytorch.sif miniconda-pytorch.def
 +
 +
</pre>
 +
 +
|}
 +
Caso precise adicionar ou remover variáveis no <code>%environment</code> durante a edição da pasta sandbox, basta editar o arquivo <code>90-environment.sh</code> localizado em <code>/.singularity.d/env/</code> dentro do container sandbox.
 +
 +
<br><br>
  
 
== <span style="color: red;">IMPORTANTE</span>: Diferença entre os 2 formatos suportados pelo <code>singularity build</code>: ==
 
== <span style="color: red;">IMPORTANTE</span>: Diferença entre os 2 formatos suportados pelo <code>singularity build</code>: ==
Line 46: Line 150:
  
 
# Confirmar se a máquina tem singularity instalado e a versão
 
# Confirmar se a máquina tem singularity instalado e a versão
−
# Solicitar sua pasta de trabalho com seu nome de usuário (storage ou homeLocal)
+
# Solicitar sua pasta de trabalho com seu nome de usuário (storage ou /draft-xxx)
 
# Escrever a "receita" (definition file) do seu container Singularity  
 
# Escrever a "receita" (definition file) do seu container Singularity  
 
# Criar seu container Singularity no formato "pasta sandbox" usando seu definition file
 
# Criar seu container Singularity no formato "pasta sandbox" usando seu definition file
Line 59: Line 163:
 
<br><br>
 
<br><br>
  
−
==== 2) Solicitar a criação da sua pasta de trabalho com seu nome de usuário (storage ou homeLocal) ====
+
==== 2) Solicitar a criação da sua pasta de trabalho com seu nome de usuário (storage ou /draft-xxx) ====
 
Deve-se solicitar a um gestor da infraestrutura da rede VeRLab/JLab para criar uma pasta com seu nome de usuário e mudar o proprietário da pasta para seu usuário da rede do Verlab e o grupo DomainUsers (<code>gid=513</code>).
 
Deve-se solicitar a um gestor da infraestrutura da rede VeRLab/JLab para criar uma pasta com seu nome de usuário e mudar o proprietário da pasta para seu usuário da rede do Verlab e o grupo DomainUsers (<code>gid=513</code>).
  
 
Existem duas opções de locais para armazenar sua pasta de containers singularity:
 
Existem duas opções de locais para armazenar sua pasta de containers singularity:
 
* No serviço de storage da rede, na pasta <code>/srv/forge/fulano/</code> ou   
 
* No serviço de storage da rede, na pasta <code>/srv/forge/fulano/</code> ou   
−
* Localemente em alguma máquina, na pasta <code>/homeLocal/fulano</code>
+
* Localemente em alguma máquina, na pasta <code>/draft-xxx/fulano</code>
  
 
===== 2a) Pasta no serviço de storage (<code>'''/srv/forge'''</code>): =====
 
===== 2a) Pasta no serviço de storage (<code>'''/srv/forge'''</code>): =====
Line 75: Line 179:
 
     cd /srv/forge/fulano
 
     cd /srv/forge/fulano
  
−
===== 2b) Pasta no disco local de alguma máquina da rede <code>'''/homeLocal'''</code>): =====
+
===== 2b) Pasta no disco local de alguma máquina da rede <code>'''/draft-xxx'''</code>): =====
−
* As máquinas da rede com GPU costumam ter uma partição do disco separada para os usuários ocuparem com dados de experimentos e testes. Essa partição é montada na pasta  <code>'''/homeLocal'''</code>
+
* As máquinas da rede com GPU costumam ter uma partição do disco separada para os usuários ocuparem com dados de experimentos e testes. Essa partição é montada na pasta  <code>'''/draft-xxx'''</code>
 
* É importante que cada usuário limpe seus dados de experimentos e testes com frequência, pois não existe uma política de "quotas", assim todos contribuem para  para liberar espaço em disco para os demais usuários.
 
* É importante que cada usuário limpe seus dados de experimentos e testes com frequência, pois não existe uma política de "quotas", assim todos contribuem para  para liberar espaço em disco para os demais usuários.
−
     cd /homeLocal
+
     cd /draft-xxx
 
     sudo mkdir fulano
 
     sudo mkdir fulano
 
     sudo chown -Rv fulano:513 fulano/
 
     sudo chown -Rv fulano:513 fulano/
−
     cd /homeLocal/fulano
+
     cd /draft-xxx/fulano
 
<br><br>
 
<br><br>
  
Line 199: Line 303:
 
<br><br>
 
<br><br>
  
−
==== 5) Usar o shell do container em modo --writable --no-home --fakeroot (instalar, modificar e testar) ====
+
==== 5) Usar o shell do container em modo --writable --fakeroot --no-home (instalar, modificar e testar) ====
  
 
Executar seu singularity no formato "pasta sandbox" em "modo escrita" para instalar pacotes.
 
Executar seu singularity no formato "pasta sandbox" em "modo escrita" para instalar pacotes.
Line 207: Line 311:
  
 
Se o instalador tentar usar a /home/root, deve-se ler a documentação do instalador para optar por pastas alternativas dentro da estrutura do container como /usr/bin, /usr/local, /opt/
 
Se o instalador tentar usar a /home/root, deve-se ler a documentação do instalador para optar por pastas alternativas dentro da estrutura do container como /usr/bin, /usr/local, /opt/
−
     singularity shell --writable --no-home --fakeroot my_container/
+
     singularity shell --writable --fakeroot --no-home my_container/
  
 
* Foi escolhido que das máquinas de processamento na rede, apenas '''EPONA, GHOST e MAGRITTE''' serão capazes de criar um container e abrir em modo edição.  
 
* Foi escolhido que das máquinas de processamento na rede, apenas '''EPONA, GHOST e MAGRITTE''' serão capazes de criar um container e abrir em modo edição.  
Line 219: Line 323:
 
<br><br>
 
<br><br>
  
−
==== 7) Montar /homeLocal/usuario dentro container para salvar resultados (opção <code> --bind </code>) ====
+
==== 7) Montar /draft-xxx/usuario dentro container para salvar resultados (opção <code> --bind </code>) ====
 
O comportamento padrão do SingularityCE é montar as pastas /home/$USER, /tmp, and $PWD da máquina host dentro do container ([https://docs.sylabs.io/guides/4.1/user-guide/bind_paths_and_mounts.html#system-defined-bind-paths algumas outras pastas também] ). A montagem automática da pasta /home/$USER foi desabilitada na rede VeRLab/JLab.
 
O comportamento padrão do SingularityCE é montar as pastas /home/$USER, /tmp, and $PWD da máquina host dentro do container ([https://docs.sylabs.io/guides/4.1/user-guide/bind_paths_and_mounts.html#system-defined-bind-paths algumas outras pastas também] ). A montagem automática da pasta /home/$USER foi desabilitada na rede VeRLab/JLab.
  
Line 225: Line 329:
 
     singularity shell --bind [/absolute/path/host/]:[/absolute/path/inside/container]
 
     singularity shell --bind [/absolute/path/host/]:[/absolute/path/inside/container]
  
−
O caminho de montagem dentro do container é opcional e se for omitido, é usado o mesmo caminho do host, porém o usuário deve ter permissão para acessar a pasta de montagem. No exemplo mostra como deixar o path /homeLocal/fulano acessível  dentro do container em /mnt:
+
O caminho de montagem dentro do container é opcional e se for omitido, é usado o mesmo caminho do host, porém o usuário deve ter permissão para acessar a pasta de montagem. No exemplo mostra como deixar o path /draft-xxx/fulano acessível  dentro do container em /mnt:
−
     singularity shell --bind /homeLocal/fulano:/mnt my_container/
+
     singularity shell --bind /draft-xxx/fulano:/mnt my_container/
  
 
Também é possível combinar as opções do --bind com --writable --no-home --fakeroot, neste caso, para fazer modificações na imagem e acessar a pasta de montagem:
 
Também é possível combinar as opções do --bind com --writable --no-home --fakeroot, neste caso, para fazer modificações na imagem e acessar a pasta de montagem:
−
     singularity shell --writable --no-home --fakeroot --bind /homeLocal/fulano:/mnt my_container/
+
     singularity shell --writable --fakeroot --no-home --bind /draft-xxx/fulano:/mnt my_container/
  
 
* link sobre a opção <code>[https://docs.sylabs.io/guides/4.1/user-guide/quick_start.html#working-with-files '''--bind''']</code>
 
* link sobre a opção <code>[https://docs.sylabs.io/guides/4.1/user-guide/quick_start.html#working-with-files '''--bind''']</code>
Line 285: Line 389:
 
Assim para criar o container usando <code>build</code> e copiando do repositório exemplo a tag <code>opencv-4.0.1</code>, tem-se:
 
Assim para criar o container usando <code>build</code> e copiando do repositório exemplo a tag <code>opencv-4.0.1</code>, tem-se:
  
−
     singularity build --sandbox opencv-base docker://jjanzic/docker-python3-opencv:opencv-4.0.1
+
     singularity build --sandbox --fakeroot --fix-perms opencv-base docker://jjanzic/docker-python3-opencv:opencv-4.0.1
 
<br><br>
 
<br><br>
  
Line 339: Line 443:
 
<br><br>
 
<br><br>
  
−
== <code>opção '''--writable'''</code>: Permitir alterar o container em formato pasta sandbox: ==
+
== <code>opção '''--writable --fakeroot'''</code>: Permitir alterar o container em formato pasta sandbox: ==
  
−
* Só é possivel alterar um container em formato <code>sandbox</code>, uma boa prática é adicionar a opção --no-home é importante para não ocorrer a montagem automática da /home do root, e evitar que instaladores tentem usar essa pasta para instalação de pacotes.
+
* Só é possível alterar um container em formato <code>sandbox</code>, uma boa prática é adicionar a opção --no-home é importante para não ocorrer a montagem automática da /home do root, e evitar que instaladores tentem usar essa pasta para instalação de pacotes.
−
     singularity shell --writable --no-home --fakeroot my_container/
+
     singularity shell --writable --fakeroot --no-home my_container/
 
<br><br>
 
<br><br>
  
Line 348: Line 452:
 
A pasta do home do usuário é montada automaticamente pelo singularity dentro da máquina container ([https://docs.sylabs.io/guides/4.1/user-guide/bind_paths_and_mounts.html#system-defined-bind-paths algumas outras também ] ), mas se for necessário acessar outra pasta no disco da máquina host, deve-se usar a opção <code>[https://docs.sylabs.io/guides/4.1/user-guide/bind_paths_and_mounts.html#user-defined-bind-paths --bind]</code> para indicar o caminho (path) a ser usado. O usuário precisa ter permissão de leitura e escrita na pasta da máquina host.
 
A pasta do home do usuário é montada automaticamente pelo singularity dentro da máquina container ([https://docs.sylabs.io/guides/4.1/user-guide/bind_paths_and_mounts.html#system-defined-bind-paths algumas outras também ] ), mas se for necessário acessar outra pasta no disco da máquina host, deve-se usar a opção <code>[https://docs.sylabs.io/guides/4.1/user-guide/bind_paths_and_mounts.html#user-defined-bind-paths --bind]</code> para indicar o caminho (path) a ser usado. O usuário precisa ter permissão de leitura e escrita na pasta da máquina host.
  
−
* Executar a máquina container no shell e montar o caminho /homeLocal/fulano da máquina host dentro da máquina container  
+
* Executar a máquina container no shell e montar o caminho /draft-xxx/fulano da máquina host dentro da máquina container
 +
 
 +
<code>singularity shell --bind /draft-xxx/fulano:/mnt my_container/</code>
 +
<br><br>
 +
 
 +
== <code>opção '''--nv'''</code>:Uso de GPU dentro do container ==
 +
A [https://docs.sylabs.io/guides/4.1/user-guide/gpu.html documentação do singularityCE] apresenta as propriedades para usar GPU Nvidia dentro do container e consequentemente o CUDA.
 +
* https://docs.sylabs.io/guides/4.1/user-guide/gpu.html
 +
 
 +
 
 +
'''Por padrão as máquinas da rede VeRLab/JLab tem apenas o driver Nvidia instalado e o container deve ter a instalação do CUDA.'''
 +
 
 +
Para utilizar os recursos da GPU, o container Singularity faz um linking com o driver da máquina host, o que já disponibiliza, para o container, a mesma versão do driver e do CUDA que já estão instalados na máquina host.
 +
 
 +
 
 +
A principal vantagem dessa abordagem é evitar ter que fazer configurações extras como a do nvidia-container-toolkit, que é necessária no Docker.
 +
 
 +
 
 +
Ainda assim, é importante prestar atenção à versão do driver Nvidia instalada no sistema para que o container consiga acessar a GPU!
 +
 
 +
 
 +
A versão de CUDA instalada dentro do container é totalmente independente da versão instalada na máquina host, o que significa que é possível rodar uma versão do CUDA no container que é diferente da versão instalada na máquina host. Mas é importante prestar atenção que a versão do driver do container será sempre igual à versão do driver na máquina host, pois é feito um link do container para o host, e isso não pode ser mudado.
 +
 
 +
Pode-se verificar a versão do driver Nvidia instalado executando '''<code>nvidia-smi</code>''' na máquina host.
 +
 
 +
 
 +
Por conta disso, '''pode ser que a versão do driver instalada na máquina host não suporte todas as versões do CUDA'''. Para ver quais versões são suportadas, é importante se atentar a quais
 +
versões do CUDA a versão do driver atual suporta. Isso pode ser verificado em:
 +
 
 +
* https://docs.nvidia.com/deploy/cuda-compatibility/index.html.
 +
 
 +
 
 +
Para carregar o driver Nvidia no container use a opção  '''<code>--nv</code>'''
 +
 
 +
<pre>
 +
Commands that run, or otherwise execute containers (shell, exec) can take an <>--nv option, w
 +
hich will setup the container’s environment to use an NVIDIA GPU and the basic CUDA libraries to run a CUDA enabled application.
 +
The --nv flag will:
 +
- Ensure that the /dev/nvidiaX device entries are available inside the container, so that the GPU cards in the host are accessible.
 +
- Locate and bind the basic CUDA libraries from the host into the container, so that they are available to the container, and match the kernel GPU driver on the host.
 +
- Set the LD_LIBRARY_PATH inside the container so that the bound-in version of the CUDA libraries are used by applications run inside the container.
 +
</pre>
 +
 
 +
 
 +
* Executar a máquina container no shell e montar o caminho /draft-xxx/fulano da máquina host dentro da máquina container  
  
−
<code>singularity shell --bind /homeLocal/fulano:/mnt my_container/</code>
+
<code>singularity shell --nv --bind /draft-xxx/fulano:/mnt my_cuda_container/</code>
 
<br><br>
 
<br><br>

Latest revision as of 13:23, 8 June 2025

Contents

Singularity CE 4.x (Community Edition)

Esta será a versão utilizada na rede VeRLab/JLab a partir de jun/2024, atualmente instalado nas máquinas a v4.1.x

Documentação oficial Singularity CE v4.1.x

User Guide CE v4.1.x
Adm Guide CE v4.1.x (Apenas para problemas mais específicos de segurança e instalação!)
Definition Files



Exemplo de Definition File - miniconda-pytorch.def 
# Origem da imagem inicial
# https://hub.docker.com/r/continuumio/miniconda3/tags
# https://hub.docker.com/r/continuumio/miniconda3/dockerfile
BootStrap: docker
From: continuumio/miniconda3:latest

# Informação  impressa com comando "singularity inspect.."
%labels
    Author mauferrari
    Maintainer Equipe de Infraestrutura da rede VeRLab/JLab
    Version 1.0 
    Date ago/2024


# Informação  impressa com comando "singularity inspect --helpfile..."
%help
    Container with:
        continuumio/miniconda3:latest
        https://hub.docker.com/r/continuumio/miniconda3
            debian
            miniconda (latest) instalado em /opt/conda
            conda create --name env-torch pytorch torchvision torchaudio pytorch-cuda=12.1 -c pytorch -c nvidia


# Environment Variables para o container em tempo de execução (runtime)
%environment
    export LC_ALL=C


# Copiar arquivos para o container
%files
    # <path_origem>  <path_destino>
    #env-conda.yml /opt/env-conda.yml


# Instalar pacotes e fazer configurações
%post

    # Conferir conda e configurar
    conda --version
    which conda
    
    # Cria arquivo de configurações do conda/opt/conda/.condarc
    # Configurações do conda
    export CONDA_ROOT=/opt/conda
    conda config --file $CONDA_ROOT/.condarc --add channels conda-forge
    conda config --file $CONDA_ROOT/.condarc --set auto_update_conda False
    conda config --file $CONDA_ROOT/.condarc --set auto_activate_base True
    conda config --file $CONDA_ROOT/.condarc --set show_channel_urls True

    # Install conda bash completion
    # https://github.com/tartansandal/conda-bash-completion
    conda install --yes --name base --channel conda-forge conda-bash-completion

    # Criar um novo environmet a partir do env-conda.yml
    #conda env create --file /opt/env-conda.yml

    # Cria arquivo de inicialização do bash para seção de %runscript
    cd /opt
    pwd
    touch .bashrc
    echo 'source /opt/conda/etc/profile.d/conda.sh' >> .bashrc
    echo 'source /opt/conda/etc/profile.d/bash_completion.sh' >> .bashrc


    # Criar un novo enviroment com pacotes desejados do pytorch
    # https://pytorch.org/get-started/locally/
    # Opções: pytorch stable 2.4.0, linux, conda, cuda 12.1
    conda create --name env-torch pytorch torchvision torchaudio pytorch-cuda=12.1 -c pytorch -c nvidia
	

    # Clear files and downloaded data 
    conda clean --all --yes
    #rm -v /opt/env-conda.yml
    rm -rf /var/lib/apt/lists/*
    apt-get clean 


# O que é executado com o comando "singularity run..."
%runscript
    echo "Informação do container..."
    cat /etc/os-release
    conda --version
    echo "Inicia bash com source dos comandos do conda: activate, deactivate e etc"
    bash --rcfile /opt/.bashrc 


# Comando para criar o container
# $ singularity build --fakeroot --fix-perms stress-pytorch.sif miniconda-pytorch.def

Caso precise adicionar ou remover variáveis no %environment durante a edição da pasta sandbox, basta editar o arquivo 90-environment.sh localizado em /.singularity.d/env/ dentro do container sandbox.



IMPORTANTE: Diferença entre os 2 formatos suportados pelo singularity build:

Pasta sandbox: INDICADO PARA FASE DE TESTES E MODIFICAÇÕES no container (instalar pacotes)

  • Destinado para desenvolvimento interativo do container, quando ainda precisa fazer testes e não se sabe exatamente as configurações/ferramentas a serem usadas, logo o container pode ter novas instalações e alterações nos pacotes.
  • Vantagem: vários arquivos e sub-pastas que são expansíveis automaticamente conforme os pacotes são instalados (opção --writable). O tamanho do disco é expansível conforme disponibilidade de espaço em disco da máquina host.
  • Desvantagem: Execução mais lenta, muitos arquivos para copiar de uma máquina para outra e reproduzir o experimento
  • writable (ch)root directory called a sandbox for interactive development ( --sandbox option)


Arquivo único, extensão .sif: SOMENTE LEITURA, NÃO é possível editar o container

  • Destinado para fase de experimentos em massa (production)
  • Vantagem: É uma imagem comprimida, ocupa menos espaço em disco e executa mais rápido que um container equivalente no formato sandbox. Também suporta criptografia
  • Desvantagem: Não é possível instalar/modificar pacotes do container. Para instalar/editar algo, tem que transformar em "pasta sandbox".
  • compressed read-only Singularity Image File (SIF) format suitable for production (default)


Passo a Passo: Uso do Singularity CE v4.1.x

Uso simplificado: NÃO É MAIS NECESSÁRIO USAR O COMANDO sudo PARA UTILIZAR O SINGULARITY

Com a introdução do Singularity 4, alguns comandos agora requerem o uso da flag --fakeroot. Esta flag permite que usuários comuns possam construir e modificar containers sem a necessidade de privilégios de superusuário, simplificando a utilização.

Ao utilizar --fakeroot, o Singularity simula um ambiente root, permitindo operações que normalmente precisariam de acesso root real, veja na documentação.

Exemplo de comando com --fakeroot: 

   singularity build --sandbox --fakeroot --fix-perms my-def-v1 my-def-v1.def

Este comando constrói um container no formato sandbox usando um arquivo de definição, sem precisar de privilégios de superusuário.



Exemplos de interação mais usuais com o container singularity

  1. Confirmar se a máquina tem singularity instalado e a versão
  2. Solicitar sua pasta de trabalho com seu nome de usuário (storage ou /draft-xxx)
  3. Escrever a "receita" (definition file) do seu container Singularity
  4. Criar seu container Singularity no formato "pasta sandbox" usando seu definition file
  5. Usar o shell do container em modo --writable --no-home (instalar, modificar e testar)
  6. Usar o shell em modo "somente leitura" para executar sem modificar
  7. Usar o shell e montar uma pasta do host
  8. Converter um container singularity do formato "pasta sandbox" para o formato .sif (imagem compactada)



1) Conferir se a máquina tem singularity instalado e a versão

   singularity --version



2) Solicitar a criação da sua pasta de trabalho com seu nome de usuário (storage ou /draft-xxx)

Deve-se solicitar a um gestor da infraestrutura da rede VeRLab/JLab para criar uma pasta com seu nome de usuário e mudar o proprietário da pasta para seu usuário da rede do Verlab e o grupo DomainUsers (gid=513).

Existem duas opções de locais para armazenar sua pasta de containers singularity:

  • No serviço de storage da rede, na pasta /srv/forge/fulano/ ou
  • Localemente em alguma máquina, na pasta /draft-xxx/fulano
2a) Pasta no serviço de storage (/srv/forge):
  • Foi escolhido que das máquinas de processamento na rede, apenas EPONA, GHOST e MAGRITTE serão capazes de criar um container.
  • Outra restrição é que essa permissão só pode ser executada na pasta /srv/forge
  • É importante que cada usuário limpe seus dados de experimentos e testes com frequência, pois não existe uma política de "quotas", assim todos contribuem para para liberar espaço na storage para os demais usuários.
   cd /srv/forge 
   sudo mkdir fulano
   sudo chown -Rv fulano:513 fulano/
   cd /srv/forge/fulano
2b) Pasta no disco local de alguma máquina da rede /draft-xxx):
  • As máquinas da rede com GPU costumam ter uma partição do disco separada para os usuários ocuparem com dados de experimentos e testes. Essa partição é montada na pasta /draft-xxx
  • É importante que cada usuário limpe seus dados de experimentos e testes com frequência, pois não existe uma política de "quotas", assim todos contribuem para para liberar espaço em disco para os demais usuários.
   cd /draft-xxx
   sudo mkdir fulano
   sudo chown -Rv fulano:513 fulano/
   cd /draft-xxx/fulano



3) Escrever a "receita" (definition file) do seu container Singularity

O Definition file é o arquivo que descreve a forma como o Singularity vai criar seu container, qual sistema operacional será usado como base, quais pacotes instalar, criar alguma pasta e etc Na documentação so singularity tem mais explicações sobre a sintaxe e função de cada campo:
Definition Files


Abaixo um exemplo de definition file (salvo como ubuntu20-cuda.def) que tem como base um sistema operacional ubuntu 20.04 e instala os pacotes para executar o cuda toolkit 11.4:

Exemplo de Definition File - ubuntu20-cuda.def 
BootStrap: library
From: ubuntu:20.04

%post
    cd
    apt -y update
    DEBIAN_FRONTEND=noninteractive \
    apt -y install \
    git \
    curl \
    wget \
    zip \
    cmake \
    ninja-build \
    build-essential \
    libboost-program-options-dev \
    libboost-filesystem-dev \
    libboost-graph-dev \
    libboost-system-dev \
    libeigen3-dev \
    libflann-dev \
    libfreeimage-dev \
    libmetis-dev \
    libgoogle-glog-dev \
    libgtest-dev \
    libsqlite3-dev \
    libglew-dev \
    qtbase5-dev \
    libqt5opengl5-dev \
    libcgal-dev \
    libceres-dev
    
    # CUDA Toolkit 11.4 pode ser encontrado em https://developer.nvidia.com/cuda-11-4-0-download-archive
    export PATH=$PATH:/usr/local/cuda/bin
    wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2004/x86_64/cuda-ubuntu2004.pin
    mv cuda-ubuntu2004.pin /etc/apt/preferences.d/cuda-repository-pin-600
    wget https://developer.download.nvidia.com/compute/cuda/11.4.2/local_installers/cuda-repo-ubuntu2004-11-4-local_11.4.2-470.57.02-1_amd64.deb
    dpkg -i cuda-repo-ubuntu2004-11-4-local_11.4.2-470.57.02-1_amd64.deb
    apt-key add /var/cuda-repo-ubuntu2004-11-4-local/7fa2af80.pub
    apt update
    DEBIAN_FRONTEND=noninteractive \
    apt -y install cuda

    wget https://github.com/colmap/colmap/archive/refs/tags/3.9.1.zip
    unzip 3.9.1.zip
    cd colmap-3.9.1
    mkdir build
    cd build
    cmake .. -GNinja -DCMAKE_CUDA_ARCHITECTURES=70
    ninja
    ninja install
    cd

    # limpar cache das instalações
    rm -rf /var/lib/apt/lists/*
    apt-get clean


%environment
   export PATH=$PATH:/usr/local/cuda/bin
   export LC_ALL=C


%labels
    Author Verlab

Para criar seu container 

   singularity build --sandbox --fakeroot --fix-perms my-cuda/ ubuntu20-cuda.def

Caso precise adicionar ou remover variáveis no %environment durante a edição da pasta sandbox, basta editar o arquivo 90-environment.sh localizado em /.singularity.d/env/ dentro do container sandbox.



4) Criar seu container Singularity no formato "pasta sandbox" usando seu definition file

O formato sandbox é usado para modificar e instalar pacotes no container 

   singularity build --sandbox --fakeroot --fix-perms [pasta_destino] [definition-file.def]

A base usada na construção do container pode ter outras fontes online ou local, veja na documentação.


Alguns exemplos:

Usando o definition file ubuntu22-cuda.def como receita para criar o container 

   singularity build --sandbox --fakeroot --fix-perms ubuntu22-cuda ubuntu20-cuda.def

Usando o repositório do docker do ubuntu 20 como base para o container 

   singularity build --sandbox --fakeroot --fix-perms my_ubuntu22 docker://index.docker.io/library/ubuntu:22.04

Usando o repositório docker do python 3.8 como base para o container 

   singularity build --sandbox --fakeroot --fix-perms my_ubuntu_py3 docker://python:3.8-bullseye



5) Usar o shell do container em modo --writable --fakeroot --no-home (instalar, modificar e testar)

Executar seu singularity no formato "pasta sandbox" em "modo escrita" para instalar pacotes.

Também é indicado usar a opção --no-home para não montar a /home/root da máquina host e evitar que os instaladores tentem salvar algo na home da máquina host. ( Link com outras dicas sobre --no-home )

Se o instalador tentar usar a /home/root, deve-se ler a documentação do instalador para optar por pastas alternativas dentro da estrutura do container como /usr/bin, /usr/local, /opt/ 

   singularity shell --writable --fakeroot --no-home my_container/
  • Foi escolhido que das máquinas de processamento na rede, apenas EPONA, GHOST e MAGRITTE serão capazes de criar um container e abrir em modo edição.
  • Outra restrição é que essa permissão só pode ser executada na pasta /srv/forge



6) Usar o shell em modo "somente leitura" para executar sem modificar

Executar seu singularity no formato "pasta sandbox" em modo "somente leitura" para testar: 

   singularity shell my_container/

Em geral, nesse momento também é necessário montar uma pasta externa ao container para salvar dados e resultados, isso é explicado no pŕoximo item

7) Montar /draft-xxx/usuario dentro container para salvar resultados (opção --bind )

O comportamento padrão do SingularityCE é montar as pastas /home/$USER, /tmp, and $PWD da máquina host dentro do container (algumas outras pastas também ). A montagem automática da pasta /home/$USER foi desabilitada na rede VeRLab/JLab.

Para acessar outros diretórios da máquina host dentro do container usa-se a sintaxe 

   singularity shell --bind [/absolute/path/host/]:[/absolute/path/inside/container]

O caminho de montagem dentro do container é opcional e se for omitido, é usado o mesmo caminho do host, porém o usuário deve ter permissão para acessar a pasta de montagem. No exemplo mostra como deixar o path /draft-xxx/fulano acessível dentro do container em /mnt: 

   singularity shell --bind /draft-xxx/fulano:/mnt my_container/

Também é possível combinar as opções do --bind com --writable --no-home --fakeroot, neste caso, para fazer modificações na imagem e acessar a pasta de montagem: 

   singularity shell --writable --fakeroot --no-home --bind /draft-xxx/fulano:/mnt my_container/



8) Converter um container singularity do formato "pasta sandbox" para o formato .sif (imagem compactada)

Depois de pronta, a máquina container, pode ser convertida do formato "pasta sandbox" para o formato de .sif) isso permite que ela execute mais rápido, reduz o espaço em disco.

O container pronto pode ser armazenado na sua pasta /home/nome_usuario da rede, assim pode ser executada como leitura de qualquer máquina de processamento que o usuário logar.

1) Para converter do formato "pasta sandbox" para o formato .sif. Dicas sobre conversão de formatos das máquinas container: 

   singularity build --fakeroot --fix-perms [container_destino] [container_origem]
   singularity build --fakeroot --fix-perms my_container-compact.sif my_container/



Limitar recursos do container (RAM, Core's, network e etc)

É possível criar um arquivo cgroups.toml e limitar (ou medir) recursos usados pelo container. Por exemplo, limitar o uso de RAM para não esgotar os recursos da máquina host.

Segue o texto original e os links com mais informações:

The cgroups (control groups) functionality of the Linux kernel allows you to limit and meter the resources used by a process, or group of processes. Using cgroups you can limit memory and CPU usage. You can also rate limit block IO, network IO, and control access to device nodes.



Docker Hub: Usar repositório de Máquinas Container Prontas!

  • Docker Hub: várias imagens prontas com ferramentas instaladas
   https://hub.docker.com/

Por exemplo pode-se buscar no google: "docker hub opencv ubuntu", uma das respostas será o repositório 

   https://hub.docker.com/r/jjanzic/docker-python3-opencv

Para usar um endereço de imagem docker hub e criar seu container singularity, usa-se o formato docker://REPOSITORIO:TAGS

No caso do repósitório exemplo, ao abrir o link, vai encontrar diversas TAGS listadas na pagina: 

   List of available docker tags:
   opencv-4.1.0 (latest branch)
   contrib-opencv-4.1.0 (opencv_contrib branch)
   opencv-4.0.1
   contrib-opencv-4.0.1
   opencv-4.0.0
   contrib-opencv-4.0.0
   opencv-3.4.2
   contrib-opencv-3.4.2
   (...)

Assim para criar o container usando build e copiando do repositório exemplo a tag opencv-4.0.1, tem-se: 

   singularity build --sandbox --fakeroot --fix-perms opencv-base docker://jjanzic/docker-python3-opencv:opencv-4.0.1



PIP: Python Package Installer

O Python Package Installer, também conhecido como PIP, é responsável por instalar os pacotes Python criados pela comunidade. Dentro do singularity + moosefs, ele tem um comportamento anômalo, não instalando nas pastas padrão. Tais pastas "padrão" são especificadas diretamente no código-fonte do python, mais precisamente no módulo sys. Faz-se portanto necessário utilizar a flag -t/--target ao instalar os pacotes via pip, apontando para a pasta dist-packages da distribuição utilizada.

pip install <package> -t /usr/local/lib/python2.7/dist-packages/

Links dos Comandos Básicos

https://docs.sylabs.io/guides/4.1/user-guide/quick_start.html#interact-with-images

  • build: Cria uma imagem para a máquina container
  • shell: Executa a imagem da máquina container e permite a interação no prompt do shell
  • exec: Executa um comando na máquina container, em segundo plano, e apresenta o resultado no shell da máquina host
  • run: Executa ações e scripts configurados no container, como se fosse um executável.



build: Criar uma máquina container

Criar uma máquina container editável (para instalar pacotes)

  • Deve-se usar um singularity no formato "pasta sandbox" (estrutura de diretórios). Dicas sobre a opção --sandbox.
  • Criar singularity sandbox usando o repositório Ubuntu 20.04 do Docker Hub: 
   singularity build --sandbox --fakeroot --fix-perms my_container/ docker://index.docker.io/library/ubuntu:20.04
   singularity build --sandbox --fakeroot --fix-perms my_container/ docker://index.docker.io/library/ubuntu:latest
  • Exemplo singularity sandbox usando um repositório qualquer do dockerhub
   singularity build --sandbox --fakeroot --fix-perms my_container/ docker://repository_name:tag



outros exemplos menos usados, pois criam container's não editável

  • Criar uma máquina container em formato .img (read-only) a partir de um repositório Docker Hub: 
   singularity build my_ubuntu.sif docker://index.docker.io/library/ubuntu:latest

Deve-se usar o formato .sif (writable) a partir de um repositório Docker Hub: 

   singularity build my_ubuntu.sif docker://index.docker.io/library/ubuntu:latest
  • Converter ou Criar uma máquina container em formato de imagem a partir de uma pasta sandbox:
   singularity build my_ubuntu.sif my_container/



shell: Executar a máquina container e interagir no shell:

  • Executar a máquina container no shell, sem salvar modificações feitas na sessão:
   singularity shell my_container/
   singularity shell my_ubuntu.sif/



opção --writable --fakeroot: Permitir alterar o container em formato pasta sandbox:

  • Só é possível alterar um container em formato sandbox, uma boa prática é adicionar a opção --no-home é importante para não ocorrer a montagem automática da /home do root, e evitar que instaladores tentem usar essa pasta para instalação de pacotes.
   singularity shell --writable --fakeroot --no-home my_container/



opção --bind:Montando pastas da máquina host para acessar dentro da máquina container

A pasta do home do usuário é montada automaticamente pelo singularity dentro da máquina container (algumas outras também ), mas se for necessário acessar outra pasta no disco da máquina host, deve-se usar a opção --bind para indicar o caminho (path) a ser usado. O usuário precisa ter permissão de leitura e escrita na pasta da máquina host.

  • Executar a máquina container no shell e montar o caminho /draft-xxx/fulano da máquina host dentro da máquina container

singularity shell --bind /draft-xxx/fulano:/mnt my_container/

opção --nv:Uso de GPU dentro do container

A documentação do singularityCE apresenta as propriedades para usar GPU Nvidia dentro do container e consequentemente o CUDA.


Por padrão as máquinas da rede VeRLab/JLab tem apenas o driver Nvidia instalado e o container deve ter a instalação do CUDA.

Para utilizar os recursos da GPU, o container Singularity faz um linking com o driver da máquina host, o que já disponibiliza, para o container, a mesma versão do driver e do CUDA que já estão instalados na máquina host.


A principal vantagem dessa abordagem é evitar ter que fazer configurações extras como a do nvidia-container-toolkit, que é necessária no Docker.


Ainda assim, é importante prestar atenção à versão do driver Nvidia instalada no sistema para que o container consiga acessar a GPU!


A versão de CUDA instalada dentro do container é totalmente independente da versão instalada na máquina host, o que significa que é possível rodar uma versão do CUDA no container que é diferente da versão instalada na máquina host. Mas é importante prestar atenção que a versão do driver do container será sempre igual à versão do driver na máquina host, pois é feito um link do container para o host, e isso não pode ser mudado.

Pode-se verificar a versão do driver Nvidia instalado executando nvidia-smi na máquina host.


Por conta disso, pode ser que a versão do driver instalada na máquina host não suporte todas as versões do CUDA. Para ver quais versões são suportadas, é importante se atentar a quais versões do CUDA a versão do driver atual suporta. Isso pode ser verificado em:


Para carregar o driver Nvidia no container use a opção --nv 

Commands that run, or otherwise execute containers (shell, exec) can take an <>--nv option, w
hich will setup the container’s environment to use an NVIDIA GPU and the basic CUDA libraries to run a CUDA enabled application. 
The --nv flag will:
- Ensure that the /dev/nvidiaX device entries are available inside the container, so that the GPU cards in the host are accessible.
- Locate and bind the basic CUDA libraries from the host into the container, so that they are available to the container, and match the kernel GPU driver on the host.
- Set the LD_LIBRARY_PATH inside the container so that the bound-in version of the CUDA libraries are used by applications run inside the container.


  • Executar a máquina container no shell e montar o caminho /draft-xxx/fulano da máquina host dentro da máquina container

singularity shell --nv --bind /draft-xxx/fulano:/mnt my_cuda_container/

Retrieved from "http://www.verlab.dcc.ufmg.br/mediawiki/index.php?title=Singularity4&oldid=1519"