Build Workloads from source¶

In the standard Workload API flow, a user supplies a pre-built container image by URI and the platform runs it. This page enables the alternative: the user supplies source code, and the platform builds the container image for them. This flow is called code to Workload; for the user-facing view of it, see Build artifacts from source code.

Builds need no configuration of their own. The registry that receives built images, the object storage that holds the build context, and the base image registry are all inherited from the installation's existing platform settings.

How a build is assembled¶

Workload API resolves the uploaded source snapshot that the codeRef points at from the Files API, which is backed by the installation's existing in-cluster object storage. A Dockerfile the user supplies is simply a file inside that snapshot; when they supply none, Workload API renders one and writes it to object storage alongside the snapshot—see Generated Dockerfile storage.

Workload API then hands the build to the platform's image build service, which builds the image and pushes it to the installation's container registry. Registry credentials belong to the build service, not to Workload API, which never contacts a registry itself. An installation that already builds custom models already has them; see Image Build Service.

When a build completes, the platform writes the resulting image URI back onto the artifact's container, and the Workload runs it like any other pre-built image. See Build results.

Prerequisites¶

• Workload API is deployed and enabled. See Enable the Workload API.
• Nothing extra to install for builds—the image build service is present on every standard installation, because custom models, custom applications, custom jobs, generative AI, and notebooks all depend on it.
• global.filestore is configured for the installation's object storage.
• The installation's container registry is reachable from the cluster for both push and pull. This is the same registry the platform already uses for custom model images.

Where built images go¶

Built images are pushed to the container registry the installation already uses, in a repository of their own, workload-api/managed-workloads. An installation that prefixes its repository names keeps that prefix, so the path sits alongside the one its custom model images use.

Nothing about this needs configuring, and the asynchronous build-status reconciler that tracks running builds is enabled by default as well. To send built images to a different repository, set IMAGE_BUILDER_WORKLOAD_API_REGISTRY_REPO under core.config_env_vars, the same way the other image builder repositories are set.

Generated Dockerfile storage¶

When a user doesn't supply a Dockerfile, Workload API generates one and stores it for the build to read. This needs no configuration: the bucket and credentials fall back to global.filestore, so the Dockerfile lands in the same object storage the Files API already uses, under a workload-api/ prefix. A build that uses only user-supplied Dockerfiles never touches this storage at all.

This holds for an S3-compatible endpoint too: a MinIO-backed installation configures its host, port, TLS settings, and S3_SERVER_SIDE_ENCRYPTION once under global.filestore.environment, and Workload API reads all of them from there. See Object storage config.

Base image resolution¶

A generated Dockerfile builds on an execution environment image. When the selected execution environment version records an image ID rather than a full image URI, Workload API reconstructs the URI from two core settings, IMAGE_BUILDER_CUSTOM_MODELS_REGISTRY_HOST and IMAGE_BUILDER_CUSTOM_MODELS_ENVIRONMENT_REGISTRY_REPO. Both reach Workload API pods through the datarobot-modeling-envvars ConfigMap and are part of the standard values for every supported cloud, so a complete installation needs no configuration here.

Network requirements¶

Builds run in the image build service's build pods, so these endpoints must be reachable from that namespace, not from Workload API pods. They're the endpoints the platform's image builds already require—container registries, PyPI, and the npm registry—so a standard installation needs no change here. For the full list, see Image Build Service network requirements.

Two endpoints are worth calling out for builds from source:

• ghcr.io, for the uv binary that every generated Python build copies in, unless you point the build at a copy in your own registry. See Air-gapped installations.
• The installation's object storage endpoint, for reading the build context and the generated Dockerfile.

A user-supplied Dockerfile can reach any endpoint its instructions name.

Air-gapped installations¶

Builds work on an air-gapped installation, with three constraints.

The target registry must be reachable in both directions. The built image is pushed to the installation's registry, and every cluster that runs the resulting Workload pulls from it. An air-gapped installation already points the platform at a registry inside its own network—an internal Harbor, or the cloud registry it uses for everything else—so this holds by default. The same applies to the execution environment registry that generated Dockerfiles pull their base image from.

