> ## 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.

# 샌드박스 배치 및 대체 배치로 재시도

> 서버리스 샌드박스와 CKS 샌드박스를 비교하고, 샌드박스를 실행할 위치를 선택하고, 모드 간 폴백을 설정하세요.

배치는 샌드박스를 어떤 컴퓨팅에서 실행할지 결정합니다. 서버리스는 CoreWeave에서 관리하는 컴퓨팅을 사용합니다. 클러스터 배치는 조직의 CoreWeave Kubernetes Service(CKS) 클러스터에 있는 컴퓨팅을 사용합니다. 대체 배치로 재시도는 초기 배치에 실패하면 다른 모드에서 샌드박스 생성을 다시 시도합니다.

<h2 id="compare-placement-modes">
  배치 모드 비교
</h2>

용량과 정책을 누가 관리하는지에 따라 모드를 선택하세요.

| | 서버리스 | CKS |
| - | - | - |
| 샌드박스 실행 위치 | CoreWeave 관리형 컴퓨팅 | 사용자 CKS 클러스터의 컴퓨팅 |
| 정책 설정 주체 | CoreWeave | 조직의 관리자 |
| 설정 | Forge 또는 CoreWeave 사용자 인증 정보로 인증 | 클러스터에서 러너 활성화 |
| 배치 제어 | 플랫폼에서 관리하므로 클러스터를 직접 선택하지 않습니다. | Python에서는 조건을 충족하는 모든 클러스터를 사용할 수 있으며, 배치를 제한하려면 러너 ID를 지정하세요. TypeScript에서는 러너 ID를 반드시 지정해야 합니다. |
| 리소스 | 샌드박스별로 CPU와 메모리 선택 | 클러스터 정책 범위 내에서 CPU와 메모리 선택 |
| 사용자 인증 정보 | Forge API 키 또는 CoreWeave API 액세스 토큰 | CoreWeave API 액세스 토큰 |
| 사용 시점 | 클러스터 용량을 직접 관리하지 않고 샌드박스를 실행하려는 경우 | 자체 클러스터 용량을 사용하면서 리소스 및 네트워크 정책을 제어하려는 경우 |

첫 번째 샌드박스를 만들려면 [서버리스 퀵스타트](/ko/products/sandboxes/get-started) 또는 [자체 컴퓨팅 사용](/ko/products/sandboxes/get-started-cks) 가이드를 따르세요.

<h2 id="choose-and-get-credentials">
  사용자 인증 정보 선택 및 발급
</h2>

사용하는 사용자 인증 정보에 따라 샌드박스를 소유하고 사용 요금을 청구받는 계정이 결정됩니다. Forge API 키는 서버리스 샌드박스를 지원합니다. CoreWeave API 액세스 토큰은 서버리스 샌드박스와 클러스터 샌드박스를 모두 지원합니다.

<span id="wb-api-key" />

<h3 id="forge-api-key">
  Forge API 키
</h3>

CoreWeave 콘솔 계정이 없거나 Forge 결제를 사용하려는 경우 Forge API 키를 선택하세요.

