Initial commit: Arista eAPI with Python (containerlab-based lab)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: nic-arista-labs

.env.example

@@ -0,0 +1,21 @@
+# ---------------------------------------------------------------------------
+# NextGen Network Academy · Arista eAPI with Python
+#
+# 1. cp .env.example .env
+# 2. The defaults below match the included containerlab topology — no edits
+#    needed if you used `containerlab deploy -t topo/topology.clab.yml`.
+# 3. NEVER commit your .env. The .gitignore in this repo blocks it, but
+#    double-check before every push.
+# ---------------------------------------------------------------------------
+
+# Switch reachable address. Defaults to the published port from the lab topo.
+EAPI_HOST=localhost
+
+# eAPI port. The lab publishes the cEOS container's 443 to host 8443.
+# Real switches usually leave this at 443.
+EAPI_PORT=8443
+
+# Lab credentials — baked into topo/configs/eos1.cfg for convenience.
+# Replace if you point this script at a different switch.
+EAPI_USERNAME=admin
+EAPI_PASSWORD=admin

.github/workflows/lint.yml

@@ -0,0 +1,33 @@
+name: lint
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  syntax-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install pyflakes
+
+      - name: Compile every Python file
+        run: |
+          python -m compileall reference starter
+
+      - name: Lint with pyflakes (non-blocking informational pass)
+        run: |
+          pyflakes reference || true
+          # `starter/` is allowed to fail because it contains intentional
+          # NotImplementedError stubs students must complete.

.gitignore

@@ -0,0 +1,29 @@
+# Credentials — never commit
+.env
+.env.*
+!.env.example
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+.venv/
+venv/
+env/
+.Python
+*.egg-info/
+.pytest_cache/
+
+# Editor / OS
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db
+*.swp
+*~
+
+# Output captures students might generate
+*.csv
+*.log
+output/
+screenshots/

README.md

@@ -2,58 +2,82 @@
 
 > A NextGen Network Academy guide. Companion code lives here; the conceptual
 > walkthrough and learning objectives live on the