Generated Python builds copy uv from ghcr.io unless you point them elsewhere. Every generated Python Dockerfile copies a fallback uv binary from ghcr.io/astral-sh/uv. The copy is unconditional—it runs even when the base image ships its own uv. Without a route to ghcr.io, generated Python builds fail while pulling that image. Two workarounds:

• Copy the uv image into the installation's registry and set workload-api.codeToWorkload.uvImage to its repository, without a tag. The build appends the uv version that the generated Dockerfile pins, so copy that tag.
• Have users supply their own Dockerfile instead of a generated one. A user-supplied Dockerfile is used verbatim and pulls nothing the user didn't ask for. See Use a provided Dockerfile.

workload-api:
  codeToWorkload:
    uvImage: registry.example.com/mirror/astral-sh/uv

Generated builds apply the installation's proxy, npm registry, and private CA. Workload API reads these optional settings from the datarobot-modeling-envvars ConfigMap, so set them under core.config_env_vars the same way as the other image builder settings. It reads them at pod start, so restart the Workload API pods after a change.

Keep these points in mind:

• On BuildKit, set both CA settings. The CA build arguments point at a secret that exists only on steps that mount it, so the arguments without the mount fail the build. On Kaniko, set only MANAGED_IMAGE_DEPENDENCIES_INJECT_CA_VARS, because Kaniko has no RUN mounts. See Image Build Service.
• Workload API reads the two CA settings from its environment only. A change made in the System Admin UI doesn't reach it.
• A proxy URL that carries credentials is stored in the generated Dockerfile and appears in the environment of dependency build code, which can print it into the build log. Don't put credentials in the proxy URL unless everyone who can run a build is allowed to see them.
• A malformed value fails the build with a message that names the setting and never its value.
• The proxy is used only for downloads during build steps. Because the platform does not have a no-proxy setting, every download in those steps goes through the proxy, and the npm registry mirror must be reachable through it. The build engine pulls the uv image directly, without the proxy. The build pod must therefore be able to reach that image's registry on its own.

A Python package mirror needs a lock file created against it. Generated Python builds run uv sync --frozen, which installs from the URLs recorded in uv.lock and ignores the index settings, including CUSTOM_MODEL_DEPENDENCIES_PYTHON_INDEX. A lock file resolved against the public index still points at the public index, so the build reaches it even when the mirror is configured. Create the lock file on a machine that resolves through the mirror: set the mirror as the project's default index in pyproject.toml ([[tool.uv.index]] with default = true) or in UV_DEFAULT_INDEX, then run uv lock. dr artifact code sync runs uv lock on the user's machine when the project has no lock file, so that machine must resolve through the mirror too. For Node builds, the npm registry setting replaces the host in registry.npmjs.org URLs only, so a lock file that records another host keeps it.

Image URI validation and built images¶

Built images are exempt from image URI validation. Validation runs on write against URIs the user supplies; the image URI produced by a build is written by the platform and skipped.

This matters because the default denylist covers the private registry host classes of every cloud (*.dkr.ecr.*.amazonaws.com, *.azurecr.io, *.pkg.dev), which is exactly where an installation's own registry lives. Builds pushing there don't require an allowlist change, and the denylist keeps doing its job against user-supplied URIs.

Verify the configuration¶

Confirm that the build settings reached Workload API pods:

kubectl exec deploy/workload-api-app -n <namespace> -- \
  env | grep -E 'WORKLOAD_API_IBS|IMAGE_BUILDER_CUSTOM_MODELS_REGISTRY'

WORKLOAD_API_IBS_IMAGE_REGISTRY and WORKLOAD_API_IBS_IMAGE_REPOSITORY are empty on a standard installation, which is expected—the push target comes from the IMAGE_BUILDER_ settings instead. Builds are disabled only when no registry resolves from either group.

To validate end to end, follow the user documentation to build a Workload from source: Tutorial: Build a Workload from source.

Troubleshoot¶

This table covers configuration failures encountered while enabling builds. For diagnosing Workload API control plane and running workloads, see Troubleshooting. For reading the output of a build that started and then failed, see Diagnose a failed build and the build error reference.