Entregue para endpoints sem URL pública

Um conector representa uma das suas redes. Ele pertence à organização, não a um projeto, então um único conector de cluster atende todos os projetos que você tem. Dentro dessa rede, você roda uma ou mais réplicas do agente. Cada uma disca para o overlay e permanece conectada.

Quando uma entrega está pendente, o SolidHooks a passa ao conector pelo nome, e o agente faz a solicitação HTTP de fato de dentro da sua rede. Seu serviço vê uma solicitação vinda de um endereço local e não precisa de nenhuma alteração.

1. 1

   Provisione o conector

   A resposta traz uma enrollmentKey (cbt_…). Ela é exibida aqui e na regeneração, e em nenhum outro lugar, então guarde-a antes de continuar. Ela não expira.

   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

   Rode o agente na sua rede

   O painel mostra a linha exata de docker run ou helm install com o seu token. Cada réplica se registra sozinha chamando o endpoint de bootstrap do SolidHooks, recebe um token de heartbeat próprio e entra no 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

   Adicione réplicas para disponibilidade

   Rode o mesmo comando de novo em outro lugar. As réplicas são membros independentes de um mesmo conector, então um reinício gradual nunca deixa o conector sem nada para discar.

4. 4

   Crie um destino privado

   Defina type: "private" e informe o conector. A URL continua sendo validada como URL, só não precisa ser resolvida publicamente.

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

Um conector informa um status agregado das suas réplicas, e os quatro valores foram escolhidos para que a nossa incerteza nunca seja informada como indisponibilidade sua.

# 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 gera um novo token de bootstrap e invalida o anterior. As réplicas já registradas continuam rodando, então fazer a rotação de um token vazado não causa indisponibilidade.

toggle-disabled impede que novos destinos privados sejam criados para o conector. As réplicas registradas continuam enviando heartbeats, porque desativar é uma chave administrativa, não uma revogação. Excluir um conector é bloqueado com 400 enquanto algum destino ainda apontar para ele.

Uma réplica só é revogada automaticamente quando ficou em silêncio além da janela de heartbeat obsoleto e também não apareceu no overlay. Essa janela é de 24 horas por padrão e é definida por implantação, então confira a sua antes de tratá-la como um número fixo. Exigir as duas condições é o que mantém vivo um agente saudável quando ele consegue atender tráfego, mas não consegue alcançar a nossa API. Uma réplica revogada recebe 403 com um motivo legível por máquina e para. Um token não reconhecido recebe um 401 opaco, para que o endpoint não possa ser usado para sondar quais credenciais estão ativas.

• Os conectores são limitados por maxConnectors. Ultrapassar o limite retorna 403 CONNECTOR_LIMIT_REACHED com a contagem atual.
• As réplicas por conector são limitadas por maxReplicasPerConnector, aplicado no bootstrap. Reduzir o plano nunca remove réplicas que já estão registradas.
• A entrega privada é um recurso opcional da plataforma. Em uma implantação sem o overlay configurado, as alterações em conectores retornam 400.

• Rode pelo menos duas réplicas em domínios de falha diferentes. Com uma réplica só, o conector continua sendo um ponto único de falha.
• Guarde a chave de registro no seu gerenciador de segredos assim que criar o conector. Ela nunca mais é exibida, e o caminho de recuperação é a regeneração.
• Crie alertas para quando connectedReplicas cair abaixo da contagem pretendida, não com base no status agregado. Um conector aparece como connected com uma réplica de três ativa.
• Trate unknown como uma leitura a repetir, não como um alerta para acionar alguém. Ele descreve a nossa visão do overlay, não o seu agente.
• Um conector por rede, reutilizado entre projetos. Eles têm escopo de organização exatamente por isso.