-> [foundations site](https://learn.nextgennetworkacademy.com/learn/foundations/).
+> [netops site](https://learn.nextgennetworkacademy.com/learn/netops/).
 
-This repo contains the working code, starter skeleton, and challenge brief
-for retrieving switch information from an Arista EOS device using Python and
+This repo contains a self-contained lab — a containerlab topology with a
+pre-staged Arista cEOS-lab node — plus the Python script, starter skeleton,
+and challenge brief for retrieving switch information from the device using
 eAPI.
 
+No physical switch required. `containerlab deploy` and you have a working
+environment.
+
 ## What's inside
 
 | Path | Purpose |
 |---|---|
+| `topo/topology.clab.yml` | Containerlab topology — single cEOS node, eAPI pre-enabled |
+| `topo/configs/eos1.cfg` | Startup config baked into the cEOS device |
 | `reference/eapi_show_version.py` | Complete working solution. Read after you've tried the challenge. |
 | `starter/eapi_starter.py` | Skeleton with TODO blocks. This is your starting point. |
-| `examples/sample_output.json` | Captured eAPI response — useful when you don't have lab access. |
+| `examples/sample_output.json` | Captured eAPI response — useful for offline iteration. |
 | `docs/instructor-guide.md` | Walkthrough notes for instructors using this in class. |
 | `docs/student-challenge.md` | The hands-on challenge brief and grading rubric. |
 | `docs/instructor-notes.md` | Answer key, common failure modes, time-box guidance. |
 
+## Lab prerequisites
+
+Install once on your machine:
+
+| Tool | Purpose | Install |
+|---|---|---|
+| Docker | Container runtime | [docs.docker.com/get-docker](https://docs.docker.com/get-docker/) |
+| Containerlab | Topology orchestrator | [containerlab.dev/install](https://containerlab.dev/install/) |
+| cEOS-lab image | The switch itself | Free download from [arista.com](https://www.arista.com/en/support/software-download) (account required) |
+| Python 3.9+ | The script | [python.org/downloads](https://www.python.org/downloads/) |
+
+After downloading the cEOS-lab tarball, import it once:
+
+```bash
+docker import cEOSarm-lab-4.34.4M.tar ceosarm:4.34.4M
+docker images | grep ceos       # confirm it's there
+```
+
+Linux users will need `sudo` for containerlab. macOS (Docker Desktop or
+OrbStack) and Windows-WSL2 typically don't.
+
 ## Quick start
 
 ```bash
 # 1. Clone
 git clone https://github.com/nextgen-network-academy/arista-eapi-python.git
 cd arista-eapi-python
 
-# 2. Set up a virtual environment
+# 2. Bring up the lab
+sudo containerlab deploy -t topo/topology.clab.yml
+
+# 3. Set up the Python environment
 python3 -m venv .venv
 source .venv/bin/activate          # Windows: .venv\Scripts\activate
 pip install -r requirements.txt
 
-# 3. Configure credentials
+# 4. Configure (defaults already match the lab — no edits needed)
 cp .env.example .env
-# edit .env with your switch IP, username, password
 
-# 4. Run the reference solution
+# 5. Run the reference solution
 python reference/eapi_show_version.py
 ```
 
-## Switch-side prerequisite
+You should see two GitHub-flavored markdown tables in your terminal — `show
+version` and `show interfaces status`, both pulled from the running cEOS node
+over eAPI.
 
-On the EOS switch (or vEOS / cEOS lab device), enable eAPI **once**:
+## Tear down when you're done
 
-```text
-switch# configure terminal
-switch(config)# management api http-commands
-switch(config-mgmt-api-http-cmds)# no shutdown
-switch(config-mgmt-api-http-cmds)# protocol https
-switch(config-mgmt-api-http-cmds)# end
-switch# show management api http-commands
+```bash
+sudo containerlab destroy -t topo/topology.clab.yml --cleanup
 ```
 
-You should see `Enabled: Yes` and `HTTPS server: running, set to use port 443`.
-
 ## A word on terminology
 
 You will hear engineers call eAPI a "REST API." Strictly speaking, it isn't —

docs/instructor-guide.md

@@ -3,7 +3,7 @@
 **Audience:** Networking students with basic CLI experience and beginner-level Python
 **Suggested duration:** ~90 minutes
 **Format:** Lecture + live demo + hands-on lab
-**Prerequisites:** Python 3.9+ installed; access to an EOS switch or vEOS / Arista cEOS lab
+**Prerequisites:** Python 3.9+, Docker, containerlab, and a cEOS-lab image imported as `ceosarm:<tag>`. Verify all of this on student machines *before* class — see `instructor-notes.md`.
 
 ---
 
@@ -14,7 +14,7 @@ After working through this guide, the student will be able to:
 | # | Objective | Bloom level |
 |---|-----------|-------------|
 | 1 | Define API, REST, JSON-RPC, and explain how they differ | Understand |
-| 2 | Enable and verify eAPI on an EOS switch | Apply |
+| 2 | Read a switch startup config to identify what enables eAPI, and verify the lab device is reachable | Apply |
 | 3 | Construct a JSON-RPC request payload for `runCmds` | Apply |
 | 4 | Use the `requests` library to send authenticated HTTPS calls | Apply |
 | 5 | Parse JSON responses and render them as readable tables | Analyze |
@@ -24,10 +24,10 @@ After working through this guide, the student will be able to:
 
 ## Materials needed
 
-- Lab pod with at least one EOS / vEOS / cEOS switch reachable over the network
-- Switch credentials with `privilege 15` (lab user, **not** production)
-- Student workstation with Python 3.9+ and `pip`
-- This repository, cloned locally
+- Student workstations with Docker, containerlab, Python 3.9+, and the
+  cEOS-lab image already imported. Pre-class setup is non-trivial — see
+  the pre-class checklist in `instructor-notes.md`.
+- This repository, cloned locally on each student's machine.
 
 ---
 
@@ -79,31 +79,55 @@ Highlight: HTTPS (encrypted), Basic Auth (header, not URL), JSON body.
 
 ---
 
-### Part 2 — Live demo (25 min)
+### Part 2 — Lab spin-up + live demo (25 min)
 
-Walk students through `reference/eapi_show_version.py` line by line.
+**2.1 Bring up the topology (5 min) — instructor screen-share**
 
-**2.1 Enabling eAPI on the switch (5 min) — instructor screen-share**
+The lab is a single cEOS node defined in `topo/topology.clab.yml`. Walk
+through what happens when you deploy it.
+
+```bash
+sudo containerlab deploy -t topo/topology.clab.yml
+sudo containerlab inspect -t topo/topology.clab.yml
+```
+
+Show the inspect output — students see the running container, its name
+(`clab-arista-eapi-python-eos1`), management IP, and published ports
+(8443→443, 2222→22). Reinforce that this is the same shape they'd get from
+any production cEOS device, just packaged for their laptop.
+
+**2.2 The startup config (5 min) — read configs/eos1.cfg together**
+
+Open `topo/configs/eos1.cfg` in the editor. Highlight the eAPI block:
 
 ```text
-switch(config)# management api http-commands
-switch(config-mgmt-api-http-cmds)# no shutdown
-switch(config-mgmt-api-http-cmds)# protocol https
-switch# show management api http-commands
+management api http-commands
+   no shutdown
+   protocol https
+   no protocol http
 ```
 
-**2.2 First call with `curl` before Python (5 min)**
+> **Teaching point:** This is the *exact same configuration* you'd type into
+> a physical switch's CLI to enable eAPI. Pre-staging it as text in Git is
+> the GitOps mindset in miniature — configuration is code, version-controlled,
+> reproducible, reviewable. Students will see this pattern again in the
+> NetOps and GitOps tracks.
+
+Also walk through the VLAN and interface stanzas — these are what produce
+non-trivial output when students later run `show interfaces status`.
+
+**2.3 First call with `curl` before Python (5 min)**
 
 Show that this is just HTTP — Python isn't magic.
 
 ```bash
-curl -k -u admin:lab123 \
+curl -k -u admin:admin \
   -H 'Content-Type: application/json' \
   -d '{"jsonrpc":"2.0","method":"runCmds","params":{"version":1,"cmds":["show version"],"format":"json"},"id":1}' \
-  https://10.0.0.5/command-api | python3 -m json.tool
+  https://localhost:8443/command-api | python3 -m json.tool
 ```
 
-**2.3 Same call in Python (15 min)**
+**2.4 Same call in Python (10 min)**
 
 Step through `reference/eapi_show_version.py`. Pause at:
 

docs/instructor-notes.md

@@ -5,11 +5,24 @@
 
 ## Pre-class checklist
 
-- [ ] Confirm lab switches are reachable from student workstations
-- [ ] Verify eAPI is **enabled** on each pod switch (`show management api http-commands`)
-- [ ] Pre-create a low-privilege lab user on each switch (don't hand out admin)
-- [ ] Confirm Python 3.9+ on lab images
-- [ ] Run `reference/eapi_show_version.py` yourself end-to-end the morning of class
+The biggest risk to this session is uneven setup across student laptops. Run
+the lab spin-up on each student's machine *before* class — losing 20 minutes
+to a missing cEOS image is a common failure mode.
+
+- [ ] Verify Docker is installed and running on each student machine
+      (`docker version`)
+- [ ] Verify containerlab is installed (`containerlab version`)
+- [ ] Verify the cEOS-lab image is imported (`docker images | grep ceos`).
+      If not, walk students through the download from arista.com and the
+      `docker import cEOSarm-lab-X.Y.Z.tar ceosarm:X.Y.Z` step. **This is the
+      step most likely to derail a class** — students need an arista.com
+      account, which takes a few minutes to register.
+- [ ] Confirm Python 3.9+ on lab images (`python3 --version`)
+- [ ] Run `sudo containerlab deploy -t topo/topology.clab.yml` yourself end
+      to end the morning of class, then `python reference/eapi_show_version.py`
+      to confirm the full path works.
+- [ ] Tear down with `sudo containerlab destroy -t topo/topology.clab.yml --cleanup`
+      so students start clean.
 
 ## Rubric notes
 
@@ -61,11 +74,15 @@ grading guidance:
 
 | Symptom | Likely cause | Fix |
 |---------|--------------|-----|
-| `ConnectionRefusedError` | eAPI not enabled on switch | `management api http-commands` / `no shutdown` |
-| `SSL: CERTIFICATE_VERIFY_FAILED` | Self-signed cert + `verify=True` | `verify=False` (lab) or install a trusted cert |
-| `401 Unauthorized` | Wrong username/password | Check `.env`; check switch user privilege |
+| `containerlab: command not found` | clab not installed | Reinstall per [containerlab.dev/install](https://containerlab.dev/install/) |
+| `Error: image ceos:X.Y.Z not found` | cEOS image not imported | `docker import cEOSarm-lab-X.Y.Z.tar ceosarm:X.Y.Z`, or set `CEOS_IMAGE` to a tag that *is* present |
+| `bind: address already in use` (port 8443 or 2222) | Another process holds the port | Stop the conflicting process, or edit `topo/topology.clab.yml` to publish a different host port and update `.env` to match |
+| Lab deploys but `containerlab inspect` shows status `unhealthy` | cEOS startup not yet complete | Wait 30–60 seconds; cEOS is slow to boot. If still unhealthy, `docker logs clab-arista-eapi-python-eos1` |
+| `ConnectionRefusedError` from the Python script | Lab not deployed, or wrong port in `.env` | `containerlab inspect -t topo/topology.clab.yml`; confirm `EAPI_PORT=8443` |
+| `SSL: CERTIFICATE_VERIFY_FAILED` | cEOS self-signed cert + `verify=True` | `verify=False` in lab; document why this is unacceptable in production |
+| `401 Unauthorized` | Wrong username/password in `.env` | Defaults are `admin / admin` — match the startup config |
 | `KeyError: 'result'` | eAPI returned an error block | Check for `'error'` key first; print `error.message` |
-| Empty interface list | User lacks privilege 15 | Re-create user with `privilege 15` or `role network-admin` |
+| Student on macOS reports lab "looks deployed but I can't reach it" | Trying to use container IP instead of `localhost:8443` | Use `localhost:8443` — the topology publishes ports for cross-platform reach |
 
 ## Time-box guidance
 
@@ -77,8 +94,8 @@ grading guidance:
 
 ## Natural follow-on topics
 
-These build directly on what students learn here. They sit naturally in the
-NetOps and GitOps tracks rather than Foundations:
+These build directly on what students learn here. The first few belong in
+NetOps; the deeper automation and AIOps items push into GitOps and AIOps:
 
 - Configuration changes via eAPI (privileged `runCmds`, change control)
 - Concurrency — hitting many switches in parallel with `concurrent.futures`

docs/student-challenge.md

@@ -8,6 +8,23 @@ to confirm software versions before a maintenance window. Your job: write a
 Python script that pulls switch info from one device today, so you can scale
 it to 40 next sprint.
 
+For this challenge you'll work against a single cEOS-lab device spun up by
+the included containerlab topology — the script you write here will work
+unchanged against a real switch.
+
+## Lab setup before you start
+
+```bash
+# From the repo root
+sudo containerlab deploy -t topo/topology.clab.yml
+sudo containerlab inspect -t topo/topology.clab.yml   # confirm it's running
+
+# Tear down when you're done
+sudo containerlab destroy -t topo/topology.clab.yml --cleanup
+```
+
+(macOS / Windows-WSL2: drop `sudo` if your Docker setup doesn't require it.)
+
 ## What you must build
 
 A Python script (`starter/eapi_starter.py` is your starting point) that:
@@ -81,12 +98,17 @@ Submit (as a pull request to your fork of this repo):
 
 ## Hints
 
-- The eAPI URL is `https://<switch>/command-api` — note the singular endpoint.
-- Lab switches usually have self-signed certs. You'll need
-  `verify=False` *and* `urllib3.disable_warnings(...)`. **Never** ship that to
-  production.
+- The eAPI URL is `https://<host>:<port>/command-api`. With the default lab,
+  that's `https://localhost:8443/command-api`.
+- The `.env.example` already has the right values for the included lab —
+  copy it to `.env` and you're connected.
+- cEOS uses self-signed certs. You'll need `verify=False` *and*
+  `urllib3.disable_warnings(...)`. **Never** ship that to production.
 - The `result` field in the response is a **list**, indexed in the same order
   as the `cmds` you sent.
 - `tabulate` is your friend for tables. `from tabulate import tabulate`.
+- To test your error handling without leaving the lab: temporarily set
+  `EAPI_PORT=9999` in `.env`. Your script should report a clear connection
+  error, not a Python traceback.
 
 Good luck. Ask questions early and often.