Docs

Lebenszyklus eines Lease

Kurzfassung

  • Diese Seite ist der operative Durchlauf, um ein Lease von Hand zu steuern: es öffnen, Ressourcen zum Erstellungszeitpunkt stempeln, auf das deployment warten, behalten, was du behalten willst (promote), und mit commit (alles behalten) oder rollback (alles verwerfen) abschließen.
  • Die Verb-Oberfläche ist lease create → file link --lease → lease wait → lease promote → lease commit / lease rollback, plus die operativen Helfer wait, debug, set-result, collect-outputs, list, delete und delete-bulk.
  • Für den häufigen Fall — das Ausführen eines Live-Tests aus einem Manifest — steuert ppl lease run --test=<manifest> den gesamten Lebenszyklus für dich. Die Verben unten sind die Oberfläche auf niedrigerer Ebene für Runs, die die Manifest-Grammatik nicht abdeckt.
  • Für das Ownership-Modell, die Verb-Semantik und die TTL-Philosophie hinter diesen Befehlen siehe Leases.

Der Standard-Konsument: lease run

Verwende diesen Modus, wenn du ein live-test-Manifest hast und es einfach laufen lassen willst.

ppl lease run --test=<manifest> --runtime=<id> steuert den gesamten Lebenszyklus für einen im Manifest beschriebenen Live-Test, sodass der häufige Konsument die Verben nicht direkt anfasst. Es prägt das Lease, veröffentlicht die prerelease des Kandidaten-components, gestempelt mit dem Lease, lädt jede lokale Fixture, gestempelt mit dem Lease, hoch, öffnet den live-test-WebSocket, streamt Build- und Deploy-Events als NDJSON und führt am Ende automatisch ein Rollback des Lease durch. Der Exit-Code ist 0 bei einem ready-Test und 1 bei einem failed-Test, was ein CI-Schritt braucht.

Für explorative Arbeit, bei der das Deployment bestehen bleiben soll — um es zu inspizieren, seine Outputs einzusammeln und von Hand über Commit oder Rollback zu entscheiden —, verwende ppl lease test statt ppl lease run. Es treibt denselben Build über einen synchronen Stream, akzeptiert aber nur ein runner-loses, einphasiges Manifest, und es belässt das Deployment bei ready auf dem Lease, statt zurückzurollen. ppl lease run räumt immer hinter sich auf, was die CI braucht.

Siehe Mit einem Live-Backend testen für das Manifest-Schema und den vollständigen Event-Stream-Vertrag.

Ein Lease öffnen

Verwende dies, wenn der Run individuell genug ist, dass die manifest-gesteuerte Abkürzung nicht passt.

Das Öffnen eines Lease deklariert den runtime, auf dem das deployment letztlich läuft, die maximale unbeaufsichtigte Lebenszeit und ein optionales Label, das das Lease später leicht auffindbar macht. Das Lease startet im Zustand open und akzeptiert sofort gestempelte Creates:

ppl lease create --runtime <runtime_id> --ttl 30m --label q-faiss-live

Beschriften lohnt sich. Ein Lease mit dem Label nightly_vector_index ist später per Teilstring-Suche auffindbar, wird per Label-Präfix per Bulk zurückgerollt und identifiziert, was ein steckengebliebenes Lease getan hat. Unbeschriftete Leases funktionieren genauso; sie sind bei der Hauswirtschaft nur schwerer zu erkennen.

Wähle die TTL so, dass sie den längsten erwarteten Run bequem abdeckt; die Plattform wendet einen Standard an und begrenzt überlange Werte. Eine TTL, die kürzer als der Run ist, erzeugt ein falsches Rollback, während der Test noch läuft. --runtime fällt auf das konfigurierte default_runtime zurück, wenn weggelassen, und --cleanup-policy ist standardmäßig delete_ephemeral_resources — übergib retain_all, um eigene Ressourcen beim Schließen des Lease an Ort und Stelle zu behalten.

Ressourcen zum Erstellungszeitpunkt stempeln

Verwende dies immer dann, wenn die Ressource mit dem Lease sterben soll.

Der eine Befehl, der ein eigenständiges --lease-Flag bereitstellt, ist ppl file link:

ppl file link <source_uri> --lease <lease_id> --kind <source_kind> --type <file_type>

Backends, deployments, versions und components werden innerhalb von ppl lease run automatisch gestempelt — kein von Hand getipptes Flag. Für die Stamp-at-Create-Regel und warum es keine Möglichkeit gibt, eine bestehende Zeile später in ein Lease zu verschieben, siehe Leases.

Auf das Hochfahren des deployment warten

Verwende dies, um "der Run ist bereit" am tatsächlichen runtime festzumachen, nicht an einem Sleep.

