Ir para o conteúdo principal

GitLab CI/CD

Introdução

O GitLab CI/CD é uma ferramenta integrada ao GitLab onde é possível descrever todos os passos de integração e implantação contínua em um arquivo dentro do repositório. Na SETIC é utilizado para automatizar os processos de integração, inspeção de código e publicação no OpenShift.

Orientações

Pré-requisitos

Sonatype Nexus Repository

Para otimização em quaisquer processos que envolvam a compilação de um projeto, seja em ambiente local de desenvolvimento ou na esteira de automação, é utilizado o Nexus como proxy de bibliotecas e imagens docker.

Para maiores informações sobre uso e configuração do Nexus, consulte este manual.

Docker

A esteira de automação da SETIC, que utiliza o GitLab CI/CD, é baseada na adoção de Containers, com isso, dentre as opções disponíveis no mercado, foi escolhido a ferramenta Docker.

Todo projeto deverá possuir um arquivo "Containerfile" ou "Dockerfile" funcional.

Para projetos .NET

Para projetos .NET é necessária uma classe de configuração para a integração correta no OpenShift. Visto essa necessidade em todos os projetos .NET disponibilizamos um pacote com esta configuração, para utilizá-lo basta seguir os passos abaixo:

  1. Instale o pacote no seu projeto com os um dos comandos abaixo ou pelo gerenciador de pacotes do Visual Studio
        Package Manager : Install-Package SETIC.OpenShift
        CLI : dotnet add package SETIC.OpenShift

  2. No método CreateHostBuilder da Program.cs, registre o serviço do OpenShift:
    public static IHostBuilder CreateHostBuilder(string[] args) =>
            Host.CreateDefaultBuilder(args)
                .ConfigureWebHostDefaults(webBuilder =>
                {
                	...
                    webBuilder.UseOpenShiftIntegration(); 
                    ...
                });

    o método também suporta a personalização do diretório do certificado caso necessário, como no exemplo abaixo:

    public static IHostBuilder CreateHostBuilder(string[] args) =>
            Host.CreateDefaultBuilder(args)
                .ConfigureWebHostDefaults(webBuilder =>
                {
                    ...
                    webBuilder.UseOpenShiftIntegration(_ => _.CertificateMountPoint = "/var/run/secrets/service-cert"); 
                    ...
                });

Para utilizar este pacote é necessário a configuração do Sonartype Nexus Repository.

Certificados

Alguns certificados são necessários para que o projeto possa ser publicado no OpenShift.

Abaixo segue o exemplo, baseado em uma imagem Linux (Alpine, Debian, Ubuntu e distribuições derivadas)

RUN curl -fsSL https://gitlab.setic.ro.gov.br/publico/ca-trust/-/raw/master/openshift_ca.crt -o /usr/local/share/ca-certificates/openshift_ca.crt
RUN curl -fsSL https://gitlab.setic.ro.gov.br/publico/ca-trust/-/raw/master/portainer_ca.crt -o /usr/local/share/ca-certificates/portainer_ca.crt
RUN update-ca-certificates

Abaixo segue o exemplo, baseado em uma imagem Linux (Centos, Fedora, Redhat e distribuições derivadas)

RUN curl -fsSL https://gitlab.setic.ro.gov.br/publico/ca-trust/-/raw/master/openshift_ca.crt -o /etc/pki/ca-trust/source/anchors/openshift_ca.crt
RUN curl -fsSL https://gitlab.setic.ro.gov.br/publico/ca-trust/-/raw/master/portainer_ca.crt -o /etc/pki/ca-trust/source/anchors/portainer_ca.crt
RUN update-ca-trust

Estrutura de branches padrão

Para utilizar a esteira de automação da SETIC, as seguintes branches devem ser utilizadas:

  • development - A branch development é a branch onde o time de desenvolvimento mantém as novas features desenvolvidas.
  • staging - A branch staging representa o ambiente de treinamento/review do produto.
  • production - A branch production deve ser tratada como the single source of truth, ou seja, ela representa exatamente o que está em produção.

O objetivo das branches não necessariamente precisam ser iguais ao sugerido, entretanto, é necessário que essa estrutura exista.

É obrigatório que as branches citadas sejam protegidas, aceitando apenas merge requests para alteração. A imagem abaixo ilustra o que deve ser configurado para atender a obrigatoriedade.

image-1652802149709.png
Fig. 1 - Painel de configuração de proteção de branches do repositório

HotFix
Correções urgentes podem ser mescladas nas branches staging ou production, mas devem seguir a seguinte regra:

  • Branches de hotfix devem iniciar com o prefixo 'hotfix-*', como por exemplo: hotfix-correcaourgente.

