Difference between revisions of "Singularity3"

From VeRLab Wiki
Jump to: navigation, search
(→‎Documentação oficial Singularity CE v3.x)
(adicionou link para definition file vs docker file)
Line 12: Line 12:
 
** https://docs.sylabs.io/guides/3.10/user-guide/definition_files.html
 
** https://docs.sylabs.io/guides/3.10/user-guide/definition_files.html
 
** '''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/3.9/user-guide/singularity_and_docker.html#sec-deffile-vs-dockerfile
 
<br>
 
<br>
  

Revision as of 14:28, 27 April 2023

Contents

Singularity CE 3.x (Community Edition)

Esta será a versão utilizada na rede VeRLab/JLab a partir de mar/2022, atualmente instalado nas máquinas a v3.10.x

Documentação oficial Singularity CE v3.x


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 v3.x


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

  1. Confirmar se a máquina tem singularity instalado e a versão
  2. Criar sua pasta de trabalho com seu nome de usuário (storage ou homeLocal)
  3. Criar seu container Singularity no formato "pasta sandbox"
  4. Corrigir o ownership da sua "pasta sandbox"
  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) Criar 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

Pasta no serviço de storage:

  • 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
   cd /srv/forge 
   mkdir fulano
   chown -Rv fulano:513 fulano/
   cd /srv/forge/fulano

Pasta no /homeLocal de alguma máquina: 

   cd /homeLocal
   mkdir fulano
   chown -Rv fulano:513 fulano/
   cd /homeLocal/fulano



3) Criar seu container Singularity no formato "pasta sandbox"

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

   sudo singularity build --sandbox [pasta_destino] [container_origem]
  • A base usada na construção do container pode ter várias fontes diferentes online ou local:
    • URI docker:// container do repositório online no Docker Hub (Mais dicas sobre usar URI Docker Hub)
    • URI library:// container do repositório online no Sylab Container Library
    • URI shub:// container do repositório online no Singularity Hub
    • caminho para um outro container .sif numa pasta local na própria máquina host
    • caminho para um outro container em pasta sandbox na própria máquina host
    • caminho para um definition file no formato Singularity CE
  • Alguns exemplos:

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

   sudo 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 ( 

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



4) Corrigir o ownership da sua "pasta sandbox"

Como seu container foi criado usando sudo singularity, o ownership da pasta vai ser root:root Deve-se pedir para algum administrador da rede alterar o onweership para seu_usuario:DomainUsers

a) descobrir o UID do usuário e o GID do grupo DomainUsers com o comando id: 

   id nome_usuario


b) mudar o ownership, recursivamente, de todos arquivos da pasta sandbox (-R=recursive, -v=verbose) 

   sudo chown -Rv [uid]:513 pasta_sandbox/



5) Usar o shell do container em modo --writable --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/ 

   sudo singularity shell --writable --no-home my_container/
  • Use sudo somente quando necessário modificar o container com instalação de pacotes e configuraçã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.
  • 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 (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: 

   sudo singularity shell --writable --no-home --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: 

   sudo singularity build [container_destino] [container_origem]
   sudo singularity build 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: 

   sudo 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://www.sylabs.io/guides/3.9/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 18.04 do Docker Hub: 
   sudo singularity build --sandbox my_container/ docker://index.docker.io/library/ubuntu:20.04
   sudo singularity build --sandbox my_container/ docker://index.docker.io/library/ubuntu:latest
  • Exemplo singularity sandbox usando um repositório qualquer do dockerhub
   sudo 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: 
   sudo 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: 

   sudo 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:
   sudo 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.
   sudo singularity shell --writable --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 /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=Singularity3&oldid=1217"