Documentação do CSGrid

Visão Geral

CSGrid é um sistema para grades computacionais que, além de dar suporte ao uso e gerenciamento de recursos computacionais distribuídos, oferece facilidades para a integração de aplicações e para o gerenciamento de dados e usuários. O CSGrid apresenta para seu usuário uma área de trabalho com todas as aplicações disponíveis e com os arquivos de dados do usuário organizados por projeto. Um usuário pode estender o ambiente adicionando novas aplicações. O sistema também oferece uma série de recursos para trabalho colaborativo entre seus usuários.

Arquitetura

O CSGrid é composto dos seguintes componentes:

Servidor

Armazena as configurações dos usuários, seus projetos e dados, e também contém um repositório de algoritmos disponíveis para execução. A gerência de usuários, projetos, algoritmos e comandos é feita por meio das APIs RMI e REST. A primeira oferece permite a gerência completa e a segunda, mais limitada, apenas a gerência de projetos e comandos. Também oferece uma API REST para a comunicação com o SGA, que tipicamente não é acessada diretamente.

SGA

Componente responsável pela interação com os ambientes de execução. É ele que executa e monitorar a execução dos comandos e também coleta informações de utilização dos ambientes de execução. Pode-se ter mais de um SGA associado a um mesmo servidor CSGrid para que comandos sejam executados em recursos computacionais de vão desde simples computadores até grades computacionais.

Cliente Desktop

Interface gráfica para gerenciar usuários, projetos, algoritmos e comandos. Utiliza a tecnologia Java Web Start para fazer a instalação local.

A seguir segue diagrama da arquitetura do CSGrid:

_images/arquitetura.svg

Guia de Instalação

Aqui são descritos os requisitos, os passos de instalação e como configurar o servidor CSGrid

Requisitos

Para a execução do servidor CSGrid as seguintes dependências devem estar instaladas na máquina:

  • Java 8 (Oracle ou OpenJDK)

  • Korn shell (ksh)

  • Docker (opcional)

Importante

As instruções para instalação/configuração/execução via Docker estão na sessão Execução via Docker.

Instalação

Baixar do repositório o arquivo .tgz correspondente à versão a ser instalada, por exemplo usando o comando wget:

$ wget -c http://maven.tecgraf.puc-rio.br:8081/nexus/service/local/repositories/releases/content/br/puc-rio/tecgraf/csgrid/csgrid-full-package/X.Y.X/csgrid-full-package-X.Y.X-csgrid.tgz

Substituindo X.Y.X pelo número da versão desejada.

Atenção

Pode ser necessário definir as variáveis de ambiente http_proxy e https_proxy para configurar o use de proxies ao comando wget. Mais informações em GNU Wget Manual:8.1 Proxies

Extrair o conteúdo do arquivo usando o comando tar:

$ tar -xzf csgrid-full-package-X.Y.Z-csgrid.tgz

Se a extração foi feita com sucesso, o conteúdo do arquivo estará no diretório csgrid e deve conter os seguintes sub-diretórios:

csgrid
├── algorithms
├── applications_repository
├── bin
├── config
├── html
├── lib
├── plugins
├── projects
├── properties
└── security

Aqui segue uma breve descrição de cada diretório:

algorithms

repositório de algoritmos

applications_repository

repositório de aplicações

bin

diretório com os scripts para inciar/para o servidor

config

diretório com os arquivos de configuração

html

diretório de documentação dos algoritmos

lib

diretório com as bibliotecas (.jar) usadas no servidor

plugins

repositório de plugins do servidor

projects

área de projetos (repositório de dados dos usuários)

properties

diretório com os arquivos padrões de configuração

security

diretório de armazenamento de chaves privadas do servidor

Por fim instalar o Tomcat e a aplicação .war:

