Estratégia de Verificação, Validação e Integração

Este documento tem por objetivo documentar toda a estratégia de integração contínua, bem como a verificação por pares e testes de software utilizados pela Basis no desenvolvimento de seus projetos, bem como estabelecer critérios de integração e evidenciar a realização da prática através de relatórios de integração, apontando problemas e correções.

Considera-se no escopo deste documento abordar todas as etapas e procedimentos que são necessários para a verificação por partes dos artefatos elaborados pela Análise e Design dos projetos de desenvolvimento, a construção efetiva de um sistema, através de integração contínua, tal como as configurações de ferramentas envolvidas e breves explicações sobre seus funcionamentos e os procedimentos utilizados para testar o produto nos ambientes de desenvolvimento, integração e pretendido para o uso.

Estão fora do limite definido como escopo deste documento as informações inerentes à configuração e conexão da VPN da Basis, bem como de acesso remoto à máquina do Jenkins e seus slaves, ou suas especificidades desnecessárias ao contexto.

A verificação por pares é executada para identificar defeitos nos requisitos, na arquitetura e no desenvolvimento do produto antes que estes sejam formalizados como código fonte estável, de forma que o custo para resolução seja mais baixo e a solução mais efetiva, garantindo a integridade da informação ao longo do ciclo de vida do software.

A Basis realiza verificações por pares em seus produtos através da técnica de Inspeção, onde um revisor fará uma inspeção com base em critérios, nos produtos selecionados.

São efetuadas inspeções em requisitos, na arquitetura do produto e no código-fonte do mesmo, com base em critérios definidos nas ferramentas SGO e Git. No momento da inspeção, a tarefa deve ser atribuída ao revisor, que deverá então analisar os documentos à luz dos critérios padronizados. Caso problemas sejam identificados, estes poderão ser relatados no texto de observação existente no checklist, bem como em evidências de captura de tela, quando pertinente.

Em todas as revisões por pares o revisor deve se preocupar em:

Executam-se inspeções em requisitos, representados pelas especificações funcionais de Casos de Uso ou Especificações por Exemplo (EPEs), de acordo com a opção do projeto. As inspeções são feitas com base em critérios definidos na ferramenta SGO, para cada tarefa de implementação.

As mesmas poderão ser efetuadas por amostragem, quando a quantidade de Casos de Uso ou EPEs for grande (maior que 10). Nestes casos, poderá se optar por realizar apenas a revisão de parte das especificações funcionais, ficando a cargo do revisor essa decisão. Recomenda-se que nestes casos a escolha leve em consideração:

Executam-se inspeções na arquitetura do produto, na qual o revisor é um par do elaborador das especificações. As inspeções são feitas com base em critérios definidos na ferramenta SGO, para cada ordem de serviço.

Executam-se inspeções no código-fonte a ser integrado à branch principal do repositório Git do sistema em questão. As inspeções são feitas com base na checklist de validação de Merge Request, evidenciada na própria criação do Merge Request no repositório, e definida na seção Qualidade.

A Integração Contínua é uma prática recente na engenharia de software, que consiste, resumidamente, em unificar todas as cópias de trabalho de cada desenvolvedor, várias vezes ao dia, em um ambiente centralizado e compartilhado. Ela ganhou grande importância na comunidade de desenvolvimento de software devido ao grande impacto causado pelas metodologias ágeis, sendo ela um dos pilares de tal agilidade e garantindo que todo o sistema funcione de forma correta em cada nova construção (build), mesmo que a equipe envolvida seja grande e diversas partes do código estejam sendo alteradas ao mesmo tempo.

Uma grande vantagem da integração contínua é a repercussão instantânea. A cada commit no repositório, a build é automaticamente realizada, executando testes e detectando falhas. Se o código de algum commit não compilar ou não passar em algum dos testes, a equipe envolvida toma conhecimento instantaneamente através de um E-mail, por exemplo, que aponta as falhas detectadas e o commit que contém o código defeituoso, possibilitando assim uma correção imediata.

