Hand off a workspace

Complete this checklist after the TauWorkspace readiness gate reports Ready. A handoff is reproducible only when every step below succeeds from a clean checkout, not from a platform owner’s already-primed shell.

The non-secret connection descriptor

The only artifact a researcher needs is tau/workspace.connection.yaml, a non-secret workspace connection descriptor:

It must never contain a credential, kubeconfig, client secret, or cloud access token. With access.method: kubeconfig, tau loads the normal kubeconfig rules (including KUBECONFIG) and copies only the named context, cluster, and user into an isolated mode-0600 kubeconfig outside the repository. With access.method: aks, it obtains normal AKS cluster-user credentials through the caller’s Azure identity and isolates those instead.

A provider-neutral descriptor uses an existing Kubernetes context:

schema: tau.workspace.connection.v1
workspace: research
cluster:
  contextName: research-cluster
  systemNamespace: tau-system
access:
  method: kubeconfig
authorization:
  mode: workspace-rbac
  requiredRole: tau-researcher-v1
requirements:
  minTauVersion: 0.3.0
network:
  privateCluster: false

An AKS platform can replace only the access block:

access:
  method: aks
  aks:
    resourceID: /subscriptions/<subscription>/resourceGroups/<group>/providers/Microsoft.ContainerService/managedClusters/<cluster>
    tenantID: <tenant-uuid>

Repository placement

Commit tau/workspace.connection.yaml at the repository root, alongside the target configs it governs (for example tau/smoke.yaml, tau/train.yaml). Two ways to produce it:

• Author it directly from the table above.
• Generate a provider-neutral descriptor with tau workspace init-repo <name> --workspace <workspace> --kube-context <context> --image <build-tag>.
• For automatic AKS access, add --azure-subscription-id <id> --azure-tenant-id <id> --aks-resource-group <group> --aks-cluster <cluster>. --kube-context then defaults to the AKS cluster name.

The generated targets are ready only after the project image is built and pushed, its immutable tag or digest is written back, and config validation succeeds:

./scripts/configure.sh --image "<registry>/<repository>:<immutable-tag>"
tau run validate --config tau/train.yaml

Verify the repository connection

tau workspace connection

This resolves credentials, contacts Kubernetes, and verifies the descriptor’s workspace, LocalQueue, and authorization contract without submitting a workload. Use tau workspace connection --offline when only local descriptor validation is appropriate. Before handoff, platform operators can also inspect the named workspace directly:

tau workspace check <workspace> --context <context>

First project run

From the same clean checkout, in order:

tau run validate --config tau/train.yaml
tau run train --dry-run=client
tau run train

The first command validates the config entirely offline. In a connected repository, the client dry-run activates the descriptor, resolves credentials through its configured access method, verifies and pins the workspace contract, and reads the live workload-profile catalog without submitting the rendered workload. The final command submits the project target and exercises its declared image and resources. Validate the workspace PVC mount and external cloud identity or data service with separate readiness checks.

What “handed off” means

A handoff is done only when all of the following hold, reproduced from a clean checkout:

• tau workspace check <workspace> exits 0.
• A checked-in project target completes.

Only then send the researcher the repository URL and, if network.privateCluster is true, the connection instructions. See Hand off to researchers for the matching completion checklist.