Configurar Tunnels

O que isso habilita

O Tunnels precisa estar habilitado para o seu workspace. Se o Tunnels não estiver disponível nas configurações do seu workspace, entre em contato com o Replit para confirmar a disponibilidade e a habilitação.

Um tunnel permite que um Replit Development Environment compatível alcance um destino TCP aprovado na sua rede privada por meio de um conector operado por você. Esta é uma abordagem de conectividade alternativa a permitir os IPs de saída do sandbox na sua rede. Execute o conector em uma rede onde ele possa resolver e alcançar seus serviços TCP privados. Você pode usar o comando Docker gerado ou implantar o conector no Kubernetes com o chart Helm abaixo. O Replit opera o plano de controle do tunnel. O chart abaixo implanta apenas o seu conector. Caminho da conexão: projeto Replit → infraestrutura de tunnel do Replit → seu conector → serviço TCP privado. A autenticação do serviço e o TLS permanecem independentes do registro do tunnel.

1. Crie o tunnel no Replit

No Replit, use o seletor de workspace para escolher o workspace que possui seus projetos. Abra Settings → Workspace overview e role até Tunnels.

Abra a seção Tunnels nas configurações do seu workspace.

Clique em Create tunnel e insira um nome descritivo.

Na caixa de diálogo Save your enrollment key, use os botões de copiar ao lado de Tunnel ID e Enrollment key. Salve a chave de registro no seu gerenciador de segredos aprovado antes de clicar em I’ve saved my key. A chave é exibida apenas uma vez e não pode ser vista novamente depois que você fechar esta caixa de diálogo.

A caixa de diálogo de chave de registro de uso único. A chave está intencionalmente oculta nesta captura de tela.

Abra Settings → Workspace overview → Tunnels e selecione seu tunnel. O ID dele aparece abaixo do nome do tunnel, com um botão de copiar. Antes de o conector ficar online, o painel Complete tunnel setup mostra o comando Docker. Substitua o placeholder da chave de registro pela chave que você salvou.

Copie o comando Docker de Complete tunnel setup.

Para o Helm, copie os valores completos de RPTUN_TUNNEL_REF e RPTUN_ENROLL_ADDR do comando de configuração para tunnelRef e enrollAddr. Copie a imagem do contêiner da última linha do comando para image. A referência completa do tunnel é diferente do ID curto do tunnel exibido abaixo do nome do tunnel. A chave de registro vem da caixa de diálogo de chave de uso único, não do comando de configuração. Execute o comando Docker em um host que possa resolver e alcançar seu serviço privado. Para o Kubernetes, use o chart Helm abaixo.

2. Implante o conector com Helm

Este chart de exemplo executa o conector do lado do cliente no Kubernetes. Adapte-o aos padrões do seu cluster e valide-o em um ambiente de não produção antes de implantá-lo.

Crie os arquivos do chart

Crie esta estrutura de diretórios:

replit-tunnel-connector/
  Chart.yaml
  values.yaml
  templates/
    deployment.yaml
customer-values.yaml

mkdir -p replit-tunnel-connector/templates

replit-tunnel-connector/Chart.yaml

apiVersion: v2
name: replit-tunnel-connector
description: Example customer-side Replit tunnel connector.
type: application
version: 0.1.0

replit-tunnel-connector/values.yaml

# Use the image and connection settings from your own tunnel's setup panel.
# Do not put enrollment keys in Helm values or --set arguments.
image: ""
tunnelRef: ""
enrollAddr: ""
existingSecret: replit-tunnel-enrollment
secretKey: enrollment-key
resources: {}
nodeSelector: {}
tolerations: []
affinity: {}

replit-tunnel-connector/templates/deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ .Release.Name }}
  labels:
    app.kubernetes.io/name: replit-tunnel-connector
    app.kubernetes.io/instance: {{ .Release.Name }}
