diff --git a/FRADrive-Übersicht/Release-Prozedur.md b/FRADrive-Übersicht/Release-Prozedur.md index 7dc351f..7fdcbcf 100644 --- a/FRADrive-Übersicht/Release-Prozedur.md +++ b/FRADrive-Übersicht/Release-Prozedur.md @@ -1 +1,271 @@ -Ausrollen einer neuen Version von FRADrive +_Hinweis: Dies ist eine automatisch generiere Markdown-Fassung eines Word Dokuments auf dem FRADrive Sharepoint_ + +---------------------------------------------------------------------------- + + +Dies ist eine Übersicht über alle notwendigen Schritte, um eine Code +Änderung in FRADrive ins Produktiv-System zu überführen. + +Gitlab +====== + +Der Quellcode des Projektes liegt auf + und ist gemäß der Lizenz des +ursprünglichen Projektes Uni2work quelloffen. Folgende Schritte werden +üblicherweise in einer per SSH geöffneten Shell auf srv01.uniworx.de +durchgeführt, da auf diesem Server alle notwendigen +Entwicklungswerkzeuge in der passenden Version installiert wurden. Für +Code-Bearbeitung empfiehlt sich ein Zugriff per sshfs. Der Server +uniworx.de wird von Uniworx-Systems (Sarah Vaupel) betrieben. + +1. Code Änderung durchführen und in einem Zweig des Git-Repositories + einpflegen + +2. Merge des Zweiges in der Hauptzweig „master" und push der Änderungen + auf den Server, entweder lokal oder per Pull Request auf + gitlab.uniworx.de + +3. Shell Befehl „npm run release"\ + Startet zuerst eine lokale Prüfung (Compiliert „master"? Werden alle + Tests lokal bestanden?) und erhöht dann die Versionsnummern (je nach + commit-log) und triggert die CI/CD auf dem Server. Dieser Prozess + dauert ca. 8 Stunden (4 Stunden lokal, 4 Stunden auf dem Server; ja, + alle Tests werden 2-mal durchgeführt -- das wurde 1:1 von UniWorX + übernommen, da dort ein größeres Entwicklerteam arbeitet und dadurch + fehlerhafte commits verhindert werden.)\ + Wenn alles funktioniert hat, ist danach ein neuer Container + verfügbar unter + + +DevOps TrustedImages +==================== + +Ab hier läuft der Prozess nun auf Servern der Fraport AG. Zuerst erfolgt +der Download des Containers ins Netz der Fraport AG. + +1. Im [DevOps + TrustedImages](https://dev.azure.com/fraport/ContainerPlatform%20Administration/_git/TrustedImages) + den Zweig „feature/fradrive\_update" auf den neusten Stand bringen + durch die Shell-Befehle:\ + git checkout master;\ + git pull\ + git rebase master feature/fradrive\_update + +2. Versionsnummer *x.y.z* des neuen Containers in der Datei + trusted-images.yaml erhöhen. Dazu die Datei nach „fradrive" + durchsuchen, da sich diese Datei immer wieder ändert. *Achtung:* die + Versionsnummer wird an zwei nah beieinander liegenden Stellen erhöht + werden! + +3. Die Datei Reviews/Review\_fradrive.md aktualisieren und anpassen. + Dieser Schritt ist optional, wenn es sich um einen Minor-Release + handelt. + +4. Diese Änderungen comitten und zum Server pushen. Die Commit-Notiz + hat üblicherweise folgendes Format:\ + *FRADrive x.y.z\ + - fix 1\ + - fix 2\ + - feature 1\ + - feature 2* + +5. Im Browser [DevOps + TrustedImages](https://dev.azure.com/fraport/ContainerPlatform%20Administration/_git/TrustedImages/pullrequests?_a=mine) + einen Pull Request beantragen, welcher den Zweig + „feature/fradrive\_update" in den Zweig „master". Dieser Pull + Request muss durch das Cloud-Team genehmigt werden. + +6. Sobald die Genehmigung vorliegt, den Merge durchführen durch Druck + auf „Complete" + +7. Abwarten bis die Pipeline erfolgreich durchgelaufen ist, ca. 10min + (siehe Abschnitt „Pipelines") + +3. DevOps FraDrive Deployment, 1. Teil +====================================== + +1. Den Zweig „test" des [DevOps Repos FraDrive + > Depolyment](https://dev.azure.com/fraport/Fahrerausbildung/_git/FraDrive%20Deployment) + > aktualisieren. + +2. Die Versionsnummer des Containers x.y.z an allen relevanten Stellen + > erhöhen, am besten alle Dateien nach der alten Nummer durchsuchen. + > Derzeit sind es 6 verschiedene Stellen, da test/qa/prod je eigene + > Versionen haben können. + +3. Der jeweilige Repository Zweig beachtet natürlich nur die relevante + > Nummer: Wenn klar ist, dass es eine Test-Version ist, welche + > niemals produktiv sein sollte, dann wird **nicht** die + > Versionsnummer in values.conf.prod.yaml erhöht. Ansonsten ist + > diese Nummer sofort erhöhen, was sich aber erst durch die späteren + > Schritte auswirkt. + +4. Erhöhung der Kubernetes Chart-Version in Chart.yaml. Idealerweise + > ist diese Nummer identisch zur Container-Version.\ + > Wenn Änderungen an der Konfiguration ohne das Ausrollen eines + > neuen Containers notwendig sind, muss diese Chart-Versionsnummer + > aber trotzdem zumindest in der letzten Stelle (patch-version) + > erhöht werden, damit die Änderungen übernommen werden. Bei der + > nächsten Erhöhung von major oder minor Version kann die + > Chart-Version dann meist wieder angeglichen werden. + +5. Nach „git push" detektiert Kubernetes automatisch diese Änderungen + > (kann bis 10min dauern). Der alte Container läuft so lange weiter, + > bis der neue Container online ist. Die Applikation ist dabei + > durchgängig verfügbar.\ + > Der Prozess kann im Azure Portal oder per Lens gut beobachtet + > werden.\ + > **Achtung:** Wenn die neue FRADrive Version Änderungen am + > Datenbank Schema durchführt, dann dürfen alte und neue Version + > nicht gleichzeitig laufen! In diesem Falle ist die alte Version + > herunterzufahren und es entsteht eine echte Downtime! + +6. Sobald der neue Container online ist, sollte die neue Version per + > fradrive-t.aps.fra.fraport.de geprüft werden. + +7. Wenn die Prüfung erfolgreich war, ist ein Pull Request von „test" + > auf Zweig „qa" durchzuführen. Diesen Pull Request kann man sich + > selbst genehmigen. Wird der Pull Request vollzogen, so beginnt + > Kubernetes automatisch mit dem Update der QA-Instanz + +4. Change Request stellen +========================= + +Vor dem Update von Prod ist im Franow ist ein ChangeRequest anzumelden. +Für kleinere Updates und Fixes gibt es einen Routine Change, den man +sich selbst genehmigen kann. + +1. Auf Neu -\> Routine -\> + Applikationen -\> FRADrive + +2. Riskio und Auswirkung einstellen + +3. Betroffendes CI „FraDrive Applikation" + +4. Zeitplan einstellen. Dieser muss mit der Fahrerausbildung + abgesprochen werden, üblicherweise ist es außerhalb deren + Geschäftszeiten (6-15 Uhr) unproblematisch; andere Kunden bemerken + den im Normalfall den \<1 Sekunde Ausfall nicht; das E-Learning ist + ohnehin dadurch gar nicht betroffen. + +5. Geplante Downtime einstellen, falls das Update eine DB Migration + vornimmt (siehe dazu auch Abschnitt DB Migrationen). In diesem Fall + unbedingt absprechen und mehrere Tage vorher durch eine + [System-Nachricht in + FRADrive](https://fradrive.apps.fra.fraport.de/msgs) auch an + Endkunden kommunizieren! + +5. DevOps BaseImages +==================== + +Der Container muss noch zweites Mal durch das Cloud-Team akzeptiert +werden, bevor die Produktiv-Instanz ein Update erhält. + +1. Im [DevOps + BaseImages](https://dev.azure.com/fraport/ContainerPlatform%20Administration/_git/BaseImages) + den Zweig „fradrive/update" auf den neusten Stand bringen durch die + Shell-Befehle (Achtung: ärgerlicherweise nicht identisch zu + Abschnitt 2 „TrustedImages")\ + git checkout master;\ + git pull\ + git rebase master fradrive/update + +2. Versionsnummer *x.y.z* des neuen Containers an zwei nah beieinander + liegenden Stellen in der Datei thirdparty/fradrive/images.yml + erhöhen. + +3. Commit mit dem gleichen Kommentar wie in Abschnitt 2 „TrustedImages" + zusätzlich ist jedoch eine neue zweite Zeile einzufügen mit einem + Link auf den in Abschnitt 4 erstellten Change. Am besten gleich im + Markdown Format angeben, so dass der Link klickbar wird:\ + \[CHG0012345\]([https://franow.fraport.de/change\_request.do?sys\_id=*\*) + +4. Im Browser auf DevOps BaseImages einen Pull-Request von Zweig + „fradrive-update" nach „master" stellen. + +5. Dieser Pull Request muss durch das Cloud-Team der Fraport genehmigt + werden. + +6. Nach der Genehmigung Pull Request abschließen und warten, bis der + Container hochgeladen wurde. Da dies dieses Mal innerhalb der + Fraport Cloud geschieht, dauert das nur noch ca. 1-2 Minuten. + +7. Im FraNow den Change freigeben, da nun alles bereit ist. + +6. DevOps FraDrive Deployment, 2. Teil +====================================== + +1. Einen Pull Request von „test" nach „master" stellen. Idealerweise + erfolgt der Merge von „qa" nach „master", aber DevOps meckert da + immer wegen Multiple merge bases. Wenn wie oben beschrieben + vorgegangen wurde, dann macht es ohnehin keinen Unterschied. + +2. Im FraNOw den Change auf „Implementieren" stellen, dies sollte + innerhalb der Planzeit erfolgen. + +3. Den Pull Request „test" nach "master" akzeptieren. Kubernetes + beginnt nach maximal 10 Minuten mit dem Update. Es wird wieder + zuerst die neue Instanz gestartet und dann erst die alte beendet, + d.h. FRADrive ist durchgängig verfügbar. + +4. Testen, ob das Update erfolgreich war (z.B. + , oder + und im Azure Log + Analytics) + +5. Im FraNow Change Implementierung beenden. + +6. Weitere Prüfungen vornehmen. + +7. Im FraNow Change nach Prüfung abschließen und Ergebnis eintragen. + +Bemerkungen +=========== + +Der erste Abschnitt entspricht dem Setup von Uni2work an der LMU. Deren +Deployment arbeitet mit einem Tag „latest" so dass alle weiteren +Schritte dort automatisch erfolgen. Das Cloud-Team erzwingt aber die +Verwendung von absoluten und genehmigungspflichtigen Tags (Abschnitte 2 +& 5). + +Abschnitt 3 wurde von Francesco Silvani nach den Anforderungen von +Steffen Jost gestaltet. Hier befindet sich auch die +Kubernetes-Konfiguration des Containers, z.B. wie viele Pods mit welchen +CPU/Speicher Eckwerten gestartet werden. + +DB-Migrationen / Downtime +========================= + +Bei der oben beschriebenen Prozedur entstehen keine Downtimes: +Kubernetes startet die neue Version parallel zur alten Version und +beendet die alte Version erst, wenn die neue Version stabil läuft. +Nutzer merken davon in der Regel nichts, im schlimmsten Fall wird ein +abgesendetes Formular ignoriert und muss ein Formular neu gesendet +werden. Es empfiehlt sich daher, die Fahrerausbildung rechtzeitig vorab +zu informieren, so dass kein Entzug/Gewährung einer Fahrlizenz deshalb +verloren geht (eigentlich sollte der Nutzer aber immer die Bestätigung +eine Anfrage abwarten). + +Falls bei einem Upgrade eine DB-Migration vorgenommen werden muss, so +dürfen alte Version und neue Version aber nicht parallel laufen, da +Konflikte zwischen den Versionen entstehen. Davon ausgenommen sind +DB-Migration, welche das Yesod-Framework als fail-safe betrachtet, z.B. +das Hinzufügen von neuen optionalen Spalten. In allen anderen Fällen +muss eine Downtime geplant und mit der Fahrerausbildung und den FRADrive +Nutzern abgesprochen werden: im ersten Fall per Email und im zweiten +Fall per Systemnachricht innerhalb von FRADrive, welche nach dem +Einloggen angezeigt wurde. + +Vorgehensweise: + +1. In der conf Datei in DevOps FraDrive Deployment im Abschnitt + „global:" ist „enabled: false" einzustellen. In Chart.yaml ist die + Chart-Version zu erhöhen. + +2. Nach Commit & Push sollte die entsprechende Instanz (test/qa/prod) + herunterfahren und nicht mehr erreichbar sein. + +3. Danach enabled wieder auf true setzen, Image-Version und + Chart-Version erhöhen. Nach Commit & Push sollte der neue Container + hochfahren und dabei die DB-Migration einmalig durchführen. +