Tunnels 설정

이 기능으로 할 수 있는 일

워크스페이스에서 Tunnels가 활성화되어 있어야 합니다. 워크스페이스 설정에서 Tunnels를 사용할 수 없다면 Replit에 문의하여 사용 가능 여부와 활성화를 확인하세요.

Tunnel을 사용하면 지원되는 Replit 개발 환경이 사용자가 운영하는 커넥터를 통해 프라이빗 네트워크의 승인된 TCP 대상에 접근할 수 있습니다. 이는 샌드박스 egress IP를 네트워크에서 허용하는 방식의 대안이 되는 연결 방법입니다. 커넥터는 프라이빗 TCP 서비스의 이름을 확인하고 해당 서비스에 도달할 수 있는 네트워크에서 실행하세요. 생성된 Docker 명령을 사용하거나 아래의 Helm 차트로 Kubernetes에 커넥터를 배포할 수 있습니다. Tunnel 컨트롤 플레인은 Replit이 운영합니다. 아래 차트는 사용자의 커넥터만 배포합니다. 연결 경로: Replit 프로젝트 → Replit tunnel 인프라 → 사용자의 커넥터 → 프라이빗 TCP 서비스. 서비스 인증과 TLS는 tunnel 등록과 별개로 유지됩니다.

1. Replit에서 Tunnel 생성

Replit에서 워크스페이스 선택기를 사용해 프로젝트를 소유한 워크스페이스를 선택합니다. Settings → Workspace overview를 열고 Tunnels까지 스크롤합니다.

Create tunnel을 클릭하고 알아보기 쉬운 이름을 입력합니다.

Save your enrollment key 대화상자에서 Tunnel ID와 Enrollment key 옆의 복사 버튼을 사용하세요. I’ve saved my key를 클릭하기 전에 승인된 시크릿 관리자에 등록 키를 저장하세요. 키는 한 번만 표시되며 이 대화상자를 닫은 뒤에는 다시 볼 수 없습니다.

일회성 등록 키 대화상자입니다. 이 스크린샷에서는 키를 의도적으로 가렸습니다.

Settings → Workspace overview → Tunnels를 열고 tunnel을 선택합니다. tunnel 이름 아래에 ID가 복사 버튼과 함께 표시됩니다. 커넥터가 온라인 상태가 되기 전에는 Complete tunnel setup 패널에 Docker 명령이 표시됩니다. 등록 키 자리 표시자를 저장해 둔 키로 바꾸세요.

Complete tunnel setup에서 Docker 명령을 복사합니다.

Helm을 사용하는 경우 설정 명령의 RPTUN_TUNNEL_REF와 RPTUN_ENROLL_ADDR 전체 값을 tunnelRef와 enrollAddr에 복사하세요. 명령의 마지막 줄에 있는 컨테이너 이미지는 image에 복사합니다. 전체 tunnel 참조는 tunnel 이름 아래에 표시되는 짧은 tunnel ID와 다릅니다. 등록 키는 설정 명령이 아니라 일회성 키 대화상자에서 가져옵니다. 프라이빗 서비스의 이름을 확인하고 도달할 수 있는 호스트에서 Docker 명령을 실행하세요. Kubernetes에서는 아래의 Helm 차트를 사용하세요.

2. Helm으로 커넥터 배포

이 예제 차트는 Kubernetes에서 고객 측 커넥터를 실행합니다. 클러스터의 표준에 맞게 조정하고, 프로덕션에 적용하기 전에 비프로덕션 환경에서 검증하세요.

차트 파일 생성

다음 디렉터리 구조를 만드세요:

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

Tunnel 구성

네임스페이스를 만들고 승인된 시크릿 관리 절차를 통해 등록 키를 프로비저닝하세요. 이 예제는 replit-tunnels 네임스페이스에 replit-tunnel-enrollment라는 Secret이 있고 그 안에 enrollment-key 필드가 있다고 가정합니다. 등록 키를 Helm values, 소스 관리, --set 인수에 넣지 마세요. customer-values.yaml — 사용자 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

프로덕션에서는 가능하다면 승인된 불변 커넥터 이미지 다이제스트를 사용하세요. 이 차트는 이미지의 엔트리포인트를 유지하고 생성된 Docker 명령에 표시된 환경 변수를 전달합니다. 사용하는 정확한 이미지와의 호환성을 검증하세요.

렌더링 및 설치

Helm과 kubectl이 대상 Kubernetes 클러스터에 맞게 구성된 상태에서, customer-values.yaml과 차트 디렉터리가 있는 디렉터리에서 다음 명령을 실행하세요. 네임스페이스와 Secret이 이미 존재해야 합니다:

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