spec:
  replicas: 1
  strategy:
    type: Recreate
  selector:
    matchLabels:
      app.kubernetes.io/name: replit-tunnel-connector
      app.kubernetes.io/instance: {{ .Release.Name }}
  template:
    metadata:
      labels:
        app.kubernetes.io/name: replit-tunnel-connector
        app.kubernetes.io/instance: {{ .Release.Name }}
    spec:
      automountServiceAccountToken: false
      containers:
        - name: connector
          image: {{ required "Set image to the connector image from your tunnel setup panel" .Values.image | quote }}
          imagePullPolicy: IfNotPresent
          env:
            - name: RPTUN_ENROLLMENT_KEY
              valueFrom:
                secretKeyRef:
                  name: {{ required "Set existingSecret" .Values.existingSecret | quote }}
                  key: {{ required "Set secretKey" .Values.secretKey | quote }}
            - name: RPTUN_TUNNEL_REF
              value: {{ required "Set tunnelRef from your tunnel setup panel" .Values.tunnelRef | quote }}
            - name: RPTUN_ENROLL_ADDR
              value: {{ required "Set enrollAddr from your tunnel setup panel" .Values.enrollAddr | quote }}
          resources:
            {{- toYaml .Values.resources | nindent 12 }}
      nodeSelector:
        {{- toYaml .Values.nodeSelector | nindent 8 }}
      tolerations:
        {{- toYaml .Values.tolerations | nindent 8 }}
      affinity:
        {{- toYaml .Values.affinity | nindent 8 }}

Configure seu tunnel

Crie o namespace e provisione a chave de registro por meio do seu processo aprovado de gerenciamento de segredos. O exemplo espera um Secret chamado replit-tunnel-enrollment com um campo chamado enrollment-key no namespace replit-tunnels. Não coloque a chave de registro em valores do Helm, no controle de versão ou em argumentos --set. customer-values.yaml — substitua os três placeholders usando o comando de configuração gerado para o seu próprio tunnel:

# Replace all three placeholders using your own tunnel's setup command.
image: "CONNECTOR_IMAGE_FROM_REPLIT"
tunnelRef: "TUNNEL_REFERENCE_FROM_REPLIT"
enrollAddr: "ENROLLMENT_ADDRESS_FROM_REPLIT"
existingSecret: replit-tunnel-enrollment
secretKey: enrollment-key

Use um digest de imagem de conector imutável aprovado para produção, quando disponível. O chart preserva o entry point da imagem e passa as variáveis de ambiente mostradas no comando Docker gerado. Valide a compatibilidade com a sua imagem exata.

Renderize e instale

Com o Helm e o kubectl configurados para o cluster Kubernetes pretendido, execute estes comandos a partir do diretório que contém customer-values.yaml e o diretório do chart. O namespace e o Secret já devem existir:

helm lint ./replit-tunnel-connector -f customer-values.yaml
helm template replit-tunnel ./replit-tunnel-connector \
  --namespace replit-tunnels -f customer-values.yaml
helm upgrade --install replit-tunnel ./replit-tunnel-connector \
  --namespace replit-tunnels -f customer-values.yaml \
  --wait --timeout 5m
kubectl -n replit-tunnels rollout status deployment/replit-tunnel
kubectl -n replit-tunnels get pods -l app.kubernetes.io/instance=replit-tunnel

O chart executa uma réplica com a estratégia Recreate, então as atualizações causam indisponibilidade. Ele não cria nenhum Service público ou LoadBalancer e não define probes de integridade. A prontidão do Kubernetes por si só não comprova a conectividade do tunnel: confirme Online no Replit e conclua os testes de Shell do projeto abaixo. Antes de usar em produção, valide recursos, arquitetura de CPU, necessidades de estado gravável, contexto de segurança, comportamento de reinicialização e requisitos de rede de saída. O conector precisa alcançar o hostname DNS e a porta TCP do seu serviço privado. Obtenha do Replit os requisitos completos de saída do conector. Para solução de problemas, revise os logs localmente e remova credenciais e informações privadas antes de compartilhá-los:

