Builds parametrisieren und Skripte verwenden

Einführung

In modernen CI/CD-Pipelines sind Flexibilität und Automatisierung entscheidend. Das Festschreiben (Hardcoding) von Werten in Build-Jobs macht diese starr und schwer zu verwalten. Jenkins ermöglicht es Ihnen, dies zu umgehen, indem Sie Ihre Builds parametrisieren und Skripte als Teil des Build-Prozesses ausführen.

In diesem Lab lernen Sie, wie Sie einen flexiblen Jenkins-Job erstellen. Sie beginnen damit, Parameter hinzuzufügen, um Benutzereingaben zur Build-Zeit zu ermöglichen. Anschließend lernen Sie, Shell-Skripte als Build-Schritt auszuführen, die Parameter an diese Skripte zu übergeben und Post-Build-Aktionen zu konfigurieren, die bedingt auf den Erfolg oder Misserfolg des Builds reagieren. Dies sind grundlegende Fähigkeiten für die Erstellung robuster und dynamischer Automatisierungs-Workflows in Jenkins.

Eine Jenkins-Instanz ist bereits in Ihrer Umgebung aktiv. Sie können die Jenkins-Weboberfläche über den Firefox-Browser auf dem Desktop aufrufen. Der Browser öffnet sich automatisch unter http://localhost:8080, sodass Sie die URL nicht manuell eingeben müssen. Es ist kein Login erforderlich.

Ein Freestyle-Projekt erstellen und parametrisieren

In diesem Schritt erstellen Sie ein neues Jenkins Freestyle-Projekt und fügen diesem Parameter hinzu. Parameter machen Ihre Jobs interaktiv und ermöglichen es Ihnen, bei jedem Auslösen eines Builds Eingaben zu tätigen.

Lassen Sie uns zunächst den Job erstellen.

1. Öffnen Sie den Firefox-Browser über die Desktop-Oberfläche. Der Browser öffnet sich automatisch unter http://localhost:8080. Es ist kein Login erforderlich.
2. Klicken Sie im Jenkins-Dashboard im linken Menü auf Neuer Job (New Item).
3. Geben Sie parameterized-script-job als Namen für das Element ein.
4. Wählen Sie Freestyle-Projekt (Freestyle project) aus und klicken Sie auf OK.

Sie werden zur Konfigurationsseite des Jobs weitergeleitet. Lassen Sie uns nun Parameter hinzufügen.

1. Aktivieren Sie im Abschnitt Allgemein (General) das Kontrollkästchen Dieses Projekt ist parametrisiert (This project is parameterized).

   

2. Klicken Sie auf das Dropdown-Menü Parameter hinzufügen (Add Parameter) und wählen Sie String-Parameter (String Parameter).

   • Name: GREETING_NAME
   • Standardwert (Default Value): World
   • Beschreibung (Description): Geben Sie einen Namen für die Begrüßung ein.

3. Klicken Sie erneut auf das Dropdown-Menü Parameter hinzufügen und wählen Sie Auswahl-Parameter (Choice Parameter).

   • Name: ENVIRONMENT

   • Auswahlmöglichkeiten (Choices): (Geben Sie jede Auswahl in eine neue Zeile ein)

     DEV
     STAGING
     PROD
     

   • Beschreibung: Wählen Sie die Bereitstellungsumgebung aus.

Diese Parameter stehen in späteren Build-Schritten zur Verfügung.

Scrollen Sie abschließend nach unten und klicken Sie auf Speichern. Sie werden zur Hauptseite des Jobs weitergeleitet, wo Sie nun anstelle von "Jetzt bauen" die Option Mit Parametern bauen (Build with Parameters) sehen.

Einen Shell-Skript-Build-Schritt hinzufügen

In diesem Schritt fügen Sie Ihrem Build-Prozess ein Shell-Skript hinzu. Dies ist eine gängige Methode, um Aufgaben wie das Kompilieren von Code, das Ausführen von Tests oder das Bereitstellen von Anwendungen durchzuführen.

