Tutorial: Deploy from a project folder¶

This tutorial deploys an app to DataRobot from the folder its code lives in, with one command, and keeps it running from the same folder. In about ten minutes you'll describe a project with dr workload config, deploy it with dr workload up, change an environment variable and watch the change roll out without a rebuild, lock the version that is serving, and tear everything down.

Where Tutorial: Hello, Workload starts from a published image and a spec file, this tutorial starts from source. The CLI builds the image on the platform, creates the artifact and the Workload, and on every later run compares the folder with what is running and applies only the difference.

前提条件¶

• The DataRobot CLI (dr), version 0.13 or later, authenticated with dr auth login.
• A project folder with a Dockerfile at its root. The CLI gets your app's port from the EXPOSE line in its Dockerfile (for example, EXPOSE 8080). Use port 1024 or higher, because containers don't run as root and can't use ports below 1024.

The project used here is a FastAPI app that answers GET / with a greeting read from an environment variable:

hello-up/
├── app.py
├── Dockerfile
└── .env 

import os

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
def hello():
    return {"message": os.environ.get("GREETING", "hello")} 

FROM python:3.12-slim
RUN pip install --no-cache-dir fastapi uvicorn
COPY app.py .
EXPOSE 8080
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8080"] 

GREETING=hello world 

Describe the project¶

Run the setup wizard from the project folder. It reads the Dockerfile and the .env, asks only what it cannot infer, and writes .datarobot.yaml:

cd hello-up
dr workload config 

The wizard asks for a Workload name, confirms the image source and port it read from the Dockerfile, asks for the sizing (CPU, memory, and replicas), and offers to carry the variables in .env into the file. A value that looks like a secret, such as a long random token or a URL with a password in it, is stored as a credential on the platform and referenced from the file as dr-credential:<credentialId>/<key> rather than written into it. The last screen shows the file before it is written.

The result is a plain Workload spec with one extra key the CLI manages:

name: hello-up
importance: low

artifact:
  name: hello-up-artifact
  type: service
  spec:
    containerGroups:
      - name: default
        containers:
          - name: primary
            primary: true
            port: 8080
            imageBuildConfig:
              dockerfile:
                source: provided
            environmentVars:
              - name: GREETING
                value: hello world

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

Every question has a flag, so the same file can be written without a terminal:

dr workload config --yes --name hello-up 

Commit .datarobot.yaml. After the first deploy it also records the Workload's ID, and every later deploy reads it to find that Workload. For the full file reference, see the Workload manifest.

デプロイ¶

Deploy the folder. up prints a plan, then carries it out:

dr workload up 

  + workload   hello-up will be created, with its first artifact
  ~ code       all project files, uploaded for the first time
  ✓ Creating the artifact (500ms)
  ✓ Syncing code (3.1s)
  ✓ Building the image (3m12s)
  ✓ Creating workload (1.1s)
  ✓ Waiting for the workload to run (5.8s)
  ✓ Checking the endpoint (300ms)
  Endpoint check: an authenticated GET answered HTTP 200 OK.

  ✓ Workload endpoint: https://app.datarobot.com/api/v2/endpoints/workloads/68b0c1d2e3f4a5b6c7d8e9f0/

  ⚠ This workload is running a draft artifact.
    Draft workloads are stopped after 8 hours, whether or not they are in use.
    Run 'dr workload promote' to version the artifact and make it permanent.

Next:
  dr workload promote  Version the artifact to make it permanent
  dr workload logs     View the container logs
  dr workload status   Check the workload status 

The first deploy of a project with a Dockerfile takes as long as the image build does, usually a few minutes. The build logs stream live under the build step. up waits for the Workload to reach running, then sends one GET to its endpoint and reports the answer; an app that is still starting can answer 503 there, which is reported, not treated as a failure. Pass --detach to return once the deploy is requested instead.

Call the endpoint. The URL ends with a slash, so append paths without a leading one:

curl -sS "$(dr workload endpoint)" -H "Authorization: Bearer $DATAROBOT_API_TOKEN" 

{"message": "hello world"} 

No Workload ID was passed to dr workload endpoint. Every dr workload command that takes an ID reads it from .datarobot.yaml when run inside the project, and says on stderr which Workload it picked.

To see what a run would do without doing it, pass --dry-run. On a project that has never deployed, it also prints the .datarobot.yaml it would write, so dr workload up --yes --dry-run is a one-command preview of a fresh project.

Change a variable and redeploy¶

Change the greeting in .datarobot.yaml:

            environmentVars:
              - name: GREETING
                value: hello again 

Run the same command. The output lists only what has changed:

dr workload up 

  .env gives 1 declared variable a different value from the manifest, and the manifest is what deploys: GREETING.
    Apply it with 'dr workload up --sync-env'.
hello-up (68b0c1d2), running

  ~ artifact   1 spec change, written to the draft in place; keeps the running image, so no rebuild
      env GREETING: changed
  ✓ Rolling out the change (300ms)
  ✓ Waiting for the rollout (11s)
  ✓ Waiting for the new version to serve (1m2s)
  ✓ Checking the endpoint (200ms)
  Endpoint check: an authenticated GET answered HTTP 200 OK. 