O processo de integração envolve três equipes principais, todos com responsabilidades, objetivos e procedimentos bem definidos:

O Jenkins é uma ferramenta de http://en.wikipedia.org/wiki/Continuous_integration[Integração Contínua] projetada para realizar builds automáticas de múltiplos projetos (definidos em configurações individuais nomeadas Jobs), a partir de gatilhos pré-definidos; periódicos, específicos ou a cada novo commit no repositório associado. Baseado em Java, ele permite restringir o acesso de usuários às Jobs, e possui vários plugins instaláveis para melhor atender às necessidades específicas de projetos. Sua construção garante que apenas builds de sucesso sejam publicadas em produção.

No ambiente Basis, o Jenkins, acessível pelo endereço https://cje-master1.basis.com.br/, possui uma estrutura padronizada de acesso a jobs de clientes. As pastas de acesso consistem em "Cliente/Sistema/Ambiente", e possuem acesso restrito aos grupos de recursos Basis associados àqueles clientes específicos.

A ação da construção de fato é dividida em agents, também conhecidos como slaves, que são máquinas individuais, executando construções em paralelo. Todos os agents são gerenciados no servidor central, Jenkins Master, responsável por configurar os jobs, atribuindo-lhes opções específicas de inicialização, e por direcionar as builds, disponibilizando-as em agents livres. Os agents, bem como certas ferramentas comuns do Jenkins como versões de Java e Maven, são configurados em uma instância de controle de Jenkins Masters, o Jenkins Operation Center, acessível em https://joc.basis.com.br/.

Versões mais recentes do Jenkins aplicam o conceito de Pipeline às jobs. Uma pipeline de entrega contínua no Jenkins consiste em um processo complexo de construção do software de maneira confiável e repetida, normalmente separada em estágios para melhor controle. Tais pipelines são elaboradas via código, utilizando uma sintaxe específica conhecida como Domain-specific Language (DSL), e podem ser colocadas ou em um arquivo Jenkinsfile dentro do próprio repositório de código, ou na configuração da job no Jenkins, ou em um Job Template.

Um Job Template no Jenkins consiste em uma configuração fixa e padronizada de jobs, de tal forma que qualquer job que seja criada a partir desse template só necessita de alguns parâmetros a configurar, em vez de uma configuração completa. Os templates do Jenkins Basis aplicam parâmetros específicos em pipelines, de forma a manter as jobs uniformemente configuradas.

Os templates do ambiente Basis possuem também uma funcionalidade associada ao SonarQube, de modo a realizar avaliações de qualidade de código toda vez que uma nova build é executada. Se o código sendo construído ficar aquém de um limite fixo de qualidade de código, o chamado Quality Gate, a construção é interrompida, exigindo a revisão do código pelos desenvolvedores de forma a eliminar os problemas de qualidade recém surgidos.

Apache Maven, ou simplesmente Maven, é uma ferramenta de http://pt.wikipedia.org/wiki/Automa%C3%A7%C3%A3o_de_compila%C3%A7%C3%A3o[automação de compilação] utilizada primariamente em projetos Java. O Maven utiliza um arquivo http://pt.wikipedia.org/wiki/XML[XML] (POM) para descrever o projeto de software em construção, bem como suas dependências de módulos e componentes externos, ordem de compilação dos mesmos, diretórios e http://pt.wikipedia.org/wiki/Plug-in[plugins] necessários. Ele possui objetivos pré-definidos para realizar tarefas específicas, como compilação e empacotamento de código.

O Maven adquire bibliotecas Java e seus plugins dinamicamente de um ou mais repositórios, como o próprio repositório central Maven ou o Nexus Basis, e armazena-os em uma área de cache local. Esse cache pode também ser atualizado com artefatos criados por projetos locais.

O Jenkins utiliza o Maven como concentrador de comandos e variáveis para integração contínua. O arquivo POM é lido para ajustar os deploys da integração a partir do plugin Cargo, bem como a migração do banco de dados a partir do Liquibase ou Flyway.

