> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ランナーの direct データプレーンを設定する

> ランナーのエンドポイントを公開し、サンドボックスの exec、ログ、ファイル操作がゲートウェイを経由しないようにします。

direct データプレーンのエンドポイントを使用すると、`cwsandbox` クライアントは exec、ログ、ファイル操作をランナーへ直接送信できます。これらの操作は CoreWeave Sandboxes のゲートウェイを経由せず、相互 TLS (mTLS) で通信します。ライフサイクルおよび管理関連の Call は、引き続きゲートウェイを経由します。

このページは、CoreWeave Kubernetes Service (CKS) クラスター上でマネージドランナーを運用する管理者を対象としています。このページでは、次の内容について説明します。

* direct パスがランナーに到達する仕組み
* 公開モードを選択して設定する方法
* 独自の Ingress コントローラー経由でエンドポイントをルーティングする方法
* エンドポイントの準備が完了していることを確認する方法

## ランナーへの direct 接続パス

各マネージドランナーは、すべてのレプリカの前段に配置される安定したデータプレーンエンドポイントを 1 つ提供できます。プラットフォームは、ランナーの `dataPlane` 設定からエンドポイントのアドレスを解決し、そのアドレス用のサーバー証明書をランナーに発行します。CoreWeave Sandboxes ゲートウェイは、このアドレスを、サンドボックスにスコープが限定されたクライアント証明書とともにクライアントに返します。

```mermaid theme={"system"}
sequenceDiagram
    participant Client as cwsandbox client
    participant API as Sandbox API
    participant EP as Runner endpoint<br/>(your cluster)
    participant Pod as Sandbox pod

    Client->>API: Request a client certificate for a sandbox
    API-->>Client: Certificate + endpoint address
    Client->>EP: mTLS connection (exec, logs, files)
    EP->>Pod: Apply
    Pod-->>EP: Result
    EP-->>Client: Result
```

このパスには次の特性があり、それがこのページで説明する設定の選択に影響します。