The note at the top of the output is expected. You changed GREETING in .datarobot.yaml but not in .env, and as a result the two files no longer match. Deployments use the values in .datarobot.yaml, so you don't need to do anything—the note is for your information. See Keep .env and .datarobot.yaml in sync for more information.

What happened¶

• No rebuild: The container reads environment variables when it starts, so the existing image is reused.
• Versioning: If the artifact is still a draft, the change updates the draft. If the artifact is locked, the change creates a new version.
• No downtime: The current version keeps serving requests until the new one is ready. The endpoint URL stays the same.

What triggers a rebuild¶

Call the endpoint again:

curl -sS "$(dr workload endpoint)" -H "Authorization: Bearer $DATAROBOT_API_TOKEN" 

{"message": "hello again"} 

If nothing has changed, dr workload up prints Already up to date and exits with code 0. That makes it safe to run automatically on every push.

Keep .env and .datarobot.yaml in sync¶

.datarobot.yaml is the only file dr workload up deploys from. It never reads .env at deploy time.

To copy changes from .env into .datarobot.yaml, run:

dr workload up --sync-env 

It shows which variables it will add, change, or remove, asks you to confirm, and then deploys.

Neither file is uploaded with your code—the starter .drignore file excludes .env, .datarobot.yaml, and the local state directory. Editing them doesn't count as a code change, so it never triggers a rebuild.

Lock the version that is serving¶

Each deploy so far created a draft artifact version, which the platform keeps for eight hours. Once a version is right, make it permanent:

dr workload promote 

Promoted workload 68b0c1d2e3f4a5b6c7d8e9f0: artifact 68b0c1d2e3f4a5b6c7d8e9f1 is locked as version 1. 

Promotion locks the artifact in place; nothing is rebuilt or rolled, and a second promote is refused because the artifact is already locked. Locking is one-way, so the next up that changes something creates a new version rather than editing this one, and locks it to match. A Workload that has been promoted once keeps deploying as locked versions without --promote being passed again. A dry run after the promotion shows the difference:

hello-up (68b0c1d2), running

  ~ lock       the running version is locked, so a new one is created and permanently locked to match
  + artifact   new version, 1 spec change; keeps the running image, so no rebuild
      env GREETING: changed

Dry run: nothing was changed. 

To lock at the end of a deploy in one step, run dr workload up --promote. For what promotion changes on the platform, see Promote a Workload to production.

Operate the Workload¶

The day-two commands all find the Workload from the folder:

# Status as a bare value, for scripts
dr workload status

# Why a Workload is in its state, per replica and container
dr workload diagnose

# Container logs, filtered
dr workload logs --level error --since 1h --follow

# What the platform did to the Workload: rollouts, starts, stops
dr workload events

# Scale right now; the next dr workload up puts back the replicaCount from .datarobot.yaml
dr workload settings --replicas 2 --wait 

For the full list of dr workload commands and their options, see Manage Workloads with the CLI.

Run it in CI¶

In a CI pipeline, add --yes so dr workload up runs without prompts, even for a project that has never been deployed:

dr workload up --yes --output-format json 

What it does depends on whether the project has a .datarobot.yaml file:

• No .datarobot.yaml: It fills in the settings from your project files, writes .datarobot.yaml, and deploys.
• A committed .datarobot.yaml: It deploys only what changed since the last deployment.

To turn off prompts for every dr command in the pipeline, set DATAROBOT_CLI_NON_INTERACTIVE=true once instead of adding --yes to each command.

With --output-format json, the command writes one JSON document to stdout with the plan and the result. If it fails, it writes a JSON error to stderr and exits with a non-zero code.

削除¶

Delete the Workload and everything the deploy created beside it:

dr workload delete --purge 

Along with the Workload, --purge deletes:

• The draft artifact the Workload ran.
• The credentials this project created.
• The local .datarobot/workload/ folder.

The output lists each item it deletes and each item it keeps.

Locked artifacts are kept. A locked artifact can't be deleted. Because you promoted the Workload earlier in this tutorial, its artifact is locked, so --purge keeps it. It also keeps the credentials, because anything that runs that artifact might still need them.

The command also removes the workloadId line from .datarobot.yaml. The next dr workload up from this folder creates a new Workload from scratch.

Deleted workload: 68b0c1d2e3f4a5b6c7d8e9f0
Removed workloadId from .datarobot.yaml; this project no longer points at a workload.
Removed /home/me/hello-up/.datarobot/workload
Kept artifact 68b0c1d2e3f4a5b6c7d8e9f1: it is locked, and a locked artifact cannot be deleted
Kept the credentials: artifact 68b0c1d2e3f4a5b6c7d8e9f1 survived, and whatever runs it may read them 

サマリー¶

You described a project once, deployed it with one command, redeployed a configuration change without a rebuild, locked the version that was serving, and tore it all down. The folder is the source of truth: .datarobot.yaml says what runs, and dr workload up makes it true.

次のステップ¶