Glossary

This page is the canonical source for TauGrid terminology. Other concept and reference pages link to a definition here instead of redefining it. Where a term below conflicts with older prose elsewhere, this definition wins.

TauGrid

The CLI (and its companion Python SDK) that resolves a project’s checked-in workload contract, applies platform-owned policy, renders a Kubernetes Job or KubeRay RayJob, submits it, and gives the researcher one lifecycle surface for status, logs, results, retry, and resume. TauGrid resolves, renders, and observes workload lifecycle; Kueue and Kubernetes own scheduling and orchestration, and platform teams provision cloud infrastructure. See What is TauGrid and Architecture.

Repository / research repository

One Git worktree containing a TauGrid-enabled research project, or a monorepo catalog of several. The repository owns entrypoint code, images, runtime dependencies, and data/output contracts; TauGrid only resolves and renders against it.

Project

The unit inside a repository that owns one or more targets and exactly one workspace connection descriptor at a time. A monorepo can hold multiple projects.

Target

A checked-in, named, runnable config – for example tau/train.yaml, or a direct run config passed with tau run --config. “Target” means “which checked-in workload to run.” It is unrelated to cluster context; keep the two distinct.

Cluster context

The kubectl context TauGrid operates against, selected with --context or the TAU_CONTEXT environment variable. Cluster context answers “which cluster,” never “which checked-in workload.” See target for that meaning.

Workspace / workspace environment

Shorthand for the platform-owned destination and shared defaults a project resolves against: cluster, namespace, queue, priority, output root, and identity. This shorthand is safe when the surrounding text describes policy rather than a specific object. When precision matters, say TauWorkspace for the Kubernetes resource, or workspace connection descriptor for the client-side file a repository holds.

TauWorkspace

The Kubernetes custom resource (tau.azure.com/v1alpha1, kind TauWorkspace) that the Tau workspace controller reconciles in the tau-system namespace. It is a Kubernetes API for onboarding, policy intent, and status: its spec declares target namespace, Kueue queue, and defaults for workload identity, output root, and priority; its controller reconciles or verifies namespace/RBAC, Kueue LocalQueue accessibility, and workload-identity ServiceAccount configuration, then reports status conditions and phase. The spec has no storage field: durable storage is external platform desired state.

TauWorkspace is a Kubernetes onboarding and policy intent and status API scoped to namespace, queue, and workload-identity wiring. The platform operator and Azure/provider tooling own the AKS cluster, network, node pools, Kueue/KubeRay installation, and cloud RBAC outside TauWorkspace. See TauWorkspace reference and Identity and security boundaries.

Workspace connection descriptor

The non-secret tau/workspace.connection.yaml file a platform operator hands to a repository once its TauWorkspace is Ready. It names the Kubernetes context, access method, TauGrid system namespace, and workspace contract a project resolves against and must never contain a credential or kubeconfig. This file is client-side project configuration only: the TauWorkspace object it describes is reconciled independently by the controller and is unaffected by edits to this file. cluster.systemNamespace defaults to tau-system.

Checking in the descriptor is explicit, portable repository/platform preconfiguration. A project without one can use tau workspace connection assign [workspace] to store the same non-secret contract under the user’s Tau config directory, scoped to that exact worktree/project. Local assignments never override checked-in descriptors and never become a global default for other repositories. Use tau workspace connection inspect to see the effective source and tau workspace connection clear to remove only the local assignment.

tau run discovers either source automatically; tau workspace connection verifies and pins the configured access before the first run. On first cluster-backed use, TauGrid isolates the named context from the user’s kubeconfig or obtains AKS cluster-user credentials, verifies the live workspace contract, and records a durable configuration pin separately from short-lived readiness evidence. An unchanged pinned connection can refresh Ready, LocalQueue, and authorization checks noninteractively after the readiness cache expires. Descriptor, trust, or live workspace-contract drift requires interactive review.

workspace-rbac is the API default and what tau workspace create writes. In that mode the controller binds the researcher subject in the workspace namespace. cluster-wide is an explicit opt-out: the workspace supplies only routing and policy defaults, and the platform grants researcher access separately, which is how some existing clusters are configured. The multiple-workspace lifecycle is Alpha: v0 activates one workspace and blocks additional workspace objects until the active workspace is removed. Researcher isolation still requires its negative-access gate.

Status condition / Ready

A TauWorkspace reports Kubernetes-style status conditions and an overall status.phase of Pending, Ready, or Degraded. “Ready” currently means RBACReady and QueueReady are true and no drift is detected. WorkloadIdentityReady is diagnostic; the overall phase gate currently excludes it. TauGrid 0.1 has no StorageReady condition on TauWorkspace or TauCluster, so Ready confirms only the conditions above: a platform-managed durable PVC may still be missing or unbound, Azure infrastructure may be older than the current reconcile, and researcher-scoped isolation needs its own check; see Identity and security boundaries.

Profile / resource profile

The render-time resource contract (name, lane, and spec) a workload builder consumes to size compute – GPU, CPU, and memory intent – for a run. A profile describes shape only. It is narrower than a topology preset, which additionally decides queue, priority, and placement routing.

Topology and placement

The platform-owned mapping from a researcher-facing preset (for example azure.research.training.l) to Kueue-facing queue, priority, and topology metadata: which queue admits the workload, its priority class, and any required or preferred node topology for pod placement. TauGrid resolves topology intent; Kueue and Kubernetes still own admission and scheduling. See Queue, quota, topology, and GPU placement.

Queue / LocalQueue / ClusterQueue

Kueue objects, not TauGrid objects. A LocalQueue is the tenant-facing entry point a workload references. A ClusterQueue owns shared quota and fairness across the LocalQueues bound to it. TauGrid resolves which LocalQueue a run should target; Kueue decides admission. See Queue, quota, topology, and GPU placement.

Direct run config vs. managed workflow manifest

The normal researcher contract is a direct run config: a checked-in tau run --config YAML file (name, engine, compute, storage, and so on) that TauGrid validates and renders directly. Its conventional filename is tau.yaml.

A managed workflow manifest carries schema_version: 1 and is normally generated by the Python SDK for staged train/eval or renderer-level workflows. It may also be named tau.yaml, so the schema, not the filename, identifies the format. It is machine-generated output rather than a hand-authored default a researcher writes directly. See Configuration resolution and the run config reference.

Run

One execution of a target plus its lifecycle handle – the object tau run status, tau logs, tau run get, tau run cancel, and tau run resume operate on.

Workload (Job / RayJob)

The rendered Kubernetes object TauGrid submits: a batch/v1 Job for single-pod work, or a KubeRay RayJob for multi-node Ray execution. The workload is what Kueue admits and Kubernetes schedules: a run’s rendered execution artifact, downstream of the run’s own lifecycle handle.

Service / endpoint

An online lifecycle target rendered by tau serve as either a KubeRay RayService or a Kubernetes Deployment. A service consumes a project-owned image and optional durable checkpoint, and it keeps its own lifecycle surface via tau serve status and tau serve delete, separate from run lifecycle commands.

Experiment

A comparison set over runs, their metrics, and their artifacts, scoped by experiment.project. Two fields define that identity inside a direct run config’s experiment block:

• name – the stable experiment identifier (experiment.name).
• group – a named arm of runs within that experiment (experiment.group).

Evidence / metrics / artifacts / checkpoints

Files and records saved by a run: metric history, summaries, checkpoints, model outputs, images, tables, reports, and retry or resume state. TauGrid keeps the durable copy with the experiment. The TauGrid Portal and optional ADX/Kusto dashboards provide additional ways to view and compare it. See Experiment evidence and artifacts.