Ihr Guide für den GitLab Runners-Operator auf OpenShift

CI/CD-Pipelines (Continuous Integration/Continuous Deployment) sind zu einem entscheidenden Bestandteil der modernen Softwareentwicklung geworden, da sie es Entwicklungsteams ermöglichen, Codeänderungen schnell und effizient zu erstellen, zu testen und bereitzustellen. Durch die Automatisierung des Entwicklungs- und Bereitstellungsprozesses von Anwendungen können CI/CD-Pipelines Teams dabei unterstützen, die Codequalität zu verbessern, Fehler zu reduzieren und die Markteinführungszeit für neue Funktionen und Anwendungen zu verkürzen.

GitLab Runners sind Anwendungen, die CI/CD-Jobs auf GitLab.com und selbst gehostete GitLab-Instanzen verarbeiten. GitLab.com bietet eigene gehostete Runners, die von den Nutzenden der Site gemeinsam verwendet werden. Sie können jedoch auch dedizierte private Runners für Ihre Projekte über verschiedene Installationstypen einrichten. Für Unternehmen oder Einzelpersonen, die ihre eigene Pipeline-Infrastruktur in der Cloud verwalten möchten, bietet der GitLab Runner-Operator, der als Red Hat Certified Operator in OpenShift verfügbar ist, eine schnelle und einfache cloudnative Installation von GitLab Runners.

Um die Einfachheit und Funktionalität des GitLab Runner-Operators zu demonstrieren, wollte ich auch einige spannende Entwicklungen in Fedora Linux hervorheben und den GitLab Runner-Operator verwenden, um benutzerdefinierte Basis-Images für Fedora Silverblue zu erstellen.

Fedora Silverblue ist eine hochmoderne, unveränderliche Distribution von Fedora Linux. Seit kurzem ist das Hybrid Image- und Paketverwaltungssystem rpm-ostree in der Lage, aus OCI-Containern zu starten. So können Nutzende oder Unternehmen ihre eigenen benutzerdefinierten Basis-Images mit dem vertrauten Workflow von Dockerfiles und Containerfiles erstellen.

Im folgenden Tutorial richten wir mit dem GitLab Runner-Operator ein vollständig automatisiertes Build-System für unsere Fedora Silverblue-Images ein.

Voraussetzungen

Sie benötigen einige zuvor konfigurierte und installierte Ressourcen, die im Tutorial nicht behandelt werden:

• Ein OpenShift Cluster
• Eine vorhandene Fedora Silverblue-Installation (wenn Sie die benutzerdefinierten Images verwenden möchten)
• Ein GitLab.com-Konto

Installieren und Konfigurieren des GitLab Runner-Operators

Öffnen Sie die Rubrik für Operatoren in der Seitenleiste Ihres OpenShift Clusters, und klicken Sie auf OperatorHub. Suchen Sie nach dem GitLab Runner-Operator, und klicken Sie auf die Option „Certified“ (die Community-Version des Operators ist ebenfalls verfügbar, aber in diesem Tutorial wird die „Certified“-Variante in OpenShift verwendet). Beachten Sie den Abschnitt mit den Voraussetzungen in der Beschreibung des Operators, bevor Sie auf Install klicken. Für den GitLab Runner-Operator müssen Sie zuerst cert-manager installieren:

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

Klicken Sie anschließend auf Install , um den GitLab Runner-Operator zu installieren.

Auf dem nächsten Bildschirm werden Sie aufgefordert, die Standardinstallationsoptionen zu ändern. Wenn Sie einen bestimmten Namespace benötigen oder erweitern möchten, sollten Sie dies jetzt tun. Andernfalls fahren Sie mit den Standardoptionen fort. Ich schlage außerdem vor, Update approval auf Automatic festgelegt zu lassen, da dies ein wichtiger Vorteil der Verwendung eines Operators ist.

