Docker-Swarm-Agent

Der Status200-Docker-Swarm-Agent überwacht einen Docker-Swarm-Cluster: seine Knoten, Dienste, Tasks, Stacks, Overlay-Netzwerke, Secrets, Configs und Volumes sowie die Metriken und Logs jedes Containers. Sie führen ihn mit Docker Compose auf einem Swarm-Manager-Knoten aus, und der Cluster erscheint mit all dem in Status200. Docker-Swarm-Monitore alarmieren anhand dessen, was ankommt.

So funktioniert es#

Der Agent besteht aus drei Containern, alle in einer docker-compose.yml definiert:

1. Collector: ein OpenTelemetry Collector, der docker_stats für die Metriken jedes Containers liest, die Logdateien der Container verfolgt und die Datei mit dem Inventar-Snapshot verfolgt. Er versieht alles mit dem Namen Ihres Clusters (docker.swarm.cluster.name) und sendet es per OTLP an Status200.
2. Inventar-Poller: ein kleiner Sidecar mit curl und jq, der alle 5 Minuten die API des Swarm-Managers abläuft (/nodes, /services, /tasks, /networks, /secrets, /configs, /volumes) und die Stacks aus dem Service-Label com.docker.stack.namespace ableitet. Er schreibt eine JSON-Zeile pro Objekt, die der Collector weiterleitet.
3. KI-Agent: status200-docker-swarm-ai-agent, der die docker-Befehle ausführt, um die Status200 AI bittet, während sie einen Vorfall oder Alarm auf diesem Cluster untersucht. Er ist schreibgeschützt, sofern Sie keine Korrekturen erlauben (siehe KI-Agent).

Der Cluster registriert sich mit seinen ersten Daten unter dem Clusternamen, den Sie konfigurieren.

Bevor Sie beginnen#

• Ein Swarm-Manager-Knoten, auf dem der Agent läuft: Der Inventar-Poller und der KI-Agent rufen API-Endpunkte auf, die nur Manager beantworten.
• Docker Engine 20.10 oder neuer mit dem Plugin Docker Compose v2.
• Ein Ingestion-Schlüssel. Legen Sie ihn unter Projekteinstellungen → Telemetrie & APM → Ingestion-Schlüssel an und kopieren Sie seinen Wert.
• Ausgehendes HTTPS vom Knoten zu Ihrer Status200-URL.

Wo der Agent laufen sollte#

Führen Sie ihn auf einem Manager-Knoten aus. Der Collector meldet die Container des Knotens, auf dem er läuft; für die Container-Metriken aller Knoten führen Sie den Collector daher auf jedem Knoten aus, alle mit demselben DOCKER_SWARM_CLUSTER_NAME. Der Inventar-Poller und der KI-Agent müssen nur auf einem Manager laufen. install.sh lässt den KI-Agent auf einem Knoten weg, der kein Manager ist (und entfernt einen, den es dort früher installiert hat). Ein KI-Agent, der trotzdem auf einem Worker gestartet wird, registriert sich nie für den Cluster: Er wartet, bis sein Knoten ein Manager ist, und kann daher den KI-Agent des Managers nicht verdrängen. Verteilen Sie den Agent als Swarm-Stack statt mit Compose? Halten Sie den Inventar-Poller und den KI-Agent mit der Einschränkung node.role == manager auf Managern.

Agent installieren#

1. Den Agent installieren und starten#

   install.shDocker Compose

   install.sh

   Laden Sie das Installationsskript herunter und führen Sie es auf einem Manager-Knoten aus:

   Bash

   curl -sSL <YOUR_STATUS200_URL>/docs/static/scripts/agents/DockerSwarmAgent/install.sh -o install.sh
   sh install.sh

   Das Skript fragt nach Ihrer Status200-URL, dem Ingestion-Schlüssel und einem Namen für den Cluster. Es installiert nach /opt/status200-docker-swarm-agent, schreibt eine .env-Datei, die nur ihr Eigentümer lesen kann, und startet alle drei Container. Fügen Sie --no-ai-agent hinzu, um den KI-Agent wegzulassen.

   Docker Compose

   Laden Sie docker-compose.yml, otel-collector-config.yaml und inventory-snapshot.sh aus dem [Verzeichnis DockerSwarmAgent](<YOUR_STATUS200_URL>/docs/static/scripts/agents/DockerSwarmAgent) in einen neuen Ordner auf einem Manager-Knoten herunter:

   Bash

   curl -fsSL <YOUR_STATUS200_URL>/docs/static/scripts/agents/DockerSwarmAgent/docker-compose.yml -o docker-compose.yml
   curl -fsSL <YOUR_STATUS200_URL>/docs/static/scripts/agents/DockerSwarmAgent/otel-collector-config.yaml -o otel-collector-config.yaml
   curl -fsSL <YOUR_STATUS200_URL>/docs/static/scripts/agents/DockerSwarmAgent/inventory-snapshot.sh -o inventory-snapshot.sh
   chmod +x inventory-snapshot.sh

   Legen Sie daneben eine Datei .env an. Sie enthält den Ingestion-Schlüssel; schützen Sie sie daher mit chmod 600 .env:

   .envBash

   STATUS200_URL=https://status200.ru
   STATUS200_SERVICE_TOKEN=your-telemetry-ingestion-key
   DOCKER_SWARM_CLUSTER_NAME=my-swarm

   Starten Sie den Agent:

   Bash

   docker compose up -d