$ cd csgrid
$ wget -c https://archive.apache.org/dist/tomcat/tomcat-6/v6.0.53/bin/apache-tomcat-6.0.53.tar.gz
$ tar zxvf apache-tomcat-6.0.53.tar.gz
$ ln -s apache-tomcat-6.0.53 tomcat
$ unzip lib/tomcat/csgrid-client-war-*.war -d tomcat/webapps/csgrid

Configuração

No pacote de instalação existe um arquivo config/System.properties que contem as propriedades mínimas que devem ser configuradas para o funcionamento do servidor CSGrid. Abaixo segue o seu conteúdo:

# Server Name
Server.name = CSGrid
# Server hostname
Server.hostName = <hostname>
# Server IP address
Server.hostAddr = <ip>
# Server URL
Server.systemURL = http://<hostname>:8080/csgrid/

# Webapp URL
HttpService.webapp = http://<hostname>:8080/csgrid/

# Mail server
MailService.mail.smtp.host = <mailserver>
# Mail server port
MailService.mail.smtp.port = 25
# Server email address
MailService.from = <csgrid@>
# Helpdesk email address
MailService.support = <helpdesk@>

# Local authentication plugin
LoginService.login.plugin.protocol.1 = local
LoginService.login.plugin.properties.1 = properties/LocalLogin.properties

Como pode ser observado é necessário definir algumas propriedades. A seguir um exemplo de configuração do arquivo config/System.properties:

# Server Name
Server.name = CSGrid Xingu
# Server hostname
Server.hostName = xingu.amazonas.com.br
# Server IP address
Server.hostAddr = 10.0.0.1
# Server URL
Server.systemURL = http://xingu.amazonas:8080/csgrid/

# Webapp URL
HttpService.webapp = http://xingu.amazonas:8080/csgrid/

# Mail server
MailService.mail.smtp.host = smtp.amazonas.com.br
# Mail server port
MailService.mail.smtp.port = 25
# Server email address
MailService.from = csgrid@amazonas
# Helpdesk email address
MailService.support = suporte@amazonas

# Local authentication plugin
LoginService.login.plugin.protocol.1 = local
LoginService.login.plugin.properties.1 = properties/LocalLogin.properties
Configuração da localização de repositórios

As localizações dos repositórios de algoritmo, aplicações, projetos e plugins estão configuradas para sub-diretórios do diretório raiz. Para alterá-las basta adicionar as seguinte propriedades no arquivo config/System.properties:

# Deve ser o caminho absoluto ou relativo ao diretório raiz do CSGrid

# Caminho para o diretório base de algoritmos
AlgorithmService.base.algorithm.dir = ../../algorithms

# Lista de diretórios para procurar aplicações
ApplicationService.applications.directory.1 = applications_repository/applications
ApplicationService.applications.directory.2 = /global/applications_repository/applications
ApplicationService.categories.directory = applications_repository/categories

PluginService.base.plugin.dir = plugins

# Caminho para o diretório base de projetos
ProjectService.base.project.dir = /storage/projects

Tipicamente somente é alterada a localização do repositório de projetos, pois, como nele são guardados os dados dos usuários, este tende a crescer e acaba ocupando todo o disco local do servidor. Então para minimizar este problema pode-se armazenar a área de projetos em um storage externo. Outra vantagem de usar um storage externo é que os SGAs também podem ter acesso direto a área de projetos, facilitando suas configurações.

Configurações da API REST

O CSGrid, além de oferecer uma API Java RMI usada pelo cliente desktop, também oferece uma API REST que pode ser usada por aplicações Web ou por outras aplicações com capacidade de fazer requisições HTTP. Para ativá-la é necessário definir algumas propriedades, que podem ser vistas no exemplo abaixo:

# Indica se o serviço está habilitado. Os valores podem ser true ou false.
RestService.enabled = true

# Porta onde o container exporta as APIs dos serviços
RestService.service.port = 8010

# URL pela qual a API REST deve ser acessada
RestService.external.url = http:///xingu.amazonas:8010/v1

# Chave privada usada para geração de token de acesso a API
RestService.private.key.file = security/xingu.key

