Tunnelsのセットアップ

これで可能になること

Tunnelsはワークスペースで有効化されている必要があります。ワークスペース設定でTunnelsが利用できない場合は、Replitに連絡して利用可否と有効化を確認してください。

Tunnelを使用すると、サポートされているReplit開発環境が、お客様が運用するコネクターを介して、プライベートネットワーク内の承認済みTCP宛先に到達できます。これは、サンドボックスのエグレス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を選択します。IDはTunnel名の下にコピーボタン付きで表示されます。コネクターがオンラインになる前は、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

# 自分のTunnelのセットアップパネルにあるイメージと接続設定を使用してください。
# 登録キーをHelmのvaluesや --set 引数に含めないでください。
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を設定する

namespaceを作成し、承認済みのシークレット管理プロセスを通じて登録キーをプロビジョニングします。この例では、namespace replit-tunnels に、replit-tunnel-enrollment という名前のSecretと enrollment-key というフィールドが存在することを前提としています。登録キーをHelmのvalues、ソース管理、--set 引数に含めないでください。 customer-values.yaml — 自分のTunnelの生成されたセットアップコマンドを使用して、3つのプレースホルダーを置き換えます：

# 自分のTunnelのセットアップコマンドを使用して、3つのプレースホルダーをすべて置き換えてください。
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 とチャートディレクトリがあるディレクトリから次のコマンドを実行します。namespaceと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

このチャートはレプリカ1つを Recreate 戦略で実行するため、更新時にはダウンタイムが発生します。公開ServiceやLoadBalancerは作成せず、ヘルスプローブも定義しません。Kubernetesのreadinessだけでは、Tunnelの接続性は証明されません。Replitで Online を確認し、下記のプロジェクトShellテストを完了してください。本番環境で使用する前に、リソース、CPUアーキテクチャ、書き込み可能な状態の必要性、セキュリティコンテキスト、再起動時の動作、アウトバウンドネットワーク要件を検証してください。コネクターは、プライベートサービスのDNSホスト名とTCPポートに到達できる必要があります。コネクターの完全なエグレス要件はReplitにお問い合わせください。トラブルシューティングのために、ログをローカルで確認し、共有する前に認証情報とプライベートな情報を削除してください：

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

3. コネクターがオンラインであることを確認する

Settings → Workspace overview → Tunnels に戻り、Tunnelを選択します。Statusカードに Online と表示されるまで待ちます。オフラインのままの場合は、登録設定、アウトバウンドネットワークアクセス、Podイベント、コネクターのログを確認してください。

Online はコネクターが接続されていることを意味します。アプリケーショントラフィックが発生する前は Never と表示されるのが正常です。

4. プライベートエンドポイントを登録する

Tunnelの詳細ページで、Endpointsセクションの Add endpoint をクリックします。
わかりやすい名前と、プライベートな宛先のホスト名およびTCPポートを入力します。例：database.internal.example:5432
コネクターのネットワークから名前解決できるホスト名を使用してください。現在のUIはIPアドレスによる宛先をサポートしていません。
Test connection を選択します。緑のチェックマークは、コネクターが宛先に到達できることを意味します。
エンドポイントを追加し、テーブルに表示されることを確認します。

接続テストの成功：Destination の横の緑のチェックマークは、コネクターがサービスに到達できることを示します。

エンドポイントはテーブルに表示され、宛先をコピーしたり、3点リーダーのアクションメニューを開いたりできます。

保存されたRedisエンドポイント。コネクターは Online、宛先は Reachable です。

5. ReplitプロジェクトのShellでエンドポイントの名前解決を検証する

ワークスペースセレクターを使用してTunnelを所有するワークスペースに戻り、そこでプロジェクトを開き、プロジェクトエディターの Shell タブを開きます。以下のチェックは、スタンドアロンのチャットではなく、このShellで実行してください。

ホスト名が名前解決されることを確認する

エンドポイントの Destination フィールドにあるホスト名を、ポートやURLスキームを付けずに使用します：

getent hosts YOUR_ENDPOINT_HOSTNAME

名前解決に成功すると、IPアドレスとホスト名が出力されます。DNS解決だけではサービスへの接続性は確認できません。次に下記のサービステストを実行してください。

サービス接続をテストする

通常のTLSおよび認証要件に従い、サービスのネイティブクライアントを使用して軽量なリクエストを送信します。Redisの場合：

redis-cli -h YOUR_ENDPOINT_HOSTNAME -p 6379 PING

6379 はRedisのデフォルトポートです。登録したエンドポイントのポートに合わせて、必要に応じて置き換えてください。期待される結果：PONG。これはRedisのアプリケーションレベルの PING であり、ICMPのネットワークpingではありません。

プロジェクトShellでのホスト名の名前解決と、Redisからの正常な PONG。

リクエストが成功すると、Tunnelダッシュボードに最近のトラフィックのタイムスタンプが表示されます。

6. 登録キーを管理する

Tunnelダッシュボードに戻り、Tunnel名の横にある3点リーダーメニューを開いて Manage enrollment key を選択します。

登録キーを追加する

空きスロットがある場合は Add enrollment key を選択します。初期セットアップ時と同じ Save your enrollment key ダイアログが開きます。新しいキーをすぐにコピーし、安全に保存してください。キーは一度しか表示されません。両方のキースロットが使用中の場合は、続行する前に、失効または置き換えるキーを特定してください。むやみにキーを失効させないでください。Retry key delivery は中断されたリクエスト用であり、すでに配信されたキーを再表示するためのものではありません。

登録キーを失効させる

対象のキーで 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、namespace、ReplitのTunnel、エンドポイントを管理しません。これらは不要になった場合にのみ、個別に削除してください。共有namespaceや他のアプリケーションのエンドポイントは絶対に削除しないでください。

トラブルシューティング

Tunnelsが利用できない

コネクターやネットワーク設定を変更する前に、Replitにワークスペースの有効化とサービスの可用性の確認を依頼してください。

コネクターのPodが失敗する

イメージのプル、スケジューリング、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が利用できない

​コネクターのPodが失敗する

​Tunnelがオフラインになる

​エンドポイントに到達できない

​接続テストは成功するがクエリが失敗する

​宛先の重複

​ホスト名が名前解決されない

これで可能になること

1. ReplitでTunnelを作成する

2. Helmでコネクターをデプロイする

チャートファイルを作成する

Tunnelを設定する

レンダリングとインストール

3. コネクターがオンラインであることを確認する

4. プライベートエンドポイントを登録する

5. ReplitプロジェクトのShellでエンドポイントの名前解決を検証する

ホスト名が名前解決されることを確認する

サービス接続をテストする

6. 登録キーを管理する

登録キーを追加する

登録キーを失効させる

キー変更後にコネクターを更新する

7. 切断とクリーンアップ

トラブルシューティング

Tunnelsが利用できない

コネクターのPodが失敗する

Tunnelがオフラインになる

エンドポイントに到達できない

接続テストは成功するがクエリが失敗する

宛先の重複

ホスト名が名前解決されない