2. Prüfen, ob der Agent läuft#

   Bash

   docker compose ps
   docker compose logs --tail 50 status200-docker-swarm-agent status200-docker-swarm-inventory

   docker compose ps listet drei Container auf: den Collector (status200-docker-swarm-agent), den Inventar-Poller (status200-docker-swarm-inventory) und den KI-Agent (status200-docker-swarm-ai-agent).

3. Den Cluster in Status200 finden#

   Öffnen Sie Produkte → Infrastruktur → Docker Swarm → Alle Cluster. Der Cluster erscheint innerhalb weniger Minuten, und seine Seiten Knoten, Dienste, Aufgaben, Stacks, Netzwerke, Geheimnisse, Konfigurationen und Volumes füllen sich nach dem ersten Inventar-Snapshot, innerhalb von 5 Minuten. Die Seite Topologie des Clusters zeichnet seine Stacks, Dienste, Aufgaben und Knoten als eine Karte: siehe Topologie.

Umgebungsvariablen#

Das Installationsskript schreibt die ersten drei nach /opt/status200-docker-swarm-agent/.env; eine Docker-Compose-Installation liest sie aus der .env neben docker-compose.yml. Fügen Sie dort eine davon hinzu oder ändern Sie sie, und führen Sie dann in diesem Ordner docker compose up -d aus.

Die eigenen Einstellungen des KI-Agents stehen unter KI-Agent.

Was der Agent erfasst#

Was ihn vom Docker-Agent unterscheidet#

Der Docker-Agent bildet einen einzelnen Host ab und hängt host.name und container.runtime=docker an. Der Docker-Swarm-Agent hängt mit Absicht nur docker.swarm.cluster.name an: Status200 ordnet die Daten dann dem Swarm-Cluster zu, statt jeden Knoten als eigenen Host zu registrieren.

Den Cluster mit Projekt-Labels versehen#

Ein Ressourcenattribut, das mit status200.label. beginnt, wird zu einem Projekt-Label am Cluster: status200.label.<dimension>=<value> ist das Label <dimension>:<value>. Fügen Sie die Attribute dem Processor resource in otel-collector-config.yaml hinzu, neben docker.swarm.cluster.name:

processors:
  resource:
    attributes:
      # ...existing attributes...
      - key: status200.label.team
        value: platform
        action: upsert
      - key: status200.label.env
        value: production
        action: upsert

Der Collector liest seine Konfiguration nur beim Start: Führen Sie docker compose restart status200-docker-swarm-agent aus. Der Cluster zeigt dann die Labels team:platform und env:production. Labels werden ohne Rücksicht auf Groß- und Kleinschreibung verglichen, daher wird ein vorhandenes Label Production wiederverwendet statt dupliziert, und der Agent entfernt nie ein Label, das jemand in Status200 hinzugefügt hat.

Als systemd-Dienst ausführen#

Um den Agent mit dem Knoten zu starten und bei einem Fehler neu zu starten, installieren Sie seine systemd-Unit. Sie geht davon aus, dass der Agent in /opt/status200-docker-swarm-agent liegt, wo das Installationsskript ihn ablegt:

sudo curl -fsSL <YOUR_STATUS200_URL>/docs/static/scripts/agents/DockerSwarmAgent/systemd/status200-docker-swarm-agent.service -o /etc/systemd/system/status200-docker-swarm-agent.service
sudo systemctl daemon-reload
sudo systemctl enable --now status200-docker-swarm-agent

Agent aktualisieren#

Der Agent meldet die Collector-Version, die er ausführt. Ist sie älter als die Version, die dieses Status200-Release festlegt, erscheint in der Übersicht des Clusters ein Warnzeichen neben der Version des Agents. Wählen Sie es aus, um diese Befehle zu sehen.

Führen Sie das Installationsskript erneut auf dem Manager-Knoten aus und beantworten Sie seine Fragen mit derselben URL, demselben Schlüssel und demselben Clusternamen. Es lädt die neuesten Dateien herunter, zieht die Images und startet den Agent neu:

curl -sSL <YOUR_STATUS200_URL>/docs/static/scripts/agents/DockerSwarmAgent/install.sh -o install.sh
sh install.sh

Das Skript schreibt .env aus Ihren Antworten neu. Es behält nur die Ziellisten des KI-Agents und das, was die KI tun darf (STATUS200_AI_INVESTIGATION, STATUS200_AI_FIXES): Fügen Sie jede Variable, die Sie selbst gesetzt haben, wieder hinzu, etwa DOCKER_API_VERSION. Haben Sie KI-Korrekturen eingeschaltet? Führen Sie es als STATUS200_AI_ALLOW_WRITES=true sh install.sh aus, damit sie eingeschaltet bleiben. Haben Sie den KI-Agent weggelassen? Übergeben Sie erneut --no-ai-agent.

