Labs (0.9)

Hands-on troubleshooting practice: Shellaro deploys something broken on a cluster you choose, and you fix it in the terminal. Each task has a Check that tells you whether it is solved.

Doing a lab

Open a lab: Marketplace > Labs, the Labs section of the sidebar's Extensions tab, or Start Lab... in the command palette.
Read what it is about and what it needs, then click Start lab.
Deploy on: choose a target.
- Local cluster: if you have none, Launch local cluster creates one right there (Kubernetes in Docker on this computer, see local-cluster.md).
- Any saved session with kubectl and a working cluster. Shellaro checks that kubectl works before running anything.
- Production sessions cannot be chosen: labs break things on purpose.
What the setup runs on the target shows the exact script. Deploy lab runs it.
The lab panel opens under the terminal with the tasks. Work in the terminal. Check runs the task's check on the target; Hint 1 of 2 shows a task's hints one at a time (see Hints); tasks without a check have Mark as done.
When every task is solved, the panel shows a summary: tasks completed, the time it took, and hints used (in total and per task). Review tasks goes back to the tasks; End lab and clean up runs the cleanup.
Reset runs the cleanup and the setup again (a new attempt: progress, hints and the clock start over). End lab runs the cleanup. The lab, your progress and the hints you opened survive a restart of Shellaro.

Hints

Every task has at most two hints, and they open one at a time:

Hint 1 points where to look (which command, which part of the output).
Hint 2 is more direct, often the fix itself.

Opened hints stay visible for the rest of the attempt, also after a restart. The summary counts them ("Hints used 2 / 6"); nothing is deducted for using them.

One lab runs at a time. Everything a Kubernetes lab creates lives in its own namespace (lab-<name>), and End lab deletes it.

Labs that come with Shellaro

Lab	Level	What breaks
CrashLoopBackOff	beginner	An API exits at start: a setting from a secret is missing
ImagePullBackOff	beginner	A release points at an image tag that does not exist
Service Without Endpoints	intermediate	A service selector does not match the pods' labels
Pod Stuck in Pending	intermediate	Resource requests no node can satisfy

Making your own lab

A lab is a folder: a lab.json, a setup script that breaks something, and the tasks.

shellaro ext create pod-down --template lab --publisher acme
cd pod-down

You get:

manifest.json      type "labPack", id acme.pod-down
lab.json           requirements, namespace, setup, cleanup, tasks
scripts/setup.sh   creates the broken situation (edit this)
README.md          shown in the Marketplace

Try it while you write it: Settings > Developer > Load extension folder..., then Start Lab... in the palette. Every Start runs your current setup.sh. When it works:

shellaro ext build      # acme.pod-down-0.1.0.shellaro-ext
shellaro ext install    # or share the file, or publish --index

lab.json

{
  "schemaVersion": 1,
  "difficulty": "beginner",
  "estimatedMinutes": 10,
  "environment": { "provider": "kubernetes", "description": "Runs in the namespace lab-pod-down." },
  "requirements": ["A Kubernetes cluster: the local cluster (one click) or any server with kubectl"],
  "namespace": "lab-pod-down",
  "setup": { "script": "scripts/setup.sh" },
  "cleanup": { "commands": ["kubectl delete namespace lab-pod-down --ignore-not-found --wait=false"] },
  "tasks": [
    {
      "id": "find",
      "title": "Find what is wrong",
      "instructions": "Markdown, with `kubectl` examples.",
      "hints": ["Where to look: kubectl describe shows the pod's events.", "More direct: the image tag has a typo."]
    },
    {
      "id": "fix",
      "title": "Fix it",
      "instructions": "Make the deployment run.",
      "check": { "command": "kubectl -n lab-pod-down rollout status deploy/web --timeout=40s" }
    }
  ]
}

Field
`environment.provider`	`kubernetes` (kubectl on the target) or `ssh` (any Linux server). `docker` (a lab with its own image) is planned.
`requirements`	Shown before starting.
`namespace`	Kubernetes labs: where everything goes. Exported to scripts as `LAB_NAMESPACE`. Shellaro waits for a previous copy of it to finish terminating before setup.
`setup`, `cleanup`	`{ "script": "scripts/x.sh" }` (a file in the package, at most 10 KB) or `{ "commands": ["...", "..."] }` (run in order with `set -e`). Without a cleanup, a Kubernetes lab's namespace is deleted.
`tasks[].hints`	At most two. The first points where to look, the second is more direct (often the fix). `shellaro ext validate` rejects a task with more.
`tasks[].check`	`command` (or `script`), optional `expectExitCode` (default 0) and `expectOutput` (text the output must contain). A task without a check is marked done by the learner.

Writing the setup

It runs with bash (or sh) on the target, as the session's user, through Shellaro's SSH connection; the learner sees it before it runs.
Make it repeatable: Reset runs the cleanup and then the setup again. kubectl apply and kubectl create ... --dry-run=client -o yaml | kubectl apply -f - are good for that.
Keep it fast and quiet; print one line at the end ("Lab ready ..."). If it fails, Shellaro runs the cleanup and shows the last lines of output.
Checks should fail clearly before the fix and pass soon after it: use --timeout of 20 to 60 seconds on kubectl rollout status or kubectl wait.