diff --git a/.DS_Store b/.DS_Store new file mode 100644 index 0000000000000000000000000000000000000000..c8ce6db02d489d6b0c23200be574ecb626877847 Binary files /dev/null and b/.DS_Store differ diff --git a/source/_static/cluster.webp b/source/_static/cluster.webp new file mode 100644 index 0000000000000000000000000000000000000000..6848a55df518809fc599f0812b1c78b8a5c2f351 Binary files /dev/null and b/source/_static/cluster.webp differ diff --git a/source/_static/root-logo.png b/source/_static/root-logo.png new file mode 100644 index 0000000000000000000000000000000000000000..d196f5a7611b6cd6d5ec99f5fac6e82909c46dc0 Binary files /dev/null and b/source/_static/root-logo.png differ diff --git a/source/conf.py b/source/conf.py index b622b9da7e481f7752033c65d1c57f8dbd7832f8..ee4b1af7ede8670b8c1d90d899c242daece838fc 100644 --- a/source/conf.py +++ b/source/conf.py @@ -7,8 +7,8 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information project = "C3HPC Documentação" -copyright = "2022, Odair M." -author = "Odair M." +copyright = "2025, Bruno S." +author = "Bruno S." release = "0.1.0" version = "0.1.0" diff --git a/source/pages/manual-usuario-c3hpc.md b/source/pages/manual-usuario-c3hpc.md new file mode 100644 index 0000000000000000000000000000000000000000..02580e46814ccc1882c670230f451c882050b4a9 --- /dev/null +++ b/source/pages/manual-usuario-c3hpc.md @@ -0,0 +1,219 @@ +<div style="text-align: center;"> + <img src="../_static/c3sl_logo.svg" alt="Logo do C3HPC" style="width: 200px;"> + <img src="../_static/root-logo.png" alt="Logo dos roots" style="width: 200px;"> +</div> + +# Manual do usuário - C3HPC +Este documento contém todas as informações necessárias para a utilização plena dos usuários do C3HPC. + +Informações mais aprofundadas sobre o funcionamento do SLURM ou do Anaconda devem ser consultadas nos repositórios de documentação do [SLURM](https://slurm.schedmd.com/documentation.html) e do [Anaconda3](https://www.anaconda.com/docs/main) + +## Solicitando abertura de conta no C3HPC: + +Favor enviar sua solicitação para [c3hpc@inf.ufpr.br](mailto:c3hpc@inf.ufpr.br) endereço eletrônico. Sua solicitação será analisada e você receberá uma resposta em **até** 7 dias úteis. Cabe ao C3SL liberar ou não o uso do C3HPC para usuários externos ao DInf-UFPR, visando manter a disponibilidade de recursos aos utentes já cadastrados. + +- Junto da sua solicitação de criação de conta, envie os seguintes dados: + - Nome Completo. + - Organização que faz parte (nome do projeto, departamento, entidade, etc). + - Informação de contato (email). + - Tempo de vida da conta (por quanto tempo utilizará os recursos do cluster) + - Quais recursos utilizará (somente CPU, GPU, alto uso de RAM, etc). + - Chave SSH pública (no padrão ED25519) + +- Sob **nenhuma** hipótese será criada uma conta de usuário com poderes administrativos (sudoer) sobre o C3HPC sem autorização expressa da diretoria do C3SL. +- Para usuários internos do DInf - UFPR serão aceitas somente chaves ssh da máquina 'macalan'. Não serão adicionadas chaves de outra máquina, mesmo que seja local do DInf - UFPR. +- O seu usuário fará parte de um grupo que tem acesso somente aos recursos solicitados. Também existem filas prioritárias que são definidas de acordo com as polÃticas e demandas do C3SL. O mesmo reserva o direito de alterar quaisquer configurações de alocação de recursos sem aviso prévio. + +## Acessando sua conta no C3HPC + +Após a confirmação da criação da sua conta no C3HPC, você terá acesso ao nó de login do C3HPC. Para acessar e começar a utilizar os sistemas você precisará de uma máquina com um cliente SSH configurado. + +O acesso pode ser feito com o seguinte comando: `ssh <seu_usuario>@c3hpc.c3sl.ufpr.br` e você verá a seguinte tela: +```sh +<seu_usuario_local>@<sua_maquina_local>:~$ ssh <seu_usuario>@c3hpc.c3sl.ufpr.br + + ██╗ ██████╗██████╗ ██╗ ██╗██████╗ ██████╗ + ██╔â•â–ˆâ–ˆâ•”â•â•â•â•â•â•šâ•â•â•â•â–ˆâ–ˆâ•—██║ ██║██╔â•â•â–ˆâ–ˆâ•—██╔â•â•â•â•â• + ██╔╠██║ █████╔â•â–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ•‘██████╔â•â–ˆâ–ˆâ•‘ + ██╔╠██║ â•šâ•â•â•â–ˆâ–ˆâ•—██╔â•â•â–ˆâ–ˆâ•‘██╔â•â•â•â• ██║ +██╗██╔╠╚██████╗██████╔â•â–ˆâ–ˆâ•‘ ██║██║ ╚██████╗ +â•šâ•â•â•šâ•â• â•šâ•â•â•â•â•â•â•šâ•â•â•â•â•â• â•šâ•â• â•šâ•â•â•šâ•â• â•šâ•â•â•â•â•â• + +Bem-vindo ao Computador de Alto Desempenho do +Centro de Computação CientÃfica e Software Livre. + +Esta máquina possui recursos limitados e é destinada +somente para submissão de jobs para o SLURM. + +Mais informações sobre o funcionamento desta podem +ser encontradas na página do suporte em: + +https://c3hpc.docs.c3sl.ufpr.br/ +<seu_usuario>@c3hpc:~$ +``` +- Note que não foi solicitado senha pois, por questões de segurança, a autenticação de acesso será feita somente com a chave ssh ed25519 fornecida no momento da solicitação da criação de contas. O usuário também não conseguirá 'criar' ou alterar a sua senha, visto que este recurso está desativado no servidor de autenticação. + +Pronto! Você está logado e pronto para utilizar o C3HPC. + +## Administrando sua conta no C3HPC +### O(s) seu(s) ambiente(s) Conda +O sistema conta com uma instalação do Anaconda3 para todos os usuários. O comando 'conda' está disponivel no PATH universal do sistema, não sendo necessário que o usuário faça sua própria instalação do anaconda3. + +- Casos isolados de pacotes que, por ventura, não estejam disponÃveis nos repositórios do Anaconda3 terão que ser solicitados aos roots via [email](mailto:c3hpc@inf.ufpr.br). + +As contas do C3HPC não tem senha. O usuário logará na máquina utilizando somente sua chave SSH pública. + +O usuário deve criar o seu ambiente virtual conda com o seguinte comando: `conda create -n <nome_do_ambiente>` + +O ambiente conda criado ficará armazenado dentro da $HOME do usuário, em: `~/$USER/.conda/envs/<nome_do_ambiente>` + +Para 'entrar' no seu ambiente virtual utilize o comando: `conda activate <nome_do_ambiente>` + +Para 'sair' do seu ambiente virtual utilize o comando: `conda deactivate <nome_do_ambiente>` + +O usuário tem total liberdade para instalar quaisquer pacotes dentro do seu ambiente Conda utilizando o comando `conda install -c <canal_do_pacote> <nome_do_pacote>` + + O Anaconda organiza os pacotes em repositórios, então, muito provavelmente, será necessário buscar em qual canal o pacote desejado está disponÃvel. + +### O seu armazenamento no C3HPC +O C3HPC conta com 80TB de armazenamento total para ser **compartilhado** entre os usuários. Atente-se quanto a arquivos duplicados no sistema, estes ocupam espaço que seu colega pode vir a precisar. + + A administração do C3HPC, assim como o C3SL, abstém-se da responsabilidade de manutenção da integridade dos dados dos usuários do C3HPC. Caso o sistema de arquivos venha a falhar e informação seja perdida, a mesma poderá não ser recuperada. Cabe somente ao usuário manter um backup dos seus dados em um local que julgue seguro. + +## CaracterÃsticas técnicas do C3HPC + +Um cluster computacional é conjunto de computadores escravos coordenados por um mestre (no caso do C3HPC é o `c3hpc-headnode`), com o propósito de compartilhar seus recursos e processar grandes volumes de dados de maneira paralela e em alta velocidade. Estas máquinas comunicam-se entre si através de uma rede de alta velocidade. + + + +Os nós escravos do C3HPC tem as seguintes configurações: + +### Nós de Processamento: +| Nó | RAM | CPU | Cores | Disco de scratch? | GPU? | Conexão | +| -- | --- | --- | ----- | ----------------- | ---- | ------- | +| node[2-7] | 200GB | Intel(R) Xeon(R) CPU E5-2683 v4 @ 2.10GHz | 32 | Sim, 8TB | Não | ETH 1Gbps | +| proc[1-2] | 500GB | Intel(R) Xeon(R) CPU E5-2683 v4 @ 2.10GHz | 64 | Sim, 8TB | Não | ETH 1Gbps | +| pti | 500GB | Intel(R) Xeon(R) CPU E5-2683 v4 @ 2.10GHz | 64 | Sim, 450GB | Não | ETH 1Gbps | +| vti1 | 180GB | Intel(R) Xeon(R) Silver 4110 CPU @ 2.10GHz | 32 | Sim, 450GB | 4x NVIDIA Tesla V100 32GB | ETH 1Gbps | +| vti2 | 150GB | Intel(R) Xeon(R) Silver 4110 CPU @ 2.10GHz | 32 | Sim, 450GB | 4x NVIDIA Tesla V100 32GB | ETH 1Gbps | + +O usuário pode conferir as caracterÃsticas das partições com o comando `scontrol show partition <nome_partição>`. O mesmo vale para imprimir as configurações de um nó especÃfico, com o comando: `scontrol show node <nome_do_nó>` + +### Nó Controlador: +O controlador do C3HPC não é acessÃvel por usuários, mas é quem armazena todas as informações. Este possui as seguintes caracterÃsticas: + +| RAM | Cores | Armazenamento | Conexão | +| --- | ----- | ------------- | ------- | +| 256GB | 40 | JBOD 12Gbps em RAIDZ60 totalizando 80TB | SFP+ 10Gbps | + +## Utilizando o SLURM para administrar seus jobs: + +A natureza de um cluster é ser um sistema robusto e **compartilhado** entre **vários** clientes, logo, o usuário deve conferir e alocar somente aquilo que irá utilizar. O SLURM aloca e bloqueia o recurso solicitado para aquele job, mesmo que não seja, de fato, utilizado. Logo, cabe ao usuário provisionar os recursos que irá utilizar. + +Todos os nós do C3HPC tem um disco de scratch montado em `/scratch`. Recomenda-se que o usuário crie um diretório dentro deste disco para **copiar temporariamente** seus datasets. Este comportamento evita sobrecarga no NFS (Network File System) do sistema, que é consideravelmente lento em comparação com um disco local. + +### Verificando a disponibilidade de recursos: + +O usuário pode ter um panorama simplificado sobre o status do sistema em tempo real com o comando `sinfo`. Aqui esta um exemplo de saÃda deste: +```shell +root@c3hpc-headnode:~# sinfo +PARTITION AVAIL TIMELIMIT NODES STATE NODELIST +cpu* up 7-00:00:00 2 mix proc[1-2] +cpu* up 7-00:00:00 6 alloc node[2-7] +cpu-test up 10:00 2 mix proc[1-2] +cpu-test up 10:00 6 alloc node[2-7] +cpu-24h up 1-00:00:00 2 mix proc[1-2] +cpu-24h up 1-00:00:00 6 alloc node[2-7] +Family-node up 7-00:00:00 6 alloc node[2-7] +Family-node-test up 10:00 6 alloc node[2-7] +Family-node-24h up 1-00:00:00 6 alloc node[2-7] +Family-proc up 7-00:00:00 2 mix proc[1-2] +Family-proc-test up 10:00 2 mix proc[1-2] +Family-proc-24h up 1-00:00:00 2 mix proc[1-2] +Family-pti up 7-00:00:00 1 idle pti +Family-pti-test up 10:00 1 idle pti +Family-pti-24h up 1-00:00:00 1 idle pti +Family-vti up 7-00:00:00 1 mix vti1 +Family-vti up 7-00:00:00 1 idle vti2 +Family-vti-test up 10:00 1 mix vti1 +Family-vti-test up 10:00 1 idle vti2 +Family-vti-24h up 1-00:00:00 1 mix vti1 +Family-vti-24h up 1-00:00:00 1 idle vti2 +gpu up 5-00:00:00 1 mix vti1 +gpu up 5-00:00:00 2 idle pti,vti2 +gpu-test up 10:00 1 mix vti1 +gpu-test up 10:00 2 idle pti,vti2 +``` +Aqui podemos ver que os nós estão em estados diferentes, com alguns completamente alocados (alloc), parcialmente alocados (mix) e ociosos (idle). + +- Uma das caracterÃsticas que os administradores do C3HPC impuseram foi limitar o usuário a utilizar somente filas com recursos que foram solicitados. Usuários que não solicitaram uso de GPU, não terão acesso as filas de máquinas que dispõe desta caracterÃstica. +- Grupos de usuários e prioridades para utilização das máquinas também foram definidas com base nas polÃticas internas de utilização do C3SL. Tais polÃticas podem ser revistas e alteradas sem aviso prévio. +- Quaisquer dúvidas sobre a utilização dos recursos alocados para o seu usuário podem ser enviadas para [c3hpc@inf.ufpr.br](mailto:c3hpc@inf.ufpr.br). + +Informações mais aprofundadas do comando `sinfo` podem ser encontradas [aqui](https://slurm.schedmd.com/sinfo.html). + +### Entendendo as filas +O C3HPC está organizado da seguinte maneira: + + - Filas para processamento somente em CPU. + - Filas para processamento utilizando GPU. + - Filas por famÃlia de máquina. +- Todos os 'sabores' de filas tem as seguintes subdivisões: + - Uma fila de alta fatia de tempo (7 dias para CPU e 5 dias para GPU). + - Uma fila para teste do seu código (com 10 minutos de limite). + - Uma fila de 24 horas para jobs envolvendo processamento em CPU. + +As filas de 'Family' são destinadas a experimentos que necessitam processamento em hardware homogêneo, como benchmarks. + + +### Submetendo seus jobs para o SLURM + +Os jobs podem ser enviados com o comando `sbatch`, mais informações sobre a formatação do documento podem ser encontradas [aqui](https://slurm.schedmd.com/sbatch.html). + + - É importante verificar se você está "dentro" do seu ambiente conda **antes** de submeter o seu job. Caso o ambiente esteja faltando ou errado, as bibliotecas podem nao ser encontradas e o seu batch não funcionará. + +O script de submissão no formato `.sbatch` deverá conter somente os comandos para outros scripts. Exemplo: + +```sh +#!/bin/sh + +#SBATCH -p cpu +#SBATCH --job-name=exemplo +#SBATCH -n 1 +#SBATCH -o ./output +#SBATCH -c 16 +#SBATCH --mem=20g + +mkdir /scratch/$USER +cp -r $HOME/dataset /scratch/$USER/ +srun script.sh +srun script2.sh +``` + +Neste `script.sbatch` o usuário enviou o seu `script1.sh` e `script2.sh` (que são arquivos **externos** ao `script.sbatch`) para uma alocação de `16 cores` na partição `cpu`, com identificação `exemplo`, em 1 único nó, encaminhando a saÃda para o arquivo `output` e com um uso total de `20GB` de memória RAM. Em adição aos comandos do SLURM, também efetuamos a cópia do dataset usado no processamento para o disco local do nó alocado. + +Existem polÃticas de penalização automática para usuários que alocam recursos de maneira imprópria, implicando em queda de prioridade na execução dos jobs. Dimensione bem os recursos que pretende utilizar para que não seja penalizado. + +### Monitorando seus jobs: + +O comando `squeue` mostra os jobs que estão rodando no cluster. Um exemplo de saida do comando `squeue` é: +```shell +root@c3hpc:~# squeue + JOBID PARTITION NAME USER ST TIME NODES NODELIST(REASON) + 103 gpu NAS-NPB root R 53:10 1 vti1 +root@c3hpc:~# +``` + +Mais informações sobre o comando `squeue` podem ser encontradas [aqui](https://slurm.schedmd.com/squeue.html). + +## Boas práticas em um ambiente computacional compartilhado: + +Um ambiente computacional compartilhado demanda que todos adotem um comportamento diplomático, com o intuito de respeitar os processos dos seus colegas e não causar indisponibilidade de recursos. + +- Priorize o uso do `sbtach` para submeter o seu job. Revise a alocação de recursos antes de submetê-lo. Utilizando o `sbatch` o nó alocado será liberado assim que a tarefa for concluÃda, para que fique livre para outros usuários. +- Configure o email para que o cluster te avise quando seu job terminar. +- Seja consciente quando a alocação de recursos: procure solicitar somente aquilo que seu experimento for, de fato, utilizar. Exemplo: não aloque a partição `gpu` para jobs que utilizarão somente CPU, para isso existe a partição `cpu`. +- Como definição de segurança, somente os administradores do C3HPC tem acesso direto aos nós, o usuário não conseguirá acessar os mesmos via `ssh`. +- A máquina de login (denominada `c3hpc`) é destinada somente para a submissão de jobs para o SLURM e administração do ambiente `conda` do usuário. Esta possui limites rÃgidos e **não** deve ser usada para processamento. +- Utilize o disco local montado em `/scratch` para copiar seus datasets. +- Qualquer dúvida não coberta por este documento ou pela documentação das ferramentas SLURM e Anaconda, não hesite em mandar um email para o suporte do C3HPC (c3hpc@inf.ufpr.br).