Livrez vers des points de terminaison sans URL publique

Un connecteur représente l’un de vos réseaux. Il appartient à l’organisation plutôt qu’à un projet : un seul connecteur de cluster sert tous vos projets. À l’intérieur de ce réseau, vous exécutez une ou plusieurs répliques de l’agent. Chacune se connecte vers l’overlay et y reste.

Quand une livraison est due, SolidHooks la remet au connecteur par son nom et l’agent effectue la requête HTTP depuis votre réseau. Votre service voit une requête provenant d’une adresse locale et ne nécessite aucune modification.

1. 1

   Provisionnez le connecteur

   La réponse contient une enrollmentKey (cbt_…). Elle n’est affichée qu’ici et lors d’une régénération : enregistrez-la avant de continuer. Elle n’expire pas.

   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

   Exécutez l’agent dans votre réseau

   Le tableau de bord affiche la ligne docker run ou helm install exacte, avec votre jeton. Chaque réplique s’inscrit elle-même en appelant le point de terminaison de bootstrap SolidHooks, reçoit un jeton de heartbeat propre et rejoint le connecteur.

   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

   Ajoutez des répliques pour la disponibilité

   Exécutez la même commande ailleurs. Les répliques sont des membres indépendants d’un même connecteur : un redémarrage progressif ne laisse jamais le connecteur sans rien à joindre.

4. 4

   Créez une destination privée

   Définissez type: "private" et nommez le connecteur. L’URL est toujours validée comme une URL, elle n’a simplement pas besoin d’être résolue publiquement.

   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"  }'

Un connecteur indique un statut agrégé sur ses répliques, et les quatre valeurs sont choisies pour que notre incertitude ne soit jamais présentée comme votre panne.

# 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 crée un nouveau jeton de bootstrap et invalide le précédent. Les répliques déjà inscrites continuent de fonctionner : renouveler un jeton qui a fuité ne provoque pas de panne.

toggle-disabled empêche la création de nouvelles destinations privées sur le connecteur. Les répliques inscrites continuent d’émettre leur heartbeat, car la désactivation est un interrupteur administratif et non une révocation. La suppression d’un connecteur est bloquée avec un 400 tant qu’une destination y fait encore appel.

Une réplique n’est révoquée automatiquement que si elle est à la fois restée silencieuse au-delà de la fenêtre de heartbeat périmé et absente de l’overlay. Cette fenêtre est de 24 heures par défaut et réglée par déploiement : vérifiez la vôtre avant de la considérer comme une valeur fixe. Exiger les deux conditions permet de garder en vie un agent sain qui peut servir du trafic mais ne peut pas joindre notre API. Une réplique révoquée reçoit un 403 avec une raison lisible par machine et s’arrête. Un jeton non reconnu reçoit un 401 opaque, afin que le point de terminaison ne puisse pas servir à sonder quels identifiants sont actifs.

• Les connecteurs sont plafonnés par maxConnectors. Le dépasser renvoie 403 CONNECTOR_LIMIT_REACHED avec le nombre actuel.
• Les répliques par connecteur sont plafonnées par maxReplicasPerConnector, appliqué au bootstrap. Réduire un plan n’évince jamais les répliques déjà inscrites.
• La livraison privée est une capacité facultative de la plateforme. Sur un déploiement sans overlay configuré, les modifications de connecteur renvoient 400.

• Exécutez au moins deux répliques dans des domaines de défaillance différents. Avec une seule réplique, le connecteur reste un point de défaillance unique.
• Stockez la clé d’inscription dans votre gestionnaire de secrets dès la création du connecteur. Elle n’est plus jamais affichée, et le seul moyen de la récupérer est de la régénérer.
• Déclenchez une alerte quand connectedReplicas passe sous le nombre prévu, plutôt que sur le statut agrégé. Un connecteur indique connected avec une seule réplique active sur trois.
• Traitez unknown comme une lecture à relancer, pas comme une alerte à déclencher. Il décrit notre vue de l’overlay, pas votre agent.
• Un connecteur par réseau, réutilisé entre les projets. C’est précisément pour cela qu’ils sont rattachés à l’organisation.