//Cloudogu EcoSystem Docs

Dokumentation

Das Admin-Dogu ist ein Tool im Cloudogu EcoSystem zur Verwaltung und Pflege von Dogus. Indem das Admin-Dogu Funktionen, die in anderen Systemen oft nur über die Konsole erreichbar sind, über eine Oberfläche anbietet, können Sie als Administrator:in Ihr Cloudogu EcoSystem mit nur wenig Aufwand verwalten.

Sie erreichen das Admin-Dogu im Warp Menü über den Eintrag "Administration" im gleichnamigen Abschnitt.

Das Admin-Dogu bietet aktuell folgende Funktionen:

• Dogu Management
• Wartung.

Dogu Management

Mithilfe des Dogu Managements können Sie Dogus starten, stoppen und neustarten sowie die Logs von einzelnen Dogus herunterladen.

Für die Benutzung des Bereichs Dogu Managements wird eine Rolle mit mindestens lesendem Zugriff benötigt.

Für die Benutzung der Start/Stopp/Neustart-Aktionen des Bereichs Dogu-Management wird eine Rolle mit mindestens schreibendem Zugriff benötigt.

In der Standardansicht sehen Sie die Dogus, die über das Warp Menü erreichbar sind. Die im EcoSystem genutzten Systemkomponenten können Sie ebenfalls über das Dogu Management verwalten. Dazu aktivieren Sie die Checkbox System-Dogus einblenden, wodurch eine weitere Tabelle mit Systemkomponenten eingeblendet wird.

Logs herunterladen

Mithilfe der Logs ist es möglich, interne Abläufe nachzuvollziehen oder mögliche Fehler zu untersuchen.

Der Bereich Dogu Managements listet dabei alle installierten Dogus auf. Für jedes Dogu haben Sie über die Aktion Logs herunterladen die Möglichkeit, eine Log-Datei herunterzuladen. Die Aktion erreichen Sie mit einem Klick auf das Dreipunktmenü in der Spalte Aktionen.

Ein Klick auf Logs herunterladen öffnet dabei einen Dialog, über den Sie angeben, wie viele Zeilen des Logs Sie herunterladen möchten.

Ist die Checkbox Komplett aktiviert, wird nach Bestätigen über die Schaltfläche Herunterladen die gesamte Log-Datei heruntergeladen.

Deaktivieren Sie das Kontrollkästchen Komplett, können Sie im Feld Zeilen die Anzahl der zuletzt entstandenen Log-Zeilen angeben, die heruntergeladen werden sollen.

Werden 0 Zeilen angegeben, wird die gesamte Log-Datei heruntergeladen.

Die Log-Datei wird als Archiv (.zip) heruntergeladen.

Start, Stopp und Neustart

Im Dogu Management werden dabei alle zur Verfügung stehenden Dogus angezeigt.

Unter Aktionen können Sie - mit einem Klick auf das Dreipunktmenü - jedes angezeigte Dogu starten, stoppen oder neustarten. Es sind jeweils nur die Aktionen verfügbar, die Sie aktuell auch ausführen können. Bei einem aktuell laufenden Dogu können Sie beispielsweise nicht die Aktion Starten wählen.

Ist ein Dogu oder eine Systemkomponente relevant für die Erreichbarkeit der Umgebung, wird die Stop-Aktion aktiv unterbunden. Andernfalls würde sich das Dogu im Anschluss nicht wieder über die Benutzeroberfläche starten lassen.

Für jedes Dogu wird der aktuelle Status des Dogus angezeigt. Die folgenden Zustände sind für ein Dogu möglich:

• gestartet: Das Dogu läuft und ist erreichbar.
• gestoppt: Das Dogu wurde gestoppt und ist nicht erreichbar.
• startet neu: Das Dogu wurde kürzlich neu gestartet und befindet sich im Startvorgang.
• startet: Das Dogu war gestoppt, wurde kürzlich gestartet und befindet sich im Startvorgang.
• stoppt: Das Dogu war gestartet, wurde kürzlich gestoppt und befindet sich im Stoppvorgang.
• unbekannt: Es gab einen Fehler bei der Abfrage des Dogu-Zustandes.

Wählen Sie Stoppen oder Neustarten eines Dogus aus, müssen Sie die jeweilige Aktion in einem sich öffnenden Dialogfenster bestätigen.

Das Starten eines Dogus muss nicht erneut bestätigt werden. Ein erfolgreiches Starten, Stoppen oder Neustarten eines Dogus wird über eine Erfolgsmeldung im unteren Bildbereich angezeigt.

Sollte es beim Starten, Stoppen oder Neustarten eines Dogus zu einem Fehler kommen, wird dieses mit einer Fehlermeldung im unteren Bereich angezeigt.

Wartung

