Astrona run

astrona run¶

Start a lab: create its cluster(s) or VM(s) and set it up

Synopsis¶

Spin up a lab environment: create the kind cluster or qemu VM(s), run bootstrap init scripts, and apply bootstrap manifests.

Before creating Kind clusters, check the engine, resources and host ports. Memory estimates include running Kind clusters created outside Astrona. Estimates warn; definite environment failures block startup. On startup failure, collect diagnostics under ~/.astrona/diagnostics. Failed Kind creation exports retained node logs before cleaning up that new cluster; later failures leave the lab available for diagnosis. CoreDNS readiness defaults to 3m; runtime.kind.dnsTimeout can override it.

Once a kind lab is ready, kubectl points at it: its context (kind-) becomes the current-context of your kubeconfig ($KUBECONFIG is respected), and astrona destroy switches back to the context you had before — unless you've switched elsewhere meanwhile. --keep-context leaves your current-context alone. qemu labs are reached with astrona ssh.

For a kind lab with runtime.portForwards, the forwards are started last (bound to 127.0.0.1) and their URLs and status are printed when the lab is ready — see astrona port-forward.

A lab from the catalog (astrona run astrona.io/ATS014/section-010/module-01/lab-02, see astrona labs) offers login when you are not signed in: progress and results will not be tracked on Astrona as a guest. Choose Log in or Continue as guest; Never ask again saves login-reminder=no. Use --without-login to confirm in automation. If you sign in with astrona login, before anything is built astrona starts a lab session on Astrona; once the lab is ready it prints the lab page URL. Your matching course page connects to it without a redirect, and setup time never counts. Labs from your own files or repositories (-c / --git) run without signing in.

If the lab is already running, run asks whether to destroy it and start over (or keep it as it is); --yes starts over without asking and is required when not in a terminal. If other labs are running, it also offers to destroy them first — only when asked in a terminal; --yes never touches other labs.

--ui shows one startup notice with Yes/No choices, then opens a lab's terminal workspace once it is ready. Downloads, setup, errors and interactive shells stay inside the UI's terminal pane. Yes accepts the displayed terms and settings and permits the lab's downloads and code for this invocation. No cancels startup. If the lab already exists, the UI asks before destroying it and starting over with all work discarded. That replacement stays local: no account session, progress or results are sent to Astrona. Use astrona ui to reopen without restarting. Interactive runs without --ui offer the UI before downloads; Enter chooses Yes. Use --ui=false to keep the command-line flow. --yes, CI and redirected input/output skip the offer. The UI will become the default in v0.5.0.

--headless keeps Kind and QEMU setup headless, including in v0.5.0 and later. It skips the UI, login reminder and new account sessions, then returns after setup with the lab still running for external validation. Missing approvals fail instead of prompting, even in a terminal. Terms, settings review, remote-code trust and --yes for replacing an existing run still apply. This uses the normal lab name and setup; it does not grade or clean up automatically. Use astrona destroy when finished, or astrona test for the full setup, reference solution, grading and cleanup pipeline.

astrona run [lab] [flags]

Examples¶

  astrona run astrona.io/ATS014/section-010/module-01/lab-02   # catalog lab: no login needed
  astrona run ./labs/my-lab
  astrona run ./labs/my-lab --ui                      # terminal workspace
  astrona run ./labs/my-lab --headless --accept-terms # setup for external checks
  astrona run --git https://github.com/org/labs -c labs/net-01
  astrona run renew                                  # a running playground: its full time limit again

Options¶

  -h, --help            help for run
      --keep-context    Leave your kubectl current-context alone (kind labs) — reach the lab with astrona shell or kubectl --context instead
      --parallel int    Create up to N linked clusters (runtime.kind.clusters) at once, 1-5 (default 1: one at a time). dependsOn is still respected, and after a failure nothing new starts (default 1)
      --ui              Open the terminal workspace (Kind or QEMU labs); confirm a local-only restart if the lab already exists
      --without-login   Confirm running a catalog lab without signing in or tracking progress on Astrona
  -y, --yes             If the lab is already running, destroy it and start over without asking

Options inherited from parent commands¶

      --accept-terms      Accept this CLI's usage terms and data-loss risk notice; required on each operational CI command (read: astrona terms)
  -c, --config string     Path or URL to the lab config directory (with --git: a subdirectory within the cloned repo) (default ".")
  -f, --file string       Configuration file name override (default "config.yaml")
      --git string        Git repository URL to clone/pull (https://, git@host:, or ssh://) — --config then selects a subdirectory within it
      --git-ref string    Git branch, tag, or commit to check out (used with --git; default: the repo's default branch)
      --headless          Disable the terminal UI and CLI prompts; run/reset skip login reminders and new account sessions
      --install-version   If the lab needs another astrona release (astronaVersion) that isn't installed, install it without asking — for CI
      --trust             Approve running a remote (--git / URL) lab without asking — for CI; review the lab first
      --update-check      Check for new CLI releases (disabled in CI, without a terminal, or by ASTRONA_NO_UPDATE_CHECK) (default true)
      --verbose           Stream the full output of every underlying command instead of the compact step view