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-systemnamespace に配置されます。カスタム公開の例を実行する場合は、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 に置き換えてください。
- CLI
- curl
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 パススルーリスナーをパブリッシュします。
- Traefik(CoreWeave チャート)
- Envoy Gateway
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 を参照してください。- Install the Gateway API CRDs の手順に従って、チャートがサポートする standard チャンネルのバンドルをインストールします。互換性のあるバンドルがすでにインストールされている場合は、それを再利用してください。
-
Gateway API プロバイダーを有効にし、
websecureエントリポイントに TLS パススルーのリスナーを追加します。リスナーのportには、LoadBalancerが公開するポート (443) ではなく、Traefik のコンテナーポート (8443) を指定します。traefik-values.yamlこのチャートで Traefik をすでにインストールしている場合は、これらの値を既存の values ファイルにマージして、リリースをアップグレードしてください。
traefik-gateway で、traefik namespace に配置されます。次のルートでは、これらの値を GATEWAY_NAME と GATEWAY_NAMESPACE に指定してください。ランナーの接続先をイングレスアドレスに設定する
custom.advertised_uri の値はクライアントが接続先として使用するアドレスです。そのため、ClusterIP の Service ではなく、イングレスのホスト名とポートを指定します。
-
custom.advertised_uriを、Ingress コントローラーが提供するアドレスに設定します。この設定により、次のステップでルーティング先となるデータプレーンの Service も作成されます。- CLI
- curl
data-plane.yaml - ランナーのロールアウトが完了するまで待ちます。
-
作成された Service の名前を確認します:
ルートをランナーの Service にバインドする
ランナーの Namespace にTLSRoute を作成し、パススルーリスナーをデータプレーンの Service にバインドします。
-
GATEWAY_NAMEとGATEWAY_NAMESPACEを準備したコントローラーの値に、SERVICE_NAMEを前のステップで確認した Service 名に置き換えます。runner-tlsroute.yaml -
status.parents[].conditionsにAccepted: TrueとResolvedRefs: Trueが表示されていることを確認します。 - エンドポイントを使用するネットワーク上のクライアントから検証します。
エンドポイントのステータスを確認する
設定を変更した後は、必ずランナーの状態を確認してください。-
installStatusとconnectionStatusを確認し、activeRevisionがtargetRevisionに達しているかどうかを確認します。- CLI
- curl
-
データプレーンの Service を確認します。
load_balancerの場合は、Service にアドレスが割り当てられていること、および設定済みのホスト名がそのアドレスに名前解決されることを確認します。customの場合は、Ingress コントローラーのアドレスとTLSRouteの条件を確認します。
クライアントから検証する
管理コマンドでcwic auth login を使用した場合でも、Python クライアントには専用のトークン環境変数が必要です。次のコマンドの API_ACCESS_TOKEN を、CoreWeave API アクセストークンのシークレットに置き換えてください。
-
Python 環境を準備するの説明に従って、有効化した Python 仮想環境にクライアントをインストールします。
-
クライアントのトランスポートポリシーを
DIRECTに設定し、設定済みの CKS ランナーで操作を実行します。このモードではゲートウェイへのフォールバックが一切行われないため、呼び出しが成功すれば、そのネットワークから direct パスが機能していることを確認できます。
DataPlaneMode.GATEWAY では成功するのに、この呼び出しではエラーが発生する場合は、トラブルシューティングを参照してください。クライアントオプションの完全な一覧については、サンドボックスへの direct 接続を参照してください。
エンドポイントを無効にする
disabled を設定すると、プラットフォームが作成した Service が削除されます。AUTO を使用する新しい操作では、direct のセットアップが利用できない場合にゲートウェイを使用できます。DIRECT に固定された操作は、direct 接続を確立できない場合に失敗します。実行中の direct 操作は中断される可能性があります。
- CLI
- curl