dadosjusbr/executor

Biblioteca go que permite a execução de um pipeline

executor

A partir da necessidade da configuração de um Pipeline no DadosJusBR, criamos um pacote em Go chamado executor. Ele será utilizado dentro da orquestradora Alba e sua principal função é ser capaz de definir, configurar e executar um Pipeline.

Consideramos um Pipeline como uma sequência de estágios que visam realizar uma tarefa macro, onde essa tarefa foi dividida em uma série de programas "dockerizados" que são executados de forma sequencial. De forma simplificada, a saída padrão de um estágio vira a entrada padrão do estágio seguinte.

Requisitos

• docker
• bash
• git

Entendendo um Pipeline DadosJusBR

Considerando o contexto do DadosJusBR, o pipeline capaz de atingir a tarefa de libertação de dados do sistema judiciário brasileiro tem os seguintes estágios:

• Coleta: Etapa responsável por encontrar, fazer o download dos arquivos e consolidar/traduzir as informações para um formato único do DadosJusBr;
• Validação: Responsável por fazer validações nos dados de acordo a cada contexto;
• Empacotamento: Responsável por padronizar os dados no formato de datapackages;
• Armazenamento: Responsável por armazenar os dados extraídos, além de versionar também os artefatos baixados e gerados durante a coleta;

Cada programa capaz de cumprir um estágio é dockerizado, ou seja, escrito de forma capaz de ser executado pela ferramenta docker, com os comandos "docker build"(que constrói uma imagem a partir das especificações definidas) e "docker run"(que executa essa imagem em um container).

No Pipeline, cada estágio, exceto o primeiro, recebe a saída padrão do estágio anterior, essa é uma forma de compartilharem informações. Também podemos definir um estágio chamado ErrorHandler, que será construído e executado quando ocorrer um erro no fluxo padrão. Consideramos como fluxo padrão a sequência de estágios descrita na definição do Pipeline.

Uma vez que sua aplicação seja dockerizada, você pode utilizar o executor para configurar e executar um Pipeline de acordo com suas necessidades.

Configurações, compartilhamento de informações e tratamento de erros

Variáveis de ambiente

É possível configurar variáveis de ambiente tanto para o docker build quanto para o docker run do seu estágio. E, caso elas se repitam para todos os estágios, você também pode defini-las como variáveis padrão. Para que essas customizações pudessem ser realizadas, adicionamos na sintaxe do Pipeline estruturas especiais que devem ser configuradas a partir da sua necessidade: BuildEnv, RunEnv, DefaultBuildEnv e DefaultRunEnv.

Exemplo

buildEnv := map[string]string{
    "COMMIT":           "1a2b3c4d5e",
}

runEnv := map[string]string{
    "URL":           "https://dadosjusbr.org",
    "OUTPUT_FOLDER": "/output",
}

Volume dadosjusbr

Antes de iniciar a execução do primeiro estágio de um Pipeline, nós criamos um volume chamado dadosjusbr. Esse volume é do tipo bind e será montado em uma pasta local(chamada output) criada a partir do diretório base que você nos informa na definição do Pipeline (Veja linhas 27 e 35 da estrutura do Pipeline). A cada "docker run" de um estágio, esse mesmo volume é utilizado para espelhar o conteúdo da pasta /output de dentro do container em execução para a sua pasta local.

$ docker run -i -v dadosjusbr:/output stage-coleta

Por isso, nós recomendamos fortemente que quando o seu programa precisar persistir arquivos ele utilize a pasta /output dentro do container. E assim o seu diretório base local tera todos os conteúdos persistidos pelos estágios.

Tratamento de erros

Caso você deseje descrever um comportamento padrão para quando houver erro na execução do pipeline, você vai definir um estágio especial para isso: o que nós chamamos de ErrorHandler. Ele será construído e executado como os demais, porém, se ocorrer outro erro, interrompemos a execução e retornamos todos os detalhes da execução do Pipeline até aquele ponto.

Aqui, consideramos erro quando a construção ou execução de uma imagem levanta um erro durante seu processamento ou quando não levanta erro mas retorna um status diferente de 0(OK).

---

Como usar o pacote executor?

O tutorial de utilização pode ser encontrado nesse link. E o código completo do tutorial aqui.

Para mais detalhes, dúvidas ou sugestões você pode entrar em contato conosco pelo email [email protected].

Esse pacote foi desenvolvido a partir de todo o trabalho e experiência dos integrantes do time DadosJusBR.

executor's Issues

Passar commit a execução

Atualmente, o dadosjusbr guarda o commit do repositório para efeitos de auditoria. Como o executor controla o processo de clonagem no caso do master, precisamos que ele passe o commit para execução dos extágios e, dessa forma, estes podem utilizar livremente. Faremos isso através de variáveis de ambiente.

Minha recomendação é criar um campo no estágio: repo_version_env_var que recebe o nome da variável de ambiente que deve ser utilizada.

Setar automaticamente diretório compartilhado

Vamos colocar "/output"

Fragmento do descritor do pipeline:

    "name": "mpba",
    "default-run-env": {
        "OUTPUT_FOLDER":"/output"
    },

Erro:

2021/11/01 08:55:16 Executando pipeline mpba
2021/11/01 08:55:16 
2021/11/01 08:55:16 # Setting up Pipeline mpba
2021/11/01 08:55:16 Cleaning up directory:
2021/11/01 08:55:16 $ rm -rf 
2021/11/01 08:55:16 $ mkdir -m 438 
2021/11/01 08:55:16 # Error setting up pipeline mpba:error (re)creating shared dir() with permissions(438): mkdir : no such file or directory

Implementar suporte a imagens

Atualmente estágios são repositórios, porém devemos também implementar dar suporte a imagens docker.

Principalmente considerando que o github tem um registro gratuito para projetos públicos que permite que a gente guarde as imagens.

Passar stdin do executor para o primeiro estágio

É muito útil para depuração receber a entrada padrão e passar para o primeiro estágio. Exemplo de caso de uso: um pipeline que os estágios demoram muito e deu erro no meio. Daí podemos re-iniciar pelo estágio que deu erro, apenas passando a entrada padrão.

Atualmente o executor pega a entrada padrão e usa como descritor. Vamos tornar isso uma flag e passar a stdin para o primeiro estágio.

Deixar tutorial mais simples

Evitar utilizar os coletores dos órgãos para não acabar sobrecarregando os servidores.

Atualizar o README.md da raiz do repo

Hoje o README está bem genérico e ainda se referindo a estágios do dadosjusbr.

Talvez possamos atualizar para refletir melhor as capacidades da biblioteca. Talvez possamos ter o tutorial todo aqui! :D

Testes para execução de estágios

Issue criada a partir de comentário no Error Handler

Usar lib status em tutorial/stage-go

Atualmente o estágio está usando log.Fatal. Acho que podemos usar o tutorial para fomentar o uso da biblioteca status

Passar variáveis de ambiente em tempo de execução

Além das variáveis passadas nos arquivos de configuração, é importante ter variáveis via linha de comando. A ideia é modificar apenas a linha de comando (cmd).

Sugestão:

• Adicionar as flags --defaul_run_env e --default_build_env -- idealmente mapas -- que receberiam pares chave:valor e passariam para os respectivos campos do pipeline.