Guida all'operatore GitLab Runners su OpenShift

Poiché consentono agli sviluppatori di creare, testare e distribuire le modifiche al codice in modo rapido ed efficiente, le pipeline di integrazione e deployment continui (CI/CD) sono diventate una parte fondamentale del moderno sviluppo del software. Automatizzando il processo di creazione e deployment delle applicazioni, le pipeline CI/CD possono aiutare i team a migliorare la qualità del codice, a ridurre gli errori e ad accelerare i tempi di rilascio di nuove funzionalità e applicazioni.

Con GitLab Runner indichiamo quelle applicazioni che elaborano i processi CI/CD su GitLab.com e nelle istanze GitLab in self-hosting. GitLab.com rende disponibili i propri runner in hosting, condividendoli con gli utenti del sito, ma tramite diversi tipi di installazione puoi anche impostare runner privati dedicati per i tuoi progetti. Per le aziende o i privati che desiderano gestire la propria infrastruttura di pipeline nel cloud, l'operatore GitLab Runner, disponibile come operatore Red Hat certificato in OpenShift, offre un'installazione cloud native rapida e semplice.

Per dimostrare la semplicità e le funzionalità dell'operatore GitLab Runner, ho pensato che sarebbe stato interessante evidenziare anche alcuni utili sviluppi di Fedora Linux e utilizzare GitLab Runner per creare immagini di base personalizzate per Fedora Silverblue.

Fedora Silverblue è una distribuzione immutabile e all'avanguardia di Fedora Linux. Da poco, il suo sistema ibrido di gestione delle immagini e dei pacchetti rpm-ostree è in grado di eseguire l'avvio dai container OCI. Ciò consente agli utenti o alle aziende di creare immagini di base personalizzate con i flussi di lavoro noti come Dockerfile e Containerfile.

Nel tutorial che segue, utilizzeremo l'operatore GitLab Runner per impostare un sistema di creazione completamente automatizzato per le nostre immagini Fedora Silverblue.

Prerequisiti

Alcune risorse che non tratteremo nel tutorial dovranno essere configurate e installate prima di iniziare:

• Un cluster OpenShift
• Un'installazione di Fedora Silverblue esistente (se vuoi effettivamente utilizzare le immagini personalizzate)
• Un account GitLab.com

Installazione e configurazione dell'operatore GitLab Runner

Apri l'intestazione Operators nella barra laterale del cluster OpenShift e fai clic su OperatorHub. Individua l'operatore GitLab Runner e fai clic sull'opzione Certified (è disponibile anche la versione Community dell'operatore, ma questo tutorial utilizza la variante Certified on OpenShift). Prima di fare clic su Install, controlla la sezione Prerequisites della descrizione dell'operatore. Per l'operatore GitLab Runner è innanzitutto necessario installare cert-manager:

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

A questo punto, fai clic su Install per installare l'operatore GitLab Runner.

Nella schermata successiva ti verrà chiesto di modificare le opzioni di installazione predefinite. Se hai bisogno o ti interessa applicare l'ambito a uno spazio dei nomi specifico, devi farlo in questa fase; in caso contrario, continua con le opzioni predefinite. Suggerisco inoltre di lasciare l'opzione Update approval impostata su Automatic poiché questo è uno dei principali vantaggi dell'utilizzo di un operatore.

Attendi il completamento dell'installazione, quindi passa a Installed Operators e poi all'operatore GitLab Runner. Visualizzerai lo stesso testo informativo precedente, oltre a un link in Provided APIs dove puoi creare un'istanza Runner. Nel testo informativo seguente sono riportate le istruzioni che seguiremo per collegare i tuoi Runner ai repository GitLab.

Creazione e registrazione dell'istanza Runner

1. Creazione del token di registrazione Secret

Innanzitutto, è necessario creare un segreto con un token di registrazione di GitLab che verrà utilizzato dalla nuova istanza Runner per registrarsi al repository. Apri GitLab.com o la tua istanza GitLab privata e quindi il repository che intendi registrare. Passa a Provided APIs, quindi a CI/CD. Espandi la sezione Runners e poi passa alla sezione Project runners. Qui trovi il token di registrazione e l'URL da utilizzare per registrare la tua istanza di Runner.

