Agent installieren

Der Agent ist Teil von Vaicoa Pro und Vaicoa Team, für Cloud- und dedizierte Server (Robot).

Der Vaicoa-Agent läuft auf deinen Linux-Servern und schickt, was die Hetzner Cloud API nicht sieht. Damit bekommst du:

• Festplatte, RAM und Load als Charts in der Detailansicht des Servers, mit Alarmen bei einer volllaufenden Festplatte und bei Speicherdruck.
• Warn-Log-Zeilen der letzten 72 Stunden im Log-Kontext, mit Alarmen bei kritischen Zeilen und gehäuften Fehlern.
• Job-Reports deiner Backups und Cronjobs.
• Dedizierte Server. Sie stehen nicht in der Hetzner Cloud API, der Agent ist also der einzige Weg, sie zu sehen.
• Einen Alarm, wenn der Server nicht mehr meldet: stopped reporting nach 5 Minuten ohne Metriken, kritisch bei einem dedizierten Server und eine Warnung bei einem Cloud-Server, den Hetzner weiterhin als laufend meldet. Siehe Alarmregeln.

Was du brauchst: einen Linux-Server mit systemd, curl und apt (Debian, Ubuntu) oder dnf/yum (RHEL-Familie), x86-64 oder Arm64, und root-Zugriff. Alle Details: Agent-Referenz.

Auf einem Server installieren

1. Öffne im Portal Überwachte Server und klick auf Server hinzufügen. Trag auf Ein Server den Servername ein, wähl die Art (Cloud oder Dediziert) und bei einem Cloud-Server sein Hetzner-Projekt. Klick auf Server registrieren.

2. Kopier das Agent-Token. Es wird einmal angezeigt und gehasht gespeichert, wie ein Passwort.

3. Führ auf dem Server den Befehl aus, den das Portal zeigt, als root:

   curl -fsSL https://get.vaicoa.com/agent | sh -s -- --token <agent_token>

   Er richtet zwei signierte Paket-Repositories ein (das von Vaicoa und das von Vector), installiert das Paket cloudviewer-agent mit apt oder dnf und registriert den Server.

4. Innerhalb einer Minute zeigt der Server unter Überwachte Server den Status Verbunden.

Achtung

Nimm für einen Hetzner-Cloud-Server ein Registrierungs-Token für die Flotte, auch für einen einzelnen Server. Nur die Flotten-Registrierung verknüpft den Agent mit dem Server in deinem Projekt. Mit einem Token pro Server kann Vaicoa die beiden noch nicht verknüpfen: Die Detailansicht des Servers zeigt keine Agent-Charts, Jobs oder Log-Zeilen, und das Löschen des Servers stellt ihn nicht außer Dienst. Tokens pro Server sind für dedizierte Server gedacht.

Danach verwaltet kein Skript mehr etwas auf dem Server: Der Agent ist ein OS-Paket und wird mit deinem normalen apt upgrade oder dnf upgrade aktualisiert. Jeder Server belegt einen der Plätze für überwachte Server in deinem Plan.

Mit dem Paketmanager installieren

Wenn du kein Skript in eine Shell pipen möchtest, richte das Repository selbst ein, und Vectors Repository, falls der Server es noch nicht hat.

Debian, Ubuntu

curl -fsSL https://get.vaicoa.com/keys/cloudviewer.gpg \
  -o /usr/share/keyrings/cloudviewer.gpg
echo "deb [signed-by=/usr/share/keyrings/cloudviewer.gpg] https://get.vaicoa.com/apt stable main" \
  > /etc/apt/sources.list.d/cloudviewer.list
apt update && apt install cloudviewer-agent
cloudviewer-agent enroll --token <agent_token>

RHEL-Familie

Leg /etc/yum.repos.d/cloudviewer.repo an:

[cloudviewer]
name=Vaicoa
baseurl=https://get.vaicoa.com/rpm
enabled=1
gpgcheck=1
repo_gpgcheck=1
gpgkey=https://get.vaicoa.com/keys/cloudviewer.gpg

dnf install cloudviewer-agent
cloudviewer-agent enroll --token <agent_token>

Das Paket tut nichts, bis enroll gelaufen ist, und enroll erneut auszuführen ist immer sicher. Für cloud-init, Ansible und ähnliche Werkzeuge schreibst du vor der Installation CV_AGENT_TOKEN=<agent_token> nach /etc/cloudviewer-agent/agent.env (Modus 0600); das Paket registriert den Server dann schon bei der Installation.

Eine Flotte registrieren

Für Hetzner-Cloud-Server, einen oder viele, und für Server, die ein Autoscaler anlegt, ersetzt ein Registrierungs-Token für die Flotte die Tokens pro Server.