* **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 に置き換えてください。デプロイ手順については、[ランナーのデプロイと管理](https://docs.coreweave.com/ja/products/sandboxes/operations/managed-runners.md)を参照してください。
* ランナーのページの [Before you begin](https://docs.coreweave.com/ja/products/sandboxes/operations/managed-runners.md#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` を設定済みのホスト名に置き換えてください。

| モード | プラットフォームがクラスター内に作成するもの | アドバタイズされるアドレス | 使用するケース |
| - | - | - | - |
| `disabled` | なし | なし。クライアントは新しいデータ操作にゲートウェイを使用する必要があります。 | クラスターがインバウンド接続を受け付けられない場合、またはゲートウェイのみを使用する確定的なポスチャーにしたい場合。 |
| `cluster_ip` | `ClusterIP` Service | `https://SERVICE_NAME.cw-sandbox-system.svc:9443` | クライアントがクラスターの Service にルーティングでき、クラスターの Service の DNS 名を解決できる場合。 |
| `load_balancer` | `LoadBalancer` Service | `https://HOSTNAME:9443` | 経路上に他のイングレスを挟まず、エンドポイント専用のパブリックまたはプライベートアドレスを使用したい場合。 |
| `custom` | `ClusterIP` Service | 指定した `advertised_uri` | 独自の Ingress コントローラー、VPN、サービスメッシュ、またはオーバーレイネットワークを経由してルーティングする場合。 |

プラットフォームは、ランナーの内部識別子に基づいて Service に名前を付けます。そのため、名前は推測せずにクラスターから読み取ってください。この Service には `sandbox.coreweave.com/component=data-plane` というラベルが付与されています。

```bash theme={"system"}
kubectl get svc -n cw-sandbox-system -l 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](https://docs.coreweave.com/products/networking/ingress-service/create-public-dns-name.md) の手順のうち、DNS の割り当てに関する手順のみを実施してください。TLS 証明書はランナーが提供するため、このエンドポイントにはイングレスの TLS 終端を設定しないでください。

CKS でパブリックアドレスを使用する場合は、`service.beta.kubernetes.io/coreweave-load-balancer-type: public` も追加します。CKS のデフォルトのアドレス設定では、このアノテーションを省略するとプライベートアドレスが割り当てられます。アドレス選択の詳細については、[Expose a Service](https://docs.coreweave.com/products/networking/ingress-service/expose-service-dns.md) を参照してください。`PRIVATE` スコープでは、プロバイダーがプライベートアドレスをどのように選択するかをプラットフォーム側で推測できないため、`load_balancer_class` またはプロバイダーのアノテーションのいずれかが必要です。

`ORG_ID` と `CLUSTER_NAME` を組織 ID とクラスター名に置き換え、`source_ranges` 内の `CLIENT_CIDR` をクライアントの接続元ネットワークの CIDR に置き換えてください。

> [tab] CLI
>
> ```yaml title="data-plane.yaml" theme={"system"}
> spec:
>   data_plane:
>     load_balancer:
>       scope: RUNNER_DATA_PLANE_SERVICE_SCOPE_PUBLIC
>       hostname: runner-a.ORG_ID-CLUSTER_NAME.coreweave.app
>       external_traffic_policy: RUNNER_DATA_PLANE_EXTERNAL_TRAFFIC_POLICY_CLUSTER
>       source_ranges:
>         - CLIENT_CIDR
>       annotations:
>         service.beta.kubernetes.io/coreweave-load-balancer-type: public
>         service.beta.kubernetes.io/external-hostname: runner-a
> ```
>
> ```bash theme={"system"}
> cwic sandbox runner edit RUNNER_ID -f data-plane.yaml
> ```

> [tab] curl
>
> ```bash title="パブリック LoadBalancer 経由でランナーのエンドポイントを公開する" theme={"system"}
> curl --fail-with-body -X PATCH \
>   'https://api.coreweave.com/v1/sandbox/managedRunners/RUNNER_ID?updateMask=spec.dataPlane' \
>   -H "Authorization: Bearer $TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "spec": {
>       "dataPlane": {
>         "loadBalancer": {
>           "scope": "RUNNER_DATA_PLANE_SERVICE_SCOPE_PUBLIC",
>           "hostname": "runner-a.ORG_ID-CLUSTER_NAME.coreweave.app",
>           "externalTrafficPolicy": "RUNNER_DATA_PLANE_EXTERNAL_TRAFFIC_POLICY_CLUSTER",
>           "sourceRanges": [
>             "CLIENT_CIDR"
>           ],
>           "annotations": {
>             "service.beta.kubernetes.io/coreweave-load-balancer-type": "public",
>             "service.beta.kubernetes.io/external-hostname": "runner-a"
>           }
>         }
>       }
>     }
>   }'
> ```

更新後、ランナーは新しい設定でロールアウトされ、`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 パススルーリスナーをパブリッシュします。

