Skip to main content
direct データプレーンのエンドポイントを使用すると、cwsandbox クライアントは exec、ログ、ファイル操作をランナーへ直接送信できます。これらの操作は CoreWeave Sandboxes のゲートウェイを経由せず、相互 TLS (mTLS) で通信します。ライフサイクルおよび管理関連の Call は、引き続きゲートウェイを経由します。 このページは、CoreWeave Kubernetes Service (CKS) クラスター上でマネージドランナーを運用する管理者を対象としています。このページでは、次の内容について説明します。
  • direct パスがランナーに到達する仕組み
  • 公開モードを選択して設定する方法
  • 独自の Ingress コントローラー経由でエンドポイントをルーティングする方法
  • エンドポイントの準備が完了していることを確認する方法

ランナーへの direct 接続パス

各マネージドランナーは、すべてのレプリカの前段に配置される安定したデータプレーンエンドポイントを 1 つ提供できます。プラットフォームは、ランナーの dataPlane 設定からエンドポイントのアドレスを解決し、そのアドレス用のサーバー証明書をランナーに発行します。CoreWeave Sandboxes ゲートウェイは、このアドレスを、サンドボックスにスコープが限定されたクライアント証明書とともにクライアントに返します。 このパスには次の特性があり、それがこのページで説明する設定の選択に影響します。
  • TLS セッションはランナーで終端します: ランナーは、すべての接続をクライアント証明書で認証します。そのため、中継するコンポーネントは Transmission Control Protocol (TCP) ストリームを変更せずに転送する必要があります。これには、ロードバランサー、Ingress コントローラー、仮想プライベートネットワーク (VPN) が含まれます。TLS を終端して再暗号化するプロキシや、クライアントのアイデンティティをヘッダーに置き換えるプロキシを使用すると、direct パスは機能しなくなります。
  • サーバー証明書はアドバタイズされたアドレスに対して発行されます: プラットフォームは、設定したアドレスから証明書のサブジェクト代替名 (SAN) を生成します。クライアントはその名前でランナーを検証するため、アドレスは固定されていて、かつエンドポイントに名前解決できる必要があります。
  • データプレーンの Service が公開するポートは 1 つだけです: どの公開モードを有効にしても、作成される Service はデータプレーンのリスナーである TCP ポート 9443 のみを対象とします。カスタムイングレスでは、443 などの別のポートをパブリッシュして、この Service に転送できます。データプレーンの Service は、健全性、メトリクス、制御用のポートを公開しません。
デフォルトの AUTO トランスポートポリシーを使用するクライアントは、direct 接続のセットアップが利用できない場合、ゲートウェイにフォールバックできます。ただし、認証情報の発行時に PERMISSION_DENIED または UNAUTHENTICATED エラーが返された場合は、フォールバックされずに失敗します。direct 証明書に特定の操作の権限がない場合は、AUTO によってゲートウェイが使用されることがあります。なお、フォールバックが行われても、すでにランナーに送信された操作を安全に再試行できるとは限りません。

前提条件

direct データプレーンを設定する前に、次の前提条件を満たしてください。
  • マネージドランナーをデプロイし、installStatus が RUNNER_INSTALL_STATUS_READY になっていることを確認します。例に含まれる RUNNER_ID は、ご自身のランナー ID に置き換えてください。デプロイ手順については、ランナーのデプロイと管理を参照してください。
  • ランナーのページの Before you begin の説明に従って、CoreWeave Intelligent CLI を認証するか、curl 用に CoreWeave API アクセストークンをエクスポートします。このページの例でも、同じ $TOKEN 変数を使用します。
  • ランナーの読み取りや更新には、sandbox_admin 権限を持つトークンを使用します。
  • ランナーをホストする CKS クラスターに kubectl でアクセスできるようにしておきます。ランナーのリソースは cw-sandbox-system namespace に配置されます。カスタム公開の例を実行する場合は、Helm もインストールし、CustomResourceDefinition (CRD) や GatewayClass などのクラスタースコープのリソースを管理する権限も用意してください。

公開モードを選択する

spec.data_plane フィールドでは、公開モードを 1 つだけ選択します。このフィールドを未設定のままにすると、ランナーはそのリリースチャンネルにおけるプラットフォームのデフォルトを継承します。有効になっているデフォルトを使用しない場合は、disabled を明示的に設定してください。 以下のアドレスでは、SERVICE_NAME をランナーの Service 名に、HOSTNAME を設定済みのホスト名に置き換えてください。 プラットフォームは、ランナーの内部識別子に基づいて Service に名前を付けます。そのため、名前は推測せずにクラスターから読み取ってください。この Service には sandbox.coreweave.com/component=data-plane というラベルが付与されています。
変更には次の制約があります。
  • 空でない load_balancer.load_balancer_class を一度設定すると、別の有効な公開モードへの切り替えを含め、その場で変更またはクリアすることはできません。まず disabled を設定し、Service が削除されるのを待ってから、新しい設定を適用してください。
  • 公開モードを変更すると、アドバタイズされるアドレスが変わり、進行中の direct 操作が中断される可能性があります。変更後は、接続性を改めて検証してください。

