# アーティファクトの概念

> アーティファクトの概念 - アーティファクトのタイプ、ライフサイクル、構成の階層化、およびリポジトリ。

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-09-02T14:28:12.968617+00:00` (UTC).

## Primary page

- [アーティファクトの概念](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

- [アーティファクトのタイプ](https://docs.datarobot.com/ja/docs/workload-api/build-artifacts/artifacts-concepts.html.md#artifact-types): In-page section heading.
- [コンテナの要件](https://docs.datarobot.com/ja/docs/workload-api/build-artifacts/artifacts-concepts.html.md#container-requirements): In-page section heading.
- [イメージビルド設定](https://docs.datarobot.com/ja/docs/workload-api/build-artifacts/artifacts-concepts.html.md#image-build-configuration): In-page section heading.
- [イメージURIの検証](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.
- [アーティファクトのライフサイクル](https://docs.datarobot.com/ja/docs/workload-api/build-artifacts/artifacts-concepts.html.md#artifact-lifecycle): In-page section heading.
- [アーティファクトとワークロード：何がどこに存在するか](https://docs.datarobot.com/ja/docs/workload-api/build-artifacts/artifacts-concepts.html.md#configuration-layering): In-page section heading.
- [アーティファクトリポジトリ](https://docs.datarobot.com/ja/docs/workload-api/build-artifacts/artifacts-concepts.html.md#artifact-repositories): In-page section heading.

## Documentation content

アーティファクトは、ワークロードが 何を 実行するかを記述します。具体的には、イメージURI、ポート、エントリーポイント、環境変数、ヘルスプローブを含むコンテナ仕様です。ワークロードはアーティファクトから作成されます。ロックされた1つのアーティファクトは、多くのワークロードの基盤として機能します。

## アーティファクトのタイプ

アーティファクトは、 `type` 判別子を使用します。APIは `service` （デフォルト）および `nim` （NVIDIA NIMモデルアーティファクト）を受け付けます。どちらも同じマルチコンテナの `containerGroups` の形状を使用しますが、NIMでは、生成されたAPIリファレンスにオプションのストレージとGPU向けのオートスケーリング指標が追加されます。

| タイプ | 使用するタイミング |
| --- | --- |
| service | イメージを提供し、プラットフォームがそれらを実行する（プライマリに加えてオプションのサイドカーコンテナ）、コンテナベースのワークロード。推論サーバー、エージェントコンテナ（LangGraph、CrewAI、AutoGen）、API、およびWebサービスが含まれます。 |
| nim | NIM固有のスケジューリング、ストレージオプション、およびスケーリングシグナル（gpuCacheUtilization、gpuRequestQueueDepth）が必要な場合の、NVIDIA NIMモデルサービング。NimArtifactSpecおよびスケーリング指標については、Workload APIリファレンスを参照してください。 |

NIMアーティファクトには、オプションの `storage` フィールド（ `NimStorageConfig` ）があり、2つの選択肢があります。 `dedicatedPvc` （デフォルト）は、モデルの重み用にワークロード独自のPVCを提供します。一方、 `nimCache` は、モデルイメージをキーとするクラスター全体のPVCを使用します。複数のワークロードが同じNIMイメージを共有する場合は、クラスターが重みのキャッシュされたコピーを1つだけ保持するように、 `nimCache` を選択します。

`NimStorageConfig` のフィールド：

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

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

## コンテナの要件

プラットフォームが実行するすべてのコンテナは、以下のベースライン要件を満たしている必要があります。

| 要件 | 理由 |
| --- | --- |
| linux/amd64向けにビルドされていること | プラットフォームはx86-64ノード上で動作します。ARM向けにビルドされたイメージ（たとえば、デフォルトのdocker buildを使用するApple Silicon上など）は起動に失敗します。正しいアーキテクチャを生成するには、docker buildx build --platform linux/amd64を使用してビルドします。 |
| 非rootユーザーとして実行する | プラットフォームはコンテナを非特権で実行します。 |
| 1024から65535の間のポートでリッスンする | コンテナは特権ポート（0～1023）にバインドできません。ポートはcontainers[].portを介してアーティファクトで設定されます。 |
| HTTPサーバーを公開する | プラットフォームは、呼び出しトラフィックをHTTPとしてプライマリコンテナにプロキシします。 |
| Readinessプローブのエンドポイントを実装する | プラットフォームはreadinessProbe.pathをポーリングして準備状況を判断します。 |
| SIGTERMシグナルのグレースフルな処理を実装している | プラットフォームはワークロードを中断する場合があります（ノードのメンテナンスなど）。この場合、猶予期間を通知するためにコンテナにSIGTERMが送信されます。この期間中、コンテナは実行中のプロセスや接続をドレインしてから、プラットフォームがSIGKILLへとエスカレートします。猶予期間は、インストール時にクラスターレベルで設定されます。 |

> [!NOTE] プライマリコンテナと非プライマリコンテナ
> コンテナグループには、正確に1つのプライマリコンテナ（ `primary: true` ）と任意の数のサイドカーがあります。プライマリコンテナは `port` を定義 しなければなりません 。非プライマリコンテナ（サイドカー）は `port` を省略 しなければなりません 。これらを誤って割り当てると、アーティファクトの作成または更新時に `422` 検証エラーが返されます。

## イメージビルド設定

ドラフトの `service` アーティファクトの場合、 `imageUri` の代わりにコンテナに `imageBuildConfig` を設定します。これにより、アップロードされたソースコードからビルドされます（ `POST /artifacts/{id}/builds` ）。事前ビルド済みの `imageUri` または `imageBuildConfig` のいずれかを提供します（両方は不可）。ビルドが成功すると、プラットフォームは `imageUri` に値を入力します。

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

| source | スキーマ | フィールド |
| --- | --- | --- |
| provided | ProvidedDockerfile | path（文字列、デフォルト ./Dockerfile）。同期されたソースコード内のDockerfileへの相対パス。 |
| generated | GeneratedDockerfile | executionEnvironmentId、executionEnvironmentVersionId、entrypoint。プラットフォームは実行環境のベースイメージからDockerfileを生成します。 |

提供されたDockerfileを使用する例：

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

`path` を省略すると、デフォルトの `./Dockerfile` が使用されます。 [イメージビルドREST](https://docs.datarobot.com/ja/docs/workload-api/build-artifacts/artifacts-rest-endpoints.html.md#image-builds) を参照してください。

## イメージURIの検証

アーティファクトを作成、更新、またはクローン化する際、プラットフォームはすべてのコンテナの `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トランスポートプロトコルで、http/protobufに設定されています。プラットフォームによって管理されています。オーバーライドしないでください。 |
| OTEL_EXPORTER_OTLP_TRACES_PROTOCOL | トレース専用のOTLPトランスポートプロトコルで、http/protobufに設定されています。一部のモデルでは、上記の汎用的な変数ではなく、このシグナル固有の変数のみが適用されます。 |
| OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE | OTel SDKのメトリクスの時間性設定で、lowmemoryに設定されています。 |
| OTEL_RESOURCE_ATTRIBUTES | トレースやメトリクス内でワークロードを識別するためのOTelリソース属性。 |

