# Runtime settings

> Runtime settings - Change importance, metadata, runtime, autoscaling, and resources on a Workload.

This Markdown file sits beside the HTML page at the same path (with a `.md` suffix). It summarizes the topic and lists links for tools and LLM context.

Companion generated at `2026-07-30T11:40:01.824176+00:00` (UTC).

## Primary page

- [Runtime settings](https://docs.datarobot.com/ja/docs/workload-api/operate-workloads/runtime-settings.html.md): Full documentation for this topic (Markdown sidecar).

## Sections on this page

- [Importance and metadata](https://docs.datarobot.com/ja/docs/workload-api/operate-workloads/runtime-settings.html.md#importance-metadata): In-page section heading.
- [Runtime, autoscaling, and replicas](https://docs.datarobot.com/ja/docs/workload-api/operate-workloads/runtime-settings.html.md#runtime-autoscaling): In-page section heading.
- [Scaling metrics](https://docs.datarobot.com/ja/docs/workload-api/operate-workloads/runtime-settings.html.md#scaling-metrics): In-page section heading.
- [Resource allocation and bundles](https://docs.datarobot.com/ja/docs/workload-api/operate-workloads/runtime-settings.html.md#resource-bundles): In-page section heading.

## Documentation content

A running Workload's configuration is mutable, but the mutations split across two endpoints with different semantics. Identity fields—name, description, importance—update in place via `PATCH /workloads/{id}`. Runtime and resource changes—replica count, autoscaling, CPU, memory, GPU, and bundle selection—go through `PATCH /workloads/{id}/settings` and queue a rolling replacement so the Workload stays available during the swap. The sections that follow cover the fields exposed at each layer and the PATCH body shapes.

## Importance and metadata

Use `PATCH /workloads/{id}` to update `name`, `description`, and `importance`. The `importance` field is mutable on a running Workload:

```
curl -X PATCH "${DATAROBOT_ENDPOINT}/workloads/${WORKLOAD_ID}" \
  -H "Authorization: Bearer ${DATAROBOT_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"importance": "critical"}' 
```

## Runtime, autoscaling, and replicas

Update a Workload's runtime configuration (replica count, autoscaling policies, per-container resource allocation, resource bundles) with `PATCH /workloads/{workload_id}/settings`. The PATCH returns a `Replacement` (HTTP 202) and queues a rolling replacement onto the new runtime; see [Replace and roll out](https://docs.datarobot.com/ja/docs/workload-api/update-workloads/replace-artifact-rollouts.html.md).

All runtime fields are nested under `runtime.containerGroups[]`, with each entry matched to the artifact's container group by `name`:

```
# Fixed scaling
curl -X PATCH "${DATAROBOT_ENDPOINT}/workloads/${WORKLOAD_ID}/settings" \
  -H "Authorization: Bearer ${DATAROBOT_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "runtime": {
      "containerGroups": [{
        "name": "default",
        "replicaCount": 5
      }]
    }
  }'

# Dynamic scaling
curl -X PATCH "${DATAROBOT_ENDPOINT}/workloads/${WORKLOAD_ID}/settings" \
  -H "Authorization: Bearer ${DATAROBOT_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "runtime": {
      "containerGroups": [{
        "name": "default",
        "autoscaling": {
          "enabled": true,
          "minReplicaCount": 2,
          "maxReplicaCount": 10,
          "policies": [{
            "scalingMetric": "httpRequestsConcurrency",
            "target": 20
          }]
        }
      }]
    }
  }' 
```

You can also set autoscaling policies at Workload creation time inside the initial `POST /workloads/` payload—see [Tutorial: Deploy a production-ready container](https://docs.datarobot.com/ja/docs/workload-api/create-workloads/tutorial-production-ready-container.html.md).

### Scaling metrics

`autoscaling` オブジェクトは、 `policies` と同じレベルで `minReplicaCount` および `maxReplicaCount` を受け付けます。これらは、定義されているポリシーの数に関係なく、ワークロードのレプリカの上限と下限を設定します。 各 `AutoscalingPolicy` は、 `scalingMetric` と `target` のみを設定します。 `maxReplicaCount` は1以上である必要があります。また、 `minReplicaCount` は `maxReplicaCount` 以下である必要があります。 カスタムメトリクス名（NIM 2.0のみ）は、Prometheus/OpenMetricsの命名規則に従います。最大63文字で、 `[a-zA-Z_:][a-zA-Z0-9_:]*` というパターンに一致する必要があります。

> [!NOTE] replicaCountとautoscalingは同時に使用できません
> `replicaCount` と `autoscaling.enabled: true` を同時に設定すると、 `422` が返されます。 どちらか一方を使用してください。固定スケーリングには `replicaCount` を、動的スケーリングには `autoscaling` を使用します。

| scalingMetric | Applies to | 動作 |
| --- | --- | --- |
| cpuAverageUtilization | All artifacts | Scales replicas to maintain a target average CPU utilization across pods. ゼロまでスケーリングすることはできません。minReplicaCountは1以上である必要があります。 |
| httpRequestsConcurrency | All artifacts | Scales replicas based on concurrent HTTP requests. Protonがアイドル状態のときは、レプリカ数をゼロまでスケーリングします。ゼロスケーリングを許可するには、minReplicaCount: 0を設定します。 Other metrics keep at least one replica. |
| gpuCacheUtilization | NIM artifacts only | Scales on model GPU memory cache utilization when the runtime exposes it. |
| gpuRequestQueueDepth | NIM artifacts only | Scales on inference request queue depth. |

ゼロスケーリングの例については、 [同じ呼び出しでオートスケーリングを設定する](https://docs.datarobot.com/ja/docs/workload-api/update-workloads/tutorial-replace-artifacts.html.md#configure-autoscaling-in-the-same-call) を参照してください。 The Console maps the same values in [Configure autoscaling](https://docs.datarobot.com/ja/docs/workload-api/operate-workloads/operate-ui.html.md#configure-autoscaling-settings).

> [!NOTE] セルフマネージドクラスター
> Protonのゼロスケーリング（ `minReplicaCount: 0` を指定した `httpRequestsConcurrency` ）には、KEDA HTTPアドオン v0.12.0以降 が必要です。 [KEDA HTTPアドオンのバージョンに関する要件](https://docs.datarobot.com/ja/docs/install/install-config/advanced-configuration/networking-infrastructure/keda.html#keda-http-add-on-version-requirements) を参照してください。

## Resource allocation and bundles

All resource configuration is runtime-side—the artifact describes container topology only and carries no CPU, memory, or GPU fields. The runtime declares resources at two layers:

| Layer | フィールド | What it declares |
| --- | --- | --- |
| Per-container | runtime.containerGroups[].containers[].resourceAllocation (a ContainerOverride.resourceAllocation) with cpu, memory, gpu. | What an individual container in the group gets at runtime. Required for multi-container groups. |
| Per-group | runtime.containerGroups[].resourceBundles (array of bundle IDs; supply exactly one) and runtime.containerGroups[].bundleSelectionPolicy (only availability is supported). | The bundle the scheduler places the group on; the applied bundle is reflected in the read-only resolvedBundle field. Passing more than one bundle ID returns a validation error. |

> [!NOTE] resourceAllocationはリクエストされた値、resolvedBundleは実際の値です
> API応答内の `resourceAllocation` フィールドには、ランタイム設定時に リクエストした 値が含まれます。 読み取り専用の `resolvedBundle` フィールドには、スケジューラーが実際にコンテナグループを配置したバンドルが表示され、これによりポッドが割り当てられるCPU、メモリー、GPUが決定されます。 これらは異なる場合があります。たとえば、 `cpu: 0.5` をリクエストしても、1.0コアを提供する `cpu.micro` バンドルに解決されることがあります。 実際にプロビジョニングされた内容を確認するには、常に `resolvedBundle` を確認してください。

ワークロードで使用可能なリソースバンドルIDを一覧表示するには、 `useCases=workload` を指定して `GET /mlops/compute/bundles/` にクエリーを実行します。

```
curl -s "${DATAROBOT_ENDPOINT}/mlops/compute/bundles/?useCases=workload" \
  -H "Authorization: Bearer ${DATAROBOT_API_TOKEN}" 
```

このクエリーによって返されるバンドルのみが、 `runtime.containerGroups[].resourceBundles` で有効な値となります。

`memory` accepts either a human-readable string with one of `B`, `KB`, `MB`, `GB` (1000-based—for example, `"4GB"`, `"512MB"`) or a raw byte integer. Kubernetes形式のバイナリサフィックス（ `Mi` 、 `Gi` ）はサポートされておらず、検証エラーが返されます。 `cpu` has a minimum of `0.1`. The `gpu` field controls GPU count only; GPU model and VRAM are determined entirely by the selected resource bundle —there is no per-container GPU type or VRAM field. Each override's `name` follows DNS-label syntax (lowercase letters, digits, and hyphens; must start with a letter and end with a letter or digit; up to 63 characters) and must match a container declared in the artifact group.

Set both layers on the Workload's `runtime`. Changing them on a running Workload via `PATCH /workloads/{workload_id}/settings` queues a rolling replacement using the strategies in [Replace and roll out](https://docs.datarobot.com/ja/docs/workload-api/update-workloads/replace-artifact-rollouts.html.md).

```
curl -X PATCH "${DATAROBOT_ENDPOINT}/workloads/${WORKLOAD_ID}/settings" \
  -H "Authorization: Bearer ${DATAROBOT_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "runtime": {
      "containerGroups": [{
        "name": "default",
        "resourceBundles": ["cpu.medium"],
        "containers": [{
          "name": "agent",
          "resourceAllocation": {"cpu": 2, "memory": "4GB"}
        }]
      }]
    }
  }' 
```