Quickstart

For a terminal dashboard, use astrona ui to browse active runs and history, or add --ui when starting a lab. Finishing a workspace submission or confirmed destruction returns to UI Home.

This walks through the full loop — bring a lab up, work on it, get graded, tear it down — using the examples/k8s-basics-01 lab shipped in the repo. Clone the repo first, or point --git at it directly (see Remote Config Sources).

1. Check your toolchain

astrona check

Fix anything reported as ✗ before continuing (and if something breaks later, astrona doctor checks the machine, the lab and the running lab in one go) — kind, Docker/Podman, and kubectl are required for this example.

2. Pick the lab and bring it up

(Looking for the published trainings instead? astrona labs lists them and every lab is runnable by name — sign in first with astrona login (it opens astrona.io in your browser, where you click Authorize), since catalog labs are tied to your Astrona account; see the Lab Catalog.)

astrona use examples/k8s-basics-01   # every command below now works on this lab
astrona run

astrona use remembers the lab (like kubectl's current context), so you don't repeat -c on every command; astrona use alone shows which lab, --clear forgets it. Lost track? Run astrona on its own: it shows the lab, whether it's running, the exam clock, your last result and the command to run next, followed by every command (the same list as astrona --help). astrona list marks the current lab too. Inside a lab directory that lab is used instead, and -c/--git — or the lab as an argument, astrona run ./other-lab — always win.

This:

1. Reads examples/k8s-basics-01/config.yaml.
2. Creates a kind cluster named astro-k8s-basics-01 (astrona prefixes every cluster it creates with astro-).
3. Runs the lab's bootstrap.init scripts (here, hello.sh).
4. Applies any bootstrap.manifests.

At this point the cluster is up and the trainee's actual work begins — this particular lab expects a lab-ns namespace with a hello-config ConfigMap holding specific content, which isn't created for you (that's the exercise).

Progress prints as a compact step view; each step's full output goes to a log file under ~/.astrona/logs/ (path shown at the end) and is printed inline only if a step fails. Add --verbose to stream everything live instead. Revisit any past run's log with astrona logs — astrona logs view opens the latest in your pager.

Read the task:

astrona docs question

(astrona docs lists the lab's other docs — case study, prerequisites, and the step-by-step guide with the solution.)

3. Inspect it

astrona status

One screen for where you are with the lab: cluster health, how to connect, port forwards, the exam clock (timed labs), your last submission and score, and a suggested next step:

Lab astro-k8s-basics-01 (kind)

  Cluster      Ready (1/1) · Kubernetes v1.37.0 · up 28s
  Connect      astrona shell astro-k8s-basics-01
  Last submit  1/2 points (50%) FAIL · 3m0s ago · attempt #1

Next: astrona submit to grade your work

For every lab on the machine:

astrona list

Shows every astrona-managed lab (kind clusters and qemu VMs), with runtime, status, and uptime — a kubectl get-style table. For kind labs, STATUS is live cluster health:

STATUS	Meaning
Ready (n/n)	every node is Ready
NotReady (r/n)	only r of n nodes Ready — e.g. a CNI that isn't installed yet
Unreachable	node containers are up but the API doesn't answer (3s timeout)
Degraded (r/n containers running)	some node containers stopped
Stopped	all node containers stopped

astrona list -o wide adds the Kubernetes version and port-forward status (1/1 Ready); -o json prints the same for scripts.

Once the lab is ready, your kubectl points at it:

kubectl get ns

astrona destroy switches kubectl back to the context you had before (run prints which one). Prefer to leave your current-context alone? astrona run --keep-context, then work from a lab shell — your $SHELL with kubectl pointed at the lab (type exit to leave) — or name the context:

astrona shell k8s-basics-01
kubectl --context kind-astro-k8s-basics-01 get ns

See kubeconfig isolation.

4. Submit for grading

astrona submit

Hands the running cluster to the Proctor, which runs this lab's validation.checks (does lab-ns exist? does hello-config exist?) and its validation.script (does the ConfigMap actually hold the right content?). Output is pytest-style — a PASS/FAIL line per check, then a summary — and the command's exit code reflects the verdict, so it's safe to gate a script on.

5. Tear it down

astrona destroy

Runs teardown.init scripts, then deletes the cluster (unless the config sets teardown.keepCluster: true).

The lab-author loop

If you're authoring a lab rather than taking one, astrona test runs the whole thing non-interactively against a reference solution, to prove the lab is actually solvable before you publish it:

astrona test examples/k8s-basics-01 --junit-xml=report.xml

This bootstraps, applies testing.manifests (the reference solution — here, examples/k8s-basics-01/solution/), submits to the Proctor, and always tears down afterwards, even on failure. It runs against a test--prefixed cluster name so it never collides with a lab you already have up via astrona run. See CI Integration for wiring this into a pipeline.

Next

• Authoring a Lab — build your own config.yaml from scratch.
• Runtimes — when to reach for qemu instead of the default kind backend.