Mithilfe der Wartung können Sie den Debug-Modus aktivieren bzw. deaktivieren. Zusätzlich können Sie ein Support-Paket, das Log-Dateien und weitere relevante Informationen über das System enthält, erstellen und herunterladen. Das Support-Paket kann den Support der Cloudogu GmbH bei der Analyse von Problemen im Cloudogu EcoSystem unterstützen.

Für die Benutzung des Bereichs Wartung wird eine Rolle mit schreibendem Zugriff benötigt.

Sowohl zum Debug-Modus als auch zum Support-Paket finden Sie direkt neben den Funktionen weitere hilfreiche Hinweise, die Sie beim Nutzen der Funktionen unterstützen können.

Funktion Support-Paket

Mit einem Klick auf die Schaltfläche Neues Support-Paket erzeugen können Sie ein neues aktuelles Support-Paket erstellen. Bereits erstellte Support-Pakete können Sie hier direkt als Archiv (.zip) herunterladen oder löschen.

Die erzeugten Support-Pakete werden in einem Verzeichnis auf dem Host-System gespeichert und können jederzeit erneut heruntergeladen werden, ohne dass sie neu zusammengestellt werden müssen.

Im Support-Paket sind folgende Informationen enthalten:

• Konfiguration

  • etcd/etcd.tree - Sämtliche Schlüssel, die im etcd gespeichert sind, als Baumstruktur (nur die Schlüssel, keine Werte)
  • etcd/etcd.json - Alle Schlüssel¹ sowie deren Werte in einer json-Datei (sensible Schlüssel sind ausgenommen)

• Logs

  • logs/[servicename].log - Die Logdateien aller installierten Dogus sowie der Services 'syslog', 'cesappd', 'cesapp', 'ces-setup' and 'backup-watcher'.

• Dogu-Informationen

  • dogu-information - Informationen über alle installierten Dogus, deren Status (gestartet, gestoppt etc.) sowie die Größe ihrer Volumes

• Umgebungsvariablen

  • env - Alle im System gesetzten Umgebungsvariablen

• Prozess-Informationen

  • process-information - Informationen zu allen laufenden Prozessen und Services, wie zum Beispiel 'cesappd' und dem 'backup-watcher'

• System-Informationen

  • system-information - Informationen zum System (Verbaute Hardware, Betriebssystem, Partitionen, Auslastung, Speicherverbrauch, installierte Pakete)

• Volume-Informationen

  • volume-information - Liste mit den Dateinamen aller Volumes der vorhandenen Dogus

¹ Sie können Werte von Verzeichnisse oder Schlüsseln aus der Datei etcd/etcd.json ausschließen. Dafür müssen Sie die Schlüssel im etcd unter config/_global/debug/excluded_etcd_keys hinterlegen. Im folgenden Beispiel sind die Schlüssel config und dogu_v2 aus der Datei etcd/etcd.json ausgeschlossen:

config/_global/debug/excluded_etcd_keys/<frei-wählbarer-name-1> => config config/_global/debug/excluded_etcd_keys/<frei-wählbarer-name-2> => dogu_v2

In der Datei etcd/etcd.json sind die Werte beider Schlüssel dann zensiert:

{ 
   "config" : "***",
   "dogu_v2" : "***"
}

Funktion Debug-Modus

Der Debug-Modus setzt alle Dogus auf das höchste Log-Level (Log-Level = DEBUG), wodurch diese die maximale Menge an Logs ausgeben. Daher können Sie den Debug-Modus gut zum Reproduzieren von Fehlern nutzen. Anschließend können Sie das Support-Paket mit den erweiterten Log-Informationen erzeugen.

Beachten Sie, dass eine Aktivierung bzw. Deaktivierung des Debug-Modus die Log-Dateien leert (die alten Logs werden dabei archiviert). Daher sollten Sie ein gewünschtes Support-Paket vor der Deaktivierung des Debug-Modus erzeugen. Es kann außerdem sinnvoll sein, auch vor Aktivierung des Debug-Modus ein Support-Paket zu erzeugen.

Eine Aktivierung des Debug-Modus ist nur für maximal 60 Minuten möglich, damit es aufgrund des erhöhten Log-Levels nicht zu Problemen kommt; das im Debug-Modus eingestellt Log-Level kann sehr viel Output produzieren, wodurch Log-Files mehrere 100 Mb groß werden könnten.

Ein Klick auf die Schaltfläche Aktivieren öffnet einen Dialog zum Bestätigen des Vorgangs. Über die Schaltfläche Abbrechen können Sie den Dialog schließen, ohne den Debug-Modus zu starten.

Beachten Sie beim Aktivieren des Debug-Modus, dass das gesamte System inkl. des Admin-Dogus für mehrere Minuten nicht mehr über die Benutzeroberfläche erreichbar ist. Beim Aktivieren des Debug-Modus wird Ihnen diese Information auch angezeigt.

