Skip to content
For Self-Managed AI Platform users running v11.1, see the on-premise platform documentation
Workload API > Manage Workloads with Pulumi

Manage Workloads with Pulumi

Preview

The Workload API is a preview feature, on by default.

Feature flag: Enable Access to Workload API Experimental Features

The DataRobot Pulumi provider exposes Workload artifacts and Workloads as native resources. Declare the artifact and the Workload in code, run pulumi up, and Pulumi reconciles the platform to your declared state.

For the full resource surface (every argument, every output), see the Pulumi registry reference. This page covers the framing: when to reach for Pulumi, how the resources map to the Workload API concepts, and what's still imperative.

When to use Pulumi

Use Pulumi when you have a built, locked artifact you trust and you want to roll it out as production infrastructure: across regions, across stages, with replica counts and importance under code review. The REST API drives verbs (build, promote, stop); Pulumi reconciles state.

Pulumi-managed artifacts always lock

Every datarobot.Artifact resource resolves to a locked artifact by the end of pulumi up. The provider creates the artifact directly as locked in a single call (passing status: locked on POST /artifacts), so a freshly applied artifact is already locked when the apply completes. To keep an artifact in draft, create it through the REST API or the Console, and only bring it under Pulumi management once it's locked.

Workflow Recommended tool
Trigger a build, promote a draft REST API
Stamp a locked artifact across stages Pulumi
Reconcile a production fleet to a new artifact version Pulumi
Manage sharing (/sharedRoles) REST or Console
What's still imperative

Even when using Pulumi, several operations remain verbs rather than state and aren't modeled by the provider:

Operation Where it lives
Image build (POST /artifacts/{id}/builds) REST or the Console
Promote draft to production (POST /workloads/{id}/promote) REST or the Console
Sharing (PATCH /workloads/{id}/sharedRoles) REST or the Console
Observability (events, stats, OTel) Read-only; managed by the platform

The pattern: run the verbs from your shell or CI, then let Pulumi reconcile the production fleet against the resulting locked artifact.

Pulumi setup

To begin using Pulumi, first, install the DataRobot Pulumi provider:

pip install "pulumi-datarobot>=0.10.38"

npm install "@pulumi/datarobot@>=0.10.38"

The provider reads its DataRobot auth from Pulumi stack config: datarobot:endpoint and datarobot:apikey. Set them once per stack:

pulumi config set datarobot:endpoint https://app.datarobot.com/api/v2
pulumi config set datarobot:apikey <your-api-token> --secret

See the Pulumi registry installation guide for the full list of supported configuration paths.

Manage credentials with ApiTokenCredential

The provider's ApiTokenCredential resource creates a managed DataRobot credential record from Pulumi state, which keeps credential lifecycle declarative alongside the artifact and Workload it serves:

import pulumi
import pulumi_datarobot as datarobot

# Container-side token. Held as a Pulumi secret so it never lands in source.
container_token = pulumi.Config().require_secret("datarobotToken")

credential = datarobot.ApiTokenCredential(
    "agent-service-token",
    name="agent-service-token",
    description="API token used by the agent-service workload",
    api_token=container_token,
)

The provider's own auth (datarobot:endpoint and datarobot:apikey above) is independent of ApiTokenCredential. The credential resource produces a managed record on the platform; how a Workload consumes that credential (for example, via environment variables in the artifact spec) is configured on the Workload itself. For the current shape of credential-related arguments on Workload, consult the Pulumi registry reference.

Quick example

The following example shows the shortest path to a Workload with Pulumi—a draft Workload backed by an inline draft artifact:

import pulumi
import pulumi_datarobot as datarobot

artifact = datarobot.Artifact(
    "whoami-artifact",
    name="whoami-artifact",
    type="service",
    spec={
        "container_groups": [{
            "name": "default",
            "containers": [{
                "name": "whoami",
                "image_uri": "containous/whoami:latest",
                "port": 8080,
                "primary": True,
                "entrypoint": ["/whoami", "--port", "8080"],
                "readiness_probe": {"path": "/", "port": 8080, "initial_delay_seconds": 5},
            }]
        }]
    },
)

