Terraform でランナーを管理する

coreweave_sandbox_managed_runner リソースを使用すると、CoreWeave Kubernetes Service (CKS) クラスター上のランナーとそのサンドボックスポリシーを管理できます。Terraform は望ましい設定を記録してドリフトを検出し、マネージドランナー API を介して設定の変更を適用します。属性スキーマの完全な一覧については、マネージドランナーリソースのリファレンスを参照してください。CLI および REST を使用した同等のワークフローについては、ランナーのデプロイと管理を参照してください。

始める前に

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

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

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

認証を設定する

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

export COREWEAVE_API_TOKEN="$CW_API_KEY"

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

ランナーを定義する

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

main.tf

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 時間に設定しています。デフォルトの有効期間は、最大ライフタイムとは異なります。制約をワークロードに合わせて調整するには、サンドボックスポリシーを設定するを参照してください。

policy オブジェクトは必須です。明示的に空のオブジェクトを指定するのは、意図的に空のポリシーを使用する場合のみにしてください。zone の値は小文字である必要がありますが、これは lower(var.zone) によって保証されます。 [RUNNER-ID]、[CLUSTER-ID]、[ZONE] をそれぞれランナー識別子、CKS クラスターの UUID、アベイラビリティゾーンに置き換え、値を terraform.tfvars ファイルに保存します。

terraform.tfvars

runner_id  = "[RUNNER-ID]"
cluster_id = "[CLUSTER-ID]"
zone       = "[ZONE]"

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

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

プロバイダーを初期化し、設定を検証します。
terraform init terraform validate
プランを確認して適用します。
terraform plan -out=runner.tfplan terraform apply runner.tfplan
適用が成功すると、API が設定を受け付けたことになります。ランナーのインストールとロールアウトは引き続き非同期で進行します。
観測されたステータスを更新し、出力を確認します。
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 のアフィニティの例を使用してください。REST で行った変更が後続の apply で上書きされないように、Terraform の設定と整合をとってください。この属性をサポートするプロバイダーをインストールしたら、既存の spec.overrides オブジェクトに次の属性をマージします。例示用のラベルは、お使いのクラスターのノードで使用されているラベルに置き換えてください。

Affinity attribute inside spec.overrides

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

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

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

terraform init
terraform import coreweave_sandbox_managed_runner.runner '[RUNNER-ID]'
terraform plan

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

ランナーを削除する

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

サンドボックス

サンドボックスを使用する

サンドボックスの管理

リファレンス

Terraform でランナーを管理する

始める前に

認証を設定する

ランナーを定義する

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

設定を更新する

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

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

ランナーを削除する

関連情報

​始める前に

​認証を設定する

​ランナーを定義する

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

​設定を更新する

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

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

​ランナーを削除する

​関連情報

始める前に

認証を設定する

ランナーを定義する

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

設定を更新する

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

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

ランナーを削除する

関連情報