Eine Custom-Verbindung anlegen

Verbindungen (Resources) haben normalerweise einen dedizierten Kind mit passendem Formular — SMTP, PostgreSQL, S3, Telegram-Bot und so weiter. Der Kind Benutzerdefiniert (Custom) ist das offene Gegenstück: eine freie JSON-Konfiguration plus optionalem Secret, für jeden Drittanbieter-Dienst, für den SupaCloud keinen eigenen Kind hat — ein PayPal-API-Zugang, ein SSH-Host, eine WooCommerce-API, ein Dashboard-Login, eine Vault-AppRole, ein Meta-Graph-Token.

Hinweis

Import aus Windmill? Importierte Workflows referenzieren ihre Resources per Name. Lege pro Windmill-Resource eine Custom-Verbindung mit genau dem Namen an, den der Flow referenziert, trage die nicht-geheimen Felder in die JSON-Konfiguration ein und das Credential in das Secret-Feld — die importierten Schritte lösen sie dann ohne Flow-Änderung auf. Windmill-Typen wie paypal_api, ssh_remote, woocommerce_api, dashboard_login, openbao_app_role und meta_graph bildet dieser eine Kind ab.

So funktioniert die Konfiguration

Die Konfiguration ist ein beliebiges JSON-Objekt. Jedes Feld wird unverändert gespeichert und an Workflows und Skripte durchgereicht — mit einer Ausnahme: Die bekannten Netzwerk-Schlüssel werden validiert, denn sie bestimmen, welche Hosts die Verbindung erreichen darf (ausgehender Verkehr ist sonst komplett gesperrt):

Schlüssel	Regel	Wirkung
base_url / url / endpoint	muss eine http(s)-URL sein	der Host der URL wird als ausgehendes Ziel erlaubt
host (+ optional port)	nicht-leerer String, Port 1–65535	host[:port] wird als ausgehendes Ziel erlaubt

Eine Konfiguration ganz ohne diese Schlüssel ist völlig zulässig — die Verbindung ist dann ein reiner Credential-Träger ohne eigenen Netzwerkzugriff.

Das Secret ist optional und nie Teil des Konfigurations-JSON. Es liegt im Vault und erreicht konsumierende Schritte als Feld secret — oder, als JSON-Objekt eingetragen, zusätzlich als einzelne Felder (siehe nächster Abschnitt).

Mehrfeldrige Secrets

Manche Dienste haben mehr als einen sensiblen Wert — ein PayPal-API-Zugang besteht aus client_id plus client_secret, ein Dashboard-Login aus username plus password, eine Vault-AppRole aus role_id plus secret_id. Trage sie als JSON-Objekt in das Secret-Feld ein:

{ "client_id": "AXY123…", "client_secret": "EGnH456…" }

Lässt sich das Secret als JSON-Objekt lesen, erreichen seine Felder konsumierende Workflow-Schritte und Skripte als einzelne Felder des Resource-Bundles — zusätzlich zum rohen String, der immer als secret verfügbar bleibt. Importierte Windmill-Schritte, die benannte Felder lesen (etwa paypal.client_secret), laufen damit unverändert, während jeder sensible Wert weiter im Vault liegt und nie im Konfigurations-JSON.

Drei Regeln zum Merken:

• Bei Namenskollision gewinnt die Konfiguration. Ein Secret-Feld wird nur hinzugefügt, wenn die Konfiguration noch kein Feld dieses Namens trägt — ein Secret kann nie einen Konfigurationswert überschreiben (und nie das Feld secret selbst).
• Alles, was kein JSON-Objekt ist, bleibt ein einfaches Secret. Ein einzelnes Token oder Passwort verhält sich exakt wie bisher: ein secret-String, nichts wird gemergt.
• Netzwerk-Schlüssel gehören in die Konfiguration. Ein base_url/url/endpoint/host im Secret-Objekt erlaubt keinen ausgehenden Zugriff — die Egress-Allowlist ergibt sich allein aus der Konfiguration.

Schritte

1. Das Verbindungen-Board öffnen.

   Gehe zu Resources und wähle + Neue Resource.

2. Den Kind „Benutzerdefiniert” wählen.

   Wähle im Kind-Picker Benutzerdefiniert. Die Konfiguration öffnet sich als JSON-Editor mit einem base_url-Grundgerüst — behalte es für einen HTTP-Dienst oder lösche es und füge eigene Felder hinzu.

3. Die Konfiguration eintragen.

   Zum Beispiel ein PayPal-API-Zugang:

   {
     "base_url": "https://api.paypal.com",
     "client_id": "AXY123…",
     "environment": "live"
   }

   Oder ein SSH-Host (keine URL — host + port erlauben das ausgehende Ziel):

   { "host": "db-host.example.com", "port": 22, "user": "deploy" }

4. Das Secret hinzufügen (optional).

   Trage die sensible Hälfte — ein API-Client-Secret, ein Passwort, ein Token — in das Secret-Feld ein. Es bleibt im Vault und erreicht Workflow-Schritte und Skripte als Feld secret des Resource-Bundles. Mehrere sensible Werte? Trage sie als JSON-Objekt ein — siehe Mehrfeldrige Secrets oben.

5. Die Verbindung testen.

   Test prüft den ersten URL-Schlüssel (ein HTTP-HEAD; Antworten, die Authentifizierung verlangen, zählen als erreichbar) oder verbindet sich ohne URL-Schlüssel per TCP auf host:port. Eine Konfiguration ohne beides ist nicht prüfbar — der Test-Button meldet genau das, statt zu raten.

Achtung

Die Netzwerk-Schlüssel sind die Egress-Allowlist der Verbindung. Trage nur base_url/url/endpoint/host-Werte ein, die der Workload wirklich braucht — jeder vorhandene Schlüssel erweitert, was ein konsumierendes Skript erreichen kann.