Guia para GitLab Runner Operator no OpenShift

2 de junho de 2023Tayler Geiger10 minutos (tempo de leitura)

Os pipelines de integração e entrega contínuas (CI/CD) se tornaram uma parte crucial dos processos modernos de desenvolvimento de software, permitindo aos desenvolvedores criar, testar e implantar alterações no código com rapidez e eficiência. Por automatizar o processo de criação e implantação de aplicações, os pipelines de CI/CD ajudam as equipes a melhorar a qualidade do código, reduzir os erros e acelerar o time to market de novas funcionalidades e aplicações.

GitLab Runners são aplicações que processam tarefas de CI/CD no GitLab.com e em instâncias de GitLab auto-hospedadas. O GitLab.com disponibiliza os próprios executores hospedados que são compartilhados entre os usuários do site. Mas você também pode configurar executores privados dedicados para seus projetos usando vários tipos diferentes de instalação. Para empresas ou pessoas que gostam de gerenciar a própria infraestrutura de pipeline na nuvem, o GitLab Runner Operator, disponível como um Red Hat Certified Operator no OpenShift, faz a instalação rápida, fácil e nativa em nuvem de GitLab Runners.

Para mostrar a simplicidade e a funcionalidade do GitLab Runner Operator, imaginei que seria divertido também destacar alguns desenvolvimentos interessantes no Fedora Linux e usar o GitLab Runner Operator para criar imagens-base personalizadas para o Fedora Silverblue.

O Fedora Silverblue é uma distribuição avançada e imutável do Fedora Linux. Recentemente, seu sistema híbrido de gerenciamento de imagens e pacotes (⁣rpm-ostree) passou a inicializar de dentro de containers OCI. Com isso, usuários ou empresas podem criar as próprias imagens-base personalizadas com o mesmo fluxo de trabalho dos Dockerfiles e Containerfiles.

No tutorial a seguir, configuraremos um sistema de build totalmente automatizado para nossas imagens do Fedora Silverblue usando o GitLab Runner Operator.

Pré-requisitos

Você precisará de alguns recursos pré-configurados e instalados que não abordaremos no tutorial:

Um cluster do OpenShift
Uma instalação do Fedora Silverblue (se você realmente quiser usar imagens personalizadas)
Uma conta no GitLab.com

Como instalar e configurar o GitLab Runner Operator

Abra a seção "Operators" na barra lateral do cluster do OpenShift e clique em OperatorHub. Pesquise por GitLab Runner Operator e clique na opção Certified (a versão da comunidade do operador também está disponível, mas usaremos só a variante certificada no OpenShift neste tutorial). Antes de clicar em Install, leia a seção "Prerequisites" da descrição do operador. O GitLab Runner Operator requer primeiro a instalação do cert-manager:

oc apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.7.1/cert-manager.yaml

Após fazer isso, clique em Install para instalar o GitLab Runner Operator.

Na próxima tela, você poderá alterar qualquer uma das opções de instalação padrão. Se você precisar ou quiser definir o escopo para um namespace específico, faça isso agora. Caso contrário, continue com as opções padrão. Sugiro também deixar Update approval definido como Automatic porque esse é um dos principais benefícios de usar um operador.

Aguarde um momento até que a instalação seja concluída. Depois, acesse Installed Operators e, em seguida, o GitLab Runner Operator. Aqui será exibido o mesmo texto informacional de antes e um link em Provided APIs que permite criar uma instância do Runner. No texto informacional abaixo, estão as instruções para vincular executores aos seus repositórios do GitLab, que vamos seguir agora.

Como criar e registrar a instância do Runner

1. Como criar o Secret de token de registro

Primeiro, devemos criar um Secret com um token de registro do GitLab, que nosso novo Runner usará para fazer o registro no repositório. Abra o GitLab.com ou sua instância privada do GitLab e, em seguida, o repositório que você quer registrar. Acesse "Settings" e "CI/CD". Expanda a seção Runners e examine a seção Project runners. É nela que encontraremos nosso token de registro e a URL que você usará para registrar sua instância do Runner.

Confira também a seção Shared runners se você estiver usando o GitLab.com. Lá estão os executores públicos disponibilizados pelo GitLab.com. Para este projeto, desative os executores compartilhados porque usaremos nossos próprios executores privados.

Crie seu Secret inserindo o token de registro do repositório no campo runner-registration-token⁣. Você pode fazer isso no console web ou na interface de terminal. Criei um arquivo chamado gitlab-runner-secret.yml e o adicionei ao meu cluster:

apiVersion: v1
kind: Secret
metadata:
  name: gitlab-runner-secret