이 차트는 Recreate 전략으로 단일 레플리카를 실행하므로 업데이트 시 다운타임이 발생합니다. 공개 Service나 LoadBalancer를 만들지 않으며 헬스 프로브도 정의하지 않습니다. Kubernetes의 readiness만으로는 tunnel 연결을 확인할 수 없습니다. Replit에서 Online 상태를 확인하고 아래의 프로젝트 Shell 테스트를 완료하세요. 프로덕션에서 사용하기 전에 리소스, CPU 아키텍처, 쓰기 가능한 상태 필요 여부, 보안 컨텍스트, 재시작 동작, 아웃바운드 네트워크 요구 사항을 검증하세요. 커넥터는 프라이빗 서비스의 DNS 호스트 이름과 TCP 포트에 도달할 수 있어야 합니다. 커넥터의 전체 egress 요구 사항은 Replit에 문의하여 받으세요. 문제 해결을 위해 로그를 로컬에서 검토하고, 공유하기 전에 자격 증명과 비공개 정보를 가리세요:

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

3. 커넥터가 온라인 상태인지 확인

Settings → Workspace overview → Tunnels로 돌아가 tunnel을 선택하세요. Status 카드에 Online이 표시될 때까지 기다립니다. 계속 오프라인이라면 등록 구성, 아웃바운드 네트워크 접근, 파드 이벤트, 커넥터 로그를 확인하세요.

Online은 커넥터가 연결되었음을 의미합니다. 애플리케이션 트래픽이 발생하기 전에는 Never로 표시되는 것이 정상입니다.

4. 프라이빗 엔드포인트 등록

Tunnel 상세 페이지의 Endpoints 섹션에서 Add endpoint를 클릭합니다.
알아보기 쉬운 이름과, TCP 포트를 포함한 프라이빗 대상 호스트 이름(예: database.internal.example:5432)을 입력합니다.
커넥터의 네트워크에서 확인 가능한 호스트 이름을 사용하세요. 현재 UI는 IP 주소 대상을 지원하지 않습니다.
Test connection을 선택합니다. 녹색 체크 표시는 커넥터가 대상에 도달할 수 있음을 의미합니다.
엔드포인트를 추가하고 표에 나타나는지 확인합니다.

연결 테스트 성공: Destination 옆의 녹색 체크 표시는 커넥터가 서비스에 도달할 수 있음을 확인해 줍니다.

엔드포인트는 표에 나타나며, 여기서 대상을 복사하거나 점 세 개 작업 메뉴를 열 수 있습니다.

커넥터가 Online이고 대상이 Reachable인 상태로 저장된 Redis 엔드포인트입니다.

5. Replit 프로젝트 Shell에서 엔드포인트 확인

워크스페이스 선택기를 사용해 tunnel을 소유한 워크스페이스로 돌아가 그곳의 프로젝트를 열고, 프로젝트 편집기에서 Shell 탭을 엽니다. 다음 확인 작업은 독립된 채팅이 아니라 이 Shell에서 실행하세요.

호스트 이름이 확인되는지 점검

포트나 URL 스킴 없이, 엔드포인트의 Destination 필드에 있는 호스트 이름을 사용하세요:

getent hosts YOUR_ENDPOINT_HOSTNAME

조회에 성공하면 IP 주소와 호스트 이름이 출력됩니다. DNS 확인만으로는 서비스 연결을 확인할 수 없으므로, 다음으로 아래의 서비스 테스트를 실행하세요.

서비스 연결 테스트

서비스의 기본 클라이언트로 일반적인 TLS 및 인증 요구 사항에 맞춰 가벼운 요청을 보내세요. Redis의 경우:

redis-cli -h YOUR_ENDPOINT_HOSTNAME -p 6379 PING

6379는 Redis의 기본 포트입니다. 등록한 엔드포인트의 포트와 다르면 그에 맞게 바꾸세요. 예상 결과: PONG. 이는 ICMP 네트워크 ping이 아니라 Redis의 애플리케이션 수준 PING입니다.

프로젝트 Shell에서의 호스트 이름 확인과 성공적인 Redis PONG 응답입니다.

요청에 성공하면 tunnel 대시보드에 최근 트래픽 타임스탬프가 표시됩니다.

6. 등록 키 관리

tunnels 대시보드로 돌아가 tunnel 이름 옆의 점 세 개 메뉴를 열고 Manage enrollment key를 선택하세요.

등록 키 추가

슬롯이 비어 있으면 Add enrollment key를 선택하세요. 초기 설정 때 보았던 것과 동일한 Save your enrollment key 대화상자가 열립니다. 새 키를 즉시 복사해 안전하게 저장하세요. 키는 한 번만 표시됩니다. 두 키 슬롯이 모두 사용 중이라면 계속하기 전에 폐기하거나 교체할 키를 확인하세요. 키를 무작정 폐기하지 마세요. 키 전달 재시도는 중단된 요청을 위한 기능이며, 이미 전달된 키를 다시 표시하기 위한 기능이 아닙니다.

등록 키 폐기

