OnDrift

Esta página aún no está disponible en tu idioma.

OnDrift controls what ensure() does when it finds a workload that already exists but no longer matches the WorkloadSpec you declared in code. It is the one knob that turns ensure() from a blunt “create or overwrite” into a predictable, reviewable reconcile step.

The default is RECONCILE. If you never pass on_drift, ensure() brings the existing workload back in line with your spec.

The decision `ensure()` makes

Every call to ensure() resolves to one of three situations. Only the middle one — present and drifted — is governed by OnDrift.

Situation	What `ensure()` does	Role of `OnDrift`
Absent — no workload with this slug	Always creates it.	Ignored. A create is never “drift”.
Present + in sync — exists and matches the spec	No-op. Returns the existing reference.	Ignored. Nothing to do.
Present + drift — exists but differs from the spec	Depends on the value below.	This is what `OnDrift` decides.

The five values

RECONCILE — default

Apply the computed plan: update the live workload so it matches your spec, then return the reference. This is what you want in CI and deploy scripts.

FAIL

Raise a ValidationError describing the drift and make no change. Use when an out-of-band edit must stop the pipeline so a human can look.

DRY_RUN

Compute and return the plan of what would change — but mutate nothing. Perfect for a “plan” stage you review before a “reconcile” stage applies it.

WARN

Emit a warning about the drift, make no change, and return the existing reference. The call still succeeds.

IGNORE

Silently leave the live workload untouched and return the existing reference. No warning, no mutation, no error.

Behavior matrix

The “Absent” and “In sync” columns are identical for every value — OnDrift only changes the drift column.

`OnDrift`	Absent	Present + in sync	Present + drift
`RECONCILE` (default)	create	no-op	update to match spec
`FAIL`	create	no-op	raise `ValidationError`, no change
`DRY_RUN`	create	no-op	return the plan, no change
`WARN`	create	no-op	warn, no change
`IGNORE`	create	no-op	no change, no warning

Passing `on_drift`

Pass it alongside (Python) or inside (TypeScript) the WorkloadSpec you hand to ensure(). Omit it to get RECONCILE.

Python
TypeScript

from inferencekey import ManagementClient, WorkloadSpec, Backend, OnDrift

mgmt = ManagementClient.from_env(project="acme")  # reads INFERENCEKEY_SDK_TOKEN

spec = WorkloadSpec(
    name="support-bot",
    slug="support-bot",  # the idempotency key drift is matched on
    model="meta-llama/Llama-3.1-8B-Instruct",
    backend=Backend.VLLM,
    command="vllm serve meta-llama/Llama-3.1-8B-Instruct --max-model-len 8192",
)

# Default — RECONCILE — brings a drifted workload back in line:
ref = mgmt.ensure(spec)

# Stop the pipeline if someone changed it out of band:
ref = mgmt.ensure(spec, on_drift=OnDrift.FAIL)

# Plan stage: see what would change without touching the platform:
ref = mgmt.ensure(spec, on_drift=OnDrift.DRY_RUN)

print(ref.project_slug, ref.workload_slug)

import { ManagementClient, Backend, OnDrift } from "@inferencekey/sdk";

const mgmt = ManagementClient.fromEnv({ project: "acme" });

const spec = {
  name: "support-bot",
  slug: "support-bot", // the idempotency key drift is matched on
  model: "meta-llama/Llama-3.1-8B-Instruct",
  backend: Backend.Vllm,
  command: "vllm serve meta-llama/Llama-3.1-8B-Instruct --max-model-len 8192",
};

// Default — Reconcile — brings a drifted workload back in line:
let ref = await mgmt.ensure(spec);

// Stop the pipeline if someone changed it out of band:
ref = await mgmt.ensure({ ...spec, onDrift: OnDrift.Fail });

// Plan stage: see what would change without touching the platform:
ref = await mgmt.ensure({ ...spec, onDrift: OnDrift.DryRun });

console.log(ref.projectSlug, ref.workloadSlug);

A plan-then-apply flow

Because DRY_RUN computes the diff client-side and returns it without mutating, you can gate every reconcile behind a review.

Plan. Run ensure() with DRY_RUN in your CI “plan” job. It reports the fields that differ from the live workload and changes nothing.
Review. A human (or a required approval on the merge) reads the plan.
Apply. Re-run ensure() with the default RECONCILE in the “deploy” job to bring the workload in line with the spec.

Which value to reach for

Deploy / CI apply

Use the default RECONCILE. Code is the source of truth; let ensure() converge the platform to it on every deploy.

Detect tampering

Use FAIL. A drifted workload means something changed outside your repo — fail loudly instead of silently overwriting it.

Preview changes

Use DRY_RUN in a plan stage, then RECONCILE to apply.

Shared / manually-tuned workloads

Use WARN or IGNORE when an operator owns the live config and your spec should observe, not overwrite.