Se utilizzi GitLab.com, consulta anche la sezione Shared runners, che contiene i runner pubblici forniti da GitLab.com. Per questo progetto disattiva i runner condivisi, poiché utilizzeremo i nostri runner privati.

Crea il tuo segreto inserendo il token di registrazione del repository nel campo runner-registration-token . Puoi procedere nella web console o tramite l'interfaccia del terminale. Ho creato un file denominato gitlab-runner-secret.yml e l'ho aggiunto al mio 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. Configurazione del runner con una ConfigMap

Prima di creare il nostro runner, occorre anche creare una ConfigMap con alcune opzioni di personalizzazione. In genere, è possibile configurare i GitLab Runner tramite un file config.toml . In un contesto Kubernetes possiamo aggiungere le personalizzazioni tramite una ConfigMap che contiene il file config.toml.

Poiché i nostri container di build sono utilizzati nell'ambiente di un cluster OpenShift, dobbiamo verificare che vengano eseguiti senza un'escalation dei privilegi e come utente non root (nota: puoi evitare questo limite se effettivamente ti occorre un ambiente di compilazione con privilegi, ma per il nostro esempio ci atteniamo a una configurazione non root). Ecco un semplice file config.toml che specifica che il pod runner viene eseguito come utente non root 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

Per aggiungerlo al nostro cluster come ConfigMap:

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

3. Avvio dell'istanza Runner