Instalação

Crie um arquivo "gitlab-ci.yml" na raiz do projeto, com a estrutura básica abaixo.

include:
  - project: ci-cd/templates
    ref: production
    file:
      - code-quality.dotnet.yml
      - deploy.openshift.yml
      - variables.yml

stages:
  - code-quality
  - deploy

variables:
  PROJECT_NAME: "nomedoprojeto"
  PROJECT_DISPLAY_NAME: "Nome do Projeto"

  DOCKERFILE_PATH: "Dockerfile"
  DOCKERFILE_CONTEXT: "/"

  ROUTER_PORT: "8080"
  ROUTER_PATH: "/"
  ROUTER_TERMINATION: "reencrypt"

  ROUTER_HOSTNAME_DEVELOPMENT: ""

  ROUTER_HOSTNAME_STAGING: >
    "rotaexternaqa.exemplo.com"

  ROUTER_HOSTNAME_PRODUCTION: >
    "rotaexternaproducao.exemplo.com"

  DEPLOY_ENVIRONMENT: >
    "TZ=America/Porto_Velho"

Trecho Include

Este trecho referência os arquivos de configuração da esteira de automação. Por padrão é incluído os seguintes arquivos de configurações:

  • deploy.openshift - O "deploy.openshift.yml" é o arquivo responsável por realizar a publicação do projeto no OpenShift.
  • variables - O "variables.yml" é o arquivo de variáveis utilizado pelos arquivos "deploy.openshift" e "code-quality".
  • code-quality - O "code-quality.{linguagem}.yml" é o arquivo responsável pela configuração do estágio de inspeção de código. Atualmente a ferramenta utilizada para inspeção de códigos na SETIC é o SonarQube.

     Linguagens suportadas:
      - .NET (code-quality.dotnet.yml)

Suporte a outras linguagens serão desenvolvidas conforme a necessidade.

Para maiores informações sobre as regras de inspeção de código adotadas pela SETIC, consulte este manual.

Trecho Stages

Este trecho especifica quais estágios do arquivo serão utilizados no processo de execução da esteira. Por padrão é incluído os seguintes estágios:

  • code-quality - é o estágio responsável por executar o processo de inspeção de código.
  • deploy - é o estágio responsável por executar o processo de publicação de código no OpenShift.

Trecho Variables

Este trecho é responsável por incluir variáveis pertinentes ao projeto para a execução da esteira, sendo customizável para cada projeto.

PROJECT_NAME

Essa variável configura o nome do projeto que será criado no OpenShift, além disso também é utilizada internamente em operações do OpenShift, como por exemplo, para criação de rotas internas.

O valor da variável deve possuir apenas letras minúsculas, sem acento ou espaço.

 PROJECT_DISPLAY_NAME

 Essa variável será o nome "amigável" do projeto que será exibido no OpenShift.

É permitido qualquer valor alfanumérico, incluindo espaço, símbolos e acentos.

DOCKERFILE_PATH

Variável que indica onde está localizado o arquivo Dockerfile do projeto.

É suportado arquivo "Dockerfile", "Containerfile" ou qualquer outro arquivo que seja suportado pela Docker Engine.

DOCKERFILE_CONTEXT

Especifica o diretório contendo arquivo de configuração de container

ROUTER_PORT

Especifica a porta de destino para o tráfego

ROUTER_PATH

Especifica o caminho que o roteador observa para rotear o tráfego para o serviço

ROUTER_TERMINATION

Especifica a terminação TLS da rota

Para saber mais sobre rotas seguras e conhecer as terminações TLS no OpenShift consulte a documentação oficial.


ROUTER_HOSTNAME_DEVELOPMENT, ROUTER_HOSTNAME_STAGING, ROUTER_HOSTNAME_PRODUCTION 

Representação das rotas externas do projeto, caso possuam. São separadas por ambientes, sendo eles: Development, Staging e Production.

Essa variável suporta uma lista de URLs, caso seu projeto possua mais de uma.

As URLs inseridas devem ser apenas externas. As URLs internas, são criadas automaticamente pela esteira de automação, sem a necessidade de especifica-las.

As URLs inseridas não devem possuir protocolo e devem conter apenas a URL base, sem diretórios.

  
DEPLOY_ENVIRONMENT

Nessa variável é possível especificar variáveis que serão utilizadas no Deployment do container.

Atualmente, esta variável é utilizada para inserir configurações no Container, como por exemplo, configurar a timezone do container.

Instalação em Multiprojetos

Essa configuração é referente a um repositório que contenha mais de um projeto.

Atualmente, a esteira de automação não suporta deploy baseado em docker-compose. Assim, foi criado uma extensão na própria esteira para suportar deploy de vários projetos do mesmo repositório.

