Dienstübergreifende Referenzen

Mit Referenzen kann ein Dienst die Werte eines anderen Dienstes oder Add-ons lesen, ohne Credentials per Copy-and-paste zu duplizieren. Sie halten jeden Wert an einer Stelle; Consumer übernehmen Änderungen beim nächsten Deploy.

Syntax

${{<name>.<KEY>}}

• <name> — der Name des Zieldienstes oder Add-ons (der im Dashboard angezeigt und in lizard add -n verwendet wird).
• <KEY> — ein Schlüssel, den das Ziel bereitstellt. Ein Add-on stellt seine Verbindungswerte bereit. Ein Dienst stellt seine Projekt- und Dienstvariablen und Secrets bereit, dazu seine LIZARD_*- und PORT-Werte. Die DATABASE_URL oder REDIS_URL, die Lizard aus Add-ons einfügt, stellt er nicht bereit; referenziere dafür das Add-on.

Verwende sie überall dort, wo ein Wert akzeptiert wird — am häufigsten in einem Secret:

lizard secrets set DATABASE_URL='${{postgres.DATABASE_URL}}' --service api

Wie sie aufgelöst werden

• Referenzen werden zur Deploy-Zeit anhand der Werte aufgelöst, die das Ziel bereitstellt.
• Referenzen, die du in einem Secret setzt (lizard secrets set oder das Dashboard), beziehen sich auf den aktuellen Namen des Ziels. Ein Umbenennen des Ziels macht sie kaputt; aktualisiere nach einer Umbenennung jedes ${{oldname.KEY}}. Referenzen, die mit lizard add -v angelegt wurden, folgen dem Ziel bei einer Umbenennung.
• Eine Referenz auf ein fehlendes Ziel oder einen fehlenden Schlüssel wird zu einem leeren String aufgelöst — das Bereitstellen schlägt dadurch nicht fehl. Das Build-Log gibt für jede leere Referenz eine Warnung mit der Ursache aus.
• Nur zirkuläre Referenzen werfen einen Fehler.

Prüfe nach dem Einrichten einer Referenz im Build-Log, ob leere Referenzen vorhanden sind:

lizard logs --build --service api

Wenn eine Referenz nicht wie erwartet erscheint, siehe Troubleshooting → ein Secret oder eine Referenz wird nicht angezeigt.

Häufige Muster

Ein Add-on mit mehreren Diensten verbinden — auf jedem Consumer binden; verwende innerhalb des Projekts die private URL:

lizard secrets set REDIS_URL='${{redis.REDIS_PRIVATE_URL}}' --service api
lizard secrets set REDIS_URL='${{redis.REDIS_PRIVATE_URL}}' --service worker

Einen Wert aus einem anderen Dienst referenzieren — z. B. eine berechnete URL oder ein Token teilen. LIZARD_PUBLIC_DOMAIN ist ein reiner Hostname und existiert, sobald der Dienst eine Domain hat; LIZARD_PRIVATE_DOMAIN (<name>.lizard.internal) erreicht den Dienst innerhalb des Projekts:

lizard secrets set UPSTREAM_URL='https://${{api.LIZARD_PUBLIC_DOMAIN}}' --service web
lizard secrets set INTERNAL_API='http://${{api.LIZARD_PRIVATE_DOMAIN}}:8080' --service web

Ein zweites Add-on desselben Typs referenzieren — verwende seinen generierten Namen:

lizard secrets set CACHE_URL='${{redis-winter-otter.REDIS_URL}}' --service api

Warum nicht einfach --global verwenden?

Wenn du einen gemeinsamen Wert im Projektbereich (--global) ablegst, ist er für jeden Dienst sichtbar, auch für solche, die ihn nicht benötigen. Eine Referenz hält den Wert an einer Stelle und bindet ihn nur dort, wo du sie setzt. Beachte, dass jeder Dienst ohnehin eine DATABASE_URL und eine REDIS_URL aus den Postgres- und Redis-Add-ons des Projekts erhält, mit der niedrigsten Priorität; gibt es mehrere Add-ons desselben Typs, ist nicht festgelegt, welches. Eine Referenz überschreibt sie. Siehe Secret-Scopes.

Siehe auch

• Variablen & Secrets — Scopes und Priorität.
• lizard secrets — die vollständige Befehlsreferenz.

Aktualisiert 21. Oktober 2026