Einen Agenten im eigenen Cluster testen lassen

In diesem Schritt fährt ein Coding-Agent die Schleife aus dem Schnellstart für dich: Er legt einen Wegwerf-Cluster an, deployt upcheck dort aus deiner upcheck.yaml, lässt deine Tests dagegen laufen, berichtet und löscht den Cluster. Er arbeitet über die MCP-Tools des Portals, mit einem API-Schlüssel, der nur die Scopes trägt, die er braucht, und jeder seiner Aufrufe wird festgehalten.

In Arbeit: noch nicht buchbar

In Arbeit Die REST-API und die MCP-Tools gibt es als Code im Portal; gegen einen echten Cluster sind sie noch nicht gelaufen. Was sie auslösen, also einen Cluster anlegen, eine versiegelte Kubeconfig und das Löschen, ist am 2026-10-10 Gebaut im Labor auf echten Hetzner-Servern gelaufen, gestartet über die Seiten und die Verwaltungsbefehle des Portals. Das Add-on PaaSbox Platform aus Schritt 2 ist am 2026-10-11 im Labor gelaufen; das Release, das es mitbringt, ist noch nicht veröffentlicht. Die Oberfläche des Portals ist englisch, darum stehen ihre Beschriftungen hier auf Englisch. Nachgehen kannst du die Schritte noch nicht. Sag mir, wenn es buchbar ist.

Was du am Ende hast

Einen Bericht deines Agenten über eine Version von upcheck, getestet in einem Cluster, den es nur für den Test gab, und ein Protokoll jedes Aufrufs, den der Agent gemacht hat, vom Anlegen dieses Clusters bis zum Löschen. upcheck-prod bleibt unberührt.

Was du brauchst

• Die Schritte 1 und 2. Der erste Cluster deines Teams hat sein Abonnement gestartet; die API kann keines starten (sie antwortet payment_method_required), darum wird der erste Cluster eines Teams immer im Portal angelegt. Behalte deine upcheck.yaml.
• Ein Release mit der PaaSbox Platform, 2026.10.2 oder neuer, im Kanal stable. Ein Cluster, den der Agent anlegt, bekommt das Release seines Kanals, stable, wenn der Aufruf keinen anderen nennt.
• Das Konto eines Team-Admins. Nur Team-Admins legen Schlüssel an, und ein Schlüssel handelt mit den Rechten des Admins, der ihn angelegt hat: Cluster anlegen und löschen braucht einen Team-Admin.
• Ein Hetzner-Projekt für Testcluster, verbunden wie das aus Schritt 1. Ein Wegwerf-Cluster bekommt eine Kopie des Tokens seines Projekts, so hat der Agent nie ein Hetzner-Token in der Hand; in einem Projekt, das nur Testcluster hält, erreicht diese Kopie nichts sonst.
• Einen Coding-Agenten, der MCP über HTTP spricht, etwa Claude Code, auf einem Rechner mit kubectl und Python 3.10 oder neuer.
• Das Image, das getestet werden soll, in einer Registry, aus der der Cluster ziehen kann, und deine Tests: einen Befehl, der die App über HTTP prüft, wenn er ihre Adresse bekommt. Was die Tests prüfen, entscheidest du.
• Platz für einen weiteren Cluster in der Grenze deines Teams von 10.

Den Schlüssel anlegen

1. Öffne API keys & agents. Trag unter Create a key als Name claude-code ein, hake bei Scopes k3s:read, k3s:write, k3s:access und k3s:destructive an und setz Expires auf in 30 days. Wähle Create key.

2. Kopier den Schlüssel. Die Seite zeigt ihn einmal und behält nur einen Hash davon.

Jeder Scope öffnet eine Gruppe von Tools, und der Agent bekommt genau diese. k3s:read listet Projekte, Servertypen, Cluster, Add-ons und Operationen. k3s:write schaltet Add-ons, hier die PaaSbox Platform auf dem Testcluster; er würde auch Snapshots machen und Upgrades einplanen. k3s:access holt Kubeconfigs. k3s:destructive legt Cluster an und löscht sie.

Ein Scope gilt nicht nur für einen Cluster: Dieser Schlüssel könnte auch auf upcheck-prod Add-ons schalten, ihn upgraden oder löschen. Gib k3s:destructive nur einem Agenten, dem du zusiehst, wie hier. Ein Schlüssel für einen Agenten, der nur an deinen Stages arbeitet, sollte ihn nicht tragen. Soll die Produktion ganz außer Reichweite eines Schlüssels sein, halte sie in einem Team, zu dem der Schlüssel nicht gehört (Leitplanken für Agenten).

Den Agenten verbinden

1. Connect your agent auf derselben Seite zeigt den MCP-Endpunkt, die Adresse des Portals gefolgt von /mcp/. Füg ihn in Claude Code hinzu:

   export PAASBOX_API_KEY=<der Schlüssel>
   claude mcp add --transport http paasbox https://<das Portal>/mcp/ \
     --header "Authorization: Bearer $PAASBOX_API_KEY"

2. Lade das Kubeconfig-Hilfsskript, das die Seite verlinkt, paasbox_kubeconfig.py, in das Arbeitsverzeichnis des Agenten und führ pip install cryptography aus.

3. Lass den Agenten dich fragen, bevor er create_cluster, delete_cluster, restore_snapshot oder detach_cluster aufruft: In Claude Code nimmst du sie nicht in die erlaubten Tools auf.

Wenn der Agent sich verbindet, sagt ihm der Server, in welchem Team er handelt, als wer und mit welchen Scopes. Mit allen vier Scopes sieht er alle 18 Tools.

Ihm die Aufgabe geben

Starte den Agenten in dem Verzeichnis mit upcheck.yaml und deinen Tests und gib ihm die Aufgabe:

Test the upcheck image registry.example.com/upcheck:<tag> in a throwaway PaaSbox cluster.
1. Create the cluster upcheck-test-1 in the Hetzner project for tests, location fsn1, server type cpx22,
   with a copy of the project's token. Open its API only to this machine's address.
2. Wait until it is ready. Switch on the paasbox-platform add-on, profile saas-http01, ACME e-mail
   you@example.com, with Flux, and wait until it reports applied.
3. Get an admin kubeconfig for one hour with paasbox_kubeconfig.py. Never show it or the private key.
4. Apply upcheck.yaml in namespace upcheck with spec.image set to the image above and without spec.exposure.
   Wait until the SaaSApplication is Ready.
5. Port-forward svc/upcheck-web to localhost:8000 and run ./smoke-test.sh http://localhost:8000.
6. Report what passed and what failed.
7. Delete the cluster without a final snapshot.

Du kannst die Aufgabe auch auf Deutsch stellen. Was der Agent damit tut:

1. Er ruft list_projects und list_server_types auf, für die ID des Projekts und die Servertypen mit ihrem Speicher und Hetzners monatlichem Nettopreis.

2. Er ruft create_cluster auf, mit name und confirm beide upcheck-test-1, hcloud_token {"mode": "copy"} und deiner Adresse in allowed_api_ranges. Dein Agent fragt dich vorher; sag ja. Das Portal lehnt den Aufruf ab, wenn confirm nicht der Name des neuen Clusters ist, und macht die Prüfungen der Seite zum Anlegen: die Grenze deines Teams, die akzeptierten Bedingungen, die Abrechnung.

3. Er fragt get_cluster ab, bis state ready ist. Im Labor war ein Cluster 2 Minuten 46 Sekunden nach der Anfrage bereit; 69 davon gingen in das Kopieren des Node-Images ins Projekt, auf das nur der erste Cluster eines Projekts wartet.

4. Er ruft set_addon auf, mit addon paasbox-platform, enabled true, options {"profile": "saas-http01", "acmeEmail": "you@example.com"} und also ["flux"], das Flux im selben Speichern einschaltet, und fragt list_addons ab, bis die Plattform applied meldet. Der Aufruf zum Anlegen hat auch ein Feld platform, aber die API hat kein Feld für die ACME-E-Mail, die jedes Profil braucht, darum wird ein Anlegen mit platform abgelehnt; die Seite zum Anlegen im Portal fragt nach der E-Mail, die API nicht.

5. Er erzeugt ein Schlüsselpaar mit python3 paasbox_kubeconfig.py keygen --out key.pem, gibt die öffentliche Hälfte an request_kubeconfig mit role admin und fragt get_kubeconfig_result ab. Das Ergebnis ist für seinen Schlüssel verschlüsselt und wird einmal ausgegeben; paasbox_kubeconfig.py decrypt öffnet es auf dem Rechner des Agenten. Das Portal kann es nicht lesen.

6. Er wendet die geänderte Kopie von upcheck.yaml an, die auch den Namespace upcheck anlegt. Ohne spec.exposure veröffentlicht die Plattform nichts: kein Ingress, kein Zertifikat, kein DNS-Name, auf den zu warten wäre, und das Django-Profil nimmt jeden Hostnamen über einfaches HTTP an. kubectl -n upcheck get saasapp zeigt die Phase Ready, sobald die Migration gelaufen ist und die Komponenten laufen.

7. Er lässt deine Tests über kubectl -n upcheck port-forward svc/upcheck-web 8000:80 laufen und berichtet.

8. Er ruft delete_cluster auf, mit confirm upcheck-test-1 und final_snapshot false: Der Cluster hat keinen Bucket, und ein letzter Snapshot bliebe auf der Platte, die gelöscht wird. Dein Agent fragt dich wieder. Die Abrechnung endet sofort; im Labor dauerte ein Löschen 14 Sekunden, und keine Ressource mit dem Label des Clusters blieb übrig.

Nachlesen, was er getan hat

Auf API keys & agents listet Recent activity die letzten Aufrufe; All activity hat alle, filterbar nach Key. Jeder MCP-Aufruf ist eine Zeile, Lesezugriffe und Ablehnungen eingeschlossen: wann er lief, der Schlüssel, der Aufruf, der Cluster und das Ergebnis, bei einer Ablehnung mit ihrem Code, etwa confirmation_required. Die Argumente bleiben erhalten, jedes Geheimnis darin ersetzt durch [redacted]. Was der Agent mit kubectl gemacht hat, steht nicht in diesem Protokoll: Diese Aufrufe gingen an die eigene API des Clusters.

In Arbeit Paddle berechnet einen weiteren Cluster, sobald er zum ersten Mal bereit ist, anteilig bis zum Ende des Abrechnungszeitraums, und schreibt den Rest gut, wenn er gelöscht wird; upcheck-prod hält das Abonnement des Teams währenddessen am Laufen. Den Server des Testclusters rechnete Hetzner stundenweise ab, zu seinem eigenen Preis.

Die Referenz der MCP-Tools listet jedes Tool mit seinem Scope und seinen Argumenten; Leitplanken für Agenten sagt, was jede Grenze aufhält und was nicht.

Was du jetzt hast

Einen Agenten, der eine Änderung in einem Cluster testet, der für den Test gebaut ist, und den Cluster danach entfernt, mit einem Schlüssel, der die Scopes trägt, die du gewählt hast, und ein Protokoll jedes Aufrufs. Der nächste Schritt gibt upcheck eine zweite Stage.

4 · Staging und Produktion getrennt betreibenStaging neben der Produktion aufstellen, jede mit eigenem Kanal und Fenster.

Rezept: ein Testcluster pro Pull RequestDieselbe Schleife aus der CI, für jeden Pull Request.