Während der Debug-Modus aktiviert wird, wird das System für einige Minuten in den Wartungsmodus versetzt und die Log-Level werden konfiguriert. Der Wartungsmodus wird Ihnen über eine Wartungsseite angezeigt, wenn Sie die Umgebung über die Benutzeroberfläche zu erreichen versuchen.

Wenn der Wartungsmodus beendet wurde, müssen Sie die Browser-Seite neu laden. Die Seite wird nicht automatisch aktualisiert.

Ist der Debug-Modus aktiv, haben Sie mit der Schaltfläche Debug-Modus deaktivieren die Möglichkeit, den Debug-Modus vor Ablauf der eingestellten Zeit beenden zu können.

Wie lange der Debug-Modus noch aktiv ist, sehen Sie an einem Hinweis unterhalb der Navigationsleiste. Dieser wird in allen Bereichen des Admin-Dogus angezeigt.

Wenn die Deaktivierung des Debug-Modus in weniger als fünf Minuten durchgeführt wird, wird der Hinweis hervorgehoben angezeigt.

Den Debug-Modus sollten sie deaktivieren, sobald Sie ihn nicht mehr benötigen, beispielsweise nachdem Sie den Fehler reproduziert und das Support-Paket erstellt haben.

Durch einen Klick auf Debug-Modus stoppen bekommen Sie erneut einen Dialog angezeigt, in dem Sie bestätigen, dass die Umgebung für einige Minuten nicht benutzbar sein wird. Auch beim Deaktivieren des Debug-Modus ist das System für mehrere Minuten nicht erreichbar und befindet sich im Wartungsmodus.

Nach der Bestätigung bekommen Sie auch hier den Hinweis noch einmal angezeigt.

Nach einer erfolgreichen Deaktivierung des Debug-Modus können Sie das System wieder wie gewohnt nutzen.

Rollen und Berechtigungen

Aktuell existieren im Admin-Dogu Rollen für den lesenden, schreibenden und administrierenden Zugriff auf die Anwendungsfunktionalitäten. Ihre zugeordnete Rolle können Sie in der Navigationsleiste des Admin-Dogu am Benutzerbild links vom eigenen Benutzernamen sehen.

Die Rollen sind im Default vordefiniert. Über die Konfiguration des Admin-Dogus im etcd können Sie diese jedoch Ihren Wünschen entsprechend umbenennen.

cesapp edit-config admin

Um Nutzer:innen die entsprechenden Rollen zuzuordnen, legen Sie manuell entsprechende Gruppen im Usermanagement an und ordnen Sie die Nutzer:innen wie gewünscht zu. Beachten Sie dabei, dass die Gruppen dabei den gleichen Namen haben sollten wie in der Konfiguration des Admin-Dogus im Etcd definiert.

Benutzer ohne mindestens eine dieser Rollen haben keinerlei Zugriff auf das Admin-Dogu.

Lesender Zugriff

Benutzer mit dieser Rolle haben Zugriff auf das Admin-Dogu und können hauptsächlich Informationen einsehen, aber keine Einstellungen am System vornehmen.

Die Rolle können Sie folgendermaßen konfigurieren:

config/admin/groups/reader

Im Default ist diese Rolle als adminReaders definiert.

Schreibender Zugriff

Benutzer mit dieser Rolle haben Zugriff auf das Admin-Dogu und können zusätzlich Daten über die Oberfläche verändern.

Die Rolle können Sie folgendermaßen konfigurieren:

config/admin/groups/writer

Im Default ist diese Rolle als adminWriters definiert.

Administrierender Zugriff

Benutzer mit dieser Rolle haben Zugriff auf das Admin-Dogu und können alle verfügbaren Funktionen über die Benutzeroberfläche verwenden. Neben der über config/admin/groups/admin konfigurierten Gruppe, erhalten auch alle Benutzter administrative Berechtigungen, wenn ihnen über das User Management die allgemeine Admin-Gruppe des Cloudogu EcoSystem zugewiesen wurde.

Die Rolle können Sie folgendermaßen konfigurieren:

config/admin/groups/admin

Im Default ist diese Rolle als adminAdmins definiert.

Troubleshooting

Zeigt das Admin-Dogu in den Tabellen statt der installierten Dogus Fehlermeldungen an, kann es an einer veralteten Version des cesappd-Services liegen. Das Admin-Dogu benötigt für die korrekte Funktionsweise einen cesappd-Service mindestens in Version 3.0.2.

Sie können eine aktuelle Version des cesappd-Services über apt installieren:

apt update && apt install cesappd

Sollte das den Fehler nicht beheben, können Sie das Admin-Dogu erneut installieren:

# aktuell installiertes Dogu entfernen
cesapp purge admin && \
# Dogu neu aus dem Premium-Namespace installieren
cesapp install premium/admin && \
# Dogu starten
cesapp start admin

Das Admin-Dogu hält keine Daten in einer Datenbank, die verloren gehen könnten.