Docker é uma plataforma Open Source, que facilita a criação e administração de ambientes isolados. O Docker possibilita o empacotamento de uma aplicação ou ambiente inteiro dentro de um container, e a partir desse momento o ambiente inteiro torna-se portável para qualquer outro Host que contenha o Docker instalado. Isso reduz drasticamente o tempo de deploy de alguma infraestrutura ou até mesmo aplicação, pois não há necessidade de ajustes de ambiente para o correto funcionamento do serviço, o ambiente é sempre o mesmo, configurado uma vez e replicado quantas vezes quiser.

O backend padrão do Docker é o LXC. Com isso é possível definir limitações de recursos por container (memória, cpu, I/O, etc.)

Vantagens:

As construções do Jenkins que utilizem um template relativo a Docker criam imagens a partir dos códigos-fonte e enviam para repositórios internos no Nexus, para que sejam utilizadas em suas máquinas respectivas. Nossas máquinas Docker, ou Docker Hosts, são separadas por cliente, mantidas e organizadas via Rancher.

O Rancher consiste numa plataforma de operação do Docker, provendo uma interface gráfica intuitiva e várias funcionalidades que facilitam a manutenção de hosts e containers. Entre elas, o gerenciamento de redes e balanceamento de carga entre hosts, criação e manutenção de volumes de armazenamento, facilitação de uso de recursos do próprio Docker, elaboração de catálogos contendo pilhas de serviços Docker para execução direta, visualização de logs, execução de comandos, entre outros.

Uma pilha de serviços no Rancher normalmente comprime tudo o que é necessário para a execução de um sistema. É composta por um ou mais containers Docker, que se comunicam entre si através de redes internas estabelecidas pelo próprio Rancher.

As construções do Jenkins que utilizem um template relativo a Docker fazem a atualização dos serviços específicos relativos aos seus sistemas diretamente no Rancher, através de um plugin desenvolvido internamente. Portanto, não há necessidade de interação com o Rancher uma vez que os serviços estejam corretamente configurados, o próprio Jenkins se encarrega dos demais processos de atualização.

O SonarQube, anteriormente conhecido simplesmente como Sonar, é uma plataforma aberta de gerenciamento de qualidade de código. Abrangendo várias linguagens e métodos, o SonarQube provê estatísticas relativas à codificação de cada sistema, apresentando resultados de testes unitários e de integração, avaliação de código duplicado, documentação, complexidade, e apontando diversos problemas encontrados no código ao longo do tempo.

A integração do SonarQube com o Jenkins é direta, feita através de um plugin que adiciona um passo de pós-build à job desejada, bastando também adicionar testes e referências no POM relativo ao projeto. O sucesso em uma build configurada desta forma já coloca o código no ambiente do SonarQube, para posterior avaliação dos resultados.

Em nosso ambiente padrão de qualidade de código, acessível pelo endereço https://codequality.basis.com.br/, o SonarQube possui um Quality Gate, um “limite de qualidade” específico para cada tipo de avaliação. A BASIS define um limite de qualidade minimo padrão para seus projetos. Esses limites podem ser alterados de acordo com os níveis acordados em contrato, sendo necessária intervenção no código caso fique abaixo de tal. Este nível de qualidade deve ser garantido pelos responsáveis pelo desenvolvimento e será verificado no momento da geração das baselines de código-fonte.

Existe também um ambiente separado para verificação de qualidade imediata em builds do Jenkins. Acessível via https://codequality-build.basis.com.br/, esta instância do SonarQube possui um Quality Gate voltado especificamente para verificação de novos problemas que tenham surgido em cada uma das construções realizadas no Jenkins, bloqueando a continuidade das mesmas enquanto o problema não for resolvido.