# Configuração opcional do SSL
RestService.SSL.enable = true
# KeyStore no formato JKS para armazenar a chave privada e o certificado associado
RestService.SSL.keystore = security/xingu.jks
# A senha do KeyStore
RestService.SSL.keystore_password = csgrid

Abaixo segue os comandos de criação da chave security/xingu.key usada no exemplo anterior:

$ cd security
$ openssl genrsa -out rsa.key 2048
$ openssl pkcs8 -topk8 -nocrypt -in rsa.key -out xingu.key -outform DER
Configuração da API REST SGA

A API REST SGA é oferecida pelo plugin csbase-sga-rest do CSBase, então para ativá-la é necessário que ele seja ativado e configurado. Para isto adicione as seguinte linhas ao arquivo config/System.properties:

SGAService.sga.plugin.type.1 = rest
SGAService.sga.plugin.properties.1 = plugins/sgarest.properties

E crie o arquivo plugins/sgarest.properties com o seguinte conteúdo alterando as propriedades host e port:

# Nome do SGA (necessário por compatibilidade)
csbase_sga_name = SGA_REST
csbase_name = SGA_REST

# Host e porta de acesso a API
host = 10.0.0.1
port = 40509

Importante

As instruções de instalação e configuração do SGA-REST estão disponíveis em https://sga-rest-daemon.readthedocs.io/. A instalação do SGA é necessária para permitir a execução de comandos no CSGrid.

Configuração de autenticação via LDAP

O CSGrid permite delegar a autenticação de usuários para outros servidores/protocolos. Um dos protocolos suportados é o LDAP que é ativado pelo plugin csbase-login-ldap do CSBase. Para ativá-lo adicione as seguinte linhas ao arquivo config/System.properties:

LoginService.login.plugin.protocol.2 = ldap
LoginService.login.plugin.properties.2 = plugins/LDAPLogin.properties

E crie o arquivo plugins/LDAPLogin.properties usando como base o exemplo abaixo:

# Servidores LDAP disponíveis para autenticação e suas portas.
LDAPServer.1 = dc01
LDAPPort.1 = 389

# Lista de padrões para autenticação dos usuários. [%U] é substituído pelo
# login do usuário.
LDAPPattern.1 = [%U]@amazonas
#LDAPPattern.2 = cn=[%U],ou=CSGrid,dc=xingu,dc=amazonas
#LDAPPattern.2 = cn=[%U],dc=xingu,dc=amazonas

# CharSet utilizado na conversão da senha em um byte[].
#LDAPCharSet = UTF8
LDAPCharSet = ISO-8859-1

# Timeout para conexão com o servidor LDAP, em segundos
LDAPConnectionTimeout = 5

# Suporte a SSL
LDAPSSLEnabled = false
# Configuração do KeyStore para acesso usando SSL
#LDAPKeyStorePath = security/ldap.jks
#LDAPKeyStorePassword = csgrid
Arquivos de log

Os arquivos de log são gerados no diretório logs/server conforme a configuração padrão, e no arquivo properties/Logging.properties está e outras propriedades podem ser alteradas.

Execução

Para iniciar o CSGrid execute o seguinte comando em um shell/terminal:

$ cd bin
$ ./csgrid start

Para parar o seguinte comando deve ser executado:

$ cd bin
$ ./csgrid stop

Execução via Docker

A imagem do CSGrid está no repositório repo.tecgraf.puc-rio.br:18089 e no caminho soma/csgrid, assim para pegar a versão x.y.z o seguinte comando deve ser usado:

$ docker pull repo.tecgraf.puc-rio.br:18089/soma/csgrid:x.y.z

Para a execução via Docker deve-se definir e mapear os seguintes volumes:

/csgrid/projects

Área de projetos

/csgrid/algorithms

Repositório de algoritmos

/csgrid/persist

Dados de persistência

/csgrid/security

Diretório de certificados/chaves

/csgrid/logs

Diretório de logs

Importante

