Eine Anwendung auf der ICC betreiben

Support

Falls Sie Verbesserungsvorschläge oder Anmerkungen bezüglich dieses Tutorials haben oder Sie auf Probleme bei dem Arbeiten mit der ICC stoßen, dann nutzen Sie bitte unseren MS-Teams-Kanal.

Vorbedingungen zum Arbeiten auf dem lokalen Computer

  • Git ist installiert: Link
  • Docker installiert
  • kubectl installiert: Link
  • Zugriff auf die ICC von außerhalb des HAW-Netzes nur mit aktiver VPN-Verbindung
  • Bei der ICC eingeloggt und eine Namensraum (Namespace/Space) erstellt. Weitere Informationen sind dazu hier zu finden.

Allgemeine Hinweise

  • Nutzung im PC - Pool: Die Benutzung von icc-login, kubectl und Docker ist zurzeit unter Windows in den PC - Pools nicht möglich. Unter Linux kann icc-login und kubectl benutzt werden.
  • Weltweite Erreichbarkeit: Standardmäßig sind die Dienste, die innerhalb der ICC zur Verfügung gestellt werden können, nur innerhalb des HAW Netzes erreichbar. Wenn eine weltweite Erreichbarkeit gewünscht ist, dann wenden Sie sich dazu an die Kanäle, die unter dem Punkt Support aufgeführt sind.
  • Nur Windows: Verwenden Sie NICHT die mingw shell, die etwa bei einigen Git Installationen dabei ist. Hier werden keine interaktiven Sessions, etwa für Passworteingabe unterstützt. Nutzen Sie stattdessen das übliche CMD, die PowerShell oder Bash for Windows.
  • Windows & macOS: Im Nachfolgenden sind die Docker Befehle mit sudo angegeben, dies ist nur für die Linuxanwender relevant. Unter Windows und Mac OS ist sudo nicht nötig.
  • Für Docker muss Ihre CPU die vT Erweiterung unterstützen. Alle modernen CPUs haben diese, bei einigen Laptops lässt sich die Erweiterung im Bios aktivieren. Einige alte Geräte mit älteren Prozessoren haben leider keine vT Erweiterung. Hier müssen Sie auf die lokale Ausführung von Docker verzichten.
  • Nutzen Sie bei der Namensgebung von Ressourcen innerhalb von Kubernetes z. B. Servicenamen oder Secrets, immer nur Zahlen, Kleinbuchstaben und Bindestriche. Ansonsten wird es zu Problemen führen.
  • Wenn Sie mit dem Tutorial durch sind, löschen Sie bitte das Deployment wieder mit: 
    1

    kubectl delete deployment haw-world -n <space-name>

    oder

    1

    kubectl delete -f deploy.yaml -n <space-name>

Erstellung und Auslieferung einer Beispiel-Webapplikation

Anlegen des Projekts

  1. Melden Sie sich bei Gitlab mit Hilfe des nachfolgenden Links an: Link
  2. Klicken Sie im ’Projects’-Fenster auf den grünen New project-Button und erstellen Sie ein neues, privates Projekt mit dem Namen „haw-world“.
  3. Öffnen Sie Ihr Projekt in GitLab, drücken Sie auf den Button 'Clone' und kopieren Sie den Link bei SSH.
  4. Öffnen Sie nun ein Terminal/Shell auf Ihrem Computer und navigieren Sie in ein Verzeichnis, in dem Sie Ihre Projekte verwalten.
  5. Geben Sie in Ihrem Terminal den folgenden Befehl ein, um Ihr Git - Repository lokal zur Verfügung zu haben: 
    1
2

    # Die GitLab Repository URL ist ohne die <> Zeichen anzugeben
git clone <Ihre GitLab Repository URL, aus dem vorherigen Schritt>

Erstellen der Beispielapplikation und der Docker Images

  1. Starten Sie Docker auf Ihrem Rechner.

  2. Im Folgenden erstellen Sie die Webapplikation, die nach dem Start einen Text ausgibt. Als Arbeitsverzeichnis dient das Verzeichnis, aus dem vorherigen Schritt 1.1. Erstellen Sie eine Datei index.php mit folgendem Inhalt:

    1
2
3
4
5

    <?php
echo "Hello HAW-World!";
// Zugriffsdatum protokollieren
file_put_contents("data/haw-world.log", strftime("%d.%m.%Y-%H:%M") . " ", FILE_APPEND);
?>

  3. Damit Docker weiß, wie das Image aussehen soll, erstellen Sie in Ihrem Arbeitsverzeichnis eine Datei namens Dockerfile mit folgendem Inhalt:

    1
2
3
4
5
6
7

    # inherit from the php:7.1-apache image from docker hub