kubectl -n replit-tunnels logs deployment/replit-tunnel --tail=100

3. Confirme que o conector está online

Volte para Settings → Workspace overview → Tunnels e selecione seu tunnel. Aguarde o card Status mostrar Online. Se ele continuar offline, verifique a configuração de registro, o acesso de rede de saída, os eventos do pod e os logs do conector.

Online significa que o conector está conectado. Never é esperado antes de qualquer tráfego de aplicativo.

4. Registre um endpoint privado

Na página de detalhes do tunnel, clique em Add endpoint na seção Endpoints.
Insira um nome descritivo e o hostname do destino privado com sua porta TCP, por exemplo database.internal.example:5432.
Use um hostname que possa ser resolvido a partir da rede do conector. A interface atual não oferece suporte a destinos com endereço IP.
Selecione Test connection. Um check verde significa que o conector consegue alcançar o destino.
Adicione o endpoint e confirme que ele aparece na tabela.

Teste de conexão bem-sucedido: o check verde ao lado de Destination confirma que o conector consegue alcançar o serviço.

O endpoint aparece na tabela, onde você pode copiar seu destino ou abrir o menu de ações de três pontos.

Endpoint Redis salvo com o conector Online e o destino Reachable.

5. Verifique a resolução do endpoint em um Shell de projeto do Replit

Use o seletor de workspace para voltar ao workspace que possui o tunnel, abra um projeto nele e abra a aba Shell no editor do projeto. Execute as verificações a seguir nesse Shell, não em um chat independente.

Confirme que o hostname é resolvido

Use o hostname do campo Destination do endpoint, sem a porta nem o esquema de URL:

getent hosts YOUR_ENDPOINT_HOSTNAME

Uma consulta bem-sucedida imprime um endereço IP e o hostname. A resolução de DNS por si só não confirma a conectividade com o serviço; execute em seguida o teste de serviço abaixo.

Teste a conexão com o serviço

Use o cliente nativo do seu serviço para uma solicitação leve, com os requisitos normais de TLS e autenticação. Para o Redis:

redis-cli -h YOUR_ENDPOINT_HOSTNAME -p 6379 PING

6379 é a porta padrão do Redis. Substitua-a, se necessário, para corresponder à porta do seu endpoint registrado. Resultado esperado: PONG. Este é o PING no nível de aplicação do Redis, não um ping de rede ICMP.

Resolução de hostname e um PONG do Redis bem-sucedido no Shell do projeto.

Após uma solicitação bem-sucedida, o painel do tunnel passa a mostrar os carimbos de data/hora do tráfego recente.

Atividade do tunnel após a solicitação Redis bem-sucedida.

6. Gerencie chaves de registro

De volta ao painel de tunnels, abra o menu de três pontos ao lado do nome do tunnel e selecione Manage enrollment key.

Abra o gerenciamento de chaves de registro.

Lista de chaves ativas e ações disponíveis.

Adicione uma chave de registro

Escolha Add enrollment key quando houver um slot disponível. Isso abre a mesma caixa de diálogo Save your enrollment key exibida durante a configuração inicial. Copie a nova chave imediatamente e salve-a com segurança: ela é exibida apenas uma vez. Se os dois slots de chave estiverem ocupados, identifique a chave a ser revogada ou substituída antes de continuar. Não revogue uma chave às cegas. Retry key delivery serve para uma solicitação interrompida, não para exibir novamente uma chave entregue anteriormente.

Revogue uma chave de registro

Escolha Revoke na chave desejada, confira os detalhes da chave selecionada e escolha Confirm selected key revocation. Isso bloqueia novos registros usando essa chave.

Revogar uma chave não desconecta sessões de conector já estabelecidas. Reinicie o conector com uma nova chave para encerrar as sessões existentes.

Revise e confirme a revogação da chave selecionada.