A questo punto creiamo la nostra istanza Runner effettiva. Anche in questo caso, puoi utilizzare la web console facendo clic su Create instance nella pagina dell'operatore GitLab Runner, oppure utilizzare il terminale. In ogni caso, dobbiamo verificare che la nostra definizione di risorsa personalizzata (CRD) includa l'URL GitLab corretto, il nome del token di registrazione Secret, il nome della ConfigMap e che i tag contengano "openshift" (l'elemento "openshift" è necessario per trasmettere i processi al cluster). Di seguito è riportata una CRD di base denominata gitlab-runner.yml che soddisfa tutti i nostri criteri:

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

Per installarla nel nostro cluster:

oc apply -f gitlab-runner.yml

A questo punto puoi controllare lo stato del tuo nuovo runner nella web console o tramite il terminale con oc get runners. È bene verificare anche le impostazioni CI/CD del nostro progetto GitLab per assicurarci che il runner sia correttamente collegato al repository. Sotto l'intestazione Assigned project runners dovrebbe essere visualizzato un runner con lo stesso nome della CRD che abbiamo creato e installato.

Utilizzo del Runner per creare immagini Silverblue

1. Definizione dei processi della pipeline CI/CD di GitLab

Dopo aver installato, configurato e collegato il runner al progetto, possiamo scrivere il file GitLab CI che definirà la versione dell'immagine. GitLab fornisce molti esempi della struttura del file gitlab-ci.yml per diversi tipi di progetto. Ne scriveremo una nostra, utilizzando buildah per creare le immagini Silverblue.

ll file  gitlab-ci.yml che utilizzeremo è simile al seguente:

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"

Questo codice contiene diversi elementi importanti.

• È necessario includere almeno il tag openshift, come accennato in precedenza, affinché i processi possano essere selezionati dall'operatore GitLab Runner.
• Come immagine della build utilizziamo l'immagine Buildah stabile e ufficiale in hosting su Quay.io.
• Il driver di storage è impostato su vfs a causa di problemi con i file system overlay su overlay. Al momento, l'utilizzo di vfs è la soluzione più semplice.
• Cambiamo $HOME in /tmp per essere certi di poter utilizzare la modalità di scrittura, perché la maggior parte dei file system container in OpenShift è di sola lettura.

L'ultima sezione, script, include un elenco dei comandi che verranno eseguiti dal processo di creazione. Qui utilizziamo le variabili predefinite di GitLab CI per accedere al registro dei container GitLab, creare e taggare l'immagine e infine inviare l'immagine al registro prima di eseguire il logout.

2. Scrittura del Containerfile per l'immagine Silverblue personalizzata

Dopo aver aggiunto gitlab-ci.yml al repository, dobbiamo aggiungere anche il Containerfile che vogliamo creare. Per l'immagine personalizzata di Fedora Silverblue, ho fatto affidamento sull'ottimo lavoro svolto dalla community Universal Blue, che ha operato su varie versioni di Silverblue per diversi scenari di utilizzo. Sono una risorsa eccellente se tu o il tuo team siete interessati a creare immagini di base personalizzate e immutabili per i sistemi Fedora Silverblue.

Ho pensato che sarebbe stato utile creare un'immagine di base che includesse le versioni più recenti di tutti gli strumenti OpenShift e Operator che utilizzo quotidianamente. Poiché verrà impostata in modo che venga compilata quotidianamente, la mia immagine di base non solo verrà aggiornata con i pacchetti Fedora più recenti, ma non perderò nessuna delle ultime versioni di questi strumenti che normalmente richiedono l'aggiornamento manuale.

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

Esaminiamo in breve ciò che accade in questo Containerfile:

• Per iniziare, specifichiamo la versione di Fedora da creare, in questo caso l'attuale versione stabile 38.
• Quindi, specifichiamo l'immagine di base da utilizzare per la nostra build, ovvero silverblue:38 dopo la sostituzione con FEDORA_MAJOR_VERSION (consulta i commenti nel Containerfile sulla posizione di queste immagini).
• Nella sezione più estesa eseguiamo diversi comandi curl per scaricare tutti i programmi OpenShift che vogliamo installare, assicurandoci di inserire i relativi file binari nella directory /usr/bin.
• Installiamo anche awscli , che comporta la decompressione del file .zip e l'esecuzione dello script di installazione.
• Infine, usiamo rpm-ostree per installare podman-docker dai repository dei pacchetti Fedora (sostanzialmente, così viene creato l'alias di tutti i comandi  docker  in podman per chi è abituato a eseguire docker), quindi eliminiamo alcuni file in sospeso dall'estrazione awscli.

Come accennato in precedenza, per approfondimenti sulla personalizzazione di Silverblue, visita la community all'indirizzo Universal Blue. Ho utilizzato pienamente il loro lavoro per studiare questo flusso di lavoro e so che sono già al lavoro su molte nuove applicazioni interessanti della funzionalità OCI avviabile in Silverblue.

3. Utilizzo e monitoraggio dei processi della pipeline

È necessario aggiungere questo Containerfile, o qualsiasi altro Containerfile o Dockerfile da creare, alla radice del repository del progetto, poiché il nostro gitlab-ci.yml specifica che buildah utilizza la directory di lavoro corrente come argomento Containerfile. In base a come hai eseguito il commit di tutte le modifiche in questo repository, potresti aver già ricevuto notifiche sui processi della pipeline non riusciti oppure, se invece esegui il commit di tutte le modifiche in una sola volta, vedrai avviarsi il primo tentativo di esecuzione del processo di creazione. Per controllare i log della tua build accedi all'intestazione CI/CD nella pagina del progetto GitLab.com, quindi fai clic su Pipelines o Jobs e poi fai clic fino a visualizzare l'output del log relativo al processo denominato buildah-build.

Se tutte le impostazioni sono corrette, dovresti vedere i log che descrivono ogni passaggio del file gitlab-ci.yml e del Containerfile che abbiamo scritto, e al termine, il messaggio "Job succeeded". Se il processo si conclude correttamente, dovremmo anche essere in grado di vedere il container completato nel registro dei progetti. Nella barra di navigazione a sinistra, fai clic su Packages and registers e poi su Container Registry. Dovrebbe essere visibile una singola immagine con il nome del progetto e un singolo tag "latest". Questa immagine si troverà all'indirizzo register.gitlab.com/{YOUR_USERNAME}/{YOUR_REPOSITORY_NAME}.

Il processo, così come è stato scritto, verrà eseguito con ogni commit nella diramazione main , ma puoi personalizzare questo comportamento nel file gitlab-ci.yml. Per pianificare la creazione regolare delle build, utilizza la pagina del repository nelle impostazioni CI/CD nella sezione Schedule. Fai clic su New schedule per configurare i tempi e la frequenza della pipeline. Scopri di più sulla pianificazione della pipeline GitLab.com qui. Per un'immagine Silverblue personalizzata, probabilmente ti servirà una creazione almeno quotidiana, che corrisponda alla cadenza di creazione delle immagini ufficiali.

Utilizzo delle immagini personalizzate

Per utilizzare questa immagine come base di avvio per Silverblue, è innanzitutto necessario installare Fedora Silverblue dalle immagini ufficiali se non disponi di un'installazione esistente. Al termine dell'installazione e dopo aver effettuato l'accesso, possiamo avviare il rebasing dell'installazione utilizzando la nostra immagine personalizzata.

Tieni presente che l'avvio da immagini OCI è ancora una funzionalità sperimentale, quindi presta particolare attenzione se devi utilizzarla su macchine personali o sistemi di produzione. Silverblue è progettato per essere resiliente a eventuali malfunzionamenti, quindi se l'immagine personalizzata non funziona come previsto, potrai ripristinare l'immagine di base originale. Accertati tuttavia di non rimuovere la base originale, eseguendo il comando sudo ostree admin pin 0 che blocca l'immagine corrente. In questo modo il riferimento non va perso con gli aggiornamenti successivi, poiché di norma Silverblue conserva solo i riferimenti alle immagini correnti e precedenti. Per avviare il rebasing all'immagine personalizzata, eseguiamo:

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

e quindi riavviamo il sistema.

Dopo il riavvio, è possibile verificare l'esecuzione dell'immagine personalizzata osservando l'output di rpm-ostree status. Il deployment corrente, identificato dal circolo sul lato sinistro, visualizza l'URI ostree-unverified-registry dell'immagine personalizzata. Puoi anche provare a eseguire uno degli strumenti OpenShift aggiunti in un terminale, ad esempio oc, operator-sdko helm.

Nell'output di rpm-ostree status, dovresti anche vedere evidenziato il nostro deployment con il riferimento precedente. Per avviare il rollback, esegui rpm-ostree rollback e riavvia. Per ulteriori informazioni sull'amministrazione di Fedora Silverblue, consulta la documentazione.

Risultati

Supponendo che tutto sia andato come previsto, disponiamo ora di una pipeline CI/CD in self-hosting eseguita sul nostro cluster OpenShift che crea regolarmente nuove immagini Silverblue personalizzate. I nostri runner non dovrebbero richiedere alcun intervento manuale, a meno che non sia necessario riconfigurare i tag dei processi di creazione o creare più runner per gestire più processi simultanei. Le build vengono avviate agli intervalli pianificati e quando eseguiamo il commit del nuovo codice nella diramazione main; se eseguiamo l'immagine personalizzata su un'installazione Silverblue, è sufficiente utilizzare rpm-ostree update per acquisire i nostri aggiornamenti quotidiani.

Questo tutorial illustra in modo semplice le funzionalità dell'operatore GitLab Runner e del sistema CI/CD di GitLab. Entrambi possono gestire esigenze di CI/CD molto più complesse; eseguendo l'operatore certificato GitLab Runner su OpenShift, potrai eliminare gran parte delle attività manuali di configurazione e manutenzione dei runner stessi, e dedicare più tempo ai contenuti e alla configurazione delle build.

 Qui puoi trovare un repository di riferimento con tutti i file di testo utilizzati in questo tutorial. Di seguito un elenco di riferimenti utili.

• Documentazione su GitLab Runners
• Documentazione su Fedora Silverblue
• Operatore GitLab Runner Red Hat Certified
• Universal Blue: immagini del sistema operativo basate su Fedora create dalla community