LoadBalancer Service でエンドポイントを公開する

load_balancer モードでは、TLS を終端せずに TCP ポート 9443 をランナーへ転送する LoadBalancer Service が作成されます。想定する到達範囲は scope で設定し、プロバイダーのアドレス選択は annotations または load_balancer_class で設定します。クライアントのネットワーク範囲は、classless inter-domain routing (CIDR) 表記で source_ranges に指定します。プロバイダー側で、これらのソース範囲がサポートされ、強制される必要があります。 hostname は必須です。プラットフォームはこの値をサーバー証明書に含め、クライアントに https://HOSTNAME:9443 を通知します。また、ExternalDNS を実行しているクラスター向けに、Service に external-dns.alpha.kubernetes.io/hostname アノテーションを設定します。CKS では、代わりに External Hostname Controller を使用して名前をパブリッシュします。service.beta.kubernetes.io/external-hostname アノテーションを追加し、hostname には CKS が割り当てる完全修飾名を設定してください。たとえば、短いアノテーション値 runner-a からは runner-a.ORG_ID-CLUSTER_NAME.coreweave.app が生成されます。Create a public DNS name の手順のうち、DNS の割り当てに関する手順のみを実施してください。TLS 証明書はランナーが提供するため、このエンドポイントにはイングレスの TLS 終端を設定しないでください。 CKS でパブリックアドレスを使用する場合は、service.beta.kubernetes.io/coreweave-load-balancer-type: public も追加します。CKS のデフォルトのアドレス設定では、このアノテーションを省略するとプライベートアドレスが割り当てられます。アドレス選択の詳細については、Expose a Service を参照してください。PRIVATE スコープでは、プロバイダーがプライベートアドレスをどのように選択するかをプラットフォーム側で推測できないため、load_balancer_class またはプロバイダーのアノテーションのいずれかが必要です。 ORG_ID と CLUSTER_NAME を組織 ID とクラスター名に置き換え、source_ranges 内の CLIENT_CIDR をクライアントの接続元ネットワークの CIDR に置き換えてください。
data-plane.yaml
更新後、ランナーは新しい設定でロールアウトされ、cw-sandbox-system namespace に Service が作成されます。Service のアドレスと DNS を確認したうえで、クライアントから接続を検証してください。設定の更新が成功しても、ネットワークに到達できることが確認されたわけではありません。

独自の Ingress コントローラー経由でエンドポイントをルーティングする

クラスターの受信トラフィックをすでに Ingress コントローラーで終端している場合は、同じアドレスの背後に置くエンドポイントに custom モードを使用します。プラットフォームがポート 9443 で ClusterIP Service を作成するので、クライアントの接続先となるアドレスを advertised_uri として指定してください。 要件は、ランナーの前段に置く他の経路の場合と同じです。
  • ルートには TLS パススルーを使用し、接続の TLS Server Name Indication (SNI) でマッチングします。Ingress コントローラーでは TLS を終端しないでください。
  • advertised_uri には、パス、クエリ、認証情報を含まない絶対 https:// オリジンを設定します (例: https://runner-a.ORG_ID-CLUSTER_NAME.coreweave.app:443)。ホストは Ingress コントローラーに名前解決される必要があり、ポートはコントローラーがリッスンしているポートと一致している必要があります。
  • 使用するコントローラーと互換性のある Gateway API CRD をインストールします。CoreWeave Traefik チャートと Envoy Gateway v1.9.1 の例は、どちらも TLSRoute バージョン v1 をサポートしています。別のコンポーネントが所有する CRD バンドルを置き換えないでください。置き換える必要がある場合は、事前にその所有者と調整してください。
どちらの例も、クラスターの .coreweave.app ドメイン配下のホスト名を使用します。Traefik ではクラスターのワイルドカードレコードを使用します。Envoy の例では、external-hostname アノテーションで個別のレコードを作成します。ORG_ID と CLUSTER_NAME はご自身の値に置き換えてください。

Ingress コントローラーを準備する

