Workload manifest¶

.datarobot.yaml is the project file that dr workload config creates and dr workload up deploys from. This page describes what's in the file and how dr workload up uses it.

For the commands and their flags, see Manage Workloads with the CLI. For the quickest way to get a Workload running, see Tutorial: Deploy from a project folder.

What the file is¶

.datarobot.yaml sits at the root of your project. It contains a Workload spec in the same format that dr workload create --spec-file accepts. For a description of every field, see Create a Workload.

The CLI passes any key it doesn't recognize directly to DataRobot. You can use new Workload fields as soon as DataRobot supports them, without updating the CLI.

The CLI adds two extras to the standard spec format:

• workloadId: Links the file to a Workload. dr workload up adds it after the first deploy, and later deploys use it to find the Workload. The CLI removes it before sending the spec to DataRobot. Commit this line to your repository—without it, the next dr workload up creates a new Workload.
• dr-credential:<credentialId>/<key>: A shorthand for using a stored credential as an environment variable value. It's equivalent to the longer object form (source: dr-credential, drCredentialId, and key), which also works.

例¶

For a project with a Dockerfile, dr workload config writes a .datarobot.yaml file like this:

workloadId: 68b0c1d2e3f4a5b6c7d8e9f0 # managed by the CLI
name: my-app
importance: low # low | moderate | high | critical

artifact:
  name: my-app-artifact
  type: service
  spec:
    containerGroups:
      - name: default
        containers:
          - name: primary
            primary: true
            port: 8080 # must be 1024 or above
            imageBuildConfig: # built from this repository's Dockerfile
              dockerfile:
                source: provided

runtime:
  containerGroups:
    - replicaCount: 1
      containers:
        - name: primary
          resourceAllocation: {cpu: 0.5, memory: 512MB} 

About the example:

The runtime group has no name. The group under runtime.containerGroups carries no name key. When a runtime has only one group, DataRobot names it default automatically. Leaving the name out also means you can use this file unchanged with the Terraform and Pulumi providers, which treat the name as read-only and reject it. Files that name the group still work. If a runtime has more than one group, you must name each one.

There's no readiness probe unless you set a health path. dr workload config adds a readiness probe only when you pass --health with a path, such as --health /ready. The CLI doesn't guess a path. If it guessed wrong and your app returned 404 there, a healthy Workload would never be marked ready.

Editing the file¶

After dr workload config creates .datarobot.yaml, you can edit it. The CLI changes the file only in these cases:

• dr workload config: Doesn't change an existing .datarobot.yaml.
• dr workload up: Changes only the workloadId key.
• --sync-env (with either command): Changes only the environment variables, and shows you what it will change first.

When the CLI does edit the file, it keeps your comments, key order, and any keys it doesn't recognize.

Where the image comes from¶

Each container gets its image in one of three ways. When you run dr workload config in a terminal, it asks which one to use, and selects your own Dockerfile by default if ./Dockerfile exists.

When there's no terminal (for example, in CI), the CLI uses ./Dockerfile if it exists. If there's no Dockerfile, use flags to choose a build mode.

How deploys work for each mode:

• Your own Dockerfile, or a base image plus your code: dr workload up uploads your project files and waits for DataRobot to build the image. It does this on the first deploy and again whenever your code changes.
• A published image: dr workload up deploys the image directly. It never uploads code.

Each container uses either imageUri or imageBuildConfig, never both. To learn what your project needs for a generated Dockerfile, see Build from source code.

.datarobot.yaml also supports every other field in the Workload spec. These include GPU resource bundles, autoscaling, secrets, extra containers, probes (startup, readiness, and liveness), and the agent type. The CLI deploys these fields exactly as written, including ones that dr workload config doesn't ask about.

What the file manages¶

dr workload up compares .datarobot.yaml with the running Workload and changes only what's different. It follows three rules:

