# Artifact concepts

> Artifact concepts - Artifact types, lifecycle, configuration layering, and repositories.

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.815601+00:00` (UTC).

## Primary page

- [Artifact concepts](https://docs.datarobot.com/ja/docs/workload-api/build-artifacts/artifacts-concepts.html.md): Full documentation for this topic (Markdown sidecar).

## Sections on this page

- [Artifact types](https://docs.datarobot.com/ja/docs/workload-api/build-artifacts/artifacts-concepts.html.md#artifact-types): In-page section heading.
- [Container requirements](https://docs.datarobot.com/ja/docs/workload-api/build-artifacts/artifacts-concepts.html.md#container-requirements): In-page section heading.
- [Image build configuration](https://docs.datarobot.com/ja/docs/workload-api/build-artifacts/artifacts-concepts.html.md#image-build-configuration): In-page section heading.
- [Image URI validation](https://docs.datarobot.com/ja/docs/workload-api/build-artifacts/artifacts-concepts.html.md#image-uri-validation): In-page section heading.
- [環境変数のタイプ](https://docs.datarobot.com/ja/docs/workload-api/build-artifacts/artifacts-concepts.html.md#environment-variable-types): In-page section heading.
- [プラットフォームが管理する環境変数](https://docs.datarobot.com/ja/docs/workload-api/build-artifacts/artifacts-concepts.html.md#platform-managed-env-vars): In-page section heading.
- [Artifact lifecycle](https://docs.datarobot.com/ja/docs/workload-api/build-artifacts/artifacts-concepts.html.md#artifact-lifecycle): In-page section heading.
- [Artifact vs. Workload: what lives where](https://docs.datarobot.com/ja/docs/workload-api/build-artifacts/artifacts-concepts.html.md#configuration-layering): In-page section heading.
- [Artifact repositories](https://docs.datarobot.com/ja/docs/workload-api/build-artifacts/artifacts-concepts.html.md#artifact-repositories): In-page section heading.

## Documentation content

An artifact describes what a Workload runs: a container specification with image URI, port, entrypoint, environment variables, and health probes. Workloads are created from artifacts; one locked artifact can serve as the foundation for many Workloads.

## Artifact types

Artifacts use a `type` discriminator. The API accepts `service` (default) and `nim` (NVIDIA NIM model artifacts). Both use the same multi-container `containerGroups` shape; NIM adds optional storage and GPU-oriented autoscaling metrics in the generated API reference.

| タイプ | 使用するタイミング |
| --- | --- |
| service | Container-based Workloads where you supply images and the platform runs them (primary plus optional sidecar containers): inference servers, agent containers (LangGraph, CrewAI, AutoGen), APIs, and web services. |
| nim | NVIDIA NIM model serving when you need NIM-specific scheduling, storage options, and scaling signals (gpuCacheUtilization, gpuRequestQueueDepth). See the Workload API reference for NimArtifactSpec and Scaling metrics. |

NIM artifacts include an optional `storage` field ( `NimStorageConfig`) with two choices: `dedicatedPvc` (default) gives the Workload its own PVC for model weights. Alternatively, `nimCache` uses a cluster-wide PVC keyed on the model image—pick `nimCache` when multiple Workloads share the same NIM image so that the cluster keeps a single cached copy of the weights.

`NimStorageConfig` のフィールド

| フィールド | タイプ | デフォルト | 説明 |
| --- | --- | --- | --- |
| mode | "dedicatedPvc" \ | "nimCache" | "dedicatedPvc" |
| pvcSize | 文字列（Kubernetesの数量） | なし | PVCのサイズ（例："150Gi"）。 modeが"dedicatedPvc"の場合にのみ有効です。 |

NIMアーティファクトでは、事前に行われたモデル設定でのNIMテンプレートを参照するためのオプションの `templateId` フィールド（文字列）も受け付けます。

## Container requirements

Every container the platform runs must satisfy the following baseline requirements:

| 要件 | Why |
| --- | --- |
| linux/amd64向けに構築されていること | プラットフォームはx86-64ノード上で動作します。 ARM向けに構築されたイメージ（例：Apple Silicon上でデフォルトのdocker buildを使用）は起動に失敗します。 正しいアーキテクチャを生成するには、docker buildx build --platform linux/amd64を使用して構築します。 |
| Runs as non-root user | The platform runs containers unprivileged. |
| Listens on a port between 1024 and 65535 | Containers cannot bind to privileged ports (0-1023). The port is set on the artifact via containers[].port. |
| Exposes an HTTP server | The platform proxies invoke traffic as HTTP to the primary container. |
| Implements a readiness probe endpoint | The platform polls readinessProbe.path to determine readiness. |
| SIGTERMシグナルのグレースフルな処理を実装している | プラットフォームは、ワークロードを中断する場合があります（例：ノードのメンテナンス）。 この場合、コンテナにSIGTERMが送信され、猶予期間が通知されます。この期間中、コンテナは実行中のプロセスや接続を正常に終了させる必要があります。これを怠ると、プラットフォームはSIGKILLを発行します。 猶予期間は、インストール時にクラスターレベルで設定されます。 |

> [!NOTE] Primary vs. non-primary containers
> A container group has exactly one primary container ( `primary: true`) plus any number of sidecars. The primary container must define a `port`; non-primary containers (sidecars) must omit `port`. Assigning these incorrectly returns a `422` validation error at artifact create or update.

## Image build configuration

For draft `service` artifacts, set `imageBuildConfig` on a container instead of `imageUri`. This then builds from uploaded source code ( `POST /artifacts/{id}/builds`). Provide either a pre-built `imageUri` or `imageBuildConfig` (not both). After a successful build, the platform populates `imageUri`.

`ImageBuildConfig.dockerfile` は判別可能ユニオン（discriminated union）です。 `source` フィールドはタグであり、その値によって以下のどのフィールドが適用されるかが決まります。デフォルトは `provided` で、ソースディレクトリ内の `./Dockerfile` が使用されます。

| source | スキーマ | フィールド |
| --- | --- | --- |
| provided | ProvidedDockerfile | path (string, default ./Dockerfile)—relative path to the Dockerfile in synced source code. |
| generated | GeneratedDockerfile | executionEnvironmentId, executionEnvironmentVersionId, entrypoint—platform generates a Dockerfile from the execution environment base image. |

Example using a provided Dockerfile:

```
"imageBuildConfig": {
  "dockerfile": {
    "source": "provided",
    "path": "./Dockerfile"
  }
} 
```

Omit `path` to use the default `./Dockerfile`. See [Image builds REST](https://docs.datarobot.com/ja/docs/workload-api/build-artifacts/artifacts-rest-endpoints.html.md#image-builds).

## Image URI validation

アーティファクトを作成、更新、またはクローン化する際、プラットフォームはすべてのコンテナの `imageUri` を、クラスターで設定された許可リストおよび拒否リストと照合して検証します。 デフォルトでは、広く知られているパブリックレジストリ（例：Docker Hub、Quay.io、GHCR、パブリックECR（ `public.ecr.aws` ）、GitLab Container Registry、JFrog、NVIDIA NGC）は許可されていますが、内部レジストリおよびクラウドプロバイダーのプライベートレジストリ（プライベート ECR、ACR、GCR、GCP Artifact Registry）は許可されていません。 クラスター管理者はこのポリシーをカスタマイズできるため、許可されるレジストリの具体的なセットはインストール環境によって異なる場合があります。

`imageUri` を直接指定しているコンテナのみがチェックの対象となります。 `imageBuildConfig` （コードからワークロードへの構築フロー）を通じて構築されたコンテナは、この時点では `imageUri` を持っていないため、チェックの対象外となります。

許可されていない `imageUri` の場合、アーティファクトの作成、更新、またはクローン化は失敗し、以下のいずれかのエラーが発生します。

| エラー | 原因 |
| --- | --- |
| Image URI '<uri>' is not permitted on this cluster. | URIが、クラスターが拒否するパターンに一致しています。 |
| Image URI '<uri>' is not in the permitted image registry allowlist. | URIが、クラスターが許可するどのパターンにも一致しません。 |

いずれのエラーも解決するには、クラスターが許可するレジストリにイメージをプッシュし、 `imageUri` でそれを参照してください。

## 環境変数のタイプ

コンテナ環境変数（ `environmentVars` ）は、 `source` フィールドの判別可能ユニオン（discriminated union）です。 APIでは3つのタイプを受け付けます。

| タイプ | source | フィールド | 説明 |
| --- | --- | --- | --- |
| StringEnvironmentVariable | "string"（またはsourceを省略） | name, value | プレーンテキストのキーと値のペア。 機微情報が含まれない設定に使用します。 |
| CredentialEnvironmentVariable | "dr-credential" | name, drCredentialId, key | 実行時にDataRobot資格情報サービスから値を検索します。 シークレット、トークン、パスワードに使用します。 |
| ApiKeyEnvironmentVariable | "api-key" | name（オプション） | ワークロードごとのAPIキーで、呼び出し元ユーザーをスコープとし、Protonの作成時に自動的に解決されます。呼び出し元から値やIDが指定されることはありません。 nameを省略した場合、デフォルトはDATAROBOT_API_TOKENとなります。 コンテナがDataRobot APIに対して認証する必要がある場合に使用します。 |

3つのタイプすべてを使用した例

```
"environmentVars": [
  {"name": "APP_MODE", "value": "production"},
  {"source": "dr-credential", "name": "DB_PASSWORD", "drCredentialId": "64abc...", "key": "password"},
  {"source": "api-key"}
] 
```

`api-key` エントリーには `name` がありません。プラットフォームがこれを、DataRobot SDKが期待する標準的な名前である `DATAROBOT_API_TOKEN` に解決します。 トークンを別の名前でマウントするには、 `name` を明示的に設定してください： `{"source": "api-key", "name": "MY_DR_TOKEN"}` 。

これらのワークロードごとのキーは、コンソールの アカウント設定 > APIのキーとツール > Workload APIキー で確認でき、そこで名前を変更したり削除したりすることができます。詳しくは、 [APIキーの管理](https://docs.datarobot.com/ja/docs/platform/acct-settings/api-key-mgmt.html.md#workload-api-keys) を参照してください。

## プラットフォームが管理する環境変数

アーティファクト仕様で宣言された `environmentVars` に加え、プラットフォームは実行時にすべてのコンテナに一連の環境変数を注入します。 これらは仕様には反映されず、 `GET /artifacts/{id}` や `GET /workloads/{id}` によっても返されず、削除することもできません。 `environmentVars` を通じて同じ名前の環境変数を宣言した場合、その値が優先されます。

| 特徴量 | 説明 |
| --- | --- |
| DATAROBOT_ENDPOINT | DataRobot APIのベースURL。デプロイ設定から算出されます。 この値を使用して、DataRobot SDKを初期化したり、コンテナ内部からAPIリクエストを構築したりします。 |
| DATAROBOT_PUBLIC_API_ENDPOINT | DataRobotのパブリックAPIのURL。 ワークロードに外部URLが設定されている場合にのみ注入されます。 |
| WORKLOAD_ID | コンテナが実行されているワークロードのID。 これを使用して、API呼び出しのスコープを所有するワークロードに戻します。 |
| OTEL_EXPORTER_OTLP_ENDPOINT | OTelコレクターのエンドポイント。 SDKはこの値を自動的に取得します。テレメトリをカスタムコレクターにルーティングする場合を除き、ハードコーディングや上書きは行わないでください。 |
| OTEL_EXPORTER_OTLP_HEADERS | OTelコレクター用の認証ヘッダー。 プラットフォームによって管理されています。オーバーライドしないでください。 |
| OTEL_EXPORTER_OTLP_PROTOCOL | OTLP transport protocol for the exporter, set to http/protobuf. プラットフォームによって管理されています。オーバーライドしないでください。 |
| OTEL_EXPORTER_OTLP_TRACES_PROTOCOL | OTLP transport protocol for traces specifically, set to http/protobuf. Some models only respect this signal-specific variable rather than the generic one above. |
| OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE | Metrics temporality preference for the OTel SDK, set to lowmemory. |
| OTEL_RESOURCE_ATTRIBUTES | トレースやメトリクス内でワークロードを識別するためのOTelリソース属性。 |

## Artifact lifecycle

This section defines `draft` and `locked` as they relate to artifacts. For the Workload-creation decision—when each fits and what each implies for TTL (time-to-live), importance, and replace rules—see [Choose draft vs. locked](https://docs.datarobot.com/ja/docs/workload-api/create-workloads/workload-concepts.html.md#choose-draft-vs-locked). Each status differs in lifecycle and editability.

| ステータス | Editable | 説明 |
| --- | --- | --- |
| draft | はい | Default status. Mutable. Update via PATCH/PUT during development. |
| locked | いいえ | Immutable. Cannot be modified once set. Required for production Workloads. |

Locking is one-way: locked artifacts cannot return to draft. To iterate further on a locked artifact, create a new draft artifact. You can lock an artifact using either of the following methods:

| 方法 | Process |
| --- | --- |
| Direct lock | Call PATCH /artifacts/{id} with {"status": "locked"}. This automatically resets the associated Workload's statistics so production starts from a clean baseline. |
| プロモート | Call POST /workloads/{id}/promote; see Promote to production. This also wipes stats and removes the draft Workload's 8-hour TTL in a single call. |

> [!NOTE] Deletion rules
> Locked artifacts cannot be deleted. Artifacts with running protons (draft or locked) cannot be deleted either—stop or delete the backing Workloads first.

## Artifact vs. Workload: what lives where

The artifact defines what runs; the Workload runtime defines how it runs. The runtime does not accept per-Workload environment variable overrides—values that need to vary across deployments belong in the artifact's `environmentVars`.

| Layer | What lives here | Mutability | 例 |
| --- | --- | --- | --- |
| Artifact (spec.containerGroups[].containers[]) | Container topology—image URI or build config, port, entrypoint, environment variables, and probes. | Immutable once locked. | imageUri, imageBuildConfig, port, entrypoint, environmentVars, readinessProbe. |
| Workload (runtime.containerGroups[]) | Deployment-time settings—replicas, autoscaling, per-container resource allocation, resource bundles. | Always mutable. On a locked Workload, changes via PATCH /workloads/{id}/settings trigger a rolling replacement rather than taking effect immediately. (It is the artifact spec that becomes immutable at lock time, not the runtime.) | replicaCount, autoscaling, per-container resourceAllocation, resourceBundles. |

> [!NOTE] Container and group name rules
> Each container's `name` (and the matching `name` on a runtime override) follows DNS-label syntax—lowercase letters, digits, and hyphens; must start with a lowercase letter and end with a letter or digit; up to 63 characters. The runtime matches its `containerGroups[].containers[]` entries to the artifact by these names, so they must agree exactly.

Consider the following guidance when deciding where to define a field:

- If a field is part of the container's identity (which code runs, what ports it listens on, which env vars it needs), it belongs in the artifact spec.
- If a field is a deployment-time knob (replica count, CPU allocation, scaling policy), it belongs in the Workload runtime.

## Artifact repositories

Artifact repositories group artifact versions and provide:

| 機能 | What you get |
| --- | --- |
| バージョン履歴 | A traceable lineage of artifact revisions in a single location. |
| Shared governance | A sharedRoles grant on the repository that controls who can read or modify the collection. |
| Discoverability | Easier discovery of artifacts that belong to the same product or team. |

The platform creates a repository automatically the first time you create an artifact with `artifactRepositoryId` set.