1. [Forge API 키 설정](https://forge.coreweave.com/settings#apikeys)을 여세요. 로그인하거나, 같은 링크에서 계정을 생성하세요.
2. API 키를 복사한 다음, 클라이언트를 실행할 터미널에서 설정하세요.

   ```bash theme={"system"}
   export FORGE_API_KEY="[FORGE-API-KEY]"
   ```

키는 Python에서는 `AuthHeaders`로, TypeScript에서는 `@coreweave/cwsandbox/wandb`의 `createSandboxClient({apiKey: process.env.FORGE_API_KEY})`로 명시적으로 전달하세요. 전체 예시는 [서버리스 퀵스타트](/ko/products/sandboxes/get-started#forge-api-key)에서 확인할 수 있습니다. `FORGE_API_KEY`는 예시로 든 변수일 뿐이며, SDK가 자동으로 감지하는 설정이 아닙니다.

<h3 id="coreweave-api-access-token">
  CoreWeave API 액세스 토큰
</h3>

CoreWeave 조직의 결제를 사용하거나 조직의 클러스터에서 샌드박스를 실행하려면 CoreWeave를 선택하세요.

1. 샌드박스를 실행하려면 **Sandbox User** 역할을 부여하는 [액세스 정책](https://console.coreweave.com/organization/iam/access-policies)을 생성하거나 업데이트해 달라고 관리자에게 요청하세요. 러너를 활성화하고 러너의 정책을 설정하는 관리자에게는 샌드박스 실행 권한이 포함된 **Sandbox Admin** 역할이 필요합니다. 자세한 내용은 [액세스 정책 생성](/security/iam/access-policies/manage#create-an-access-policy) 및 [샌드박스 역할](/security/iam/access-policies/roles#sandbox)을 참조하세요.
2. [Tokens](https://console.coreweave.com/tokens) 페이지에서 **Create Token**을 클릭하고 토큰 세부 정보를 입력한 다음 **Create**를 클릭하세요.
3. **Token Secret**을 복사한 후 클라이언트를 실행할 터미널에서 환경 변수로 설정하세요.

   ```bash theme={"system"}
   export CWSANDBOX_API_KEY="[API-ACCESS-TOKEN]"
   ```

토큰을 생성할 수 없다면 관리자에게 **Access Token User** 역할을 요청하세요. 토큰 시크릿은 한 번만 표시됩니다. 자세한 내용은 [API 액세스 토큰 관리](/security/authn-authz/manage-api-access-tokens)를 참조하세요.

Python에서는 `AuthStrategy.COREWEAVE_API_KEY`를 선택하세요. TypeScript에서는 `@coreweave/cwsandbox/node`에서 클라이언트를 임포트하세요.

<h2 id="select-a-placement-mode">
  배치 모드 선택
</h2>

Python과 TypeScript 모두 서버리스 배치와 클러스터 배치를 지원합니다. 기본값은 서버리스입니다. 지원되는 모드 값은 [`PlacementMode` 레퍼런스](/ko/products/sandboxes/client/ref/workload/placement#placementmode)에서 확인할 수 있습니다.

두 클러스터 예시 모두 `CWSANDBOX_API_KEY`를 읽습니다. 먼저 [사용자 인증 정보 설정](#coreweave-api-access-token)을 완료하세요. 그런 다음 [자체 컴퓨팅 사용](/ko/products/sandboxes/get-started-cks)을 참고하여 러너를 활성화하거나, [서버리스 퀵스타트](/ko/products/sandboxes/get-started)를 참고하여 TypeScript 클라이언트를 설치하세요.

클러스터 배치를 명시적으로 선택하는 방법은 다음과 같습니다.

<Tabs>
  <Tab title="Python">
    `placement_mode="cks"`를 사용하세요. 특정 러너에만 배치하려면 `runner_ids`를 추가하세요.

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

    with Sandbox.run(
        auth=AuthStrategy.COREWEAVE_API_KEY,
        placement_mode="cks",
        runner_ids=["[RUNNER-ID]"],
        resources={"cpu": "1", "memory": "1Gi"},
    ) as sandbox:
        print(sandbox.exec(["echo", "Hello!"]).result().stdout)
    ```

    `runner_ids`를 지정하지 않으면 CKS 배치 시 조직 내에서 사용 가능한 모든 러너가 대상이 됩니다. 서버리스로 배치하려면 두 필드를 모두 생략하거나, `runner_ids` 없이 `placement_mode="serverless"`를 설정하세요.
  </Tab>

  <Tab title="TypeScript">
    CKS 배치를 선택하려면 CoreWeave 진입점과 비어 있지 않은 `runnerIds` 배열을 사용하세요.

    ```typescript theme={"system"}
    import { createSandboxClientFromEnv } from "@coreweave/cwsandbox/node";

    const client = createSandboxClientFromEnv();
    const result = await client.withSandbox(
      async (sandbox) => sandbox.commands.run(["echo", "Hello!"]),
      {
        runnerIds: ["[RUNNER-ID]"],
        resources: { cpu: "1", memory: "1Gi" },
      },
    );
    console.log(result.stdout);
    ```

    서버리스로 배치하려면 `runnerIds`를 생략하세요.
  </Tab>
</Tabs>

<h2 id="spill-over-between-modes">
  모드 간 대체 배치로 재시도
</h2>

자동 대체 배치로 재시도는 Python 클라이언트에서 사용할 수 있습니다. TypeScript 클라이언트는 두 배치 모드 중 하나를 선택할 수는 있지만, 자동 대체 배치로 재시도는 제공하지 않습니다.

대체 배치로 재시도는 용량 부족이나 적합한 러너 부재처럼 재시도 대상에 해당하는 배치 실패가 발생하면, 다른 모드에서 샌드박스 생성을 한 번 더 시도합니다. 이미 실행 중인 샌드박스를 다른 모드로 옮기지는 않습니다.

서버리스 액세스 권한이 있고 CKS 러너가 설정된 조직의 CoreWeave API 액세스 토큰을 사용하세요. Forge API 키만으로는 CKS에 액세스할 수 없습니다.

CKS를 우선 사용하고 실패 시 서버리스로 전환하려면 `placement_spillover="cks_then_serverless"`를 설정하세요.

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

with Sandbox.run(
    auth=AuthStrategy.COREWEAVE_API_KEY,
    placement_spillover="cks_then_serverless",
    resources={"cpu": "1", "memory": "1Gi"},
) as sandbox:
    print(sandbox.exec(["echo", "Hello!"]).result().stdout)
```

이 예시에서는 두 시도 모두에 CPU와 메모리를 지정합니다. 모드마다 자체 정책이 적용되므로, 요청은 실제로 실행되는 모드의 정책을 충족해야 합니다.

폴백 동작을 제어하려면 `placement_spillover`를 다음 옵션 중 하나로 설정하세요.

| 옵션 | 첫 번째 시도 | 폴백 | 제약 조건 |
| - | - | - | - |
| `strict` (기본값) | 선택한 배치 모드 | 없음 | 템플릿에서 생성하거나 `run_from_file()`로 생성할 때 필수 |
| `cks_then_serverless` | CKS | 서버리스 | `placement_mode`가 `"cks"`이거나 생략되어야 함 |
| `serverless_then_cks` | 서버리스 | CKS | `placement_mode`가 `"serverless"`이거나 생략되어야 함. `runner_ids`와 함께 사용할 수 없음. |

지원되는 폴백 값은 [`PlacementSpillover` 레퍼런스](/ko/products/sandboxes/client/ref/workload/placement#placementspillover)를 참조하세요. 리소스 및 timeout 설정은 [샌드박스 구성](/ko/products/sandboxes/client/guides/sandbox-configuration)을 참조하세요.