Entrega a endpoints sin URL pública

Un conector representa una de tus redes. Pertenece a la organización y no a un proyecto, así que un solo conector de clúster sirve a todos tus proyectos. Dentro de esa red ejecutas una o varias réplicas del agente. Cada una se conecta hacia fuera a la red superpuesta y se queda ahí.

Cuando toca hacer una entrega, SolidHooks se la pasa al conector por su nombre y el agente hace la solicitud HTTP real desde dentro de tu red. Tu servicio ve una solicitud desde una dirección local y no necesita ningún cambio.

1. 1

   Aprovisiona el conector

   La respuesta incluye una enrollmentKey (cbt_…). Se muestra aquí y al regenerarla, y en ningún otro sitio, así que guárdala antes de seguir. No caduca.

   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

   Ejecuta el agente en tu red

   El panel muestra la línea exacta de docker run o helm install con tu token incluido. Cada réplica se registra sola llamando al endpoint de arranque de SolidHooks, recibe un token de latido propio y se une al conector.

   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

   Añade réplicas para la disponibilidad

   Ejecuta el mismo comando en otro sitio. Las réplicas son miembros independientes de un conector, así que un reinicio escalonado nunca deja al conector sin nada a lo que llamar.

4. 4

   Crea un destino privado

   Establece type: "private" e indica el conector. La URL se sigue validando como URL; simplemente no tiene que resolverse públicamente.

   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 conector informa de un estado agregado de sus réplicas, y los cuatro valores están elegidos para que nuestra incertidumbre nunca se presente como una caída tuya.

# 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 genera un token de arranque nuevo e invalida el anterior. Las réplicas ya registradas siguen funcionando, así que rotar un token filtrado no provoca una caída.

toggle-disabled impide crear destinos privados nuevos con el conector. Las réplicas registradas siguen enviando latidos, porque desactivar es un interruptor administrativo y no una revocación. Eliminar un conector se bloquea con 400 mientras algún destino siga apuntando a él.

Una réplica solo se revoca automáticamente cuando lleva en silencio más tiempo que la ventana de latido caducado y además no aparece en la red superpuesta. Esa ventana es de 24 horas por defecto y se configura por despliegue, así que comprueba la tuya antes de tomarla como un número fijo. Exigir las dos condiciones es lo que mantiene vivo a un agente sano cuando puede atender tráfico pero no puede llegar a nuestra API. Una réplica revocada recibe un 403 con un motivo legible por máquinas y se detiene. Un token no reconocido recibe un 401 opaco, así que el endpoint no sirve para averiguar qué credenciales están activas.

• Los conectores están limitados por maxConnectors. Superarlo devuelve 403 CONNECTOR_LIMIT_REACHED con el recuento actual.
• Las réplicas por conector están limitadas por maxReplicasPerConnector, que se aplica en el arranque. Reducir un plan nunca expulsa a las réplicas que ya están registradas.
• La entrega privada es una capacidad opcional de la plataforma. En un despliegue sin la red superpuesta configurada, las mutaciones de conectores devuelven 400.

• Ejecuta al menos dos réplicas en dominios de fallo distintos. Con una sola réplica, el conector sigue siendo un punto único de fallo.
• Guarda la clave de registro en tu gestor de secretos en cuanto crees el conector. No se vuelve a mostrar, y la forma de recuperarla es regenerarla.
• Configura alertas cuando connectedReplicas baje del número previsto, no sobre el estado agregado. Un conector aparece como connected con una sola réplica de tres activa.
• Trata unknown como una consulta que repetir, no como un aviso de guardia. Describe nuestra visión de la red superpuesta, no tu agente.
• Un conector por red, reutilizado entre proyectos. Pertenecen a la organización justo por eso.