使用しているコントローラーを選択してください。どちらの設定でも、.coreweave.app の DNS 名を持つパブリックな LoadBalancer Service 上で、ランナーのホスト名用の TLS パススルーリスナーをパブリッシュします。
CoreWeave の Traefik チャートでは、Ingress ルートと同じ Pod および同じ LoadBalancer Service 上で Gateway API ルートを提供できます。このチャートの Service には、service.beta.kubernetes.io/coreweave-load-balancer-type: public と service.beta.kubernetes.io/external-hostname: '*' がすでに設定されています。このワイルドカードにより、個別の DNS レコードが優先される場合を除き、*.ORG_ID-CLUSTER_NAME.coreweave.app 配下のホスト名は Traefik に名前解決されます。ランナーのホスト名を使用する前に、そのホスト名が Traefik のアドレスに名前解決されることを確認してください。既存のレコードが別の宛先を指している場合は、未使用のホスト名を選択するか、そのレコードを更新してください。チャートの前提条件と CRD の所有権に関するガイダンスについては、Gateway API を参照してください。
  1. Install the Gateway API CRDs の手順に従って、チャートがサポートする standard チャンネルのバンドルをインストールします。互換性のあるバンドルがすでにインストールされている場合は、それを再利用してください。
  2. Gateway API プロバイダーを有効にし、websecure エントリポイントに TLS パススルーのリスナーを追加します。リスナーの port には、LoadBalancer が公開するポート (443) ではなく、Traefik のコンテナーポート (8443) を指定します。
    traefik-values.yaml
    このチャートで Traefik をすでにインストールしている場合は、これらの値を既存の values ファイルにマージして、リリースをアップグレードしてください。
作成される Gateway の名前は traefik-gateway で、traefik namespace に配置されます。次のルートでは、これらの値を GATEWAY_NAME と GATEWAY_NAMESPACE に指定してください。

ランナーの接続先をイングレスアドレスに設定する

custom.advertised_uri の値はクライアントが接続先として使用するアドレスです。そのため、ClusterIP の Service ではなく、イングレスのホスト名とポートを指定します。
  1. custom.advertised_uri を、Ingress コントローラーが提供するアドレスに設定します。この設定により、次のステップでルーティング先となるデータプレーンの Service も作成されます。
    data-plane.yaml
  2. ランナーのロールアウトが完了するまで待ちます。
  3. 作成された Service の名前を確認します:

ルートをランナーの Service にバインドする

ランナーの Namespace に TLSRoute を作成し、パススルーリスナーをデータプレーンの Service にバインドします。
  1. GATEWAY_NAME と GATEWAY_NAMESPACE を準備したコントローラーの値に、SERVICE_NAME を前のステップで確認した Service 名に置き換えます。
    runner-tlsroute.yaml
  2. status.parents[].conditions に Accepted: True と ResolvedRefs: True が表示されていることを確認します。
  3. エンドポイントを使用するネットワーク上のクライアントから検証します。

エンドポイントのステータスを確認する

設定を変更した後は、必ずランナーの状態を確認してください。
  1. installStatus と connectionStatus を確認し、activeRevision が targetRevision に達しているかどうかを確認します。
  2. データプレーンの Service を確認します。
    load_balancer の場合は、Service にアドレスが割り当てられていること、および設定済みのホスト名がそのアドレスに名前解決されることを確認します。custom の場合は、Ingress コントローラーのアドレスと TLSRoute の条件を確認します。
これらの確認だけでは、クライアントが mTLS を完了できるかどうかまではわかりません。続けて、クライアント側の確認を行ってください。

クライアントから検証する

管理コマンドで cwic auth login を使用した場合でも、Python クライアントには専用のトークン環境変数が必要です。次のコマンドの API_ACCESS_TOKEN を、CoreWeave API アクセストークンのシークレットに置き換えてください。
  1. Python 環境を準備するの説明に従って、有効化した Python 仮想環境にクライアントをインストールします。
  2. クライアントのトランスポートポリシーを DIRECT に設定し、設定済みの CKS ランナーで操作を実行します。このモードではゲートウェイへのフォールバックが一切行われないため、呼び出しが成功すれば、そのネットワークから direct パスが機能していることを確認できます。
同じ呼び出しが DataPlaneMode.GATEWAY では成功するのに、この呼び出しではエラーが発生する場合は、トラブルシューティングを参照してください。クライアントオプションの完全な一覧については、サンドボックスへの direct 接続を参照してください。

エンドポイントを無効にする

disabled を設定すると、プラットフォームが作成した Service が削除されます。AUTO を使用する新しい操作では、direct のセットアップが利用できない場合にゲートウェイを使用できます。DIRECT に固定された操作は、direct 接続を確立できない場合に失敗します。実行中の direct 操作は中断される可能性があります。

トラブルシューティング

関連項目

ゲートウェイとランナーが全体のどこに位置するかについては、サンドボックスのアーキテクチャを参照してください。
最終更新日 2026年11月17日