workload = datarobot.Workload(
    "hello-whoami",
    name="hello-whoami",
    artifact_id=artifact.artifact_id,
    runtime={
        "container_groups": [{
            "name": "default",
            "replica_count": 1,
            "containers": [{
                "name": "whoami",
                "resource_allocation": {"cpu": 1, "memory": "512MB"},
            }],
        }]
    },
)

pulumi.export("endpoint", workload.endpoint)

Production example

Production-grade Workloads typically need a managed credential, an explicit importance, parameterization across stacks, and a clear policy for what happens when the artifact changes:

"""Pulumi program that stands up a service workload."""
import pulumi
import pulumi_datarobot as datarobot

# Container-side credentials. Held as a Pulumi secret so they never land in source.
# Provider auth (datarobot:endpoint, datarobot:apikey) is read directly from stack config.
datarobot_token = pulumi.Config().require_secret("datarobotToken")
datarobot_endpoint = pulumi.Config("datarobot").require("endpoint")

credential = datarobot.ApiTokenCredential(
    "agent-service-token",
    name="agent-service-token",
    description="API token used by the agent-service workload",
    api_token=datarobot_token,
)

artifact = datarobot.Artifact(
    "agent-service-artifact",
    name="agent-service-artifact",
    description="Agent service container artifact",
    type="service",
    spec={
        "container_groups": [{
            "containers": [{
                "name": "main",
                "image_uri": "ghcr.io/example/agent-service:0e90773",
                "port": 8000,
                "primary": True,
                "environment_vars": [
                    {"name": "DATAROBOT_ENDPOINT", "value": datarobot_endpoint},
                    {"name": "DATAROBOT_API_TOKEN", "value": datarobot_token},
                ],
            }],
        }],
    },
)

workload = datarobot.Workload(
    "agent-service",
    name="agent-service",
    description="Agent service workload",
    importance="low",
    artifact_id=artifact.artifact_id,
    runtime={
        "container_groups": [{
            "replica_count": 1,
            "containers": [{
                "name": "main",
                "resource_allocation": {
                    "cpu": 2.0,
                    "memory": 5096 * 1024 * 1024,
                },
            }],
        }],
    },
    opts=pulumi.ResourceOptions(replace_on_changes=["artifact_id"]),
)

pulumi.export("credentialId", credential.id)
pulumi.export("artifactId", artifact.artifact_id)
pulumi.export("workloadId", workload.id)
pulumi.export("endpoint", workload.endpoint)

The following patterns are worth highlighting:

  • pulumi.Config().require_secret(...) keeps the container-side token out of source and out of Pulumi state in plaintext.
  • pulumi.Config("datarobot").require("endpoint") reads the provider's stack-config endpoint so the same value flows into the container via environment_vars.
  • replace_on_changes=["artifact_id"] ensures that pointing the Workload at a new artifact triggers a full replace, surfacing the artifact swap in the Pulumi diff instead of an in-place update.
  • memory as bytes (5096 * 1024 * 1024) matches the provider's resource-allocation schema.

From here you can deploy the same Workload across stages by parameterizing name, replica_count, and importance per Pulumi stack (dev, stage, prod); add canaries by declaring multiple Workload resources backed by the same locked artifact_id; and integrate Pulumi into CI so every promote is followed by a pulumi up that reconciles your declared production fleet to the new artifact version.

This process maps to the following REST flow:

REST step Pulumi
Create the Workload with an inline artifact (POST /workloads) datarobot.Artifact + datarobot.Workload
Manage an API token credential (Console or REST) datarobot.ApiTokenCredential
Wait for running pulumi up blocks until ready.
Invoke pulumi stack output endpoint
Raise importance (PATCH /workloads/{id}) Declarative importance="critical".
Replace the artifact behind the Workload Change artifact_id; replace_on_changes triggers a managed replace.
Share via /sharedRoles Manage via REST or Console.
Read events / stats Unchanged; observability is read-side.

Reference

For more information, see the Pulumi provider registry and reference: