# 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-06-22T16:50:38.245685+00:00` (UTC).

## Primary page

- [Artifact concepts](https://docs.datarobot.com/en/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/en/docs/workload-api/build-artifacts/artifacts-concepts.html.md#artifact-types): In-page section heading.
- [Container requirements](https://docs.datarobot.com/en/docs/workload-api/build-artifacts/artifacts-concepts.html.md#container-requirements): In-page section heading.
- [Image build configuration](https://docs.datarobot.com/en/docs/workload-api/build-artifacts/artifacts-concepts.html.md#image-build-configuration): In-page section heading.
- [Artifact lifecycle](https://docs.datarobot.com/en/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/en/docs/workload-api/build-artifacts/artifacts-concepts.html.md#configuration-layering): In-page section heading.
- [Artifact repositories](https://docs.datarobot.com/en/docs/workload-api/build-artifacts/artifacts-concepts.html.md#artifact-repositories): In-page section heading.

## Related documentation

- [Workload API](https://docs.datarobot.com/en/docs/workload-api/index.html.md): Linked from this page.
- [Build artifacts](https://docs.datarobot.com/en/docs/workload-api/build-artifacts/index.html.md): Linked from this page.
- [Scaling metrics](https://docs.datarobot.com/en/docs/workload-api/operate-workloads/runtime-settings.html.md#scaling-metrics): Linked from this page.
- [Image builds REST](https://docs.datarobot.com/en/docs/workload-api/build-artifacts/artifacts-rest-endpoints.html.md#image-builds): Linked from this page.
- [Choose draft vs. locked](https://docs.datarobot.com/en/docs/workload-api/create-workloads/workload-concepts.html.md#choose-draft-vs-locked): Linked from this page.
- [Promote to production](https://docs.datarobot.com/en/docs/workload-api/update-workloads/promote-production.html.md): Linked from this page.

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

| Type | When to use |
| --- | --- |
| 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.

## Container requirements

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

| Requirement | Why |
| --- | --- |
| 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. |

> [!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` is a discriminated union on `source` (defaults to `provided` using `./Dockerfile` from your source):

| source | Schema | Fields |
| --- | --- | --- |
| 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/en/docs/workload-api/build-artifacts/artifacts-rest-endpoints.html.md#image-builds).

## 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/en/docs/workload-api/create-workloads/workload-concepts.html.md#choose-draft-vs-locked). Each status differs in lifecycle and editability.

| Status | Editable | Description |
| --- | --- | --- |
| draft | Yes | Default status. Mutable. Update via PATCH/PUT during development. |
| locked | No | 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:

| Method | 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. |
| Promote | 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 | Examples |
| --- | --- | --- | --- |
| 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:

| Capability | What you get |
| --- | --- |
| Version history | 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.