> ## 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. # Deploy and manage a runner > Deploy a runner on a CKS cluster, check its health, update its configuration, and delete it. **관리형 러너**는 CKS 클러스터 내에서 샌드박스를 실행하는 CoreWeave 관리 컴포넌트입니다. 이 페이지에서는 러너 배포, 정상 작동 확인, 요구 사항 변화에 따른 설정 조정, 더 이상 필요하지 않을 때 제거하기까지 전체 라이프사이클을 다룹니다. 샌드박스 아키텍처에서 러너의 위치와 게이트웨이가 러너에 요청을 중개하는 방식은 [샌드박스 아키텍처](/ko/products/sandboxes/architecture)를 참조하세요. 러너 활성화부터 첫 샌드박스 실행까지의 과정을 단계별로 살펴보려면 [자체 컴퓨팅 사용하기](/ko/products/sandboxes/get-started-cks)를 참조하세요.

시작하기 전에

이 페이지의 CLI 및 `curl` 예시는 모두 CoreWeave API 액세스 토큰으로 인증합니다. Cloud Console의 [Tokens](https://console.coreweave.com/tokens) 페이지에서 토큰을 생성하고 **Token Secret** 값을 복사하세요. 토큰에 대한 자세한 내용은 [API 액세스 토큰 관리](/security/authn-authz/manage-api-access-tokens)를 참조하세요. **CLI**: [CoreWeave Intelligent CLI](https://github.com/coreweave/cwic)(`cwic`)를 설치한 다음 `cwic auth login`을 실행하고, 메시지가 표시되면 토큰을 붙여넣으세요. 토큰은 로컬 `cwic` 설정에 저장되며, 이후 명령어를 실행할 때 자동으로 사용됩니다. 별도로 환경 변수를 설정할 필요는 없습니다. ```bash theme={"system"} cwic auth login ``` **`curl`**: 이 페이지의 예시에서 토큰을 사용할 수 있도록 셸에서 토큰을 export하세요. `[API-ACCESS-TOKEN]`을 CoreWeave API 액세스 토큰으로 바꾸세요. ```bash theme={"system"} export TOKEN="[API-ACCESS-TOKEN]" ```

러너 명령어

`cwic sandbox runner` 그룹은 러너를 관리합니다. 다음 table은 각 라이프사이클 작업과 이를 수행하는 명령어를 연결합니다. 이후 섹션에서는 실제 사용 맥락에서 이러한 명령어를 설명합니다. | 목표 | 명령어 | | - | - | | 러너 배포(마법사) | `cwic sandbox runner create [RUNNER-ID]` | | 파일에서 러너 배포 | `cwic sandbox runner create [RUNNER-ID] -f runner.yaml` | | 러너 목록 조회 | `cwic sandbox runner get` (별칭 `ls`) | | 러너 하나 확인 | `cwic sandbox runner get [RUNNER-ID]` | | 상세 뷰 | `cwic sandbox runner describe [RUNNER-ID]` | | 러너 편집 | `cwic sandbox runner edit [RUNNER-ID]` | | 사용 가능한 업데이트 적용 | `cwic sandbox runner upgrade [RUNNER-ID]` | | 러너 삭제 | `cwic sandbox runner delete [RUNNER-ID]` | | 러너 정책 조회 | `cwic sandbox runner policy get [RUNNER-ID]` | | 러너 정책 편집 | `cwic sandbox runner policy edit [RUNNER-ID]` | 모든 입력은 YAML 또는 JSON을 허용합니다.

러너 배포

조직 내에서 각 CKS 클러스터는 최대 하나의 관리형 러너를 호스팅합니다. 배포하려면 다음을 제공하세요: * 러너 ID: 클라이언트가 할당한 사람이 읽을 수 있는 ID로, 조직 내에서 고유합니다. * 영역: 클러스터가 속한 지리적 영역. * Cluster ID (또는 cluster name): 러너가 실행되는 CKS 클러스터. Cloud Console의 [Clusters](https://console.coreweave.com/clusters) 페이지에서 둘 다 찾을 수 있습니다. * Policy: 클러스터의 샌드박스에 대해 러너가 강제 적용하는 규칙. 샌드박스를 실행하려면 정책이 있어야 합니다. 정책을 생략하면 러너가 연결될 때 CoreWeave가 기본 정책을 제공합니다. 정책에서 기본 샌드박스 수명을 지정할 수 있으며, 최대 수명인 30일은 플랫폼이 강제 적용합니다. [샌드박스 정책 설정](/ko/products/sandboxes/profiles/configure) 참조. 마법사가 클러스터, 릴리스 채널 및 유지 관리 창을 대화식으로 수집한 다음 제출하기 전에 미리 채워진 사양으로 편집기를 엽니다: ```bash theme={"system"} cwic sandbox runner create prod-us-east-1 ``` 파일 모드는 YAML 또는 JSON을 허용하므로 반복 가능한 설정에 선호되는 경로이며, 대신 러너 사양을 생성하는 Claude Code 또는 Codex와 같은 에이전트에 적합합니다. CLI는 `-f -`로 표준 입력에서도 읽습니다. 러너를 배포할 CKS 클러스터 이름으로 `[CLUSTER-NAME]`을 교체하세요: ```yaml title="runner.yaml" theme={"system"} identity: zone: us-east-1 cluster_name: [CLUSTER-NAME] spec: release_channel: RELEASE_CHANNEL_STABLE maintenance_policy: windows: - cron: "0 9 * * SAT" duration_seconds: 14400 policy: display_name: default constraints: resources: default_cpu: "1" default_memory: "2Gi" max_cpu: "4" max_memory: "8Gi" require_limits: true lifecycle: default_lifetime_seconds: 3600 ``` 사양을 제출하세요: ```bash theme={"system"} cwic sandbox runner create prod-us-east-1 -f runner.yaml ``` 러너를 배포할 CKS 클러스터 ID로 `[CLUSTER-ID]`를 교체하세요: ```bash title="Deploy a managed runner" theme={"system"} curl -X POST https://api.coreweave.com/v1/sandbox/managedRunners \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "displayName": "Production runner (US East)", "identity": { "runnerId": "prod-us-east-1", "zone": "us-east-1", "clusterId": "[CLUSTER-ID]" }, "spec": { "releaseChannel": "RELEASE_CHANNEL_STABLE", "maintenancePolicy": { "windows": [ { "cron": "0 9 * * SAT", "durationSeconds": 14400 } ] } }, "policy": { "displayName": "default", "constraints": { "resources": { "defaultCpu": "1", "defaultMemory": "2Gi", "maxCpu": "4", "maxMemory": "8Gi", "requireLimits": true }, "lifecycle": { "defaultLifetimeSeconds": 3600 } } } }' ``` 다음 동작에 유의하세요: * `maintenance_policy.windows`는 선택 사항입니다. 설정하면 자동 업데이트가 지정된 cron 창 동안에만 적용됩니다. * `runner_group_id`는 선택 사항입니다. 동일한 영역에 여러 러너가 있을 때 스케줄링 어피니티에 사용하세요.

일반적인 검증 오류

| 오류 | 해결 방법 | | - | - | | `runner.identity.zone is required` | 영역을 지정하세요. Cloud Console의 [Clusters](https://console.coreweave.com/clusters) 페이지에서 또는 `cwic cluster get`을 실행하여 CKS 클러스터가 있는 영역(따라서 러너 할당량이 있는 영역)을 찾으세요. | | `runner.identity.cluster_id or cluster_name is required` | 둘 중 하나를 지정하세요. Cloud Console의 [Clusters](https://console.coreweave.com/clusters) 페이지에서 또는 `cwic cluster get`을 실행하여 두 값을 모두 확인할 수 있습니다. | | `policy exceeds 256 KiB limit` | 정책 문서의 크기를 줄이세요. 인코딩된 문서의 크기는 256 KiB로 제한됩니다. | | `a managed runner already exists for this cluster` | 클러스터는 관리형 러너를 최대 하나만 호스팅할 수 있습니다. [기존 러너를 업데이트](#update-a-runner)하거나 먼저 [삭제](#delete-a-runner)하세요. |

러너 상태 확인

생성 후 러너의 상태를 확인하여 성공적으로 배포되었는지 확인하고, 그렇지 않은 경우 문제를 진단하세요. ```bash theme={"system"} cwic sandbox runner describe prod-us-east-1 ``` 간단한 요약을 표 형식으로 보려면 별칭 `get`을 사용하세요: ```bash theme={"system"} cwic sandbox runner get prod-us-east-1 ``` 두 명령 모두 생성 시 지정한 러너 ID(`prod-us-east-1`) 또는 서버에서 부여한 UUID를 입력으로 받습니다. ```bash title="러너 조회" theme={"system"} curl -H "Authorization: Bearer $TOKEN" \ https://api.coreweave.com/v1/sandbox/managedRunners/prod-us-east-1 ``` 생성 시 지정한 러너 ID 또는 서버에서 부여한 UUID를 전달할 수 있습니다. 응답에는 추적할 상태 필드가 두 개 포함됩니다: * **`installStatus`**: 클러스터에 러너를 배포하는 진행 상태(`PENDING`, `PROVISIONING`, `READY` 또는 `FAILED`). * **`connectionStatus`**: 실시간 연결 상태(`CONNECTED` 또는 `DISCONNECTED`). 러너의 하트비트가 이 값을 업데이트합니다. 최대 30초의 지연이 발생할 수 있습니다. `installStatus == FAILED`인 경우 응답에 구조화된 `installError`가 포함됩니다: ```json theme={"system"} { "installError": { "reason": "...", "message": "...", "remediationHints": ["Add toleration for taint 'workload=gpu:NoSchedule'"], "occurredAt": "2026-04-24T12:03:11Z" } } ``` `remediationHints`는 수행해야 할 조치입니다. `diagnosticDetail`에는 지원 요청을 제출할 때 첨부하면 유용한 내부 로그도 포함되어 있습니다.

러너 업데이트

러너 편집 명령은 대화형 마법사와 파일 기반 패치를 모두 지원합니다. 내부적으로 업데이트는 필드 마스크를 사용하여 변경한 필드만 적용합니다. `installStatus`, `connectionStatus`, 타임스탬프, 최종 배포 사양을 포함한 나머지 모든 항목은 읽기 전용입니다. 다음 경로는 수정할 수 있습니다. * `identity.zone` * `identity.runner_group_id` * `spec` (전체 객체) * `spec.release_channel` * `spec.maintenance_policy` * `spec.overrides` * `spec.enforce_resource_limits` * `policy` (전체 문서) REST API에서 `PATCH` 본문은 요청 래퍼 없이 관리형 러너 자체이며, 필드 마스크는 `updateMask` 쿼리 매개변수로 전달됩니다. 마스크가 없거나 `updateMask=*`인 경우 수정 가능한 리소스 전체를 대체합니다. 다음 두 경로는 기존 `v1beta2` API에서만 허용되며 `v1` 관리형 러너 쓰기 작업에서는 거부됩니다. `profile_bindings` (대신 `policy`를 설정하세요) 및 `spec.allow_privileged_profile_annotations`.

일반적인 러너 업데이트

다음 예시는 러너에 가장 자주 적용하는 변경 사항을 보여줍니다. 릴리스 채널 전환, 러너에 적용된 정책 교체, 클러스터 내 러너 파드 배치 위치 조정, 기존 프로필 템플릿에 특권 보안 설정 허용이 포함됩니다.

예시: 릴리스 채널 전환

표준 입력에서 한 줄 패치를 적용하세요: ```bash theme={"system"} echo 'spec: {release_channel: RELEASE_CHANNEL_RAPID}' \ | cwic sandbox runner edit prod-us-east-1 -f - ``` 또는 패치를 파일에 작성한 후 제출하세요: ```yaml title="patch.yaml" theme={"system"} spec: release_channel: RELEASE_CHANNEL_RAPID ``` ```bash theme={"system"} cwic sandbox runner edit prod-us-east-1 -f patch.yaml ``` ```bash title="RAPID 채널로 러너 이동" theme={"system"} curl -X PATCH "https://api.coreweave.com/v1/sandbox/managedRunners/prod-us-east-1?updateMask=spec.releaseChannel" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "identity": { "runnerId": "prod-us-east-1" }, "spec": { "releaseChannel": "RELEASE_CHANNEL_RAPID" } }' ```

예시: 정책 교체

정책은 전체 문서로 교체됩니다. 현재 정책을 조회하고 필요한 부분을 변경한 후 다시 전송하세요. `policy` 내부에는 필드 수준 마스크가 없으므로, 부분 본문을 전송하면 생략한 그룹이 모두 지워집니다. 정책 업데이트에는 `etag`도 포함되며, 이는 러너를 조회할 때 러너가 반환하는 불투명한 리비전 토큰입니다. 더 최신 값이 아니라, 편집할 때 기준으로 삼은 조회에서 받은 값을 전송하세요. 오래된 토큰은 `FAILED_PRECONDITION` 오류와 함께 실패하며 아무것도 변경되지 않습니다. 따라서 동시 편집이 발생하면 조용히 덮어써지지 않고 오류로 보고됩니다. ```bash theme={"system"} cwic sandbox runner get prod-us-east-1 -o json > runner.json jq '.[0].policy' runner.json > policy.json ``` `policy.json`을 편집한 후, 같은 조회에서 받은 `etag`로 고정하여 제출하세요: ```bash theme={"system"} cwic sandbox runner policy edit prod-us-east-1 -f policy.json \ --etag "$(jq -r '.[0].etag' runner.json)" ``` `policy get`은 `etag` 없이 정책을 내보내고, `--etag` 없이 실행한 `policy edit -f`는 제출하는 시점에 러너의 현재 리비전을 조회합니다. 따라서 둘 다 파일을 가져온 리비전을 고정하지 않습니다. 내보낸 후 `policy describe` 등으로 토큰을 따로 조회해도 같은 문제가 생깁니다. 문서보다 새로운 토큰은 검사를 통과하므로 그 사이에 이루어진 변경 사항을 덮어쓰게 됩니다. `cwic sandbox runner edit` 템플릿을 사용하면 이런 추가 단계가 필요 없습니다. `--print-template`은 변경 가능한 설정, 정책, `etag`를 한꺼번에 내보내고, `-f`는 파일에 있는 값을 사용합니다. 러너를 조회하여 현재 정책과 `etag`를 모두 캡처합니다: ```bash theme={"system"} curl -H "Authorization: Bearer $TOKEN" \ https://api.coreweave.com/v1/sandbox/managedRunners/prod-us-east-1 \ | jq '{policy, etag}' > policy-and-etag.json ``` 해당 파일에서 `policy` 객체를 편집한 후, 함께 제공된 `etag`와 함께 다시 전송합니다: ```bash title="Replace a runner's policy" theme={"system"} curl -X PATCH "https://api.coreweave.com/v1/sandbox/managedRunners/prod-us-east-1?updateMask=policy" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d @policy-and-etag.json ``` 모든 제약 그룹과 예시는 [샌드박스 정책 설정](/ko/products/sandboxes/profiles/configure)을 참조하세요.

예시: 배포 오버라이드로 노드 배치 고정하기

`spec.overrides` 필드는 샌드박스 파드가 아니라 러너 자체의 파드를 조정합니다. 러너 파드를 올바른 노드에 배치하는 데 특정 toleration, 노드 셀렉터 또는 런타임 클래스가 필요한 경우에 사용하세요. 흔히 사용하는 방식은 러너 파드를 SUNK Pod Scheduler로 라우팅하여 SUNK 클러스터에서 Slurm 작업과 함께 실행하는 것입니다. 러너 오버라이드에 스케줄러 이름과 SUNK 어노테이션을 설정하세요. 사용 가능한 어노테이션과 필요한 설정은 [SUNK Pod Scheduler 인테그레이션](/ko/products/sandboxes/profiles/sunk-integration)을 참조하세요. ```yaml title="overrides.yaml" theme={"system"} spec: overrides: node_selector: node-pool: system tolerations: - key: dedicated operator: Equal value: system effect: NoSchedule ``` ```bash theme={"system"} cwic sandbox runner edit prod-us-east-1 -f overrides.yaml ``` ```bash title="러너를 특정 Node Pool에 고정하기" theme={"system"} curl -X PATCH "https://api.coreweave.com/v1/sandbox/managedRunners/prod-us-east-1?updateMask=spec.overrides" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "identity": { "runnerId": "prod-us-east-1" }, "spec": { "overrides": { "nodeSelector": { "node-pool": "system" }, "tolerations": [ { "key": "dedicated", "operator": "Equal", "value": "system", "effect": "NoSchedule" } ] } } }' ```

예시: 특권 프로필 보안 설정 허용

`allow_privileged_profile_annotations`는 러너에 바인딩된 기존 프로필 템플릿에 특권 보안 설정을 허용할지 제어합니다. 정책 대신 프로필 바인딩을 여전히 사용하는 러너에 적용되므로 요청은 `v1beta2` API로 전송됩니다. 기본값은 `false`이며, 이 플래그가 설정되지 않은 러너에서는 특권 보안 설정을 포함한 템플릿이 거부됩니다. 이름과 달리 이 플래그는 두 가지 유형의 콘텐츠를 제어합니다. * 권한 있는 파드 어노테이션으로, 런타임 및 스케줄러 접두사를 의미합니다. * `serviceAccountName`, 호스트 namespace, `hostPath` 볼륨, 권한 있는 컨테이너 또는 권한 상승이 가능한 컨테이너와 같은 권한 있는 구조화된 파드 사양 필드. 러너가 거부하는 템플릿은 `permission_denied`를 반환하고 문제가 되는 필드를 명시합니다. 예를 들어, `securityContext.appArmorProfile`과 `securityContext.seccompProfile`을 설정하는 템플릿은 다음과 같이 실패합니다. ```text title="Example output" theme={"system"} Error: updating runner: permission_denied: profile_bindings[7]: template "[TEMPLATE-ID]" contains privileged pod-spec fields [securityContext.appArmorProfile securityContext.seccompProfile]; runner does not have allow_privileged_profile_annotations=true ``` 템플릿을 거부한 러너에 플래그를 설정하세요. 이 플래그는 하나의 러너에만 적용되므로, 특권 보안 설정이 필요한 각 러너에 대해 이 작업을 반복하세요. ```bash theme={"system"} echo 'managed_spec: {allow_privileged_profile_annotations: true}' \ | cwic sandbox runner edit prod-us-east-1 -f - ``` ```bash title="Allow a privileged profile posture on one runner" theme={"system"} curl -X PATCH https://api.coreweave.com/v1beta2/sandbox/managed-runners/prod-us-east-1 \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "runner": { "id": "prod-us-east-1", "managedSpec": { "allowPrivilegedProfileAnnotations": true } }, "updateMask": "managedSpec.allowPrivilegedProfileAnnotations" }' ``` 업데이트가 성공하면 거부된 프로필 템플릿을 다시 적용하세요. 이 플래그를 설정하면 호스트 리소스 접근을 포함하여 러너의 샌드박스가 수행할 수 있는 작업 범위가 확대됩니다. 특권 보안 설정이 필요한 러너에만 설정하세요.

필요 시 러너 업데이트 트리거

러너의 `updateAvailable`이 `true`이면 다음 유지 관리 창까지 기다리지 않고 업데이트를 즉시 적용할 수 있습니다: ```bash theme={"system"} cwic sandbox runner upgrade prod-us-east-1 ``` ```bash title="사용 가능한 업데이트 즉시 적용" theme={"system"} curl -X POST https://api.coreweave.com/v1/sandbox/managedRunners/prod-us-east-1:applyAvailableUpdate \ -H "Authorization: Bearer $TOKEN" ``` 컨트롤 플레인은 러너의 릴리스 채널에서 최신 버전을 확인하고 `target_revision`을 갱신합니다. 클러스터 내 컨트롤러가 이를 배포합니다.

러너 목록 조회

조직의 모든 러너를 확인하거나 특정 존, 클러스터 또는 연결 상태로 범위를 좁혀 보려면 다음 목록 명령어를 사용하세요. ```bash theme={"system"} cwic sandbox runner get ``` 존, 클러스터 또는 연결 상태로 필터링하세요. ```bash theme={"system"} cwic sandbox runner get --zone us-east-1 cwic sandbox runner get --connection-status CONNECTED ``` ```bash title="관리형 러너 목록 조회" theme={"system"} curl -H "Authorization: Bearer $TOKEN" \ 'https://api.coreweave.com/v1/sandbox/managedRunners?pageSize=50&zone=us-east-1' ``` 지원되는 쿼리 매개변수: `zone`, `clusterId`, `connectionStatus`, `runnerId`, `managementMode`, `pageSize`(기본값 50, 최대 100), `pageToken`. 페이지 매김은 커서 기반입니다.

러너 삭제

클러스터에서 더 이상 샌드박스 용량이 필요하지 않거나 같은 클러스터에 새 러너를 다시 배포하기 전에 러너를 제거하세요. ```bash theme={"system"} cwic sandbox runner delete prod-us-east-1 ``` CLI에서 확인을 요청합니다. 스크립트에서 사용할 때 확인 요청을 건너뛰려면 `--yes`를 전달하세요: ```bash theme={"system"} cwic sandbox runner delete prod-us-east-1 --yes ``` ```bash title="Decommission a runner" theme={"system"} curl -X DELETE https://api.coreweave.com/v1/sandbox/managedRunners/prod-us-east-1 \ -H "Authorization: Bearer $TOKEN" ``` 러너를 삭제하면 클러스터에서 러너 배포가 제거됩니다. 해당 러너에서 실행 중인 모든 샌드박스가 중지됩니다. 정책은 러너의 일부이므로 함께 삭제됩니다. 클러스터를 다시 배포할 계획이라면 정책 문서를 버전 관리 시스템에 보관하세요. 삭제는 영구적입니다. 트래픽을 일시 중지하기만 하려면 이 러너를 삭제하기 전에 샌드박스를 다른 러너로 이동하세요.

참고 항목

* [노드 할당 예산 설정](/ko/products/sandboxes/operations/node-allocation-budgets): Node Pool 또는 노드 그룹별로 샌드박스의 CPU 및 메모리 요청량을 제한합니다. * [샌드박스 아키텍처](/ko/products/sandboxes/architecture): 리소스 모델, 컨트롤 플레인과 데이터 플레인 비교, 다중 클러스터 토폴로지를 설명합니다. * [정책 개요](/ko/products/sandboxes/profiles/profiles): 샌드박스에 정책이 적용되는 방식을 설명합니다. * [샌드박스 정책 설정](/ko/products/sandboxes/profiles/configure): 모든 제약 조건 그룹을 구체적인 예시와 함께 설명합니다. * [컨트롤 플레인 API 개요](/ko/products/sandboxes/reference/control-plane-api): 인증, 필드 마스크, 모든 엔드포인트의 요청 및 응답 구조를 설명합니다. * [정책 레퍼런스](/ko/products/sandboxes/reference/profile): 정책에서 설정할 수 있는 모든 필드를 설명합니다.