Ein Lease hält ein deployment; das deployment hält Container; Container brauchen eine gewisse, von null verschiedene Zeit zum Starten. ppl lease wait ist das Gate: es öffnet einen Server-Sent-Events-Stream, schreibt ein NDJSON-Event pro Zeile und beendet sich mit 0, wenn das Lease seinen Zielzustand erreicht (deployed standardmäßig), 1 bei failed, timeout oder Transportfehler.

ppl lease wait <lease_id> --until started --max-crashes 5 --timeout 15m

--until lässt dich wählen, wie streng "bereit" gemeint ist. started beendet sich, sobald das deployment läuft, stable (der Standard) wartet darauf, dass jeder Container running ist, ohne dass Crash-Budget übrig ist. --max-crashes setzt das Neustart-Budget pro Container und --timeout ist die Wanduhr-Obergrenze für den gesamten Aufruf. Der Exit-Code ist das, was du in den nächsten CI-Schritt leitest.

Promote, dann commit (oder rollback)

Verwende Promote, wenn eine bestimmte Zeile des Lease überleben soll, selbst wenn der Rest verworfen wird.

Was jedes Verb gegenüber dem Ownership-Modell bedeutet, siehe Leases. Operativ ist die Sequenz:

ppl lease promote <lease_id> --kind file --id <file_id>ppl lease commit <lease_id>      # alles, was noch im Lease ist, behalten, es schließenppl lease rollback <lease_id>    # alles, was noch im Lease ist, verwerfen, es schließen

Das typische Muster ist: ein Live-Test läuft, erzeugt ein generiertes Artefakt, das es wert ist behalten zu werden (etwa ein gebauter FAISS-Index), promotet diese einzelne Datei aus dem Lease heraus und rollt dann den Rest zurück. Die behaltene Datei überlebt; die prerelease des Kandidaten-components, das Test-backend, die temporären Fixtures, das deployment werden alle aufgeräumt.

Commit und Rollback sind idempotent auf bereits geschlossenen Leases. Der Aufruf von einem von beiden auf einem geschlossenen Lease ist ein No-op-Erfolg — nützlich für Aufräum-Skripte, die den seltenen Wettlauf mit einem TTL-Auto-Rollback nicht gesondert behandeln wollen.

Bulk-Hauswirtschaft

Verwende dies, wenn viele Leases auf einmal sterben müssen.

Bulk-Rollback schließt viele Leases in einem Aufruf — zum Beispiel jedes fehlgeschlagene Lease aus einem CI-Run. Die Filter werden mit AND verknüpft, und der Server verweigert einen leeren Filter-Body, sodass ein Tippfehler nicht jedes Lease im workspace zurückrollen kann.

ppl lease rollback --bulk --older-than 24hppl lease rollback --bulk --failedppl lease rollback --bulk --runtime <runtime_id> --label-prefix nightly-

Das nächtliche Aufräummuster ist eine Zeile Cron — und weil jedes Lease entweder committet hat (seine Zeilen behalten) oder zurückgerollt wurde (sie zerstört), gibt es keinen Reststand, dem man nachjagen müsste.

Bulk-Rollback schließt noch offene Leases. Um die Zeilen bereits geschlossener Leases zu bereinigen, nimmt ppl lease delete-bulk dieselbe Filterform plus --status (auf die geschlossenen Zustände rolled_back, failed, committed beschränkt) und eine --dry-run-Vorschau und berührt nie ein offenes Lease.

ppl lease delete-bulk --closed-before 24hppl lease delete-bulk --status rolled_back --older-than 7d --dry-run

Ein fehlgeschlagenes Lease debuggen

Verwende dies zuerst, wenn etwas schiefgegangen ist.

ppl lease debug <lease_id> gibt ein JSON-Bundle zurück: das Lease, sein backend, den Status und die Meldung des deployment sowie einen Status / Exit-Code / eine Status-Meldung pro Container. Es ist der eine Aufruf, den man zuerst macht, wenn ein Lease fehlschlägt — er sagt fast immer genug, um zu entscheiden, ob der nächste Schritt "Container-Logs lesen", "den backend-Graph reparieren und erneut versuchen" oder "der runtime klemmt" ist.

Die Kombination mit ppl lease set-result <lease_id> --status failed --json '{…}' bewahrt ein strukturiertes Ergebnis und das Debug-Bundle über das Schließen hinaus, was die Nachanalyse möglich macht, nachdem das Lease selbst verschwunden ist.

Wo das hineinpasst

Diese Seite ist die Befehlssequenz, um ein Lease von Hand zu steuern; das Ownership-Modell, die Verb-Semantik und die TTL-Philosophie, die die Oberfläche kohärent machen, leben in Leases. Die operativen Helfer — wait, debug, set-result, collect-outputs, list, delete, delete-bulk — sind in den Abschnitten oben dokumentiert.

Verwandt

War diese Seite hilfreich?