Difference between revisions of "Singularity4"

From VeRLab Wiki
Jump to: navigation, search
(→‎A utilização ficou mais simples: NÃO É PRECISO USAR MAIS O COMANDO sudo QUANDO FOR USAR OSINGULARITY)
(→‎Singularity CE 4.x (Community Edition))
 
(43 intermediate revisions by 2 users 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 29: Line 133:
 
* compressed read-only Singularity Image File (SIF) format suitable for production (default)
 
* compressed read-only Singularity Image File (SIF) format suitable for production (default)
 
<br>
 
<br>
−
==== '''A utilização ficou mais simples''': <span style="color: red;">NÃO É PRECISO USAR MAIS O COMANDO <code>sudo</code> QUANDO FOR USAR OSINGULARITY</span> ====
+
 
−
Com a introdução do Singularity 4.1.x, alguns comandos agora requerem o uso da flag <code>--fakeroot</code>. 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 <code>--fakeroot</code>, o Singularity simula um ambiente root, permitindo operações que normalmente precisariam de acesso root real.
+
== Passo a Passo: Uso do Singularity CE v4.1.x ==
 +
==== '''Uso simplificado''': <span style="color: red;">NÃO É MAIS NECESSÁRIO USAR O COMANDO <code>sudo</code> PARA UTILIZAR O SINGULARITY</span> ====
 +
Com a introdução do Singularity 4, alguns comandos agora requerem o uso da flag <code>--fakeroot</code>. 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 <code>--fakeroot</code>, o Singularity simula um ambiente root, permitindo operações que normalmente precisariam de acesso root real, [https://docs.sylabs.io/guides/4.1/user-guide/fakeroot.html#fakeroot veja na documentação].
  
 
Exemplo de comando com <code>--fakeroot</code>:
 
Exemplo de comando com <code>--fakeroot</code>:
Line 37: Line 145:
  
 
Este comando constrói um container no formato sandbox usando um arquivo de definição, sem precisar de privilégios de superusuário.
 
Este comando constrói um container no formato sandbox usando um arquivo de definição, sem precisar de privilégios de superusuário.
−
<br>
 
  
−
== Passo a Passo: Uso do Singularity CE v4.1.x ==
+
<br><br>
−
<br>
 
 
Exemplos de interação mais usuais com o container singularity
 
Exemplos de interação mais usuais com o container singularity
  
 
# 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
 
# Usar o shell do container em modo --writable --no-home (instalar, modificar e testar)
 
# Usar o shell do container em modo --writable --no-home (instalar, modificar e testar)
−
# Usar o shell em modo "somente leitura" para testar
+
# Usar o shell em modo "somente leitura" para executar sem modificar
 
# Usar o shell e montar uma pasta do host
 
# Usar o shell e montar uma pasta do host
 
# Converter um container singularity do formato "pasta sandbox" para o formato '''<code>.sif</code>''' (imagem compactada)
 
# Converter um container singularity do formato "pasta sandbox" para o formato '''<code>.sif</code>''' (imagem compactada)
Line 57: 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 73: 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 93: Line 199:
 
<br>
 
<br>
  
−
Abaixo um exemplo de definition file (salvo como ubuntu-cuda.def) que tem como base um sistema operacional ubuntu 20.04 e instala os pacotes para executar o cuda toolkit 11.4:
+
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:
  
 
{| class="wikitable"
 
{| class="wikitable"
Line 133: Line 239:
 
      
 
      
 
     # CUDA Toolkit 11.4 pode ser encontrado em https://developer.nvidia.com/cuda-11-4-0-download-archive
 
     # 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
 
     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
 
     mv cuda-ubuntu2004.pin /etc/apt/preferences.d/cuda-repository-pin-600
Line 164: Line 271:
 
%labels
 
%labels
 
     Author Verlab
 
     Author Verlab
−
 
−
 
−
# To build the container
 
−
# $ singularity build --sandbox --fakeroot --fix-perms my-cuda/ ubuntu20-cuda.def
 
  
 
</pre>
 
</pre>
 +
Para criar seu container
  
 +
    singularity build --sandbox --fakeroot --fix-perms my-cuda/ ubuntu20-cuda.def
  
 
|}
 
|}
 +
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>
 
<br><br>
Line 191: Line 297:
  
 
Usando o [https://hub.docker.com/_/ubuntu repositório do docker do ubuntu 20] como base para o container
 
Usando o [https://hub.docker.com/_/ubuntu repositório do docker do ubuntu 20] como base para o container
−
     singularity build --sandbox my_ubuntu20 docker://index.docker.io/library/ubuntu:20.04
+
     singularity build --sandbox --fakeroot --fix-perms my_ubuntu22 docker://index.docker.io/library/ubuntu:22.04
  
−
Usando o [https://hub.docker.com/_/python repositório docker do python 3.8] como base para o container (
+
Usando o [https://hub.docker.com/_/python repositório docker do python 3.8] como base para o container
−
     singularity build --sandbox my_ubuntu20_py3 docker://python:3.8-bullseye
+
     singularity build --sandbox --fakeroot --fix-perms my_ubuntu_py3 docker://python:3.8-bullseye
 
<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 205: 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 211: Line 317:
 
<br><br>
 
<br><br>
  
−
==== 6) Usar o shell em modo "somente leitura" para testar ====
+
==== 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:
 
Executar seu singularity no formato "pasta sandbox" em modo "somente leitura" para testar:
 
     singularity shell my_container/
 
     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
 
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
 
<br><br>
 
<br><br>
−
==== 7) Montar /homeLocal/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 ([httphttps://docs.sylabs.io/guides/4.1/user-guide/bind_paths_and_mounts.html#system-defined-bind-paths algumas outras pastas também] ).
+
==== 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.
  
 
Para acessar outros diretórios da máquina host dentro do container usa-se a sintaxe
 
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]
 
     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 é possivel combinar as opções do --bind com --writable --no-home, neste caso, o root precisa ter permissão para 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 282: 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 312: Line 419:
 
* Criar singularity sandbox usando o repositório Ubuntu 20.04 do Docker Hub:  
 
* Criar singularity sandbox usando o repositório Ubuntu 20.04 do Docker Hub:  
  
−
     singularity build --sandbox my_container/ docker://index.docker.io/library/ubuntu:20.04
+
     singularity build --sandbox --fakeroot --fix-perms my_container/ docker://index.docker.io/library/ubuntu:20.04
−
     singularity build --sandbox my_container/ docker://index.docker.io/library/ubuntu:latest
+
     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
 
* Exemplo singularity sandbox usando um repositório qualquer do dockerhub
−
     singularity build --sandbox my_container/ docker://repository_name:tag
+
     singularity build --sandbox --fakeroot --fix-perms my_container/ docker://repository_name:tag
 
<br><br>
 
<br><br>
 
==== outros exemplos menos usados, pois criam container's não editável ====
 
==== outros exemplos menos usados, pois criam container's não editável ====
Line 336: 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 345: 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"