1. Einführung

In diesem Projekt richten wir eine CI/CD-Pipeline mit GitHub Actions ein, um ein Quarkus-Projekt automatisiert zu bauen, zu testen und auf einer Kubernetes-Umgebung (K8s) unserer Schule bereitzustellen. Die Pipeline ermöglicht eine nahtlose Bereitstellung und stellt sicher, dass jede Änderung zuverlässig und ohne manuelle Eingriffe auf die Cloud gelangt.

1.1. Voraussetzungen

Bevor du loslegst, benötigst du:

  • Grundkenntnisse in GitHub Actions, Docker und Kubernetes.

  • Zugriff auf ein Quarkus-Projekt-Repository in GitHub.

  • Rechte ein Package erstellen, bearbeiten und auf "public" stellen zu können.

  • Zugang zur Leocloud mit den nötigen Zugriffsrechten und Konfigurationen.

2. Dockerfile Setup für die GitHub Actions Pipeline

Im build.yaml werden Umgebungsvariablen verwendet, um das Dockerfile korrekt zu referenzieren und zu positionieren. Hier erfährst du, wie das Dockerfile so konfiguriert wird, dass es in der Pipeline erfolgreich eingesetzt werden kann.

# Umgebungsvariablen im build.yaml
env:
  DOCKERFILE_LOCATION: './src/main/docker/Dockerfile'      # Ursprünglicher Speicherort des Dockerfiles
  DOCKERFILE_LOCATION_NEW: './vehicle/target/'             # Zielort für das Dockerfile im Build

2.1. Schritte zum Einrichten und Kopieren des Dockerfiles

  1. Definieren der Dockerfile-Positionen In der build.yaml sind zwei zentrale Umgebungsvariablen für das Dockerfile definiert:

    • DOCKERFILE_LOCATION: Der Quellort des Dockerfiles, in dem es ursprünglich liegt.

    • DOCKERFILE_LOCATION_NEW: Der Zielort, an den das Dockerfile kopiert wird.

  2. Kopieren des Dockerfiles in das Zielverzeichnis Während des Build-Schrittes wird das Dockerfile mit cp von ${{ env.DOCKERFILE_LOCATION }} zu ${{ env.DOCKERFILE_LOCATION_NEW }} kopiert. Dadurch liegt das Dockerfile in demselben Ordner wie das generierte *-runner.jar, was für den Docker-Build entscheidend ist.

  3. Verwendung des Dockerfiles im Docker-Build Im Schritt für das Erstellen und Veröffentlichen des Docker-Images wird DOCKERFILE_LOCATION_NEW als Verzeichnis für den Docker-Build verwendet. Hierdurch kann der Build-Prozess das Dockerfile direkt im Zielverzeichnis referenzieren.

Beispiel für den maven-Schritt, der das Kopieren ausführt:

3. Leocloud Setup

Für dieses Projekt ist der Zugriff auf die Leocloud-Umgebung erforderlich, um die Kubernetes-Deployment-Funktionen nutzen zu können. Bitte folge den Anweisungen im offiziellen Benutzerhandbuch, um die Leocloud korrekt einzurichten:

Link zur Anleitung: https://cloud.htl-leonding.ac.at/

3.1. Schritte zur Einrichtung

  1. Zugang zur Leocloud Öffne die Anleitung und folge den Schritten zur Registrierung und Anmeldung, falls du noch keinen Account hast.

  2. Grundlegende Einrichtung Befolge die Schritte zur Installation und Konfiguration der notwendigen Tools für den Zugriff auf die Leocloud. Stelle sicher, dass du über die entsprechenden Rechte und die Konfiguration für den Zugriff auf die Kubernetes-Umgebung verfügst.

  3. Verbindungstest Teste, ob die Verbindung zur Leocloud erfolgreich hergestellt werden kann, indem du die in der Anleitung beschriebenen Schritte ausführst.

Nach Abschluss dieser Einrichtung solltest du die Leocloud vollständig nutzen können, um Deployments im Rahmen des Projekts durchzuführen. Vergewissere dich, dass die kubectl Konfigurationsdatei die korrekten Werte enthält. Du kannst dies überprüfen, indem du den Befehl kubectl config view ausführst.

3.2. Einmaliges Starten des Kubernetes Deployments auf Leocloud

Um das Kubernetes Deployment auf Leocloud erfolgreich einzurichten, musst du das Deployment einmal manuell starten. Die GitHub Actions sind so konfiguriert, dass sie nur ein vorhandenes Deployment mit dem neuen Image neu starten. Hier sind die Schritte, um das initiale Deployment durchzuführen:

  • Leocloud Authentifizierung