## アーティファクトのライフサイクル

このセクションでは、アーティファクトに関連する `draft` と `locked` を定義します。ワークロード作成の判断、つまりそれぞれがどの場合に適合し、TTL（time-to-live）、重要度、置き換えルールに関して何を意味するかについては、 [ドラフトとロックの選択](https://docs.datarobot.com/ja/docs/workload-api/create-workloads/workload-concepts.html.md#choose-draft-vs-locked) を参照してください。各ステータスは、ライフサイクルと編集可能性が異なります。

| ステータス | 編集可能 | 説明 |
| --- | --- | --- |
| draft | はい | デフォルトのステータス。可変。開発中にPATCH/PUTで更新します。 |
| locked | いいえ | 不変。一度設定すると変更できません。本番ワークロードに必要です。 |

ロックは一方向です。ロックされたアーティファクトはドラフトに戻すことができません。ロックされたアーティファクトをさらに反復するには、新しいドラフトアーティファクトを作成します。次のいずれかの方法でアーティファクトをロックできます。

| 方法 | プロセス |
| --- | --- |
| 直接ロック | PATCH /artifacts/{id}を{"status": "locked"}で呼び出します。これにより、関連するワークロードの統計情報が自動的にリセットされ、本番環境がクリーンなベースラインから開始されます。 |
| 昇格 | POST /workloads/{id}/promoteを呼び出します。本番環境への昇格を参照してください。これにより、統計情報も消去され、ドラフトワークロードの8時間TTLが単一の呼び出しで削除されます。 |

> [!NOTE] 削除ルール
> ロックされたアーティファクトは削除できません。実行中のproton（ドラフトまたはロック）を持つアーティファクトも削除できません。まず、バックとなるワークロードを停止または削除してください。

## アーティファクトとワークロード：何がどこに存在するか

アーティファクトは何を実行するかを定義し、ワークロードランタイムはどのように実行するかを定義します。ランタイムはワークロードごとの環境変数のオーバーライドを受け付けません。デプロイ間で異なる必要がある値は、アーティファクトの `environmentVars` に属します。

| レイヤー | ここに存在するもの | 可変性 | 例 |
| --- | --- | --- | --- |
| アーティファクト（spec.containerGroups[].containers[]） | コンテナのトポロジー。イメージURIまたはビルド設定、ポート、エントリーポイント、環境変数、プローブ。 | lockedになると不変。 | imageUri、imageBuildConfig、port、entrypoint、environmentVars、readinessProbe。 |
| ワークロード（runtime.containerGroups[]） | デプロイ時の設定。レプリカ、オートスケーリング、コンテナごとのリソース割り当て、リソースバンドル。 | 常に可変。ロックされたワークロードでは、PATCH /workloads/{id}/settingsを介した変更は即座に有効になるのではなく、ローリング置換をトリガーします。（ロック時に不変になるのはアーティファクト仕様であり、ランタイムではありません。） | replicaCount、autoscaling、コンテナごとのresourceAllocation、resourceBundles。 |

> [!NOTE] コンテナ名とグループ名のルール
> 各コンテナの `name` （および対応するランタイムオーバーライドの `name` ）は、DNSラベル構文に従います。小文字、数字、ハイフンを使用し、小文字で始まり、文字または数字で終わる必要があり、最大63文字です。ランタイムは、これらの名前によって `containerGroups[].containers[]` のエントリをアーティファクトに一致させるため、正確に一致している必要があります。

フィールドをどこに定義するかを決定するときは、次のガイダンスを考慮してください。

- フィールドがコンテナのアイデンティティの一部である場合（どのコードが実行されるか、どのポートでリッスンするか、どの環境変数が必要か）、それはアーティファクト仕様に属します。
- フィールドがデプロイ時のつまみ（レプリカ数、CPU割り当て、スケーリングポリシー）である場合、それはワークロードランタイムに属します。

## アーティファクトリポジトリ

アーティファクトリポジトリは、アーティファクトのバージョンをグループ化し、以下を提供します。

| 機能 | 得られるもの |
| --- | --- |
| バージョン履歴 | 単一の場所にあるアーティファクトのリビジョンの追跡可能な系統。 |
| 共有ガバナンス | コレクションを読み取りまたは変更できるユーザーを制御する、リポジトリ上のsharedRoles付与。 |
| 発見可能性 | 同じ製品またはチームに属するアーティファクトをより簡単に発見できます。 |

`artifactRepositoryId` を設定してアーティファクトを初めて作成すると、プラットフォームは自動的にリポジトリを作成します。