Getting started: Run a test container¶

This guide walks you through deploying your first container using the Workload API.

Prerequisites¶

Before you begin, ensure you have:

• DataRobot API endpoint (base URL)—your DataRobot instance URL.
• Container images hosted in a registry accessible by the DataRobot cluster.
• DataRobot API token for authentication.

Set environment variables¶

Before running any commands, set your DataRobot API credentials:

export DATAROBOT_ENDPOINT=https://app.datarobot.com/api/v2
export DATAROBOT_API_TOKEN=<your-api-token>

Ensure your container:

• Runs in unprivileged mode—containers cannot run as root.
• Exposes a port higher than 1024—privileged ports (0–1024) are not available.
• Implements health check endpoints for readiness probes.
• Exposes an HTTP server.

Step 1: Deploy the whoami container¶

Before deploying your own container, try this example using the containous/whoami image—a simple HTTP server that returns request information.

Create the workload:

curl -X POST "${DATAROBOT_ENDPOINT}/console/workloads/" \
  -H "Authorization: Bearer ${DATAROBOT_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "test-whoami",
    "artifact": {
      "name": "whoami-artifact",
      "description": "Simple HTTP server for testing",
      "spec": {
        "containerGroups": [{
          "containers": [{
            "imageUri": "containous/whoami:latest",
            "port": 8080,
            "primary": true,
            "resourceRequest": {"cpu": 1, "memory": 536870912},
            "entrypoint": ["/whoami", "--port", "8080"],
            "readinessProbe": {
              "path": "/",
              "port": 8080,
              "initialDelaySeconds": 5
            }
          }]
        }]
      }
    },
    "runtime": {"replicaCount": 1}
  }'

Step 2: Monitor workload status¶

Poll the workload status to track deployment progress. Status progression: submitted → initializing → running.

curl -s -X GET "${DATAROBOT_ENDPOINT}/console/workloads/{workloadId}" \
  -H "Authorization: Bearer ${DATAROBOT_API_TOKEN}" | jq '.status'

Step 3: Access the running service¶

Once the workload reaches running status, you can access it:

curl -X GET "${DATAROBOT_ENDPOINT}/endpoints/workloads/{workloadId}/" \
  -H "Authorization: Bearer ${DATAROBOT_API_TOKEN}"

The invoke URL is a base prefix. Append your application's path to reach specific endpoints (for example, /health or /api/...). Requests are forwarded to the container with the same path and method.

Step 4: Stop the running workload¶

When you're done experimenting, stop the running workload:

curl -X POST "${DATAROBOT_ENDPOINT}/console/workloads/{workloadId}/stop" \
  -H "Authorization: Bearer ${DATAROBOT_API_TOKEN}"