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 schicken Sie bitte eine Mail an: icc@informatik.haw-hamburg.de oder nutzen Sie MS-Teams.

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 HAW Account ein:

    1
    
    sudo docker login git.haw-hamburg.de:5005
    
  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 Packages -> 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 Hacken 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:5005 \
    --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.
    • Bei <your-email> tragen Sie Ihre HAW - Mail Adresse ein.
  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:5005/<GitLab-Gruppe(=HAW-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(=HAW-Kennung)> durch Ihre HAW-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