Warten Sie einen Moment, bis die Installation abgeschlossen ist, und navigieren Sie dann zu Installed Operators und dann zum GitLab Runner-Operator. Hier sehen Sie den gleichen Infotext wie zuvor sowie einen Link unter Provided APIs , über den Sie eine Runner-Instanz erstellen können. Im folgenden Infotext finden Sie Anweisungen zum Verknüpfen Ihrer Runners mit Ihren GitLab-Repositories, die wir nun befolgen.

Erstellen und Registrieren unserer Runner-Instanz

1. Erstellen des Registrierungstoken Secret

Zuerst müssen wir ein Secret mit einem Registrierungstoken von GitLab erstellen, das unser neuer Runner verwendet, um sich bei unserem Repository zu registrieren. Öffnen Sie GitLab.com oder Ihre private GitLab-Instanz, und öffnen Sie dann das Repository, das Sie registrieren möchten. Navigieren Sie zu „Settings“ und dann zu „CI/CD“. Erweitern Sie den Abschnitt mit dem Titel Runners , und sehen Sie sich dann den Abschnitt Project runners an. Hier finden Sie unser Registrierungstoken und die URL, mit der Sie Ihre Runner-Instanz registrieren.

Beachten Sie auch den Abschnitt Shared Runners , wenn Sie GitLab.com verwenden. Dies sind öffentliche Runners, die von GitLab.com bereitgestellt werden. Deaktivieren Sie die gemeinsam genutzten Runners für dieses Projekt, da wir unsere eigenen privaten Runners verwenden.

Erstellen Sie Ihr Secret, und fügen Sie das Registrierungstoken Ihres Repositorys in das Feld runner-registration-token  ein. Sie können diesen Vorgang in der Webkonsole oder über die Terminalschnittstelle durchführen. Ich habe eine Datei mit dem Namen gitlab-runner-secret.yml erstellt und sie dann zu meinem Cluster hinzugefügt:

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. Konfigurieren des Runners mit einer ConfigMap

Bevor wir unseren Runner erstellen, müssen wir auch eine ConfigMap mit einigen Anpassungsoptionen erstellen. GitLab-Runners können normalerweise mit einer config.toml -Datei konfiguriert werden. In einem Kubernetes-Kontext können wir diese Anpassungen mit einer ConfigMap hinzufügen, die unsere config.toml -Datei enthält.

Da wir unsere Build-Container in der Umgebung eines OpenShift Clusters ausführen, müssen wir sicherstellen, dass die Build-Container ohne erweiterte Berechtigungen und als Nicht-Root-Benutzer ausgeführt werden (Hinweis: Es gibt Möglichkeiten, dies zu umgehen, wenn Sie sicher sind, dass Sie eine privilegierte Build-Umgebung benötigen, aber wir bleiben bei einem Nicht-Root-Setup). Hier ist eine einfache config.toml , die angibt, dass der Runner-Pod als Nicht-Root-Benutzer 1000 ausgeführt wird:

[[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

So fügen Sie dies zu unserem Cluster als ConfigMap hinzu:

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

3. Starten der Runner-Instanz

Jetzt können wir unsere eigentliche Runner-Instanz erstellen. Auch hier können Sie dies über die Webkonsole tun, indem Sie auf der Seite des GitLab Runner-Operators auf Create instance klicken, oder über das Terminal. In beiden Fällen möchten wir sicherstellen, dass unsere benutzerdefinierte Ressourcendefinition (CRD) die richtige GitLab-URL, den Namen unseres Registrierungstoken-Secret, den Namen unserer ConfigMap und „openshift“ in den Tags enthält (dieses „openshift"-Tag ist erforderlich, damit Jobs an Ihren Cluster weitergeleitet werden). Hier ist eine einfache CRD mit dem Namen gitlab-runner.yml , die alle unsere Kriterien erfüllt:

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

So installieren Sie es in unserem Cluster:

oc apply -f gitlab-runner.yml

Sie können jetzt den Status des neuen Runners in der Webkonsole oder über das Terminal mit oc get runners überprüfen. Wir sollten auch die CI/CD-Einstellungen unseres GitLab-Projekts überprüfen, um sicherzustellen, dass der Runner ordnungsgemäß mit unserem Repository verknüpft ist. Unter der Rubrik Assigned project runners sollte nun ein Runner mit dem gleichen Namen wie die von uns erstellte und installierte CRD angezeigt werden.

Verwenden unseres Runners zum Erstellen von Silverblue-Images

1. Definieren der GitLab-CI/CD-Pipeline-Jobs

Nachdem unser Runner nun installiert, konfiguriert und mit unserem Projekt verknüpft ist, können wir die GitLab-CI -Datei erstellen, die unseren Image-Build definiert. GitLab bietet viele Beispiele der Dateistruktur gitlab-ci.yml für verschiedene Projekttypen. Wir schreiben unsere eigenen und verwenden buildah , um unsere Silverblue-Images zu erstellen.

Die verwendete Datei gitlab-ci.yml sieht wie folgt aus:

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"

Diese Datei enthält mehrere wichtige Elemente, die zu beachten sind.

• Wir müssen, wie bereits erwähnt, mindestens das Tag openshift einschließen, damit unsere Jobs vom GitLab Runner-Operator übernommen werden.
• Wir verwenden das offizielle stabile Buildah-Image, das in Quay.io gehostet wird, als Build Image.
• Wir haben den Storage-Treiber aufgrund von Problemen mit Overlay on Overlay-Dateisystemen auf vfs festgelegt. Die Verwendung von vfs ist derzeit die einfachste Lösung.
• Wir ändern $HOME in /tmp , um Schreibzugriff sicherzustellen, da die meisten Container-Dateisysteme in OpenShift schreibgeschützt sind.

Der letzte Abschnitt script ist eine Liste der Befehle, die unser Build-Job ausführen wird. Hier verwenden wir die  vordefinierten Variablen von GitLab CI, um uns bei der GitLab Container Registry anzumelden, unser Image zu erstellen und zu taggen und schließlich das Image an die Registry zu übertragen, bevor wir uns abmelden.

2. Schreiben des Containerfiles für unser benutzerdefiniertes Silverblue-Image

Nachdem wir unserem Repository die Datei gitlab-ci.yml hinzugefügt haben, müssen wir auch das Containerfile hinzufügen, das wir erstellen möchten. Bei unserem benutzerdefinierten Fedora Silverblue-Image habe ich mich auf die großartige Arbeit der Universal Blue -Community verlassen. Sie haben an verschiedenen Versionen von Silverblue für unterschiedliche Use Cases gearbeitet und sind eine hervorragende Ressource, wenn Sie oder Ihr Team daran interessiert sind, angepasste, unveränderliche Basis-Images für Fedora Silverblue-Systeme zu erstellen.

Ich dachte, es wäre hilfreich, ein Basis-Image zu erstellen, das die neuesten Versionen aller OpenShift- und Operator-Tools enthält, die ich täglich verwende. Da wir dies so einstellen, dass es täglich erstellt wird, wird nicht nur mein Basis-Image mit den aktuellen Fedora-Paketen aktualisiert, sondern ich gerate auch nie in Verzug hinsichtlich der neuesten Versionen dieser OpenShift- und Operator-Tools, die normalerweise manuelle Aktualisierungen erfordern würden.

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

Hier eine kurze Aufschlüsselung der Vorgänge in diesem Containerfile:

• Zunächst geben wir die Version von Fedora an, die wir erstellen möchten, in diesem Fall die aktuelle stabile Version 38.
• Als Nächstes geben wir das Basis-Image an, das für unseren Build verwendet werden soll, das nach unserer FEDORA_MAJOR_VERSION -Ersetzung silverblue:38 ist (siehe die Kommentare im Containerfile zum Speicherort dieser Images).
• Im größten Abschnitt führen wir mehrere curl -Befehle aus, um alle OpenShift-Programme, die ich installieren möchte, herunterzuladen, und stellen dabei sicher, dass die Binärdateien im Verzeichnis /usr/bin abgelegt werden.
• Wir installieren auch awscli . Dies beinhaltet das Entpacken der .zip-Datei und das Ausführen des Installationsskripts.
• Schließlich verwenden wir rpm-ostree , um podman-docker aus den Fedora-Paket-Repositories zu installieren (dies verwendet im Grunde einen Alias aller docker -Befehle für podman für diejenigen von uns, die gewöhnlich dockerausführen), und löschen dann veraltete Dateien aus der awscli -Extrahierung.

Wie bereits erwähnt, finden Sie weitere Anregungen zur Anpassung von Silverblue in der Community bei Universal Blue. Ich habe mich beim Erlernen dieses Workflows stark auf ihre Arbeit verlassen. Sie arbeiten bereits an vielen neuen interessanten Anwendungen der startfähigen OCI-Funktion in Silverblue.

3. Verwenden und Überwachen der Pipeline-Jobs

Wir sollten dieses Containerfile, oder ein Containerfile oder Dockerfile, das Sie lieber erstellen möchten, zur Root unseres Projekt-Repositorys hinzufügen, da unsere gitlab-ci.yml angibt, dass buildah das aktuelle Arbeitsverzeichnis als Containerfile-Argument verwendet. Je nachdem, wie Sie die Änderungen in diesem Repository festgeschrieben haben, haben Sie möglicherweise bereits Benachrichtigungen über fehlgeschlagene Pipeline-Jobs erhalten. Falls Sie alle Änderungen auf einmal festschreiben, sehen Sie, dass der erste Versuch zur Ausführung des Build-Jobs jetzt startet. Sie können die Protokolle für Ihren Build anzeigen, indem Sie auf Ihrer GitLab.com-Projektseite zur Rubrik CI/CD navigieren und dann entweder auf Pipelines oder auf Jobs klicken und sich durchklicken, bis das Protokoll für den Job namens buildah-build angezeigt wird.

Wenn wir alles richtig eingerichtet haben, sollten Protokolle angezeigt werden, die die einzelnen Schritte der von uns erstellten Datei gitlab-ci.yml und Containerfile beschreiben und am Ende mit „Job succeeded“ abgeschlossen werden. War unser Job erfolgreich, sollte der fertige Container auch in unserer Projekt-Registry angezeigt werden. Klicken Sie in der linken Navigationsleiste auf Packages and registries und dann auf Container Registry. Es sollte ein einzelnes Image angezeigt werden, das nach Ihrem Projekt benannt ist und das einzelne Tag „latest“ aufweist. Dieses Image befindet sich unter registry.gitlab.com/{YOUR_USERNAME}/{YOUR_REPOSITORY_NAME}.

Der Job, wie wir ihn erstellt haben, wird mit jedem Commit in der Verzweigung main ausgeführt, aber Sie können dieses Verhalten in der Datei gitlab-ci.yml anpassen. Regelmäßige Builds können wir auf unserer Repository-Seite in den CI/CD-Einstellungen im Abschnitt Schedule planen. Klicken Sie auf New schedule , um den Zeitpunkt und die Häufigkeit Ihrer Pipeline zu konfigurieren. Weitere Informationen zur Planung der GitLab.com-Pipeline finden Sie hier. Für ein benutzerdefiniertes Silverblue-Image sollten Sie wahrscheinlich mindestens täglich einstellen, um der Build-Kadenz der offiziellen Images zu entsprechen.

Verwenden unserer benutzerdefinierten Images

Um dieses Image als startfähige Basis für Silverblue zu verwenden, müssen Sie zunächst Fedora Silverblue über die offiziellen Images installieren, falls Sie diese Installation noch nicht durchgeführt haben. Nachdem Sie die Installation abgeschlossen und sich angemeldet haben, können wir unsere Installation auf unser benutzerdefiniertes Image umstellen.

Beachten Sie, dass das Starten von OCI-Images noch eine experimentelle Funktion ist. Die Verwendung dieser Funktion auf persönlichen oder Produktionsrechnern liegt daher in Ihrem eigenen Ermessen. Silverblue ist jedoch so konzipiert, dass es gegen Ausfälle geschützt ist. Funktioniert Ihr benutzerdefiniertes Image nicht wie erwartet, sollten Sie ein Rollback auf das ursprüngliche Basis-Image durchführen können. Um sicherzustellen, dass wir diese ursprüngliche Basis nicht entfernen, können wir sudo ostree admin pin 0 ausführen, um das aktuelle Image anzupinnen. So wird sichergestellt, dass der Verweis bei nachfolgenden Aktualisierungen nicht verloren geht, da Silverblue normalerweise nur die aktuellen und vorherigen Image-Verweise beibehält. Um tatsächlich ein Umstellen auf unser benutzerdefiniertes Image durchzuführen, führen wir folgenden Befehl aus:

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

und führen anschließend einen Neustart aus.

Nach dem Neustart können wir überprüfen, ob das benutzerdefinierte Image ausgeführt wird, indem wir uns die Ausgabe von rpm-ostree status ansehen. In Ihrem aktuellen Deployment, durch den Kreis/Punkt auf der linken Seite gekennzeichnet, sollte die URI ostree-unverified-registry unseres benutzerdefinierten Images angezeigt werden. Sie können auch versuchen, eines der von uns hinzugefügten OpenShift-Tools in einem Terminal auszuführen, wie oc, operator-sdk oder helm.

Außerdem sollte unser angepinntes Deployment mit der alten Basisreferenz in der Ausgabe von rpm-ostree status angezeigt werden. Wenn Sie ein Rollback durchführen möchten, führen Sie einfach rpm-ostree rollback aus, und starten Sie neu. Weitere Informationen zur Fedora Silverblue-Administration finden Sie in der Dokumentation.

Ergebnisse

Unter der Annahme, dass alles reibungslos verläuft, haben wir jetzt eine selbst gehostete CI/CD-Pipeline, die auf unserem eigenen OpenShift Cluster ausgeführt wird und regelmäßig neue benutzerdefinierte Silverblue-Images erstellt. Unsere Runners sollten keinen manuellen Eingriff erfordern, es sei denn, wir möchten Build-Job-Tags neu konfigurieren oder weitere Runners erstellen, um mehr gleichzeitige Jobs zu bewältigen. Builds werden zu den von uns geplanten Intervallen gestartet, wenn wir neuen Code in der Verzweigung main festschreiben. Wenn wir unser benutzerdefiniertes Image in einer Silverblue-Installation ausführen, müssen wir lediglich rpm-ostree update ausführen, um unsere täglichen Updates abzurufen.

Dieses Tutorial-Beispiel veranschaulicht die Funktionen des GitLab Runner-Operators und des GitLab CI/CD-Systems. Beide sind in der Lage, weitaus anspruchsvollere CI/CD-Anforderungen zu erfüllen. Durch den Einsatz des zertifizierten GitLab Runner-Operators auf OpenShift können Sie einen Großteil der manuellen Einrichtung und Wartung der Runners selbst einsparen und so Zeit und Mühe für die eigentlichen Inhalte und Konfiguration Ihrer Builds aufwenden.

Ich habe ein Referenz-Repository mit allen in diesem Tutorial verwendeten Textdateien hier erstellt. Bitte beachten Sie dazu die Liste mit hilfreichen Referenzen.

• Dokumentation zu GitLab Runners
• Dokumentation zu Fedora Silverblue
• Red Hat Certified GitLab Runner-Operator
• Universal Blue: Von der Community entwickelte Betriebssystem-Images auf Basis von Fedora