Concepts¶

The mental model¶

An organization in VTK owns one or more users and pays for usage. A user submits a job: an ordered list of tasks, where each task runs a single tool (a containerized program — ffmpeg:cmd, shaka:package_dash, storage:get, …) inside an isolated worker. Files produced by one task are visible to the next under /job/ inside the container. When the last task finishes, the job reaches a terminal state.

organization ──owns──> user ──submits──> job ──contains──> task ──runs──> tool

Glossary¶

Organization — billing and tenancy boundary. Identified by an organization_urn like urn:janus:organization:acme. Every API path is scoped to one (/o/{organization_urn}/...).

Organization API name — the short, kebab-case form of the org name (e.g. acme-api-name), visible in the VTK UI under Organizations → API Name. Used as the IAM ExternalId when VTK assumes a role in your AWS account.

User — a human identity in Castlabs SSO. Authenticates with a Castlabs API access key (see Setup). Membership in an organization grants vtk:* IAM-style permissions; the same user can belong to several organizations.

Job — one submitted unit of work. Has an id, a status, optional tags, optional notify, an optional region, an optional role_arn (for cross-account S3), and a required tasks array.

Task — one execution of one tool. Has a tool identifier (namespace:name), parameters, optional version, status, and per-task logs. Tasks within a job run in order by default; append |p to a tool name to mark a task as parallel-eligible (see Tasks → Parallel task execution).

Tool — a containerized program that VTK can run. Tool names use a namespace:name form (ffmpeg:cmd, shaka:package_dash, storage:get, drmtoday:ingest-cenc-key, utils:env, …). The full catalog is under Tools.

tool_version — every tool has versions; the version pinned for your organization is used by default. Override per task with "version": "...".

job_bundle — a named group of jobs, used for tagging, filtering, and aggregated billing. Identified by a name unique within the organization (see Jobs → Job Bundles).

region — the AWS region the worker runs in (e.g. aws:eu-west-1, aws:eu-central-1). Omit to let VTK decide based on your resource pool.

Secret — an organization-scoped variable storing a credential (DRMtoday password, AWS access keys, …). Referenced inside any string parameter as {secret-name} (see Security → Passwords).

Job lifecycle¶

The status field is an integer; the same codes apply to jobs and to tasks.

Typical flow: 0 → (5 →) 1 → 2. Terminal states are 2, 3, 4, 6. The notify field on a job fires only when a terminal state is reached (see Status).

Task I/O model¶

Each job’s worker container is bind-mounted to its own subdirectory under /job/, so files written by one task are read by the next from the same working directory. Jobs are fully isolated from each other — no file from one job is visible to another, even if the underlying storage is shared.

Tools can also pass environment variables between tasks. For example, drmtoday:ingest-cenc-key writes CENC key material into the job’s environment with a configurable env_prefix, and later tasks reference those values via {var_name}. The placeholder {job_id} is substituted by the runner and is most commonly used in S3 output paths to avoid collisions.

Encryption: where DRMtoday comes in (and where it doesn’t)¶

The packaging tools (shaka:package_dash and its CMAF/HLS siblings) can encrypt their output with any CENC key you give them — explicit key/key_id pairs, raw key materials from environment variables, anything you can construct in a previous task. Encryption itself is independent of any specific key-management system.

DRMtoday is Castlabs’ DRM key, license, and KMS service, and it’s one option for sourcing those keys. The DRM-aware tools have an optional integration: pass asset_id, environment, merchant, user, password, and drmkeys, and the tool will contact DRMtoday to fetch or generate the CENC keys before encrypting (this is what Quickstart Example B does). Skip those parameters and the tool encrypts with whatever keys you supplied yourself; DRMtoday is never involved.

If you do want keys registered with DRMtoday up front — for example to provision them under a specific asset before any packaging runs — use the dedicated drmtoday:ingest-cenc-key tool. It talks to DRMtoday and writes the resulting key material into the job environment for downstream packaging tasks to consume.

Whenever DRMtoday credentials are used in either pattern, the password must be referenced as a Secret, not inlined.