Laden Sie mit Docker Compose die drei Dateien im Ordner des Agents erneut herunter (und nehmen Sie Ihre Änderungen an docker-compose.yml erneut vor), ziehen Sie dann die Images und starten Sie neu:

docker compose pull
docker compose up -d --force-recreate

Die Collector-Version ist in den Dateien festgelegt; ein Pull allein bringt den Agent daher nicht voran.

Agent deinstallieren#

cd /opt/status200-docker-swarm-agent
docker compose down

KI-Agent#

Die docker-compose.yml des Swarms (und install.sh) führt außerdem den Docker-Swarm-KI-Agent aus: einen dritten Container, status200-docker-swarm-ai-agent (Image status200/resource-ai-agent:release), der die lesenden docker-Befehle ausführt, um die Status200 AI bittet, während sie einen Vorfall oder Alarm auf diesem Cluster untersucht — docker node ls, docker service ps web --no-trunc, docker service logs --tail 200 web — und, nur wenn Sie es erlauben, Korrekturen anwendet, etwa einen rollierenden Neustart eines benannten Dienstes. Er liest dieselben STATUS200_URL, STATUS200_SERVICE_TOKEN und DOCKER_SWARM_CLUSTER_NAME wie der Collector, bedient also genau diesen Cluster, und erscheint in Status200 auf der Seite KI → KI-Agent des Clusters.

• KI-Untersuchungen sind standardmäßig aktiviert. Sobald der Agent verbunden ist, untersucht Status200 AI Vorfälle und Alarme auf diesem Cluster mit ihm, und die Übersicht des Clusters zeigt den Status des Agents an. Zum Beenden setzen Sie STATUS200_AI_INVESTIGATION=false dort, wo der Agent läuft (Ändern unter Was die KI tun darf auf der Seite des KI-Agents zeigt, wie), oder lassen den Agent weg.
• Wie der Inventar-Poller muss er auf einem Manager-Knoten laufen: Befehle für Knoten, Dienste und Tasks gibt es nur auf Managern. Auf einem Worker führt er nichts aus und registriert sich nicht für den Cluster, bis der Knoten ein Manager ist (sein /status sagt, warum). Führen Sie einen pro Cluster aus.
• Er ist schreibgeschützt, sofern Sie nicht STATUS200_AI_ALLOW_WRITES=true in .env setzen und docker compose up -d ausführen (oder install.sh damit ausführen; das Installationsskript schreibt STATUS200_AI_ALLOW_WRITES, STATUS200_AI_INVESTIGATION, STATUS200_AI_FIXES, STATUS200_AI_WRITE_TARGETS und STATUS200_AI_PROTECTED_TARGETS aus seiner Umgebung in .env, und ein erneuter Lauf behält für die letzten vier, was .env bereits enthält, sofern Sie die Variable nicht übergeben, auch leer); STATUS200_AI_WRITE_TARGETS (Globs für Dienst- und Knotennamen, zum Beispiel web_*,api_*) begrenzt, was eine Korrektur antasten darf. STATUS200_AI_FIXES in derselben .env legt fest, wie Korrekturen ablaufen — ask-for-approval (ein Mensch genehmigt jede), automatic oder bypass-approval —, und die Seite des KI-Agents zeigt es schreibgeschützt an (Was die KI tun darf, vom Agent festgelegt). Einen Knoten zu leeren braucht immer die Genehmigung eines Menschen, unabhängig vom Modus.
• Er läuft als root mit eingehängtem Docker-Socket, weil der Socket root gehört — und auf einem Manager kontrolliert, wer den Socket benutzen kann, den ganzen Swarm, ob :ro oder nicht. Die Befehlsrichtlinie des Agents ist die Grenze: Er erstellt oder entfernt nie Dienste oder Stacks, rührt nie Secrets oder Configs an und ändert nie sich selbst, den Collector, den Inventar-Poller oder irgendetwas in STATUS200_AI_PROTECTED_TARGETS (Globs für Dienst- und Knotennamen).
• install.sh --no-ai-agent lässt ihn weg, oder löschen Sie den Dienst status200-docker-swarm-ai-agent aus docker-compose.yml.

Was er ausführen darf, wie Korrekturen funktionieren und wie Sie Fehler beheben: Infrastructure AI Agents.

Fehlerbehebung#

curl -sSL <YOUR_STATUS200_URL>/docs/static/scripts/agents/DockerSwarmAgent/troubleshoot.sh -o troubleshoot.sh
bash troubleshoot.sh    # add -d <dir> if you installed outside /opt/status200-docker-swarm-agent

Error: cannot start pipelines: failed to start "docker_stats" receiver:
Error response from daemon: client version 1.44 is too new.
Maximum supported API version is 1.41

docker version --format '{{ .Server.APIVersion }}'

Nächste Schritte#