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

# Terraform でランナーを管理する

> CoreWeave Terraform プロバイダーを使用して、CoreWeave Sandbox のマネージドランナーをデプロイ、設定、インポートします。

`coreweave_sandbox_managed_runner` リソースを使用すると、CoreWeave Kubernetes Service (CKS) クラスター上のランナーとそのサンドボックスポリシーを管理できます。Terraform は望ましい設定を記録してドリフトを検出し、マネージドランナー API を介して設定の変更を適用します。

属性スキーマの完全な一覧については、[マネージドランナーリソースのリファレンス](/platform/terraform/resources/sandbox_managed_runner)を参照してください。CLI および REST を使用した同等のワークフローについては、[ランナーのデプロイと管理](/ja/products/sandboxes/operations/managed-runners)を参照してください。

## 始める前に

次のリソースとツールが必要です。

* Terraform と [CoreWeave Terraform プロバイダー](/platform/terraform)。例では、`0.x` 系のプロバイダーバージョン `0.26.0` 以降を使用します。
* 既存の CKS クラスターと、その汎用一意識別子 (UUID) および アベイラビリティゾーン。これらの値は、Cloud console の [Clusters](https://console.coreweave.com/clusters) ページで確認できます。
* `SANDBOX_ADMIN` 権限を持つ CoreWeave API アクセストークン。[API アクセストークンを管理する](/security/authn-authz/manage-api-access-tokens)および[アクセスポリシーを管理する](/security/iam/access-policies/manage)を参照してください。
* アクセス制御を備えた Terraform の state バックエンド。Terraform は、ランナーの環境オーバーライドやポリシーの値を sensitive としてマークしている場合でも、それらを state に保存することがあります。

各 CKS クラスターでホストできるマネージドランナーは 1 つまでです。クラスターにすでにマネージドランナーがある場合は、設定を適用する前に[インポートしてください](#import-an-existing-runner)。

## 認証を設定する

プロバイダーは `COREWEAVE_API_TOKEN` を読み取ります。すでにトークンを `CW_API_KEY` としてエクスポートしている場合は、次のようにプロバイダー用の環境変数を設定してください。

```bash theme={"system"}
export COREWEAVE_API_TOKEN="$CW_API_KEY"
```

プロバイダーのデフォルトのエンドポイントは `https://api.coreweave.com` です。認証は CoreWeave Intelligent CLI のログインとは別に行われます。トークンは Terraform の設定ファイルに含めないでください。

## ランナーを定義する

次の設定を `main.tf` ファイルに保存します。この設定では、stable リリースチャンネル、毎週のメンテナンス期間、およびサンドボックスのリソースのデフォルト値とデフォルトの有効期間を定めるポリシーを備えたランナーを作成します。

```terraform title="main.tf" theme={"system"}
terraform {
  required_providers {
    coreweave = {
      source  = "coreweave/coreweave"
      version = "~> 0.26"
    }
  }
}

provider "coreweave" {}

variable "runner_id" {
  type        = string
  description = "Runner identifier, unique within your organization."
}

variable "cluster_id" {
  type        = string
  description = "UUID of the existing CKS cluster."
}

variable "zone" {
  type        = string
  description = "Availability Zone of the existing CKS cluster."
}

resource "coreweave_sandbox_managed_runner" "runner" {
  runner_id  = var.runner_id
  cluster_id = var.cluster_id
  zone       = lower(var.zone)

  spec = {
    release_channel = "RELEASE_CHANNEL_STABLE"
    maintenance_policy = {
      windows = [{ cron = "0 2 * * SAT", duration_seconds = 3600 }]
    }
    overrides = {
      resources = {
        cpu_request    = "1"
        memory_request = "2Gi"
        cpu_limit      = "4"
        memory_limit   = "8Gi"
      }
    }
  }

  policy = {
    display_name = "Sandbox constraints"
    constraints = {
      resources = {
        default_cpu    = "1"
        default_memory = "2Gi"
        max_cpu        = "8"
        max_memory     = "32Gi"
        max_gpu_count  = 0
      }
      lifecycle = { default_lifetime_seconds = 3600 }
    }
  }
}

output "runner_status" {
  value = {
    runner_id           = coreweave_sandbox_managed_runner.runner.runner_id
    install_status      = coreweave_sandbox_managed_runner.runner.install_status
    connection_status   = coreweave_sandbox_managed_runner.runner.connection_status
    active_revision     = coreweave_sandbox_managed_runner.runner.active_revision
    target_revision     = coreweave_sandbox_managed_runner.runner.target_revision
    rollout_in_progress = coreweave_sandbox_managed_runner.runner.rollout_in_progress
  }
}
```

2 つのリソースセクションは、それぞれ役割が異なります。

* `spec` はランナーを設定します。この例では、`spec.overrides.resources` でランナー自身の Pod のサイズを指定し、メンテナンス期間を毎週土曜日の午前 2 時 (UTC) 開始に設定しています。
* `policy` は、ランナーが提供するサンドボックスを設定します。この例では、各サンドボックスコンテナーの CPU とメモリに上限を設け、`max_gpu_count = 0` で GPU の使用を禁止し、デフォルトの有効期間を 1 時間に設定しています。デフォルトの有効期間は、最大ライフタイムとは異なります。制約をワークロードに合わせて調整するには、[サンドボックスポリシーを設定する](/ja/products/sandboxes/profiles/configure) を参照してください。

`policy` オブジェクトは必須です。明示的に空のオブジェクトを指定するのは、意図的に空のポリシーを使用する場合のみにしてください。`zone` の値は小文字である必要がありますが、これは `lower(var.zone)` によって保証されます。

`[RUNNER-ID]`、`[CLUSTER-ID]`、`[ZONE]` をそれぞれランナー識別子、CKS クラスターの UUID、アベイラビリティゾーンに置き換え、値を `terraform.tfvars` ファイルに保存します。

```terraform title="terraform.tfvars" theme={"system"}
runner_id  = "[RUNNER-ID]"
cluster_id = "[CLUSTER-ID]"
zone       = "[ZONE]"
```

## 設定を適用してロールアウトを検証する

設定を適用してランナーのロールアウトを検証するには、次の手順を実行します。

1. プロバイダーを初期化し、設定を検証します。

   ```bash theme={"system"}
   terraform init
   terraform validate
   ```

2. プランを確認して適用します。

   ```bash theme={"system"}
   terraform plan -out=runner.tfplan
   terraform apply runner.tfplan
   ```

   適用が成功すると、API が設定を受け付けたことになります。ランナーのインストールとロールアウトは引き続き非同期で進行します。

3. 観測されたステータスを更新し、出力を確認します。

   ```bash theme={"system"}
   terraform plan -refresh-only -out=runner-status.tfplan
   terraform apply runner-status.tfplan
   terraform output runner_status
   ```

   `install_status` が `RUNNER_INSTALL_STATUS_READY`、`connection_status` が `RUNNER_CONNECTION_STATUS_CONNECTED` で、かつ `active_revision` が `target_revision` と一致していれば、ランナーは準備完了です。まだプロビジョニング中の場合は、ロールアウトがある程度進んでから再度更新してください。インストールが失敗した場合は、computed 属性 `install_error` で詳細を確認できます。

## 設定を更新する

`main.tf` ファイル内のリソースを編集し、新しいプランを確認してから適用します。以降の適用でも意図した状態が維持されるよう、ポリシーとオーバーライドの設定は、望ましい状態をすべて Terraform で管理してください。CLI または API で行った変更はドリフトとして検出される場合があり、その後の Terraform の適用によって元に戻される可能性があります。

`spec` 内の省略可能な設定を削除すると、明示的な API 更新マスクによってその設定がリセットされます。オーバーライドを変更すると `spec.overrides` オブジェクト全体が置き換えられるため、維持したい他のオーバーライドも忘れずに残してください。解決済みの `deployment_spec` は読み取り専用です。

プロバイダーはポリシーのリビジョントークン (`etag`) を使用するため、ポリシーが同時に編集されると適用が失敗する場合があります。再試行する前に、状態をリフレッシュして新しいプランを確認してください。`runner_id`、`cluster_id`、または `zone` を変更すると、ランナーはインプレースで更新されず、置き換えられます。

### ランナーのアフィニティを設定する

アフィニティを使用するには、`spec.overrides.affinity` を含むプロバイダーのリリースが必要です。プロバイダー `0.26.0` にはこの属性が含まれていません。この属性をサポートするバージョンが利用可能になるまでは、[REST のアフィニティの例](/ja/products/sandboxes/operations/managed-runners#example-configure-runner-affinity)を使用してください。REST で行った変更が後続の apply で上書きされないように、Terraform の設定と整合をとってください。

この属性をサポートするプロバイダーをインストールしたら、既存の `spec.overrides` オブジェクトに次の属性をマージします。例示用のラベルは、お使いのクラスターのノードで使用されているラベルに置き換えてください。

```terraform title="Affinity attribute inside spec.overrides" theme={"system"}
affinity = jsonencode({
  nodeAffinity = {
    preferredDuringSchedulingIgnoredDuringExecution = [{
      weight = 100
      preference = {
        matchExpressions = [{
          key      = "example.com/capacity-class"
          operator = "In"
          values   = ["on-demand"]
        }]
      }
    }]
  }
})
```

この属性は、ノードアフィニティ、Pod アフィニティ、Pod アンチアフィニティを含む Kubernetes の `Affinity` JSON を受け入れます。`jsonencode()` 内のキーには Kubernetes のキャメルケースを使用します。この優先ルールでは、条件を満たす他のノードも引き続き利用可能なため、On-demand ノードが優先的に配置先になるとは限りません。既存のノードセレクターとトレランスも引き続き適用されます。

アフィニティが制御するのはランナー Pod のみです。サンドボックス Pod の配置や[ノード割り当て予算](/ja/products/sandboxes/operations/node-allocation-budgets)は設定されません。

アフィニティは部分的にではなく、全体が置き換えられます。継承されたアフィニティを含むすべてのルールをクリアするには、`affinity = jsonencode({})` を設定します。プラットフォームのデフォルトに戻すには、この属性を削除します。いずれの場合も、`spec.overrides` 内の他の属性のうち、引き続き必要なものは残しておいてください。

## 既存のランナーをインポートする

ランナー設定の例にあるリソースと変数を定義し、適用する前に、そのポリシーと spec を既存のランナーに合わせて調整します。`[RUNNER-ID]` は、API トークンに関連付けられた組織内のランナー識別子に置き換えてください。

```bash theme={"system"}
terraform init
terraform import coreweave_sandbox_managed_runner.runner '[RUNNER-ID]'
terraform plan
```

インポートでは、新しいランナーを作成せずに、既存のランナーを state に記録します。適用する前にプランを確認し、設定をインポートした値と一致させてください。Terraform は、インポート ID としてクラスター UUID ではなくランナー識別子を使用します。

## ランナーを削除する

設定から、リソースと、`runner_status` 出力を含むそのリソースへの参照をすべて削除します。その後、生成されたプランを確認して適用します。リソースを削除すると、マネージドランナーは廃止されます。プロバイダーは削除の完了を最大 30 分間待機し、その後リソースを state から削除します。

## 関連情報

関連するワークフローとリファレンス情報については、以下のページを参照してください。

* [マネージドランナーリソースのリファレンス](/platform/terraform/resources/sandbox_managed_runner)
* [ランナーのデプロイと管理](/ja/products/sandboxes/operations/managed-runners)
* [サンドボックスポリシーを設定する](/ja/products/sandboxes/profiles/configure)