type: Opaque
stringData:
  runner-registration-token: YOUR_TOKEN_HERE

oc apply -f gitlab-runner-secret.yml

2. Como configurar o executor com um ConfigMap

Antes de criarmos nosso executor, também precisamos criar um ConfigMap com algumas opções de personalização. Em geral, é possível configurar os GitLab Runners com um arquivo config.toml . No contexto do Kubernetes, podemos adicionar essas personalizações com um ConfigMap que contenha nosso arquivo config.tom .

Como estamos executando nossos containers de build no ambiente de um cluster do OpenShift, precisamos garantir que esses containers sejam executados sem privilégios escalonados e como um usuário não raiz. Observação: existem maneiras de contornar isso se você precisar de fato de um ambiente de build com privilégios, mas vamos nos ater à configuração não raiz. Aqui está um simples config.toml que especifica que o pod do executor será executado como usuário não raiz 1000:

[[runners]]
  name = "gitlab-runner"
  url = "https://gitlab.com"
  executor = "kubernetes"
  [runners.kubernetes]
    [runners.kubernetes.pod_security_context]
      run_as_non_root = true
      run_as_user = 1000

Para adicionar isso ao nosso cluster como um ConfigMap:

oc create configmap my-runner-config --from-file=config.toml

3. Como iniciar a instância do Runner

Agora, podemos criar nossa instância real do Runner. Novamente, você pode fazer isso no console web clicando em Create instance na página do GitLab Runner Operator ou no terminal. De qualquer maneira, queremos ter certeza de que nossa definição de recurso personalizado (CRD) inclua a URL correta do GitLab, os nomes do Secret de token de registro Secret e do ConfigMap e "openshift" em tags (este último item é necessário para as tarefas serem transmitidas para o cluster). Aqui está uma CRD básica chamada gitlab-runner.yml , que atende a todos os nossos critérios:

apiVersion: apps.gitlab.com/v1beta2
kind: Runner
metadata:
 name: gitlab-runner
spec:
 gitlabUrl: https://gitlab.com
 token: gitlab-runner-secret
 tags: openshift
 config: my-runner-config

Para instalar no cluster:

oc apply -f gitlab-runner.yml

Agora, você pode verificar o status do novo executor no console web ou no terminal com oc get runners. Também precisamos verificar as configurações de CI/CD do projeto no GitLab para garantir que o executor esteja vinculado corretamente ao repositório. Agora, deve haver um executor em Assigned project runners com o mesmo nome da CRD que criamos e instalamos.

Como usar o executor para compilar imagens do Silverblue

1. Como definir as tarefas do pipeline de CI/CD do GitLab

Agora que o executor já foi instalado, configurado e vinculado ao nosso projeto, podemos criar o arquivo GitLab CI que definirá a compilação de imagens. O GitLab oferece muitos exemplos de estrutura de arquivos gitlab-ci.yml para diferentes tipos de projeto. Vamos escrever o nosso próprio arquivo usando o buildah para compilar as imagens do Silverblue.

O arquivo gitlab-ci.yml que usaremos será assim:

stages:
  - build

buildah-build:
  stage: build
  tags:
    - openshift
  image: quay.io/buildah/stable
  variables:
    STORAGE_DRIVER: vfs
  script:
    - export HOME=/tmp
    - buildah login --username "$CI_REGISTRY_USER" --password "$CI_REGISTRY_PASSWORD" "$CI_REGISTRY"
    - buildah build -t "$CI_REGISTRY_IMAGE:latest" .
    - buildah push "$CI_REGISTRY_IMAGE:latest"
    - buildah logout "$CI_REGISTRY"

Há vários elementos importantes a serem considerados nesse arquivo.

Precisamos incluir pelo menos a tag openshift , como mencionado anteriormente, para as tarefas serem selecionadas pelo GitLab Runner Operator.
Estamos usando a imagem estável oficial do Buildah hospedada no Quay.io como nossa imagem de build.
Definimos o driver de armazenamento como vfs devido a problemas com sistemas de arquivos overlay-on-overlay. Usar vfs é a solução mais simples por enquanto.
Alteramos $HOME para /tmp para ser possível gravar, já que a maioria dos sistemas de arquivos de container no OpenShift será somente leitura.

A última seção (⁣script) é uma lista dos comandos que a tarefa de build executará. Aqui, utilizamos as variáveis predefinidas de CI do GitLab para entrar no registro de containers do GitLab, compilar e marcar nossa imagem e, por fim, enviar a imagem para o registro antes de sair.

2. Como gravar o Containerfile da imagem personalizada do Silverblue

