Artifact concepts¶

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.

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 fields:

NIM artifacts also accept an optional templateId field (string) to reference a NIM template for preconfigured model settings.

Container requirements¶

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

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—the source field is a tag whose value determines which of the following fields apply—and defaults to provided using ./Dockerfile from your source:

Example using a provided Dockerfile:

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

Omit path to use the default ./Dockerfile. See Image builds REST.

Image URI validation¶

The platform validates every container's imageUri against the cluster's configured allowlist and denylist when you create, update, or clone an artifact. By default, well-known public registries are permitted (for example, Docker Hub, Quay.io, GHCR, public ECR (public.ecr.aws), GitLab Container Registry, JFrog, and NVIDIA NGC), while internal and cloud-provider-private registries (private ECR, ACR, GCR, GCP Artifact Registry) are not. Cluster administrators can customize this policy, so the exact set of permitted registries can vary by installation.

Only containers that specify an imageUri directly are checked—containers built through imageBuildConfig (the code-to-workload build flow) don't have an imageUri at this point and are skipped.

A disallowed imageUri fails artifact create, update, or clone with one of the following errors:

To resolve either error, push the image to a registry your cluster permits and reference it in imageUri.

Environment variable types¶

Container environment variables (environmentVars) are a discriminated union on the source field. The API accepts three types:

Example using all three types:

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

The api-key entry has no name—the platform resolves it to DATAROBOT_API_TOKEN, the conventional name expected by the DataRobot SDK. To mount the token under a different name, set name explicitly: {"source": "api-key", "name": "MY_DR_TOKEN"}.

These per-Workload keys are visible in Console under Account settings > API keys and tools > Workload API keys, where they can be renamed or deleted; see Manage API keys.

Platform-managed environment variables¶

In addition to environmentVars declared in the artifact spec, the platform injects a set of environment variables into every container at runtime. These are not represented in the spec, not returned by GET /artifacts/{id} or GET /workloads/{id}, and cannot be removed. If you declare an env var with the same name via environmentVars, your value takes precedence.

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. Each status differs in lifecycle and editability.

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:

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.

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:

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