1. Navigieren Sie zum Dashboard des parameterized-script-job in Jenkins.
2. Klicken Sie im linken Menü auf Konfigurieren (Configure).
3. Scrollen Sie nach unten zum Abschnitt Build-Schritte (Build Steps).
4. Klicken Sie auf das Dropdown-Menü Build-Schritt hinzufügen (Add build step) und wählen Sie Shell ausführen (Execute shell).
5. Geben Sie im Textbereich Befehl (Command) das folgende Skript ein. Dieses Skript erstellt eine Projektverzeichnisstruktur innerhalb des Jenkins-Workspaces und listet deren Inhalt auf.

echo "--- Starting Build Step ---"
echo "Current directory:"
pwd
echo "Creating project directory structure:"
mkdir -p my-app
echo "Version 1.0" > my-app/version.txt
echo "Listing files in the project directory:"
ls -la my-app
echo "--- Build Step Finished ---"

6. Klicken Sie auf Speichern, um die Änderungen zu übernehmen.

Lassen Sie uns nun den Job ausführen, um das Skript in Aktion zu sehen.

1. Klicken Sie auf der Job-Seite auf Mit Parametern bauen.
2. Behalten Sie die Standard-Parameterwerte bei und klicken Sie auf die Schaltfläche Bauen (Build).
3. Ein neuer Build erscheint im Build-Verlauf (Build History) auf der linken Seite. Klicken Sie auf die Build-Nummer (z. B. #1).
4. Klicken Sie auf Konsolenausgabe (Console Output), um die Protokolle anzuzeigen.

Sie sollten die Ausgabe Ihres Shell-Skripts sehen, einschließlich der Dateiauflistung.

Started by user unknown or anonymous
Running as SYSTEM
Building in workspace /var/jenkins_home/workspace/parameterized-script-job
[parameterized-script-job] $ /bin/sh -xe /tmp/jenkins....sh
+ echo --- Starting Build Step ---
--- Starting Build Step ---
+ echo Current directory:
Current directory:
+ pwd
/var/jenkins_home/workspace/parameterized-script-job
+ echo Creating project directory structure:
Creating project directory structure:
+ mkdir -p my-app
+ echo Version 1.0
+ echo Listing files in the project directory:
Listing files in the project directory:
+ ls -la my-app
total 12
drwxr-xr-x 2 jenkins jenkins 4096 ... .
drwxr-xr-x 3 jenkins jenkins 4096 ... ..
-rw-r--r-- 1 jenkins jenkins   12 ... version.txt
+ echo --- Build Step Finished ---
--- Build Step Finished ---
Finished: SUCCESS

Parameter an das Shell-Skript übergeben

In diesem Schritt lernen Sie, wie Sie die in Schritt 1 definierten Parameter innerhalb Ihres Shell-Skripts verwenden. Jenkins stellt Build-Parameter als Umgebungsvariablen bereit, auf die Sie in Ihrem Skript mit der Syntax $VARIABLE_NAME zugreifen können.

1. Gehen Sie zurück zur Konfigurationsseite für Ihren parameterized-script-job.
2. Scrollen Sie nach unten zum Abschnitt Build-Schritte und suchen Sie das Befehlsfeld Shell ausführen.
3. Ersetzen Sie das vorhandene Skript durch das folgende:

echo "--- Starting Parameterized Build Step ---"
echo "Hello, $GREETING_NAME!"
echo "Deploying to the $ENVIRONMENT environment."

## Create project structure if not exists and read the version from the file
mkdir -p my-app
echo "Version 1.0" > my-app/version.txt
APP_VERSION=$(cat my-app/version.txt)
echo "Application version is: $APP_VERSION"
echo "--- Parameterized Build Step Finished ---"

Beachten Sie, wie $GREETING_NAME und $ENVIRONMENT direkt in den echo-Befehlen verwendet werden. Wenn der Job ausgeführt wird, ersetzt Jenkins diese durch die vom Benutzer ausgewählten Werte.

4. Klicken Sie auf Speichern.

Lassen Sie uns nun den Build mit benutzerdefinierten Parametern ausführen.

1. Klicken Sie auf Mit Parametern bauen.
2. Ändern Sie GREETING_NAME in LabEx.
3. Wählen Sie STAGING aus dem Dropdown-Menü ENVIRONMENT.
4. Klicken Sie auf Bauen.
5. Überprüfen Sie die Konsolenausgabe für den neuen Build.

Die Ausgabe sollte nun die von Ihnen bereitgestellten benutzerdefinierten Werte widerspiegeln.

--- Starting Parameterized Build Step ---
+ echo Hello, LabEx!
Hello, LabEx!
+ echo Deploying to the STAGING environment.
Deploying to the STAGING environment.
+ mkdir -p my-app
+ echo Version 1.0
+ cat my-app/version.txt
+ APP_VERSION=Version 1.0
+ echo Application version is: Version 1.0
Application version is: Version 1.0
+ echo --- Parameterized Build Step Finished ---
--- Parameterized Build Step Finished ---

Build-Fehler mit Shell-Bedingungen behandeln

In diesem Schritt simulieren Sie einen Build-Fehler direkt im Shell-Skript. Dies ist eine zuverlässige Methode, um einen Freestyle-Job zu stoppen, wenn eine Bereitstellungsregel verletzt wird.

Das Skript zur Simulation eines Fehlers ändern

Lassen Sie uns nun das Skript so ändern, dass es unter einer bestimmten Bedingung fehlschlägt.

1. Gehen Sie zur Konfigurationsseite für Ihren parameterized-script-job.
2. Ersetzen Sie im Befehlsfeld Shell ausführen das Skript durch das folgende:

echo "Deploying to the $ENVIRONMENT environment."

if [ "$ENVIRONMENT" = "PROD" ]; then
  echo "Error: Production deployment is not allowed!"
  echo "Failure handled by shell condition."
  exit 1
fi

echo "Deployment to $ENVIRONMENT was successful."

Dieses Skript überprüft den Parameter ENVIRONMENT. Wenn er auf PROD gesetzt ist, gibt es einen Fehler aus und beendet das Skript mit dem Statuscode 1. In der Shell-Programmierung signalisiert jeder Exit-Code ungleich Null einen Fehler an Jenkins.

3. Klicken Sie auf Speichern.

Die Fehlerbedingung testen

Lassen Sie uns nun die Fehlerbedingung testen.

1. Klicken Sie auf Mit Parametern bauen.
2. Wählen Sie PROD für ENVIRONMENT und klicken Sie auf Bauen.
3. Der Build schlägt fehl, was durch ein rotes Symbol im Build-Verlauf angezeigt wird.
4. Überprüfen Sie die Konsolenausgabe. Sie sehen die Fehlermeldung aus Ihrem Skript und den endgültigen Jenkins-Build-Status.

Deploying to the PROD environment.
+ [ PROD = PROD ]
+ echo Error: Production deployment is not allowed!
Error: Production deployment is not allowed!
+ echo Failure handled by shell condition.
Failure handled by shell condition.
+ exit 1
Build step 'Execute shell' marked build as failure
Finished: FAILURE

Wenn Sie den Build erneut mit DEV oder STAGING ausführen, wird er erfolgreich sein, da die Fehlerbedingung nicht ausgelöst wird.

Zusammenfassung

Herzlichen Glückwunsch. Sie haben erfolgreich einen flexiblen und robusten Jenkins-Job erstellt.

In diesem Lab haben Sie gelernt:

• Einen parametrisierten Jenkins-Job unter Verwendung von String- und Auswahl-Parametern zu erstellen.
• Shell-Skripte als Teil eines Build-Prozesses auszuführen.
• Auf Build-Parameter als Umgebungsvariablen innerhalb Ihrer Skripte zuzugreifen und diese zu verwenden.
• Bedingte Logik in einem Skript zu implementieren, um das Build-Ergebnis zu steuern.
• Shell-Bedingungen und Exit-Codes zu verwenden, um zu steuern, ob ein Build erfolgreich ist oder fehlschlägt.

Diese Fähigkeiten sind unerlässlich für den Aufbau anspruchsvoller CI/CD-Pipelines, die sich an unterschiedliche Eingaben anpassen und Fehler intelligent behandeln können. Sie können diese Konzepte nun anwenden, um Ihre eigenen Entwicklungs- und Bereitstellungs-Workflows zu automatisieren.