FROM php:7.1-apache
# create data Directory and set permissions
RUN mkdir -p /var/www/html/data
# copies your php files
COPY . /var/www/html/
RUN chown -R www-data:www-data /var/www/html/*

  4. Fügen Sie alle neue Dateien Ihrem Git Repository hinzu, committen und pushen Sie diese:

    1
2
3

    git add .
git commit -m “Added basic files”
git push -u origin

  5. Loggen Sie sich bei der Informatik-Docker-Registry mit Ihrem infw-Account ein:

    1

    sudo docker login git.haw-hamburg.de:5000

  6. Erzeugen Sie nun das Image haw-world durch Ausführen des nachfolgenden Befehls (Punkt am Ende für das aktuelle Verzeichnis nicht vergessen):

    1

    sudo docker build -t haw-world .

  7. Lassen Sie sich das erzeugte Image mit dem nachfolgenden Befehl anzeigen.

    1

    sudo docker images

    Die Ausgabe sollte ähnlich zu der in der nachfolgenden Abbildung aussehen:

    Beispielausgabe des Befehls

    Beispielausgabe des Befehls

  8. Damit das Docker Image in die Docker-Registry hochgeladen werden kann, muss ein spezieller Alias vergeben werden, dieser wird von GitLab vorgegeben.
    Sie finden diesen, in dem Sie Ihr Projekt in GitLab öffnen und dort den Punkt Deploy -> Container Registry aufrufen. In der nachfolgenden Abbildung sehen Sie einen Ausschnitt aus dem Menüpunkt. Die für Sie relevante Information wurde in der Abbildung mit einem roten Kasten markiert. Sie können die Information im Kasten durch einen Druck auf den danebenstehenden Button kopieren.

    Ausschnitt aus dem GitLab Registry Menüpunkt

    Ausschnitt aus dem GitLab Registry Menüpunkt

  9. Um dem Image einen Alias zu geben, muss man es taggen.

    1

    sudo docker tag haw-world <Pfad aus Container Registry>

  10. Lassen Sie sich erneut die lokal vorhandenen Images anzeigen, die Ausgabe des Befehls sollte ähnlich zu der in der nachfolgenden Abbildung sein.

    Beispielausgabe des Befehls

    Beispielausgabe des Befehls


    Kontrollieren Sie, dass die IMAGE ID bei beiden erzeugten Images identisch ist, da es sich bei dem neu benannten Image, lediglich um einen Alias handelt.

  11. Laden Sie Ihr Image nun mit dem push Befehl in die Informatik-Docker-Registry:

    1

    sudo docker push <Pfad aus Container Registry>

Deployment (Auslieferung) der Applikation in die ICC

  1. Erstellen Sie in GitLab ein Deploy-Token, dieses benötigt Kubernetes, damit auf private Repositories zugegriffen werden kann.

    1. Öffnen Sie Ihr Projekt in GitLab.
    2. Öffnen Sie über die Navigationsleiste den Punkt Settings -> Repository und öffnen über den Button 'Expand' den Punkt Deploy Token. Sie sollten anschließend, wie in der nachfolgenden Abbildung zusehen ist, den Menüpunkt vor sich haben.
      Ausschnitt des Menüpunkts Deploy Token

      Ausschnitt des Menüpunkts Deploy Token

    3. Geben Sie im Feld Name einen Namen für das Token ein z.B. Haw World Tutorial.
    4. Sie können auch ein Verfalldatum angeben, in dem Sie in das Feld 'Expires at' klicken und dann anschließend über den Kalender ein Datum auswählen.
    5. Es ist auch möglich, einen eigenen Benutzernamen anzugeben, wenn Sie mit dem von GitLab generierten unzufrieden sind. Ansonsten lassen Sie das Feld leer.
    6. Setzten Sie den Haken beim Feld 'read_registry'. Danach sollte dies ungefähr so bei Ihnen aussehen, wie in der nachfolgenden Abbildung zu sehen ist.
      Ausschnitt des Menüpunkts Deploy Token ausgefüllt

      Ausschnitt des Menüpunkts Deploy Token ausgefüllt

    7. Klicken Sie anschließend auf den Button 'Create deploy token'.
    8. GitLab zeigt Ihnen anschließend in einem neuen Fenster, den Benutzernamen und das Passwort für das Token an.
    9. Kopieren Sie sich die beiden Informationen. GitLab stellt Ihnen das Passwort nicht noch einmal zur Verfügung und Sie benötigen die beiden Informationen im nächsten Schritt.

  2. Vorbereitung für den Zugriff auf die ICC:

    • Sollten Sie sich innerhalb der letzten 7 Tagen noch nicht bei der ICC angemeldet haben, dann tun Sie dies jetzt und holen sich Ihre Konfiguration. Weitere Informationen dazu finden Sie hier. Sie können sich Ihre Spaces mit folgendem Befehl anschauen: 
      1

         kubectl get spaces
    • Möchten Sie nicht im default-Space arbeiten, sollten Sie spätestens nun einen eigenen Space erstellt haben. Weitere Informationen dazu finden Sie unter Erste Schritte: Einen neuen Space erstellen.

  3. Damit Kubernetes auf Ihr Repository zugreifen kann, müssen die Tokens aus dem vorherigen Schritt als Secret angelegt werden. Führen Sie dazu den folgenden Befehl aus und ergänzen Sie die fehlenden Informationen.

    1
2
3
4

    kubectl create secret docker-registry <secret-name> -n <space-name> \
--docker-server=git.haw-hamburg.de:5000 \
--docker-username=<token-benutzername> \
--docker-password=<token-passwort>
    • Bei <secret-name> tragen Sie einen Namen für das Secret ein, dieses wird später noch benötigt. Nutzen Sie hier nur Zahlen, Kleinbuchstaben und Bindestriche.
    • Bei <space-name> tragen Sie den Namen Ihres Spaces ein, welchen Sie vorher erstellt haben.
    • Bei <token-benutzername> geben Sie den Benutzernamen des Token aus Schritt 1 an.
    • Bei <token-passwort> geben Sie das Passwort des Token aus Schritt 1 an.

  4. Erstellen Sie nun eine Beschreibungsdatei mit dem Namen deploy.yaml für das Deployment des Containers in der ICC mit folgendem Inhalt (Achtung: Einrückungen haben semantische Bedeutung und dürfen nicht verändert werden.)

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

    apiVersion: apps/v1
kind: Deployment
metadata:
  name: haw-world
  namespace: <space-name>
  labels:
    service: haw-world
spec:
  selector:
    matchLabels:
      service: haw-world
  template:
    metadata:
      labels:
        service: haw-world
    spec:
      containers:
        - image: git.haw-hamburg.de:5000/<GitLab-Gruppe(=infw-Kennung)>/haw-world
          name: haw-world
          ports:
            - containerPort: 80
              protocol: TCP
      imagePullSecrets:
        - name: <secret-name>
---
apiVersion: v1
kind: Service
metadata:
  name: haw-world
  namespace: <space-name>
  labels:
    service: haw-world
spec:
  ports:
    - name: http
      port: 80
      protocol: TCP
      targetPort: 80
  selector:
    service: haw-world
  type: ClusterIP
    • Ersetzen Sie <GitLab-Gruppe(=infw-Kennung)> durch Ihre infw-Kennung.
    • Ersetzen Sie <secret-name> durch den Namen, den Sie in Schritt 1 festgelegt haben.
    • Ersetzen Sie <space-name>\ durch den Namen des Spaces, welchen Sie vorher erstellt haben.

  5. Fügen Sie die YAML-Datei Ihrem Git-Repository hinzu.

    1
2
3

    git add deploy.yaml
git commit -n -m "Added YAML - Deploy file"
git push -u origin

  6. Bringen Sie nun dieses Deployment via kubectl in das Cluster. Führen Sie dazu folgenden Befehl aus:

    1

    kubectl apply -f deploy.yaml

    Das Cluster startet nun Ihre Container in den Pods und erzeugt dazu Services, so dass diese Container zugänglich sind.

  7. Sehen Sie sich das Ergebnis mit folgendem Befehl an.

    1

    kubectl get deploy,pod,svc

    Die Ausgabe des Befehls sollte ähnlich wie in der nachfolgenden Abbildung aussehen.

    Ergebnis des Befehls

    Ergebnis des Befehls


    Die Ausgabe zeigt Ihnen ihren Pod Namen an (alles ab dem Punkt pod/), ob der Pod Ready ist, den Status, hier sollte Running stehen, die Anzahl der Neustarts (Restart.), hier sollte am Anfang 0 stehen und das Alter (Age).

  8. Führen Sie nun den kubectl proxy in Ihrem Terminal/shell aus, damit Sie auf Ihre Webseite von Ihrem Rechner aus zugreifen können und lassen Sie das Fenster offen.

    1

    kubectl proxy

    Sie können nun Ihren Service über die folgende URL aufrufen:
    localhost:8001/api/v1/namespaces/<ProjektNamespace>/services/<ServiceName>:http/proxy/
    Ergänzen Sie die Felder <Projekt Namespace> und <ServiceName> um Ihre entsprechenden Daten.

  1. (Optional) Um eine interaktive Shell in Ihrem Container zu erhalten, geben Sie bitte ein: 
    1

    kubectl exec -it <Name des Pods> -n <space-name> -- bash
  2. Löschen Sie nun Ihr Deployment und damit den haw-world Pod, in dem Sie folgenden Befehl eingeben:
1

kubectl delete deployment haw-world -n <space-name>

oder

1

kubectl delete -f deploy.yaml