Crie um arquivo "gitlab-ci.yml" na raiz do projeto, com a estrutura básica abaixo.

include:
  - project: ci-cd/templates
    ref: production
    file:
      - deploy.openshift.yml
      - variables.yml

stages:
  - deploy

variables:
  PROJECT_NAME: "nomedosistema"
  PROJECT_DISPLAY_NAME: "Nome do Sistema"

  PROJECT_DEPLOY: "multi-deploy"

sistema-web:
  extends: .multi_deploy
  variables:
    PROJECT_NAME: "sistemaweb"
    PROJECT_DISPLAY_NAME: "Sistema Web"

    DOCKERFILE_PATH: "Dockerfile"

    ROUTER_PORT: "8080"
    ROUTER_TERMINATION: "reencrypt"

    ROUTER_HOSTNAME_DEVELOPMENT: ""

    ROUTER_HOSTNAME_STAGING: >
      "sistemawebstaging.exemplo.com"

    ROUTER_HOSTNAME_PRODUCTION: >
      "sistemaweb.exemplo.com"

    DEPLOY_ENVIRONMENT: >
      "TZ=America/Porto_Velho"

sistema-api:
  extends: .multi_deploy
  variables:
    ## PROJETO
    PROJECT_NAME: "sistema-api"
    PROJECT_DISPLAY_NAME: "Sistema API"

    DOCKERFILE_PATH: "Dockerfile"

    ROUTER_PORT: "8080"
    ROUTER_TERMINATION: "reencrypt"
    
    ROUTER_HOSTNAME_DEVELOPMENT: ""

    ROUTER_HOSTNAME_STAGING: ""

    ROUTER_HOSTNAME_PRODUCTION: ""
    
    DEPLOY_ENVIRONMENT: >
      "TZ=America/Porto_Velho"

Trecho Variables

Este trecho é responsável por incluir variáveis pertinentes ao projeto para a execução da esteira, sendo customizável para cada projeto.

PROJECT_DEPLOY

Essa variável é a responsável por disponibilizar a configuração de multi-deploy na esteira de automação.

Trecho por Projeto

Para cada projeto que será publicado, deve existir um trecho com o nome do projeto.

extends

Essa variável especifica que o projeto fará uso da esteira de automação multi-deploy.

variables

Neste trecho serão adicionadas as configurações básicas de variáveis de cada projeto, similar a configuração padrão de projeto já demonstrada anteriormente.

Enriquecendo a configuração do CI

Trecho Variables

PROJECT_SDK (.NET)

Esta variável especifica a versão .NET utilizada no projeto, para ser utilizada no processo de inspeção de código.

Versões de SDKs .NET suportadas:
- 3.1
- 5.0
- 6.0

Esta variável é obrigatória para projetos .NET

Suporte a outros SDKs serão desenvolvidos conforme a necessidade.

PROJECT_SOLUTION (.NET)

Esta variável especifica o arquivo .SLN, sendo necessário para execução do comando build do .NET.

Esta variável é obrigatória para projetos .NET

CERTIFICATE_SECRET_NAME (.NET)

Especifica o nome do certificado

Esta variável é obrigatória para projetos .NET

CERTIFICATE_MOUNT_PATH (.NET)

Especifica o diretório do certificado

Esta variável é obrigatória para projetos .NET

DISABLE_SCALE

Variável que define se o projeto usará a funcionalidade de escalonamento horizontal.

Esta variável deve ser definida apenas em legados que não podem ser escalados ou workers.

BUILD_ENVIRONMENT

Nessa variável é possível especificar variáveis que serão utilizadas no build do projeto.

Exemplo de inserção:

BUILD_ENVIRONMENT: >
  "DOTNET_RESTORE_DISABLE_PARALLEL=True"
  "DOTNET_INCREMENTAL=True"
  "DOTNET_VERBOSITY=diag"

Atualmente utilizamos para inserir variáveis de configurações do Container referentes a linguagem.

BUILD_ENVIRONMENT_FILE

Nessa variável é especificado o arquivo .ENV caso seu projeto possua um.

Para facilitar o uso dinâmico baseado em ambientes distintos, é possível utilizar a variável CI_COMMIT_REF_NAME do GitLab-CI para obter o nome da branch onde o estágio está sendo executado, como por examplo:
BUILD_ENVIRONMENT_FILE: "${CI_COMMIT_REF_NAME}.env"
Se for executado na branch development, será obtido o resultado: development.env.

Caso queira conhecer mais variáveis pré-definidas no GitLab-CI para utilizar na sua configuração do GitLab-CI, acesse: Variáveis pré-definidas do GitLab-CI