1. Gib unter Überwachte Server → Server hinzufügen → Flotten-Registrierung dem Token ein Label, wähl das Hetzner-Projekt und klick auf Registrierungs-Token erzeugen. Kopier es; es wird einmal angezeigt.

2. Führ das auf jedem Server als root aus, oder aus cloud-init, Terraform user_data oder Ansible:

   curl -fsSL https://get.vaicoa.com/agent | sh -s -- --enroll-token <fleet_token>

Jeder Server identifiziert sich über Hetzners Metadaten-Dienst. Vaicoa gleicht ihn mit dem Inventar des Projekts ab und registriert ihn als eigenen überwachten Server, mit eigenem Token. Das Flotten-Token kann nur Server registrieren und wird nicht auf ihnen gespeichert, du kannst es also in Ansible Vault oder einem CI-Secret-Store ablegen. Den Befehl erneut auszuführen ändert nichts. Dedizierte Server haben keinen Metadaten-Dienst und brauchen Tokens pro Server.

Container und Kubernetes

Systeme ohne apt, dnf oder systemd, etwa Alpine, können das Container-Image nutzen. Auf Kubernetes betreibt das Helm-Chart ein DaemonSet. Mit einem Flotten-Token registriert sich jeder Node als eigener Server, und Ersatz-Nodes registrieren sich selbst. Die Nodes müssen Hetzner-Cloud-Server sein.

kubectl create secret generic cloudviewer-agent \
  --from-literal=enroll-token=<fleet_token>
helm install cloudviewer-agent \
  oci://ghcr.io/cloudviewer-app/charts/cloudviewer-agent \
  --set existingSecret=cloudviewer-agent

Values und der Single-Node-Fall stehen in der Chart-README.

Ein Token ohne Lücke rotieren

Ein Server kann zwei aktive Tokens gleichzeitig haben:

1. Klick unter Überwachte Server auf Agent-Token rotieren. Das neue Token wird einmal angezeigt; beide funktionieren.
2. Aktualisiere deine Hosts (cloudviewer-agent enroll --token <new_token>) und Secret-Stores. Die Zeile zeigt, wann jedes Token zuletzt benutzt wurde, so siehst du, wann alles umgestellt ist. Das kann Tage dauern.
3. Klick auf Rotation abschließen. Das alte Token funktioniert innerhalb von etwa zehn Sekunden nirgends mehr.

Agent-Token entziehen macht alle Tokens eines Servers auf einmal ungültig. Neues Token ausstellen reaktiviert einen Server mit entzogenen Tokens und behält seine Historie.

Einen Server entfernen

• Ein per Flotte registrierter Cloud-Server, den du über die Hetzner API löschst, zum Beispiel mit terraform destroy oder durch einen Autoscaler, wird von selbst außer Dienst gestellt: kein Offline-Alarm, Tokens entzogen, Platz im Plan sofort frei.
• Auf dem Server entfernt apt purge cloudviewer-agent oder dnf remove cloudviewer-agent Konfiguration, Token und gepufferte Daten, und der Server meldet sich selbst ab.
• Im Portal macht Server entfernen das Token ungültig. Der Server selbst bleibt unberührt, entferne also auch das Paket.

Ein außer Dienst gestellter Server bleibt 72 Stunden mit der Kennzeichnung Außer Dienst sichtbar, damit seine Logs und seine Job-Historie lesbar bleiben. Danach werden der Server und seine Daten gelöscht. Was installiert bleibt, apt remove und Kubernetes: Referenz.

Ein Server, der so außer Dienst gestellt oder entfernt wird, löst keinen Alarm aus. Ein Server, der noch existiert, aber nichts mehr sendet, löst nach 5 Minuten stopped reporting aus.

Was der Agent tut und was nicht

Der Agent sendet Metriken alle 30 Sekunden und Log-Zeilen ab Schweregrad WARN, sonst nichts, und maskiert offensichtliche Secrets auf deinem Server, bevor eine Zeile gesendet wird. Er öffnet keine eingehenden Ports, läuft unter unprivilegierten Systemnutzern und kann weder auf deinen Servern noch in deinen Hetzner-Projekten etwas ändern. Einstellungen aus dem Portal erreichen ihn als wenige deklarierte Parameter, nie als Code. Sendet ein Server zu viel, wird nur dieser Server gedrosselt.

Agent-ReferenzSysteme, Pakete, Dateien, Befehle, Flags, was er erfasst und wohin er sich verbindet.

Bei fehlgeschlagenen Jobs Bescheid bekommenBackups und Cronjobs mit dem Agent-Token des Servers melden.