Após a revogação, a contagem de chaves ativas é atualizada. O conector já estabelecido ainda pode estar Online.

Atualize um conector após alterar sua chave

Provisione a nova chave por meio do seu gerenciador de segredos aprovado. Reinicie o deployment do conector após a atualização do Secret:

kubectl -n replit-tunnels rollout restart deployment/replit-tunnel
kubectl -n replit-tunnels rollout status deployment/replit-tunnel

Confirme Online e repita a solicitação de serviço no Shell do projeto. Planeje uma indisponibilidade com a estratégia Recreate de réplica única deste exemplo. Não presuma que a revogação por si só encerra uma conexão existente.

7. Desconecte e limpe

Quando o conector é interrompido, o tunnel passa a Offline e o endpoint não deve ser tratado como alcançável.

Tunnel Offline e endpoint Unreachable após desconectar o conector.

Para remover o release Helm do conector:

helm uninstall replit-tunnel --namespace replit-tunnels

O chart não gerencia o Secret, o namespace, o tunnel do Replit nem os endpoints. Remova-os separadamente somente quando não forem mais necessários. Nunca remova um namespace compartilhado nem o endpoint de outro aplicativo.

Solução de problemas

Tunnels indisponível

Peça ao Replit para verificar a habilitação do workspace e a disponibilidade do serviço antes de alterar a configuração do conector ou da rede.

Falha no pod do conector

Inspecione erros de pull de imagem, agendamento, referências ao Secret e inicialização do contêiner.

Tunnel offline

Inspecione a configuração de registro e a conectividade de saída do conector.

Endpoint inalcançável

Verifique o DNS privado, o serviço e a porta de destino, o roteamento, as regras de firewall e quaisquer NetworkPolicies do Kubernetes a partir da rede do conector.

O teste de conexão é bem-sucedido, mas a consulta falha

Verifique o TLS do banco de dados, as credenciais, as permissões do banco de dados e o caminho de roteamento do sandbox do Replit compatível.

Destino duplicado

Verifique os endpoints existentes em todo o workspace antes de criar outro registro.

O hostname não é resolvido

Confirme que você está em um Shell de projeto do Replit, no mesmo workspace do endpoint salvo. Verifique o hostname de destino exato e o status do tunnel. Se o problema persistir, entre em contato com o Replit informando o workspace/projeto e o erro. Nunca compartilhe a chave de registro.

​O que isso habilita

​1. Crie o tunnel no Replit

​2. Implante o conector com Helm

​Crie os arquivos do chart

​Configure seu tunnel

​Renderize e instale

​3. Confirme que o conector está online

​4. Registre um endpoint privado

​5. Verifique a resolução do endpoint em um Shell de projeto do Replit

​Confirme que o hostname é resolvido

​Teste a conexão com o serviço

​6. Gerencie chaves de registro

​Adicione uma chave de registro

​Revogue uma chave de registro

​Atualize um conector após alterar sua chave

​7. Desconecte e limpe

​Solução de problemas

​Tunnels indisponível

​Falha no pod do conector

​Tunnel offline

​Endpoint inalcançável

​O teste de conexão é bem-sucedido, mas a consulta falha

​Destino duplicado

​O hostname não é resolvido

O que isso habilita

1. Crie o tunnel no Replit

2. Implante o conector com Helm

Crie os arquivos do chart

Configure seu tunnel

Renderize e instale

3. Confirme que o conector está online

4. Registre um endpoint privado

5. Verifique a resolução do endpoint em um Shell de projeto do Replit

Confirme que o hostname é resolvido

Teste a conexão com o serviço

6. Gerencie chaves de registro

Adicione uma chave de registro

Revogue uma chave de registro

Atualize um conector após alterar sua chave

7. Desconecte e limpe

Solução de problemas

Tunnels indisponível

Falha no pod do conector

Tunnel offline

Endpoint inalcançável

O teste de conexão é bem-sucedido, mas a consulta falha

Destino duplicado

O hostname não é resolvido