> [tab] Traefik（CoreWeave チャート）
>
> CoreWeave の [Traefik](https://docs.coreweave.com/products/cks/clusters/coreweave-charts/traefik.md) チャートでは、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](https://docs.coreweave.com/products/cks/clusters/coreweave-charts/traefik.md#gateway-api) を参照してください。
>
> 1. [Install the Gateway API CRDs](https://docs.coreweave.com/products/cks/clusters/coreweave-charts/traefik.md#install-the-gateway-api-crds) の手順に従って、チャートがサポートする standard チャンネルのバンドルをインストールします。互換性のあるバンドルがすでにインストールされている場合は、それを再利用してください。
>
> 2. Gateway API プロバイダーを有効にし、`websecure` エントリポイントに TLS パススルーのリスナーを追加します。リスナーの `port` には、`LoadBalancer` が公開するポート (`443`) ではなく、Traefik のコンテナーポート (`8443`) を指定します。
>
>    ```yaml title="traefik-values.yaml" theme={"system"}
>    traefik:
>      providers:
>        kubernetesGateway:
>          enabled: true
>      gateway:
>        enabled: true
>        listeners:
>          web:
>            port: 8000
>            protocol: HTTP
>          sandbox-data-plane:
>            port: 8443
>            protocol: TLS
>            hostname: "runner-a.ORG_ID-CLUSTER_NAME.coreweave.app"
>            mode: Passthrough
>            namespacePolicy:
>              from: All
>    ```
>
>    ```bash theme={"system"}
>    helm repo add coreweave https://charts.core-services.ingress.coreweave.com
>    helm upgrade --install traefik coreweave/traefik \
>      --namespace traefik --create-namespace \
>      -f traefik-values.yaml
>    ```
>
>    このチャートで Traefik をすでにインストールしている場合は、これらの値を既存の values ファイルにマージして、リリースをアップグレードしてください。
>
> 作成される Gateway の名前は `traefik-gateway` で、`traefik` namespace に配置されます。次のルートでは、これらの値を `GATEWAY_NAME` と `GATEWAY_NAMESPACE` に指定してください。

> [tab] Envoy Gateway
>
> [Envoy Gateway](https://gateway.envoyproxy.io/) は Gateway API を組み込みでサポートしています。ここで使用する `v1.9.1` の Helm チャートには、`TLSRoute` を `v1` として提供する Gateway API CRD が含まれています。デフォルトでは、Envoy Gateway は `Gateway` ごとに `LoadBalancer` Service を作成します。CoreWeave のアノテーションを指定すると、アドレスがパブリックになり、DNS 名が割り当てられます。これらのアノテーションは、`Gateway` が参照する `EnvoyProxy` リソースに追加してください。
>
> 1. Envoy Gateway をインストールします。
>
>    ```bash theme={"system"}
>    helm upgrade --install eg oci://docker.io/envoyproxy/gateway-helm --version v1.9.1 \
>      --namespace envoy-gateway-system --create-namespace
>    ```
>
>    別のコンポーネントで Gateway API CRD を管理している場合は、そのバンドルが Envoy Gateway `v1.9.1` と互換性があり、ここで使用するルートのバージョンを提供していることを確認してください。`--set crds.enabled=false` を追加する場合は、事前に Envoy Gateway の CRD を個別にインストールしてください。このフラグを指定すると、両方の CRD セットのインストールがスキップされます。詳しくは、[チャートの既存 CRD 向けインストール手順](https://github.com/envoyproxy/gateway/tree/v1.9.1/charts/gateway-helm#skip-install-crds)に従ってください。
>
> 2. `GatewayClass`、CoreWeave の Service アノテーションを含む `EnvoyProxy`、およびポート `443` に TLS パススルーのリスナーを持つ `Gateway` を作成します。`external-hostname` に短い値 `runner-a` を指定すると、`runner-a.ORG_ID-CLUSTER_NAME.coreweave.app` が割り当てられます。このホスト名は、リスナーのホスト名と一致している必要があります。
>
>    ```yaml title="envoy-gateway.yaml" theme={"system"}
>    apiVersion: gateway.networking.k8s.io/v1
>    kind: GatewayClass
>    metadata:
>      name: envoy
>    spec:
>      controllerName: gateway.envoyproxy.io/gatewayclass-controller
>    ---
>    apiVersion: gateway.envoyproxy.io/v1alpha1
>    kind: EnvoyProxy
>    metadata:
>      name: sandbox-data-plane
>      namespace: envoy-gateway-system
>    spec:
>      provider:
>        type: Kubernetes
>        kubernetes:
>          envoyService:
>            annotations:
>              service.beta.kubernetes.io/coreweave-load-balancer-type: public
>              service.beta.kubernetes.io/external-hostname: runner-a
>    ---
>    apiVersion: gateway.networking.k8s.io/v1
>    kind: Gateway
>    metadata:
>      name: sandbox-data-plane
>      namespace: envoy-gateway-system
>    spec:
>      gatewayClassName: envoy
>      infrastructure:
>        parametersRef:
>          group: gateway.envoyproxy.io
>          kind: EnvoyProxy
>          name: sandbox-data-plane
>      listeners:
>        - name: sandbox-data-plane
>          protocol: TLS
>          port: 443
>          hostname: "runner-a.ORG_ID-CLUSTER_NAME.coreweave.app"
>          tls:
>            mode: Passthrough
>          allowedRoutes:
>            namespaces:
>              from: All
>    ```
>
>    ```bash theme={"system"}
>    kubectl apply -f envoy-gateway.yaml
>    ```
>
> Gateway の名前は `sandbox-data-plane`、namespace は `envoy-gateway-system` です。次のルートでは、これらの値を `GATEWAY_NAME` と `GATEWAY_NAMESPACE` に指定してください。

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

`custom.advertised_uri` の値はクライアントが接続先として使用するアドレスです。そのため、`ClusterIP` の Service ではなく、イングレスのホスト名とポートを指定します。

1. `custom.advertised_uri` を、Ingress コントローラーが提供するアドレスに設定します。この設定により、次のステップでルーティング先となるデータプレーンの Service も作成されます。

   > [tab] CLI
   >
   > ```yaml title="data-plane.yaml" theme={"system"}
   > spec:
   >   data_plane:
   >     custom:
   >       advertised_uri: https://runner-a.ORG_ID-CLUSTER_NAME.coreweave.app:443
   > ```
   >
   > ```bash theme={"system"}
   > cwic sandbox runner edit RUNNER_ID -f data-plane.yaml
   > ```

   > [tab] curl
   >
   > ```bash title="Ingress コントローラー経由でランナーのエンドポイントを公開する" theme={"system"}
   > curl --fail-with-body -X PATCH \
   >   'https://api.coreweave.com/v1/sandbox/managedRunners/RUNNER_ID?updateMask=spec.dataPlane' \
   >   -H "Authorization: Bearer $TOKEN" \
   >   -H "Content-Type: application/json" \
   >   -d '{
   >     "spec": {
   >       "dataPlane": {
   >         "custom": {
   >           "advertisedUri": "https://runner-a.ORG_ID-CLUSTER_NAME.coreweave.app:443"
   >         }
   >       }
   >     }
   >   }'
   > ```

2. ランナーのロールアウトが完了するまで待ちます。

3. 作成された Service の名前を確認します：

   ```bash theme={"system"}
   kubectl get svc -n cw-sandbox-system -l sandbox.coreweave.com/component=data-plane
   ```

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

ランナーの Namespace に `TLSRoute` を作成し、パススルーリスナーをデータプレーンの Service にバインドします。

1. `GATEWAY_NAME` と `GATEWAY_NAMESPACE` を準備したコントローラーの値に、`SERVICE_NAME` を前のステップで確認した Service 名に置き換えます。

   ```yaml title="runner-tlsroute.yaml" theme={"system"}
   apiVersion: gateway.networking.k8s.io/v1
   kind: TLSRoute
   metadata:
     name: runner-data-plane
     namespace: cw-sandbox-system
   spec:
     parentRefs:
       - name: GATEWAY_NAME
         namespace: GATEWAY_NAMESPACE
         sectionName: sandbox-data-plane
     hostnames:
       - "runner-a.ORG_ID-CLUSTER_NAME.coreweave.app"
     rules:
       - backendRefs:
           - name: SERVICE_NAME
             port: 9443
   ```

   ```bash theme={"system"}
   kubectl apply -f runner-tlsroute.yaml
   kubectl get tlsroute -n cw-sandbox-system runner-data-plane -o yaml
   ```

2. `status.parents[].conditions` に `Accepted: True` と `ResolvedRefs: True` が表示されていることを確認します。

3. エンドポイントを使用するネットワーク上の[クライアントから検証します](#verify-from-a-client)。

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

設定を変更した後は、必ずランナーの状態を確認してください。

1. `installStatus` と `connectionStatus` を確認し、`activeRevision` が `targetRevision` に達しているかどうかを確認します。

   > [tab] CLI
   >
   > ```bash theme={"system"}
   > cwic sandbox runner describe RUNNER_ID
   > ```

   > [tab] curl
   >
   > ```bash title="ランナーの設定とステータスを取得する" theme={"system"}
   > curl -H "Authorization: Bearer $TOKEN" \
   >   https://api.coreweave.com/v1/sandbox/managedRunners/RUNNER_ID
   > ```

2. データプレーンの Service を確認します。

   ```bash theme={"system"}
   kubectl get svc -n cw-sandbox-system -l sandbox.coreweave.com/component=data-plane
   ```

   `load_balancer` の場合は、Service にアドレスが割り当てられていること、および設定済みのホスト名がそのアドレスに名前解決されることを確認します。`custom` の場合は、Ingress コントローラーのアドレスと `TLSRoute` の条件を確認します。

これらの確認だけでは、クライアントが mTLS を完了できるかどうかまではわかりません。続けて、クライアント側の確認を行ってください。

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

管理コマンドで `cwic auth login` を使用した場合でも、Python クライアントには専用のトークン環境変数が必要です。次のコマンドの `API_ACCESS_TOKEN` を、CoreWeave API アクセストークンのシークレットに置き換えてください。

1. [Python 環境を準備する](https://docs.coreweave.com/ja/products/sandboxes/client.md#prepare-your-python-environment)の説明に従って、有効化した Python 仮想環境にクライアントをインストールします。

   ```bash theme={"system"}
   uv pip install 'cwsandbox>=1.14.2'
   export CWSANDBOX_API_KEY="API_ACCESS_TOKEN"
   ```

2. クライアントのトランスポートポリシーを `DIRECT` に設定し、設定済みの CKS ランナーで操作を実行します。このモードではゲートウェイへのフォールバックが一切行われないため、呼び出しが成功すれば、そのネットワークから direct パスが機能していることを確認できます。

   ```python theme={"system"}
   from cwsandbox import AuthStrategy, DataPlaneMode, Sandbox

   with Sandbox.run(
       auth=AuthStrategy.COREWEAVE_API_KEY,
       placement_mode="cks",
       runner_ids=["RUNNER_ID"],
       data_plane_mode=DataPlaneMode.DIRECT,
   ) as sandbox:
       print(sandbox.exec(["echo", "direct"]).result().stdout)
   ```

同じ呼び出しが `DataPlaneMode.GATEWAY` では成功するのに、この呼び出しではエラーが発生する場合は、[トラブルシューティング](#troubleshooting)を参照してください。クライアントオプションの完全な一覧については、[サンドボックスへの direct 接続](https://docs.coreweave.com/ja/products/sandboxes/client/guides/direct-connections.md)を参照してください。

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

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

> [tab] CLI
>
> ```bash theme={"system"}
> echo 'spec: {data_plane: {disabled: {}}}' \
>   | cwic sandbox runner edit RUNNER_ID -f -
> ```

> [tab] curl
>
> ```bash title="direct データプレーンを無効にする" theme={"system"}
> curl --fail-with-body -X PATCH \
>   'https://api.coreweave.com/v1/sandbox/managedRunners/RUNNER_ID?updateMask=spec.dataPlane' \
>   -H "Authorization: Bearer $TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "spec": {
>       "dataPlane": {
>         "disabled": {}
>       }
>     }
>   }'
> ```

## トラブルシューティング

| 症状 | 考えられる原因 | 対処法 |
| - | - | - |
| `load_balancer.hostname must be a stable DNS name` というエラーで更新が拒否される | `hostname` が空であるか、有効な DNS 名ではありません。 | エンドポイントの名前解決に使用される完全修飾名を指定します。 |
| `private scope requires a load_balancer_class or provider annotation` というエラーで更新が拒否される | `PRIVATE` スコープが指定されていますが、プライベートアドレスを選択する手段がありません。 | プロバイダーのクラスまたはアノテーションを追加します。CKS のデフォルトのアドレス設定では、`coreweave-load-balancer-type` を省略するとプライベートアドレスが割り当てられます。その他の必須アノテーションは指定してください。 |
| `advertised_uri must be an absolute https origin` というエラーで更新が拒否される | URI (Uniform Resource Identifier) にパス、クエリ、認証情報、または `https` 以外のスキームが含まれています。 | `https://HOSTNAME:PORT` の形式を使用します。 |
| `load_balancer_class cannot change in place` というエラーで更新が拒否される | Kubernetes では、この Service フィールドを変更できません。 | `disabled` を設定し、データプレーンの Service が削除されるのを待ってから、新しい設定を適用します。 |
| `load_balancer` モードでエンドポイントに到達できない | Service にまだアドレスが割り当てられていないか、`hostname` の DNS がそのアドレスに名前解決されていません。 | `kubectl get svc -n cw-sandbox-system` を実行して `LoadBalancer` が保留中になっていないかを確認し、DNS レコードも確認します。CKS では、`external-hostname` アノテーションによって設定した名前が生成されていることを確認します。 |
| `TLSRoute` が `ResolvedRefs: False` を報告する | ルートで指定している Service がまだ存在しません。 | 先にランナーの更新を適用してから、Service 名を `backendRefs` にコピーします。 |
| `GATEWAY` は動作するが `DIRECT` が失敗する | クライアントネットワークからアドバタイズされたアドレスに到達できないか、中間装置で TLS が終端されています。 | クライアントネットワークから、アドバタイズされたホストとポートに TCP で到達できるかをテストします。`custom` モードの場合は、ルートがパススルーに設定され、SNI ホスト名と一致していることを確認します。 |
| 証明書の名前の不一致により TLS ハンドシェイクが失敗する | クライアントが、サーバー証明書の対象外の名前で接続しています。 | `advertised_uri` または `hostname` をクライアントが使用する名前と一致させ、ランナーが新しい証明書を使用するようになるまで待ちます。 |

## 関連項目

ゲートウェイとランナーが全体のどこに位置するかについては、[サンドボックスのアーキテクチャ](https://docs.coreweave.com/ja/products/sandboxes/architecture.md)を参照してください。
