Skip to content

Deploy a Gaia worker with Helm

Deploy a yasp-eval worker on a Kubernetes cluster from the published yasp-eval-worker chart. Use this for a GPU cluster or a fleet; for a single host use the Docker deploy instead.

Run these from a machine with kubectl/helm configured for the target cluster and yasp-agent installed. Fill each <…> from your cluster.

1. Get a registry key

The chart pull and the image pull both authenticate with a registry key. Get yours and export it as REGISTRY_KEY, with your API key in YASP_API_KEY.

2. Add the chart repository

helm repo add yasp-public https://nexus.yasp.ai/repository/helm/ --username token --password "$REGISTRY_KEY"
helm repo update yasp-public

3. Create the cluster Secrets

Set your context and namespace, then create the image-pull Secret (one chart-level imagePullSecrets covers both the controller and the per-task Job pods):

export CTX=<kube-context>; export NS=<namespace>
kubectl --context="$CTX" create namespace "$NS" --dry-run=client -o yaml | kubectl --context="$CTX" apply -f -

kubectl --context="$CTX" -n "$NS" create secret docker-registry yasp-nexus-pull \
  --docker-server=docker.yasp.ai --docker-username=token --docker-password="$REGISTRY_KEY" \
  --dry-run=client -o yaml | kubectl --context="$CTX" apply -f -

Store a Gaia (eval) long-lived worker register key (~6 months) so the worker can register.

export GAIA_WORKER_KEY=$(yasp-toolkit eval key)

export GAIA_WORKER_KEY=$(curl -fsS -X POST \
  -H "Authorization: Bearer $YASP_API_KEY" -G \
  --data-urlencode "audience=eval-api" \
  --data-urlencode "scope=eval-register" \
  "https://compile.yasp.ai/api/token")

kubectl --context="$CTX" -n "$NS" create secret generic yasp-eval-register-key \
  --from-literal=token="$GAIA_WORKER_KEY" \
  --dry-run=client -o yaml | kubectl --context="$CTX" apply -f -

Alternatively, you can continue to use your API key:

kubectl --context="$CTX" -n "$NS" create secret generic yasp-eval-register-key \
  --from-literal=token="$YASP_API_KEY" \
  --dry-run=client -o yaml | kubectl --context="$CTX" apply -f -

4. Install the chart

One release number drives both the chart and the image — the yasp-toolkit registry helm-version command below prints it. The chart --version and the image tag are the same value (no v prefix). The eval chart uses a single image.repository containing the full registry path, and two router URLs:

  • router.evalApiBase — the Eval router the worker registers against (https://compile.yasp.ai/eval).
  • auth.apiHost — the platform API used for token exchange (https://compile.yasp.ai/api).

List the exact GPU product labels on the cluster's nodes — the value for job.nodeSelector.nvidia.com/gpu.product:

kubectl --context="$CTX" get nodes \
  -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.metadata.labels.nvidia\.com/gpu\.product}{"\n"}{end}'

Then install:

export VERSION=$(yasp-toolkit registry helm-version yasp-eval-worker --latest)

helm --kube-context="$CTX" upgrade --install <release> yasp-public/yasp-eval-worker \
  --version "$VERSION" \
  --namespace "$NS" \
  --set router.evalApiBase=https://compile.yasp.ai/eval \
  --set auth.apiHost=https://compile.yasp.ai/api \
  --set auth.existingSecret=yasp-eval-register-key \
  --set auth.secretKey=token \
  --set image.repository=docker.yasp.ai/yasp-eval/<nvidia|amd> \
  --set image.tag="$VERSION" \
  --set 'imagePullSecrets[0].name=yasp-nexus-pull' \
  --set 'worker.tags.host=<gpu-node>' \
  --set "worker.tags.version=$VERSION" \
  --set "worker.tags.last_update=$(date +%F)" \
  --set job.gpu.enabled=true --set job.gpu.resourceKey=nvidia.com/gpu --set job.gpu.count=1 \
  --set 'job.nodeSelector.nvidia\.com/gpu\.product=<EXACT-GPU-PRODUCT-LABEL>' \
  --set job.runtimeClassName=nvidia \
  --set-json 'job.tolerations=[{"key":"nvidia.com/gpu","operator":"Exists","effect":"NoSchedule"}]'

The chart is now stored in the release, so you can drop the repo entry: helm repo remove yasp-public.

Per-cluster knobs to validate rather than assume:

  • job.runtimeClassName — set to the cluster's NVIDIA RuntimeClass (commonly nvidia) only if nvidia is not already the nodes' default runtime.
  • controller.replicaCount — set equal to the number of nvidia.com/gpu units on the node (MIG slices or multiple cards) so each GPU gets its own worker registration.
  • GPU name auto-detects — leave worker.gpuName unset; the worker runs a yasp-eval detect Job on first registration.
  • worker.tags.routing=<name> — registers the worker in a separate routing pool for testing instead of the shared stable pool.

5. Verify

kubectl --context="$CTX" -n "$NS" rollout status deploy/<release>-yasp-eval-worker --timeout=600s
kubectl --context="$CTX" -n "$NS" logs deploy/<release>-yasp-eval-worker --tail=20 \
  | grep -iE 'API Key OK|worker_registered'
yasp-toolkit eval workers

Agent-assisted deploy and upgrades

From the yasp shell the deploy-eval-worker-helm skill automates this flow, and upgrade-helm-releases bumps existing releases to the latest version across the cluster.