대상 키에서 Revoke를 선택하고, 선택한 키의 세부 정보를 확인한 다음 Confirm selected key revocation을 선택하세요. 이 키를 사용한 이후의 등록이 차단됩니다.

키를 폐기해도 이미 수립된 커넥터 세션은 끊어지지 않습니다. 기존 세션을 종료하려면 새 키로 커넥터를 재시작하세요.

폐기 후 활성 키 수가 갱신됩니다. 이미 연결된 커넥터는 계속 Online일 수 있습니다.

키 변경 후 커넥터 업데이트

승인된 시크릿 관리자를 통해 새 키를 프로비저닝하세요. Secret을 업데이트한 후 커넥터 디플로이먼트를 재시작합니다:

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

Online 상태를 확인하고 프로젝트 Shell에서 서비스 요청을 다시 실행하세요. 이 예제의 단일 레플리카 Recreate 전략에서는 다운타임이 발생하므로 이에 대비하세요. 키 폐기만으로 기존 연결이 종료된다고 가정하지 마세요.

7. 연결 해제 및 정리

커넥터가 중지되면 tunnel은 Offline이 되며 엔드포인트에 도달할 수 있다고 간주해서는 안 됩니다.

커넥터 연결을 해제한 후 Tunnel은 Offline, 엔드포인트는 Unreachable 상태입니다.

커넥터의 Helm 릴리스를 제거하려면:

helm uninstall replit-tunnel --namespace replit-tunnels

이 차트는 Secret, 네임스페이스, Replit tunnel, 엔드포인트를 관리하지 않습니다. 더 이상 필요하지 않을 때 이들을 별도로 제거하세요. 공유 네임스페이스나 다른 애플리케이션의 엔드포인트는 절대 제거하지 마세요.

문제 해결

Tunnels를 사용할 수 없음

커넥터나 네트워크 구성을 변경하기 전에 Replit에 워크스페이스 활성화 여부와 서비스 가용성 확인을 요청하세요.

커넥터 파드 실패

이미지 풀, 스케줄링, Secret 참조, 컨테이너 시작 오류를 점검하세요.

Tunnel 오프라인

등록 구성과 커넥터의 아웃바운드 연결을 점검하세요.

엔드포인트에 도달할 수 없음

프라이빗 DNS, 대상 서비스와 포트, 라우팅, 방화벽 규칙, 그리고 커넥터 네트워크의 Kubernetes NetworkPolicy를 확인하세요.

연결 테스트는 성공하지만 쿼리가 실패함

데이터베이스 TLS, 자격 증명, 데이터베이스 권한, 지원되는 Replit 샌드박스 라우팅 경로를 확인하세요.

중복된 대상

다른 등록을 만들기 전에 워크스페이스 전체의 기존 엔드포인트를 확인하세요.

호스트 이름이 확인되지 않음

저장된 엔드포인트와 같은 워크스페이스의 Replit 프로젝트 Shell에 있는지 확인하세요. 대상 호스트 이름과 tunnel 상태가 정확한지 확인하세요. 문제가 계속되면 워크스페이스/프로젝트와 오류 내용을 포함해 Replit에 문의하세요. 등록 키는 절대 공유하지 마세요.

​이 기능으로 할 수 있는 일

​1. Replit에서 Tunnel 생성

​2. Helm으로 커넥터 배포

​차트 파일 생성

​Tunnel 구성

​렌더링 및 설치

​3. 커넥터가 온라인 상태인지 확인

​4. 프라이빗 엔드포인트 등록

​5. Replit 프로젝트 Shell에서 엔드포인트 확인

​호스트 이름이 확인되는지 점검

​서비스 연결 테스트

​6. 등록 키 관리

​등록 키 추가

​등록 키 폐기

​키 변경 후 커넥터 업데이트

​7. 연결 해제 및 정리

​문제 해결

​Tunnels를 사용할 수 없음

​커넥터 파드 실패

​Tunnel 오프라인

​엔드포인트에 도달할 수 없음

​연결 테스트는 성공하지만 쿼리가 실패함

​중복된 대상

​호스트 이름이 확인되지 않음

이 기능으로 할 수 있는 일

1. Replit에서 Tunnel 생성

2. Helm으로 커넥터 배포

차트 파일 생성

Tunnel 구성

렌더링 및 설치

3. 커넥터가 온라인 상태인지 확인

4. 프라이빗 엔드포인트 등록

5. Replit 프로젝트 Shell에서 엔드포인트 확인

호스트 이름이 확인되는지 점검

서비스 연결 테스트

6. 등록 키 관리

등록 키 추가

등록 키 폐기

키 변경 후 커넥터 업데이트

7. 연결 해제 및 정리

문제 해결

Tunnels를 사용할 수 없음

커넥터 파드 실패

Tunnel 오프라인

엔드포인트에 도달할 수 없음

연결 테스트는 성공하지만 쿼리가 실패함

중복된 대상

호스트 이름이 확인되지 않음