# 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.