A chave usada para configurar a API REST deve estar no diretório mapeado em /csgrid/security e deve ser nomeada rest_api_token_key. Detalhes sobre a API REST em Configurações da API REST

As seguintes variáveis de ambiente devem ser definidos no container:

CSGRID_SERVER_NAME

Nome do servidor

CSGRID_HOST_NAME

Nome da máquina do servidor

CSGRID_RMI_REGISTRY_PORT

Porta do registro RMI

CSGRID_RMI_EXPORT_PORT

Porta RMI exportada

CSGRID_FTC_EXPORT_PORT

Porta FTC exportada

CSGRID_REST_EXPORT_PORT

Portas da API REST do servidor exportada

CSGRID_LDAP_AUTH

Indicador opcional para ativar a autenticação via LDAP. A definição de qualquer valor basta para ativar a funcionalidade. Por exemplo: "CSGRID_LDAP_AUTH=1"

Importante

Para configurar a autenticação via LDAP veja a sessão Configuração de autenticação via LDAP e mapeie o arquivo de propriedades para o seguinte caminho no container: /csgrid/properties/LDAPLogin.properties. Por exemplo:

$ docker run
...
-v /external/LDAPLogin.properties:/csgrid/properties/LDAPLogin.properties:ro
...
repo.tecgraf.puc-rio.br:18089/soma/csgrid:x.y.z

As seguintes portas devem ser exportadas – use o valor definido nas variáveis de ambiente acima para saber qual deve ser a porta exportada para alguns serviços:

8010

REST API - Porta para acessar a API REST do CSGrid

1099

Java RMI - Porta para acessar a API Java RMI do CSGrid (CSGRID_RMI_REGISTRY_PORT)

1098

Java RMI - Porta para acessar a API Java RMI do CSGrid (CSGRID_RMI_EXPORT_PORT)

6681

FTC - Porta para acesso ao serviço FTC – transferência de arquivos – do CSGrid (CSGRID_FTC_EXPORT_PORT)

8080

Java Web Start - Porta para acessar o servidor Tomcat para disparar a aplicação Java via Java Web Start

7778

SGA - Porta para acessar a API CORBA do SGA

7878

SGA-SSL - Porta para acessar a API CORBA do SGA usando SSL

40500

SGA-REST - Porta para acessar a API REST do SGA (CSGRID_REST_EXPORT_PORT) – é a porta onde o SGA publica a sua API REST

E por fim, utilizar as seguintes opções do comando docker run:

--network=host

Usar a configuração de rede da máquina hospedeira

--user user_id:group_id

Executar informando o UID e GID do usuário que irá executar o processo do servidor

--restart=unless-stopped

Define a política de reinício do container Docker. O valor unless-stopped indica que o container deve ser reiniciado sempre, menos se ele foi parado antes do daemon Docker ter sido parado. Mais detalhes em Docker run reference:Restart policies

Exemplo de script para iniciar um container Docker usando a imagem do CSGrid:

#!/bin/bash

REPO=repo.tecgraf.puc-rio.br:18089
IMAGE=soma/csgrid
VERSION=x.y.z

WORKING_DIR=$(dirname "$PWD")
CONTAINER_NAME=csgrid-${VERSION}

function start() {
        docker run -d \
        --rm \
        --name ${CONTAINER_NAME} \
        -p 8010:8010 \
        -p 1099:1099 \
        -p 1098:1098 \
        -p 6681:6681 \
        -p 8080:8080 \
        -p 7778:7778 \
        -p 7878:7878 \
        -p 40500:40500 \
        -v "${WORKING_DIR}/data/persist":/csgrid/persist \
        -v "${WORKING_DIR}/data/projects":/csgrid/projects \
        -v "${WORKING_DIR}/data/algorithms":/csgrid/algorithms \
        -v "${WORKING_DIR}/data/security":/csgrid/security \
        -v "${WORKING_DIR}/data/logs":/csgrid/logs \
        -e "CSGRID_SERVER_NAME=CSGrid" \
        -e "CSGRID_HOST_NAME=${HOSTNAME}" \
        -e "CSGRID_RMI_REGISTRY_PORT=1099" \
        -e "CSGRID_RMI_EXPORT_PORT=1098" \
        -e "CSGRID_FTC_EXPORT_PORT=6681" \
        -e "CSGRID_REST_EXPORT_PORT=8010" \
        --restart=unless-stopped \
        --network=host \
        --user "$(id -u "${USER}")":"$(id -g "${USER}")" \
        ${REPO}/${IMAGE}:${VERSION}
}