Melde dich bei Leocloud an:
leocloud auth login

  • Maven Projekt bauen

Baue das Projekt und bereite das Dockerfile vor:
mvn clean package
cp src/main/docker/Dockerfile target

  • Docker Image erstellen

Baue das Docker-Image und achte darauf, dass der Tag in Kleinbuchstaben geschrieben ist:
docker build --tag ghcr.io/<dein Repository>:latest ./vehicle/target

  • Docker Login

Melde dich bei der GitHub Container Registry an:
docker login ghcr.io

  • Docker Image pushen

Push das Docker-Image zur Registry, wobei der Tag ebenfalls in Kleinbuchstaben sein muss:
docker push ghcr.io/<dein Repository>:latest

  • Kubernetes Deployment anwenden

Wende das Kubernetes Deployment an:
kubectl apply -f k8s/appsrv.yaml

4. Berechtigungen für die Paketverwaltung in GitHub

Um ein Package in GitHub erstellen und bearbeiten zu können, muss man Mitglied einer Organisation sein. Hier sind die erforderlichen Schritte und Einstellungen:

  1. Mitgliedschaft in der Organisation Stelle sicher, dass du ein Mitglied der betreffenden Organisation bist.

  2. Öffentliche Pakete erstellen Um ein Package auf öffentlich zu setzen, muss in der Organisation unter Settings > Code, planning, and automation > Packages die Option zur Erstellung öffentlicher Pakete aktiviert sein.

  3. Schreibberechtigungen Mitglieder benötigen Schreibberechtigungen, die unter Settings > Access > Organization roles > Role assignments vergeben werden können.

  4. Paketverwaltung aktivieren Wenn das Package lokal erstellt und auf öffentlich gesetzt werden kann, gehe zu dem jeweiligen Package, öffne die Package-Einstellungen und klicke unter "Manage Actions access" auf den Button "Add Repository". Füge dein Repository hinzu, damit es auf das Package zugreifen und es bearbeiten kann.

5. Weitere wichtige Umgebungsvariablen in den Workflows

In den GitHub Actions Workflows (build.yaml und release-artifacts.yaml) werden verschiedene Umgebungsvariablen (env) verwendet, um die Pipeline-Anforderungen und die Projektkonfiguration zu steuern. Dazu gehören Variablen wie die Java-Version und die Java-Distribution, die für den Build und das Deployment festgelegt werden können. Beispiele dafür sind:

env:
  JAVA_VERSION: '21'
  JAVA_DISTRIBUTION: 'temurin'

Diese Variablen (JAVA_VERSION und JAVA_DISTRIBUTION) sorgen dafür, dass beide Workflows mit der gewünschten Java-Version und Distribution ausgeführt werden, wodurch eine konsistente Umgebung gewährleistet wird. Du kannst diese Werte in den Dateien build.yaml und release-artifacts.yaml nach Bedarf anpassen.

6. GitHub Secrets

6.1. Zugriff auf die Kubernetes-Konfigurationsdatei

Um sicherzustellen, dass der deployment.yaml Workflow Zugriff auf die Kubernetes-Konfigurationsdatei für Leocloud hat, musst du das folgende Kommando ausführen:

cat $HOME/.kube/config | base64

Die Ausgabe dieses Kommandos muss dann in die GitHub Actions unter dem Namen KUBE_CONFIG_DATA hinzugefügt werden. Dadurch kann der Workflow auf die Konfigurationsdatei zugreifen und die notwendigen Berechtigungen für die Interaktion mit Leocloud bereitstellen.

7. Verwendung anderer Kubernetes-Deployments

Neben der Leocloud-Plattform ist es auch möglich, andere Kubernetes-Deployments zu nutzen. Voraussetzung ist, dass die korrekte Konfigurationsdatei verwendet wird, die den Zugriff auf das entsprechende Kubernetes-Cluster ermöglicht. Achte darauf, dass alle erforderlichen Berechtigungen und Konfigurationen in der Datei korrekt angegeben sind.

8. Abschluss

Nach der Durchführung aller oben genannten Schritte sollten die GitHub Actions nun ohne Probleme durchlaufen. Das Projekt ist jetzt vollständig konfiguriert und bereit für den Einsatz. Du kannst fortfahren, neue Änderungen zu implementieren und diese effizient über die GitHub Actions zu integrieren. Viel Erfolg bei der weiteren Entwicklung!