Singularity4

From VeRLab Wiki
Revision as of 13:58, 8 June 2024 by Othiago (talk | contribs) (→‎3) Escrever a "receita" (definition file) do seu container Singularity)
Jump to: navigation, search

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


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 homeLocal)
  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 testar
  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 homeLocal)

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 /homeLocal/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 /homeLocal):
  • 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 /homeLocal
  • É 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
   sudo mkdir fulano
   sudo chown -Rv fulano:513 fulano/
   cd /homeLocal/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 my_ubuntu20 docker://index.docker.io/library/ubuntu:20.04

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

   singularity build --sandbox my_ubuntu20_py3 docker://python:3.8-bullseye



5) Usar o shell do container em modo --writable --no-home --fakeroot (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 --no-home --fakeroot 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 testar

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 /homeLocal/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 ([httphttps://docs.sylabs.io/guides/4.1/user-guide/bind_paths_and_mounts.html#system-defined-bind-paths algumas outras pastas também] ).

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 /homeLocal/fulano acessível dentro do container em /mnt: 

   singularity shell --bind /homeLocal/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: 

   singularity shell --writable --no-home --fakeroot --bind /homeLocal/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 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 my_container/ docker://index.docker.io/library/ubuntu:20.04
   singularity build --sandbox my_container/ docker://index.docker.io/library/ubuntu:latest
  • Exemplo singularity sandbox usando um repositório qualquer do dockerhub
   singularity build --sandbox 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: Permitir alterar o container em formato pasta sandbox:

  • Só é possivel 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 --no-home --fakeroot 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 /homeLocal/fulano da máquina host dentro da máquina container

singularity shell --bind /homeLocal/fulano:/mnt my_container/

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