function stop() {
        docker stop ${CONTAINER_NAME}
}

case "$1" in
        start)
                start
                ;;
        stop)
                stop
                ;;
        *)
                echo "Usage: csgrid.sh {start|stop}"
                ;;
        esac

Importante

A imagem Docker do CSGrid define o umask para o valor 002, fazendo com que todos os usuários Unix do grupo informado no argumento --user do comando docker run tenham acesso de leitura e escrita aos arquivos e diretórios criados pelo container. Importante enfatizar que isso é válido também para aqueles localizados nos volumes mapeados.

Execução em ambiente com escalonadores de jobs em clusters

O CSGrid pode usar escalonadores de jobs em clusters para execução de comandos e assim aproveitar todos os benefícios que esses sistemas oferecem. Um desses benefícios é a definição de uma política de alocação de recursos com base no usuário de submissão do job. Um exemplo de política seria uma que defina que um usuário pode executar em máquinas com alta capacidade de CPU ou de GPU. Ou ainda uma que defina que um outro usuário somente tem permissão de executar em um número reduzido de nós do cluster. Para tanto é necessário uma atenção especial na configuração do SGA – mais detalhes em https://sga-rest-daemon.readthedocs.io/ – e na definição de um grupo de usuários para aproveitar os sinalizadores de direitos de acesso do Unix.

Importante

Essa configuração somente é recomendada para os casos em que seja realmente necessário que os jobs sejam submetidos ao escalonador do cluster em nome do usuário final. Se a submissão de jobs puder ser feita pelo usuário do sistema – assumindo que é esse usuário que executa tanto o servidor CSGrid quanto o SGA – os jobs em execução no cluster já terão acesso de leitura e escrita aos arquivos e diretórios da área de projetos.

Um configuração recomendada é a adição do usuário do sistema – aquele que executa o servidor CSGrid e o SGA – e dos usuários finais – correspondentes daqueles que utilizarão o CSGrid – a um novo grupo de usuários Unix criado exclusivo para a utilização do CSGrid. Dessa forma os arquivos armazenados na área de projetos serão acessíveis pelos jobs submetidos em nome de um usuário final ao escalonador do cluster.

Atenção

É necessário que o umask do usuário do sistema – que executa o servidor CSGrid e o SGA – seja 002, para que os sinalizadores de direitos de acesso Unix padrões para grupo permitam a leitura e escrita nos arquivos e diretórios criados pelo servidor CSGrid. O comando umask 002 pode ser adicionado ao script de inicialização do CSGrid e do SGA – no caso da execução via Docker esse já é o comportamento padrão.

Atenção

É necessário ativar o setgid nos diretórios raiz da área de projetos, raiz do repositório de algoritmos e no de armazenamento de dados do SGA – definido pela chave runtime_data_dir. Segue exemplo do comando:

$ chmod g+s path_to_projects_root_dir
$ chmod g+s path_to_algorithms_root_dir
$ chmod g+s path_to_runtime_data_dir

Desta forma quaisquer diretórios e arquivos criados dentro da área de projetos, do repositório de algoritmos ou do diretório de armazenamento de dados do SGA herdarão o grupo destes, permitindo que eles sejam acessíveis com permissão de leitura e escrita pelo servidor CSGrid.

Execução do Cliente Desktop

Para executar o Cliente Desktop execute o comando, substituindo na URL o host e port conforme a configuração do ambiente:

$ javaws http://host:port/csgrid/init