Após adicionar o gitlab-ci.yml ao repositório, também precisamos adicionar o Containerfile que queremos compilar. Para nossa imagem personalizada do Fedora Silverblue, contei com o excelente trabalho que está sendo feito na comunidade Universal Blue. Eles têm trabalhado em várias versões do Silverblue para diferentes casos de uso e são um excelente recurso se você ou sua equipe tiverem interesse em criar imagens-base imutáveis e personalizadas para sistemas Fedora Red Hat.

Achei que seria útil criar uma imagem base que incluísse as versões mais recentes de todas as ferramentas do OpenShift e do Operator que uso diariamente. Como nossa configuração determina com que o build ocorra todos os dias, minha imagem base não apenas será atualizada com os pacotes mais recentes do Fedora, mas também nunca ficarei sem as versões mais recentes dessas ferramentas do OpenShift e do Operator, que normalmente exigiriam atualizações manuais.

ARG FEDORA_MAJOR_VERSION=38

FROM quay.io/fedora-ostree-desktops/silverblue:${FEDORA_MAJOR_VERSION}
# Starting with Fedora 39, the new official location for these images is quay.io/fedora/fedora-silverblue
# See https://pagure.io/releng/issue/11047 for more information

# Install Openshift tools -- oc, opm, kubectl, operator-sdk, odo, helm, crc from official OpenShift sources
RUN curl -SL https://mirror.openshift.com/pub/openshift-v4/x86_64/clients/ocp/latest/opm-linux.tar.gz | tar xvzf - -C /usr/bin
RUN curl -SL https://mirror.openshift.com/pub/openshift-v4/x86_64/clients/operator-sdk/latest/operator-sdk-linux-x86_64.tar.gz | tar xvzf - --strip-components 2 -C /usr/bin
RUN curl -SL https://mirror.openshift.com/pub/openshift-v4/clients/oc/latest/linux/oc.tar.gz | tar xvzf - -C /usr/bin
RUN curl -SL https://mirror.openshift.com/pub/openshift-v4/x86_64/clients/helm/latest/helm-linux-amd64 -o /usr/bin/helm && chmod +x /usr/bin/helm
RUN curl -SL https://mirror.openshift.com/pub/openshift-v4/x86_64/clients/odo/latest/odo-linux-amd64 -o /usr/bin/odo && chmod +x /usr/bin/odo
RUN curl -SL https://mirror.openshift.com/pub/openshift-v4/x86_64/clients/crc/latest/crc-linux-amd64.tar.xz | tar xfJ - --strip-components 1 -C /usr/bin

# Install awscli
RUN curl -SL https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip -o awscliv2.zip && unzip awscliv2.zip && ./aws/install --bin-dir /usr/bin --install-dir /usr/bin

# Install overrides and additions, remove lingering files
RUN rpm-ostree install podman-docker
RUN rm -rf aws && \
    rm -f awscliv2.zip && \
    rm -f /usr/bin/README.md && \
    rm -f /usr/bin/LICENSE

Uma breve descrição do que está acontecendo nesse Containerfile:

Para começar, especificamos a versão do Fedora que queremos compilar, neste caso, a versão estável atual 38.
Em seguida, especificamos a imagem base a ser usada para a compilação, que é a silverblue:38 após a substituição de FEDORA_MAJOR_VERSION (consulte os comentários no Containerfile sobre o local dessas imagens).
Na maior seção, executamos vários comandos curl para fazer o download de todos os programas do OpenShift que quero instalar, sem esquecer de colocar os binários no diretório /usr/bin .
Também instalamos o awscli , que envolve a descompactação do arquivo .zip e a execução do script de instalação.
Por fim, usamos o rpm-ostree para instalar o podman-docker de dentro dos repositórios de pacotes do Fedora. Basicamente, isso cria um alias de qualquer comando docker para o podman para quem está acostumado a executar o docker. Em seguida, exclua alguns arquivos remanescentes da extração do awscli .

Como já mencionei, para obter mais inspirações de personalização do Silverblue, confira a comunidade Universal Blue. Eu dependi muito do trabalho deles para aprender sobre esse fluxo de trabalho. A comunidade já está trabalhando em várias novas aplicações interessantes do OCI inicializável no Silverblue.

3. Como usar e monitorar as tarefas do pipeline

