234 lines
9.8 KiB
Markdown
234 lines
9.8 KiB
Markdown
# CI/CD Dokumentation
|
|
|
|
Dies ist die Dokumentation für die CI/CD Pipeline von dem <RANDOM JAVA WEBSERVICE>
|
|
|
|
|
|
## Was wird Automatisiert ?
|
|
Durch das CI/CD System werden Folgende Prozesse Automatisiert durchgeführt :
|
|
|
|
- **Build**: Build Prozess der Software
|
|
- Automatische Generierung von API-Server Boilercode
|
|
- Kompilierung und Verpacken der Software in eine **.jar*
|
|
- **Test**: Automatisierte Tests
|
|
- Modul-Test mit angebundenen externen Test Datenbank
|
|
- Code-Coverage Report
|
|
- **Analyse**: Analyse von Sourcecode und Test Reports
|
|
- Statische Code Analyse durch SonarQube mit Qualitätsprofil **Sonar-Way**
|
|
- Analyse des Code-Coverage Reports
|
|
- Analyse des Modul-Test Ergebnisses
|
|
- **Package**: Cloudgerechte Verpackung des Software
|
|
- Containerisierung in einem Container-Image für die Cloudnutzung
|
|
- Linting des Helm-Charts für Kubernetes
|
|
- **Deploy**: Deployment der Software
|
|
- Deployment auf einem Kubernetes Cluster durch Helm
|
|
|
|
## Welche Komponenten/Tools werden verwendet
|
|
|
|
Folgende Komponenten/Tools werden im CI/CD Prozess verwendet:
|
|
|
|
- **Build**
|
|
- OpenAPI Codegenerator
|
|
- Maven
|
|
- **Test**
|
|
- JUnit-5
|
|
- JaCoCo
|
|
- **Analyse**
|
|
- Static Code Analysis
|
|
- SonarQube 7
|
|
- **Package**
|
|
- Kaniko
|
|
- Helm
|
|
- **Deploy**
|
|
- Helm
|
|
- Kubernetes
|
|
|
|
**CI/CD Engine**: Serverless Jenkins X
|
|
|
|
# CI/CD In-,Outputs
|
|
|
|
|
|
|
|
## Trigger
|
|
Jenkins X erhält verschiedene Inputs,Trigger und Signale durch einen Webhook-Server namens *Lighthouse*. An ihn werden Eventbenachichtigungen durch GitLab gesendet um anschließend ein **CI-Run** zu starten.
|
|
|
|
Dabei wird ein **CI-Run** durch folgende Trigger und Konditionen gestartet:
|
|
|
|
- Push auf den **master** branch auf GitLab
|
|
- Push auf einen branch mit offenen *Merge Request*
|
|
- Ausführen des Befehlt ``jx start pipeline``
|
|
|
|
## Inputs und Kontexte Daten
|
|
|
|
Diese Daten fliesen und beeinflussen den **CI-Build**:
|
|
|
|
- Source-Code
|
|
- Branch von den die Pipeline getriggert wurde
|
|
- User, der die Pipeline ausgelöst hat.
|
|
- Offene Mergerequests
|
|
- Prow-Konfiguration
|
|
- Jenkins X Projekt Konfiguration
|
|
- HMAC Secret des Webhookrequestes
|
|
# Pipeline Definitionen
|
|
|
|
Es existieren zwei verschiedene Pipelines die durch die Trigger ausgelöst werden können:
|
|
|
|
- Release
|
|
- Preview
|
|
|
|
## Release
|
|
|
|
Diese Pipeline kompeliert, testet, analysiert, verpackt und bereitet die Software zum Deployment vor.
|
|
|
|
Sie deployed jedoch die Anwendung nicht, sondern erstellt/modifiziert lediglich verschiedene Umgebungskonfigurationen, bei denen das automatische Deployment vorgesehen ist.
|
|
|
|
**Trigger**: Push oder Merge auf den **master** Branch.
|
|
|
|
### Stage: Setup (Buildpack Maven)
|
|
|
|
In dieser Stage wird der Buildprozess vorbereitet und eingeleitet.
|
|
|
|
Befehle:
|
|
|
|
- `echo \$(jx-release-version) > VERSION`
|
|
Schreiben der neuen Software Version in eine Temporäre `VERSION` Datei um diese in späteren Schritten wieder abrufen zu können
|
|
- `mvn versions:set -DnewVersion=\$(cat VERSION)`
|
|
Setzen der Software Version in Maven um die neuen Software-Artefakte direkt mit richtigen namen und Tags zu versehen.
|
|
- `jx step tag --version \$(cat VERSION)`
|
|
Setzen der Software Version in Jenkins X und in Git als Tag.
|
|
|
|
### Stage: Build (Buildpack Maven)
|
|
|
|
In dieser Stage werden alle zum Build dazugehörigen komponenten und Tools ausgeführt. Bei einigen befehlen werden mehrere Tools und Komponenten gleichzeitig ausgeführt um den Buildprozess erfolgreich abzuschließen.
|
|
|
|
**Befehle**:
|
|
|
|
- ` mvn clean deploy`
|
|
Durch diesen Befehl wird die eigentliche Software gebaut. Der Bauprozess in Maven ist in verschiedene Phasen aufgeteilt, die in einer festen Reinfolge abgearbeitet werden.
|
|
In jedem dieser Phasen wird ein anderes Tool/Plugin/Komponente aufgerufen. Nach dem Abschluss jeder Phase wird überprüft, ob die Phase erfolgreich abgeschlossen wurde.
|
|
**Phasen**:
|
|
|
|
- `clean`
|
|
Bereinigt den Projekt Ordner von überresten eines vorherigen buildprozesses.
|
|
|
|
- `generate-sources`
|
|
Erstellt mithilfe von **openapi-generator.tech** Serverboilercode und API Schnittstellendefinitionen aus einer *OpenAPI-Definitions Datei*.
|
|
Diese liegt unter `src/main/resources/api.yaml` und ist in *OpenAPI v3* formatiert.
|
|
|
|
Der generierte Code ist unter `target/generated-sources/openapi` abgelegt und wird automatisch in den *Classpath* eingebunden.
|
|
|
|
- `compile`
|
|
Erhebt alle Dependencys und stellt diese zu den entsprechenden Phasen des Buildvorgangs zuverfügung. Anschließend werden alle Sourcen die sich in dem Sourcepath befinden kompeliert.
|
|
|
|
- `test`
|
|
Führt UnitTests mithilfe von *JUnit 5* aus. *JUnit* scannt nach Aktivierten und Relevanten Tests und führt diese aus. Die Ergebnisse werden in Form eines XML-Reports in den `target` Ordner abgelegt. Bei der Ausführung der Tests wird zusätzlich die Code Coverage durch *JaCoCo* erhoben und ebenfals ein Report unter `target` abgelegt.
|
|
|
|
- `package`
|
|
Erzeugt eine ausführbare `.jar` Datei mit allen benötigten Dependencys um diese zu Containerisieren.
|
|
|
|
- `skaffold build -f skaffold.yaml`
|
|
Wird durch Jenkins X zu Kaniko build umformatiert.
|
|
Baut Container Image mit Parameter aus Jenkins X und veröffentlich diese in einem Container Registry
|
|
|
|
- Sonarqube Analyse (Custom addition)
|
|
|
|
```bash
|
|
mvn --batch-mode sonar:sonar \
|
|
-Dsonar.projectKey=<sonarqube projekt key> \
|
|
-Dsonar.host.url=<sonarqube host> \
|
|
-Dsonar.login=<sonarqube login key> \
|
|
-Dsonar.gitlab.commit_sha=$(git rev-parse HEAD) \
|
|
-Dsonar.gitlab.ref_name=$(git rev-parse --abbrev-ref HEAD) \
|
|
-Dsonar.gitlab.project_id=<project id> \
|
|
-Dsonar.branch.name=$BRANCH_NAME \
|
|
-Dsonar.gitlab.user_token=<gitlab access toekn>\
|
|
```
|
|
|
|
Analysiert Projekt mit Hilfe von SonarQube und bricht die Pipeline ab wenn Qualitätsprobleme gefunden wurden.
|
|
|
|
|
|
|
|
### Stage: Promote (Buildpack Maven)
|
|
|
|
In dieser Stage werden die erzeugten Artefakte in die zugehörigen Artefaktarchivierungssysteme hochgeladen und die verschiedenen Umgebungskonfigurationen modifiziert um den *CD-Prozess* zu starten.
|
|
|
|
**Befehle:**
|
|
|
|
- `jx step changelog --version v\$(cat ../../VERSION)`
|
|
Fügt dem Tag und dem Release in GitLab Changelogs aus den Commitnachichten hinzu.
|
|
- ` jx step helm release`
|
|
Veröffentlich das Helmchat aus dem `charts` Ordner unter einer neuen Version im Chartmuseum.
|
|
- `jx promote -b --all-auto --timeout 1h --version \$(cat ../../VERSION)`
|
|
Modifiziert oder Erstellt die Umgebunskonfigurationen bei denen in Jenkins X *Autodeploy* aktiviert wurde.
|
|
|
|
## Preview
|
|
|
|
Diese Pipeline kompeliert, testet, analysiert, verpackt und bereitet die Software zum deployment in eine temporäre Previewenvirgonment.
|
|
|
|
Diese Pipeline ist nicht zum Bau einer Realease Version gedacht und bereitet die Software nur für ein themporäres Preview vor.
|
|
|
|
**Trigger**: Push oder Merge auf einen Branch, der Quelle eines offenen *Merge-Request* ist.
|
|
|
|
### Stage: Build (Buildpack Maven)
|
|
|
|
In dieser Stage werden alle zum Build dazugehörigen komponenten und Tools ausgeführt. Bei einigen befehlen werden mehrere Tools und Komponenten gleichzeitig ausgeführt um den Buildprozess erfolgreich abzuschließen.
|
|
|
|
**Befehle**:
|
|
|
|
- ` mvn clean install`
|
|
Durch diesen Befehl wird die eigentliche Software gebaut. Der Bauprozess in Maven ist in verschiedene Phasen aufgeteilt, die in einer festen Reinfolge abgearbeitet werden.
|
|
In jedem dieser Phasen wird ein anderes Tool/Plugin/Komponente aufgerufen. Nach dem Abschluss jeder Phase wird überprüft, ob die Phase erfolgreich abgeschlossen wurde.
|
|
**Phasen**:
|
|
|
|
- `clean`
|
|
Bereinigt den Projekt Ordner von überresten eines vorherigen buildprozesses.
|
|
|
|
- `generate-sources`
|
|
Erstellt mithilfe von **openapi-generator.tech** Serverboilercode und API Schnittstellendefinitionen aus einer *OpenAPI-Definitions Datei*.
|
|
Diese liegt unter `src/main/resources/api.yaml` und ist in *OpenAPI v3* formatiert.
|
|
|
|
Der generierte Code ist unter `target/generated-sources/openapi` abgelegt und wird automatisch in den *Classpath* eingebunden.
|
|
|
|
- `compile`
|
|
Erhebt alle Dependencys und stellt diese zu den entsprechenden Phasen des Buildvorgangs zuverfügung. Anschließend werden alle Sourcen die sich in dem Sourcepath befinden kompeliert.
|
|
|
|
- `test`
|
|
Führt UnitTests mithilfe von *JUnit 5* aus. *JUnit* scannt nach Aktivierten und Relevanten Tests und führt diese aus. Die Ergebnisse werden in Form eines XML-Reports in den `target` Ordner abgelegt. Bei der Ausführung der Tests wird zusätzlich die Code Coverage durch *JaCoCo* erhoben und ebenfals ein Report unter `target` abgelegt.
|
|
|
|
- `package`
|
|
Erzeugt eine ausführbare `.jar` Datei mit allen benötigten Dependencys um diese zu Containerisieren.
|
|
|
|
- `skaffold build -f skaffold.yaml`
|
|
Wird durch Jenkins X zu Kaniko build umformatiert.
|
|
Baut Container Image mit Parameter aus Jenkins X und veröffentlich diese in einem Container Registry
|
|
|
|
- Sonarqube Analyse (Custom addition)
|
|
|
|
```bash
|
|
mvn --batch-mode sonar:sonar \
|
|
-Dsonar.projectKey=<sonarqube projekt key> \
|
|
-Dsonar.host.url=<sonarqube host> \
|
|
-Dsonar.login=<sonarqube login key> \
|
|
-Dsonar.gitlab.commit_sha=$(echo $PULL_REFS | cut -d':' -f3) \
|
|
-Dsonar.gitlab.ref_name=$(git rev-parse --abbrev-ref HEAD) \
|
|
-Dsonar.gitlab.project_id=<project id> \
|
|
-Dsonar.branch.name=$BRANCH_NAME \
|
|
-Dsonar.gitlab.user_token=<gitlab access toekn>\
|
|
```
|
|
|
|
Analysiert Projekt mit Hilfe von SonarQube.
|
|
|
|
|
|
|
|
### Stage: Promote (Buildpack Maven)
|
|
|
|
In dieser Stage werden die erzeugten Artefakte in die zugehörigen Artefaktarchivierungssysteme hochgeladen und eine temporäre Previewumgebung erstellt um die Anwendung kurzzeitig zu testen.
|
|
|
|
**Befehle:**
|
|
|
|
- `jx step changelog --version v\$(cat ../../VERSION)`
|
|
Fügt dem Tag und dem Release in GitLab Changelogs aus den Commitnachichten hinzu.
|
|
- ` jx step helm release`
|
|
Veröffentlich das Helmchat aus dem `charts` Ordner unter einer neuen Version im Chartmuseum.
|
|
- `jx promote -b --all-auto --timeout 1h --version \$(cat ../../VERSION)`
|
|
Modifiziert oder Erstellt die Umgebunskonfigurationen bei denen in Jenkins X *Autodeploy* aktiviert wurde.
|