Existem dois tipos de repositórios utilizados na configuração dos projetos de integração: os repositórios de código-fonte de cada sistema (Git – http://gitlab.basis.com.br) e o repositório interno referente às bibliotecas a serem utilizadas pelo Maven, NPM, Bower, bem como às imagens Docker (Nexus – http://element.basis.com.br). No Git, utilizado como ferramenta de controle de versão, armazenam-se a documentação e o código-fonte de cada sistema. Código este em que se encontra o pom.xml, responsável por fornecer os parâmetros do Maven. O Nexus é responsável pelas bibliotecas do Maven, a partir das quais os comandos de construção são executados, bem como por Docker Registries privados, onde se armazenam imagens Docker construídas e utilizadas pelo Jenkins para uso nos ambientes Basis.

Cargo é um empacotador que permite a manipulação de diversos tipos de servidores de aplicações, como Java EE, de maneira padronizada. No Maven, ele funciona como um plugin para configurar, iniciar, parar ou implantar aplicativos em seus devidos servidores. Para chamá-lo no Jenkins, utiliza-se a opção cargo:redeploy, e seus parâmetros serão lidos do pom.xml. O Cargo é normalmente utilizado em projetos de arquitetura antiga, onde não se utiliza o Docker.

Para sistemas construídos pela Basis que necessitem de banco de dados, utilizamos ferramentas que possibilitem uma migração automatizada e controlada de forma simples. Tais ferramentas de migração de banco de dados são integradas ao Maven como um plugin, e podem ser executadas tanto em cada construção do sistema quanto na inicialização do mesmo. Funcionam com scripts SQL padrão ou no formato XML, e são compatíveis com os principais bancos de dados.

Tal abordagem tem como motivações:

A depender do projeto, escolhe-se uma das duas ferramentas abaixo: Liquibase ou Flyway.

A preparação determina um planejamento para a sequência de integração, o estabelecimento do ambiente de integração, os itens de software a serem integrados, bem como procedimentos e critérios para a integração do produto. A definição da estratégia e das ferramentas que serão utilizadas no projeto é registrada e aprovada no Documento de Arquitetura de Software dos projetos.

A compatibilidade entre interfaces é garantida através da execução e manutenção de práticas como a revisão das descrições de interfaces internas e externas, evidenciando quaisquer alterações por rastreamento.

Executa-se, por fim, o planejamento de integração elaborado inicialmente, de forma a evidenciar por fim a disponibilidade dos componentes do produto para integração.

Para que a integração possa ocorrer de maneira completa, há três ambientes que devem estar preparados previamente:

Acessível pelos projetos específicos listados no site https://gitlab.basis.com.br/, necessita minimamente de arquivos base para inicialização das builds, como um POM, e de scripts de banco para execução do Liquibase ou Flyway. Acessos são restritos à equipe de cada sistema.

Configurado pela equipe de banco e acessível também à equipe de configuração, deve ter suas configurações de acesso e especificidades colocadas no código e nos próprios ambientes de desenvolvimento. O tipo de banco varia de acordo com o projeto.

Criados pela equipe de configuração a partir de uma tarefa repassada pelo gestor, logo após a aprovação da proposta de trabalho relativa ao sistema. Consistem em containers Docker empilhados no Rancher, ou máquinas virtuais que possuem os requisitos de hardware e software mínimos para aplicação do código e associação com o banco de dados.

Faz-se necessário, por fim, a configuração de uma job no Jenkins propriamente dito, realizada pela equipe de configuração. Acessando o endereço apontado na sessão Jenkins, com nome e senha específicos de usuário, temos a tela inicial do ambiente:

A partir desta tela, a equipe de configuração seleciona um projeto do cliente desejado dentre os já existentes, organizados em pastas. Caso não haja ainda uma pasta do cliente específico, uma nova pode ser criada no botão Novo job, ou New Item, e selecionando o tipo Folder.

Na configuração que segue, por padrão, se estabelece o nome do cliente, possivelmente um nome de exibição com mais detalhamento, e uma variável de ambiente DOCKER_REGISTRY, para direcionamento das jobs ao repositório Docker associado ao mesmo.

Uma vez dentro da pasta do cliente, seguem-se procedimentos semelhantes para criação das pastas do sistema propriamente dito, e das instâncias separadas de DES/TST/HOM que forem necessárias. O destaque a ser feito para este ponto do processo é que, da mesma forma que a pasta do cliente possui uma variável de ambiente DOCKER_REGISTRY para direcionamento das imagens do Docker, as pastas de cada sistema devem ter também uma variável, GRUPO, para que as imagens tenham um subgrupo específico do sistema em questão.

Dentro da pasta final, por padrão seguindo a estrutura Cliente/Sistema/Ambiente, podem ser criadas as jobs de construção de fato. Para tal, clica-se em New Item, seleciona-se o nome e o tipo ou template de job a ser configurada. Supondo uma construção de um container Docker para o backend de um sistema, por exemplo, seleciona-se o Template Docker Backend.

Na tela que segue, toda a configuração acerca do sistema em questão é realizada, incluindo, entre os detalhes mais importantes, a definição do repositório a usar-se para o código, utilizando endereço de acesso SSH com as credenciais estabelecidas na configuração do próprio Jenkins, a automatização de construções baseada em frequência de atualizações do repositório, os parâmetros do Maven utilizados na build, como escolha de um profile do POM. Os parâmetros de configuração da job possuem um ícone de ajuda para maior esclarecimento sobre a utilidade de cada parâmetro.

Diferentes sistemas podem exigir diferentes configurações ou templates, incluindo jobs mais abertas que não utilizem templates propriamente. O padrão para todos, independente das configurações individuais de sistema, é utilizar os repositórios Git corretos, selecionando a branch master por padrão, e ativar a consulta periódica do SCM para ambientes de desenvolvimento. Dessa forma, sempre que houver um novo commit no repositório de código do sistema, uma build será automaticamente executada.

No caso de jobs específicas para verificação de qualidade, deve ser utilizado o Template Sonar. A job em questão terá seu foco em testes que estejam configurados para aquele cliente/sistema, para atestar qualidade e erros de código. Vale constar que existem dois Templates Sonar principais, sendo o segundo o Template Sonar Branch. Este possui como diferencial a parametrização da branch do repositório que será usada na execução manual da job, sendo que o primeiro foca numa única branch, definida na configuração, e roda automaticamente e periodicamente.

Configurados e salvos os detalhes da job, as construções do sistema podem ser realizadas. Na tela padrão da job, clicando em Construir agora, uma nova build é iniciada. Todos os usuários com acesso ao Jenkins e às pastas específicas dos clientes, requisitado pelo gestor, podem executar builds e visualizar os detalhes da execução.

Na seção “Histórico de builds”, clicando nos detalhes da build em execução, ou mesmo em alguma previamente executada, é exibida a tela de detalhes da build em questão, incluindo detalhes da alteração no repositório que iniciou sua execução.

Ainda dentro da tela da build, selecionando Saída do console, ou a partir de outra tela que exiba o progresso atual das builds do Jenkins, ao clicar na barra de progressão das mesmas, é possível ver o log de execução da construção em tempo real.

Se a build finalizar em vermelho, houve algum problema em sua execução, e o log deve ser examinado para determinar a solução. Nesse caso, o sistema não é construído e fica inacessível em sua versão mais recente.

Se finalizar em azul, o sistema foi corretamente construído de acordo com os parâmetros de configuração anteriormente especificados e deve estar acessível por seu link ao ambiente específico.

Se a build finalizar em amarelo, a construção terminou de modo instável. Isso indica que algo na construção não saiu como esperado e pode acarretar em problemas no sistema. Também cabe investigar os logs para determinar se a situação necessita de reparo.

Independente do resultado das builds, quando esta é finalizada, as equipes de configuração e gestão são informadas por e-mail e por chat, de acordo com a configuração da própria job. O e-mail inclui o resultado da build e a saída de log da build em questão.

Para solucionar o problema apontado na build, o executor da mesma inicialmente examina o log. Se o erro apontado for algo relativo a seu próprio trabalho, ele mesmo faz as devidas alterações, seja em código ou ambiente, e realiza uma nova build. Caso o erro não faça parte da sua própria jurisdição, ele deve abrir uma ocorrência no SGO para direcionar o erro à equipe responsável por tal departamento.