Precisamos adicionar esse ou qualquer outro Containerfile ou Dockerfile que você prefira compilar, à raiz do repositório do projeto, já que o gitlab-ci.yml especifica que o buildah usa o diretório de trabalho atual como argumento do Containerfile. Dependendo de como você confirmou todas as alterações no repositório, talvez já tenha recebido notificações sobre tarefas do pipeline com falha. Se você estiver confirmando tudo ao mesmo tempo, testemunhará a primeira tentativa de executar a tarefa de build agora. Para conferir os logs do build, vá até a seção CI/CD na página do seu projeto no GitLab.com e clique em Pipelines ou Jobs. Clique em tudo até encontrar a saída de log da tarefa chamada buildah-build.

Se tudo foi configurado corretamente, serão exibidos logs descrevendo cada etapa do gitlab-ci.yml e do Containerfile que criamos, concluindo com "Job succeeded" ao terminar. Se a tarefa for concluída com êxito, também aparecerá o container concluído no registro do projeto. Na barra de navegação à esquerda, clique em Packages and registries e depois em Container Registry. Deverá ser mostrada uma única imagem com o nome do projeto e só a tag "latest". Essa imagem estará localizada em registry.gitlab.com/{SEU_NOME_DE_USUÁRIO}/{NOME_DO_SEU_REPOSITÓRIO}.

A tarefa, da maneira como a escrevemos, será executada com todas as confirmações na ramificação main , mas você pode personalizar esse comportamento no arquivo gitlab-ci.yml . Se quisermos programar build regulares, podemos fazer isso na página do repositório, nas configurações de CI/CD na seção Schedule. Clique em New schedule para configurar o horário e a frequência do seu pipeline. Para mais informações sobre a programação de pipelines no GitLab.com, clique aqui. No caso de uma imagem personalizada do Silverblue, o usual é fazer builds diários para acompanhar a cadência de build das imagens oficiais.

Como usar as imagens personalizadas

Para usar essa imagem como uma base inicializável do Silverblue, primeiro você precisa instalar o Fedora Silverblue usando as imagens oficiais, caso não tenha já não esteja instalado. Após instalar e acessas, podemos mudar a base da instalação para a imagem personalizada.

É bom lembrar: a inicialização com imagens OCI ainda é uma funcionalidade experimental. Então, usar isso em máquinas pessoais ou de produção fica a seu critério. Mas o Silverblue foi desenvolvido para ser resiliente a falhas. Portanto, se sua imagem personalizada não funcionar como esperado, é provável que você consiga reverter para a imagem base original. Para ter certeza de que essa base original não será removida, podemos executar sudo ostree admin pin 0 para fixar a imagem atual. Isso garante que a referência não seja perdida nas próximas atualizações, já que o Silverblue normalmente só mantém as referências das imagens atual e anterior. Para alterar a base para a imagem personalizada, executamos este comando:

rpm-ostree rebase ostree-unverified-registry:registry.gitlab.com/{YOUR_USERNAME}/{YOUR_REPOSITORY_NAME}:latest

Reinicialize em seguida.

Após a reinicialização, podemos verificar se estamos executando a imagem personalizada na saída de rpm-ostree status. Sua implantação atual, identificada pelo círculo/pip no lado esquerdo, deve mostrar o URI de ostree-unverified-registry da imagem personalizada. Você também pode tentar executar qualquer uma das ferramentas do OpenShift que adicionamos em um terminal, como oc, operator-sdk ou helm.

A implantação fixa com a referência da base antiga aparece na saída de rpm-ostree status. Se quiser reverter, basta executar rpm-ostree rollback e reinicializar. Para mais informações sobre a administração do Fedora Silverblue, consulte a documentação.

Resultados

Se tudo ocorreu sem problemas, agora temos um pipeline de CI/CD auto-hospedado em execução no nosso próprio cluster do OpenShift que cria novas imagens personalizadas do Silverblue em intervalos regulares. Os executores não precisam de intervenção manual, a menos que você queira reconfigurar as tags de tarefa de build ou criar mais executores para processar mais tarefas simultâneas. Os builds serão iniciados nos intervalos programados e quando um novo código for confirmado na ramificação main . Se você estiver executando a imagem personalizada em uma instalação do Silverblue, basta executar rpm-ostree update para receber as atualizações diárias.

Este tutorial usou um exemplo simples para mostrar os recursos do GitLab Runner Operator e do sistema de CI/CD do GitLab. Ambos podem ser usados para gerenciar necessidades de CI/CD muito mais sofisticadas. Ao executar o Certified GitLab Runner Operator no OpenShift, você pode eliminar grande parte do trabalho manual de configuração e manutenção dos executores e dedicar mais tempo e esforço ao conteúdo e à configuração de seus builds.

Criei aqui um repositório de referência com todos os arquivos de texto usados neste tutorial. E aqui está uma lista de referências úteis: