k8s-receptionservice

README

Projektbeispiel Receptionservice

Dies ist ein Basisprojekt für das Wahlpflichtfach im Sommersemester 2020 mit Stefan Sarstedt und Christian Bargmann.

Viel Spaß!

Installation und Konfiguration

1. Stelle sicher, dass Du Folgende Software installiert hast:

   • git (https://git-scm.com)
   • die aktuellste go Version (im Augenblick 1.14.x, https://golang.org). Führe zum Testen "go version" aus.
   • JetBrains GoLand (aktuelle Version ist 2020.1 RC). Zum einfacheren Update von GoLand kannst Du die JetBrains ToolBox (https://www.jetbrains.com/toolbox-app/) installieren. Diese übernimmt automatische das Updaten Deiner Jetbrains-Produkte.
   • Docker und Docker Compose (https://www.docker.com/get-started).
   • Postman (https://www.postman.com).
   • Unter Windows: wir benötigen make - hier gibt es mehrere Möglichkeiten zur Installation, bspw. mittels Cygwin (https://cygwin.com):
     • Wähle beim Installer die beiden Pakete gcc-core und make in den aktuellsten Versionen und installiere diese.
     • Füge dann noch C:\cygwin64\bin zu Deiner Umgebungsvariablen PATH hinzu, damit Du die cygwin-Tools (make, rm, ...) von Deinem normalen Terminal (Command) aus verwenden kannst (starte das Terminal neu, damit die Änderungen wirksam werden).

2. Forke dieses Projekt in Deinen GitLab-Namespace. Falls dies nicht geht, weil Du dieses Projekt bereits geforkt hast: Benenne dein altes Projekt in Deinem Namespace unter Settings->General->Advanced->Rename project um (benenne sowohl den Projektnamen, als auch den Repository-Link um!). Danach entfernst Du die Fork-Beziehung unter Settings->General->Advanced->Remove fork relationship. Danach kannst Du dieses Projekt in Deinen Namespace neu forken.

3. Klone Deinen Fork (git clone).

4. Aktiviere in Deinem GitLab-Projekt unter Settings->CI/CD->Runners die Shared Runners, falls dieser noch nicht aktiv ist.

5. Öffne das geklonte Projekt in JetBrains GoLand.

6. Stelle sicher, dass in JetBrains GoLand Settings/Preferences->Go->GOROOT auf Deine Installation von Go korrekt gesetzt ist.

7. Aktiviere in JetBrains GoLand in Settings bzw. Preferences die Option Go->Go Modules->Enable Go Modules integration, damit GoLand die Module erkennt.

   Hinweis: jeder Microservice enthält eine Datei go.mod, die das dortige go-Modul definiert. Der Modulname ist dort in der ersten Zeile definiert: module git.haw-hamburg.de/aat913/<name des Microservice>. Alle lokalen Imports in diesem Microserviceprojekt beziehen sich auf das Modul. Beispielsweise in der main.go der Import:

   import (
      ...
      "git.haw-hamburg.de/aat913/receptionservice/internal/app"
      ...
   )
   

   In einem Realprojekt würdet Ihr dieses Modulnamen natürlich ändern. Dies ist bei uns allerdings nicht nötig, es kommt nicht zu Konflikten mit den anderen Projekten.

8. Um das Projekt in Goland ausführen und debuggen zu können: füge eine Go Run-Konfiguration (in der Toolbar in GoLand) für dieses Projekt in GoLand mittles "+ -> Go Build" hinzu, damit Du Deinen Microservice auch über die IDE starten kannst. Achte darauf, dass Du als Run kind die Option Directory wählst und bei Directory das .../cmd/service-Verzeichnis des Microservices referenziert wird. Unter Working directory muss das Verzeichnis des Microservices gesetzt sein, ansonsten kommt es zu einem Fehler, dass das go-Modul nicht gefunden werden kann. Aktiviere auch Run after build. Nun kannst du den Service über die Toolbar (grüner Pfeil) starten.

9. Installiere ein Datenbanktool für MySQL/MariaDB (z.B. MySQLWorkbench, https://www.mysql.com/de/products/workbench/ oder mysqlsh, https://dev.mysql.com/doc/mysql-shell/8.0/en/mysqlsh.html) und eines für MongoDB (z.B. mongoDB compass, https://docs.mongodb.com/compass/current/install/), um die Inhalte der Datenbanken anzusehen.

Ausführen des Projekts lokal

1. Führe im Terminal (View->Tool Windows->Terminal) in GoLand im Projektverzeichnis den Befehl make build aus. Dies lädt initial alle abhängigen Pakete herunter.
2. Öffne die Datei http.go Deines Projekts. Hier sollte nun nichts (mehr) rot markiert sein.
3. Starte die backingservice-container mittels docker-compose up -d. Schaue mit docker ps, ob sie laufen.
4. Führe im Terminal in GoLand im Projektverzeichnis den Befehl make test aus. Diese sollten erfolgreich durchlaufen.
5. Schaue mit Deinem Datenbanktool für MySQL/MariaDB nach, welche Tabellen durch das Ausführen der Testfälle erstellt und gefüllt wurden.
6. Arbeite mit Postman mit Deiner REST-API (POST /customers und GET /customers), d.h. lege neue Customer an und lasse alle Customer anzeigen. Prüfe den Zustand in Deiner Datenbank mittels Deines Datenbanktools.

Setup für die Google Cloud Platform (GCP) / Google Kubernetes Engine (GKE)

Voraussetzungen: Du hast einen Google Cloud Platform Account und hast das Cloud SDK installiert und eingerichtet.

1. Erstelle ein neues GCP-Projekt (oder nehme ein vorhandenes) und merke Dir die Projekt-ID.
2. Aktiviere unter APIs & Services->Dashboard die folgenden APIs: Compute Engine API, Container Registry API, Kubernetes Engine API, Cloud Logging API und Cloud Pub/Sub API.
3. Erstelle unter IAM & Admin->Service accounts einen Serviceaccount mit Project->Owner-Rechten; diesen benötigen wir, damit unser Projekt aus der Gitlab-Pipeline in die Google Cloud deployed werden kann. Exportiere am Ende des Erstellens das JSON-Servicetoken an einen sicheren Ort auf Deinem Rechner. Sei vorsichtig: Checke das Token nicht mit in Dein Git-Repository ein! Falls Du den Serviceaccount neu anlegen musst (bspw., weil Du falsche Berechtigungen gesetzt hast), wähle einen anderen Namen! Siehe hier unter Deleting and recreating service accounts. Details zu Serviceaccounts findest Du hier.
4. Installiere das kubectl-Tool mittels gcloud components install kubectl.
5. Ändere am Anfang Deines makefile die folgenden Variablen:
   • GCP_PROJECTID auf die Google-Cloud-Projekt-ID aus Schritt 1.
   • GCP_CLUSTER auf den Namen Deines Kubernetes-Clusters.
6. Lege einen Kubernetes-Cluster an mittels make clusterUp, falls in Deinem Projekt noch kein Cluster vorhanden ist.
   -- Wenn der Cluster per UI erzeugt wurde, dann führe folgendes aus: gcloud container clusters get-credentials <ClusterName>
7. Setze in Deinem Gitlab-Projekt die folgenden Variablen unter Settings->CI/CD->Variables:
   • GCP_PROJECTID (Type: Variable) auf die Google-Cloud-Projekt-ID aus Schritt 1.
   • GCP_GITLAB_TOKENFILE (Type: File) auf den Inhalt des erzeugten Serviceaccount-Tokens aus Schritt 3.
   • GCP_CLUSTER (Type: Variable) auf den Namen Deines Kubernetes-Clusters.
8. Triggere Deine gitlab-Pipeline - sie sollte nun grün sein.
9. Beobachte den Status der Deployments in Deinem Cluster mittels kubectl get pods,svc,deploy.
10. Richte ein Port-Forwarding ein (kubectl port-forward service/receptionservice 8080:8080) und teste Deine API z.B. mittels curl localhost:8080/customers oder Postman.

Credits für dieses Projekt

• https://github.com/PacktPublishing/Cloud-Native-programming-with-Golang
• https://github.com/demo-apps/mux-postgres-rest
• https://github.com/italolelis/coffee-shop