• Fields in the file are enforced: If someone changes one of these fields outside the file (for example, in the DataRobot UI), the next dr workload up reports the change as drift and restores the value from the file.
• Fields not in the file are left alone: A Workload can have a GPU bundle, a sidecar container, or an autoscaling policy that the file doesn't mention. dr workload up doesn't treat these as drift and doesn't change them.
• Deleting a field stops managing it: If you delete a line from the file, dr workload up stops enforcing that field. It doesn't reset the field to its previous or default value.

dr workload up compares the file with what's actually running, not with a saved record of the last deploy. A fresh CI checkout needs only the committed .datarobot.yaml to deploy correctly.

What up does¶

Every run prints a plan, then carries it out. --dry-run prints the plan and stops. Nothing is confirmed—the plan is for review.

A first deploy of a project the platform builds is two lines:

  + workload   my-app will be created, with its first artifact
  ~ code       all project files, uploaded for the first time 

A later one lists what differs, one line per kind of change:

my-app (68b0c1d2), running

  ~ code       3 files changed since the last deploy
  + artifact   new version, 1 spec change
      env GREETING: changed
  ~ runtime    containerGroups[default].replicaCount: 1 -> 3 

A spec change that keeps the image says so on its line (keeps the running image, so no rebuild), and on a draft artifact it is written to the draft in place. When the running version is locked, a ~ lock line says a new version is created and locked to match.

When nothing differs the plan is Already up to date.

The following table lists the three kinds of change and how each is applied.

What dr workload up does depends on the Workload's current state:

• Doesn't exist yet: Creates the Workload from the file.
• Stopped: Starts it.
• In an error state: Rolls out the update if the file has changes. If nothing has changed, the command stops and explains why, because deploying the same thing again would fail again. To rebuild an image that DataRobot built, add --force-build.
• Deploy already in progress: Waits for that deploy to finish, then continues.

How updates roll out¶

A rollout moves the Workload to a new version, or to an updated version of the current draft. The endpoint URL never changes. The current version keeps serving requests until the new one is ready.

Locking can't be undone. DataRobot never changes a locked artifact, so the next update creates a new artifact in the same repository and locks it too. A locked Workload keeps deploying this way.

For details on how DataRobot handles rollouts, see Replace artifacts and roll out.

Local state¶

up keeps machine-managed state beside the code, never in the manifest, under .datarobot/workload/:

The code sync is the one step that writes to your working tree. Before it replaces or deletes a local file it keeps a copy as <path>.LOCAL.<timestamp>, and a sync that fails partway restores the originals. dr artifact code doctor checks this state and repairs it; see Manage artifacts with the CLI.

What the CLI checks before sending¶

config validates the file before it writes it, and up validates it before every deploy. Every finding names the key and the line. The checks are as follows:

• name is present and not empty.
• Exactly one of artifact (inline definition) or artifactId (an existing artifact).
• An artifactId a bound Workload is to be swapped onto belongs to the same repository as the version the Workload runs now, and is not a locked version while the Workload runs a draft. A draft Workload that should take a locked version is promoted first with dr workload promote.
• An inline artifact has spec.containerGroups with at least one group, and each group has at least one named container.
• Each container sets either imageUri or imageBuildConfig, and imageBuildConfig.dockerfile.source is provided or generated.
• generated carries executionEnvironmentId, executionEnvironmentVersionId, and a non-empty entrypoint; provided needs ./Dockerfile beside the manifest.
• A generated build that would be made this run has a project the platform builds from (pyproject.toml with uv.lock, or package.json with package-lock.json) and an execution environment whose language agrees with those files. A pyproject.toml without uv.lock passes, since the sync generates the lock.
• The primary container has a numeric port of at least 1024; no other container sets one.
• At most one container per group is marked primary.
• Every environment variable has a value or a credential source, and a dr-credential: reference is well formed.
• runtime groups and containers match the artifact's by name.
• A group sets replicaCount or autoscaling, not both.
• resourceAllocation.memory is a byte count or a 1000-based unit (512MB, 2GB).

Everything else is checked by the server; a rejected deploy comes back as a 422 naming the field.

When a deploy fails¶

The following table lists the most common failures. up prints the platform's reason beside the errored state, and dr workload diagnose names the container and the reason.

See Best practices and troubleshooting for more information.