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. 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 need ghcr.io. 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—and the source image isn't configurable, so ghcr.io is a hard dependency of that path. Without a route to it, generated Python builds fail while pulling that image. Two workarounds:

• Mirror ghcr.io/astral-sh/uv into the installation's registry and redirect ghcr.io there through the cluster's registry mirror or proxy.
• 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.

Internal package mirrors don't redirect generated builds. The CUSTOM_MODEL_DEPENDENCIES_PYTHON_INDEX and related mirror settings on the Image Build Service page apply to execution environment builds. A generated Dockerfile declares no package-index override, so those settings don't redirect a code-to-workload build. A user who needs an internal index configures it in the uploaded project itself, through the uv or npm configuration their project already carries.

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.