Stelle an Endpunkte ohne öffentliche URL zu

Ein Connector steht für eines deiner Netzwerke. Er gehört zur Organisation, nicht zu einem Projekt, sodass ein einziger Cluster-Connector alle deine Projekte bedient. In diesem Netzwerk betreibst du eine oder mehrere Agent-Replikas. Jede baut eine Verbindung nach außen zum Overlay auf und bleibt dort.

Wenn eine Zustellung fällig ist, übergibt SolidHooks sie dem Connector per Name, und der Agent stellt die eigentliche HTTP-Anfrage aus deinem Netzwerk heraus. Dein Dienst sieht eine Anfrage von einer lokalen Adresse und braucht keinerlei Änderungen.

1. 1

   Stelle den Connector bereit

   Die Antwort enthält einen enrollmentKey (cbt_…). Er wird nur hier und beim Neuerzeugen angezeigt, sonst nirgends. Speichere ihn also, bevor du weitermachst. Er läuft nicht ab.

   curl

   curl -s "$API/v1/connectors" \  -H "authorization: Bearer $SDHK_KEY" \  -H 'content-type: application/json' \  -d '{ "name": "prod-cluster", "description": "EU production" }' → { "id": "cntr_...", "enrollmentKey": "cbt_...", "provisionedAt": "2026-08-18T09:14:02.000Z" }# The enrollment key is shown once here. Store it now.# provisionedAt reads null only if you read the connector back while this call is still in flight.

2. 2

   Starte den Agent in deinem Netzwerk

   Das Dashboard zeigt die genaue docker run- oder helm install-Zeile mit deinem Token darin. Jede Replika registriert sich selbst über den Bootstrap-Endpunkt von SolidHooks, erhält ein eigenes Heartbeat-Token und tritt dem Connector bei.

   curl

   # Install using helmhelm repo add interstellar-labs https://interstellar-labs.github.io/charts/helm repo updatehelm install solidhooks-connector interstellar-labs/solidhooks-connector \ --set enrollmentKey="cbt_..." # Install using dockerdocker run -e ENROLLMENT_KEY="cbt_..." \ -v solidhooks-connector:/ziti \ interstellarlabs/solidhooks-connector:latest 

3. 3

   Füge Replikas für die Verfügbarkeit hinzu

   Führe denselben Befehl woanders noch einmal aus. Replikas sind unabhängige Mitglieder eines Connectors, sodass ein Rolling Restart den Connector nie ohne Verbindung lässt.

4. 4

   Erstelle ein privates Ziel

   Setze type: "private" und nenne den Connector. Die URL wird weiterhin als URL validiert, sie muss nur nicht öffentlich auflösbar sein.

   curl

   curl -s "$API/v1/destinations" \  -H "authorization: Bearer $SDHK_KEY" \  -H 'content-type: application/json' \  -d '{    "name": "In-cluster payments service",    "type": "private",    "connectorId": "cntr_...",    "url": "http://payments.default.svc.cluster.local:8080/hooks",    "method": "POST"  }'

Ein Connector meldet einen über seine Replikas zusammengefassten Status, und die vier Werte sind so gewählt, dass unsere Unsicherheit nie als dein Ausfall gemeldet wird.

# Aggregate across replicascurl -s "$API/v1/connectors/cntr_..." -H "authorization: Bearer $SDHK_KEY"→ { "status": "connected", "connectedReplicas": 2, "totalReplicas": 3 } # Which one is missingcurl -s "$API/v1/connectors/cntr_.../replicas" -H "authorization: Bearer $SDHK_KEY"

regenerate-enrollment erzeugt ein neues Bootstrap-Token und macht das vorherige ungültig. Bereits registrierte Replikas laufen weiter, ein geleaktes Token zu rotieren ist also kein Ausfall.

toggle-disabled verhindert, dass neue private Ziele für den Connector erstellt werden. Registrierte Replikas senden weiter Heartbeats, denn Deaktivieren ist ein administrativer Schalter und kein Widerruf. Das Löschen eines Connectors wird mit 400 blockiert, solange noch ein Ziel auf ihn zeigt.

Eine Replika wird nur dann automatisch widerrufen, wenn sie sowohl länger als das Fenster für veraltete Heartbeats still war als auch nicht im Overlay aufgetaucht ist. Dieses Fenster beträgt standardmäßig 24 Stunden und wird pro Deployment eingestellt, prüfe also deines, bevor du es als feste Zahl behandelst. Dass beide Bedingungen nötig sind, hält einen gesunden Agent am Leben, der Traffic bedienen, aber unsere API nicht erreichen kann. Eine widerrufene Replika bekommt 403 mit einem maschinenlesbaren Grund und hält an. Ein unbekanntes Token bekommt ein undurchsichtiges 401, damit sich über den Endpunkt nicht ausloten lässt, welche Zugangsdaten gültig sind.

• Connectors sind durch maxConnectors begrenzt. Wer darüber hinausgeht, bekommt 403 CONNECTOR_LIMIT_REACHED mit der aktuellen Anzahl.
• Replikas pro Connector sind durch maxReplicasPerConnector begrenzt, durchgesetzt beim Bootstrap. Ein kleinerer Plan entfernt nie Replikas, die bereits registriert sind.
• Private Zustellung ist eine optionale Plattformfunktion. Auf einem Deployment ohne konfiguriertes Overlay liefern Änderungen an Connectors 400.

• Betreibe mindestens zwei Replikas in unterschiedlichen Ausfallbereichen. Mit nur einer Replika bleibt der Connector ein Single Point of Failure.
• Speichere den Registrierungsschlüssel in deinem Secret-Manager, sobald du den Connector erstellst. Er wird nie wieder angezeigt, und der Weg zur Wiederherstellung ist das Neuerzeugen.
• Alarmiere, wenn connectedReplicas unter deine geplante Anzahl fällt, statt auf den zusammengefassten Status. Ein Connector zeigt connected, auch wenn nur eine von drei Replikas lebt.
• Behandle unknown als Abfrage, die du wiederholst, nicht als Anlass für einen Alarm. Es beschreibt unsere Sicht auf das Overlay, nicht deinen Agent.
• Ein Connector pro Netzwerk, wiederverwendet über alle Projekte. Genau deshalb gelten sie für die ganze Organisation.