workshops

KO | EN

gitlite — search

#terminal #awesome-list #css #ruby #llm #windows #agents #csharp #database #agent

(★ 9)

Hands-on Modern Network Observability workshops

File Explorer

ZIP Download

- - docs.yml
  - validate.yml
- - architecture.svg
  - book-cover.jpg
- - autocon5.css
- - advanced.md
  - guides.md
  - index.md
  - part-1.md
  - part-2.md
  - part-3.md
  - tour.md
- index.md
- install.md
- quickstart.md
- - book-cover.jpg
- - packt.css
- index.md
- part-1.md
- part-2.md
- part-3.md
- prework.md
- take-home.md
- .gitkeep
- README.md
- - pyproject.toml
  - README.md
- __init__.py
- test_compose_env.py
- test_env_loader.py
- test_flap_cascade.py
- test_main_detect.py
- test_registry.py
- test_reset_infrahub_ensure.py
- test_up_collision_guard.py
- test_workshops_model.py
- - .env.example
  - docker-compose.yml
  - lab_vars.yml
  - pyproject.toml
  - README.md
- - .env.example
  - docker-compose.yml
  - lab_vars.yml
  - pyproject.toml
  - README.md
.env.example
.gitignore
.python-version
LICENSE
mkdocs.packt.yml
mkdocs.yml
pyproject.toml
README.md
uv.lock

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

Self-contained, laptop-friendly workshops for **Modern Network Observability** —
the book and the talks.
Each workshop spins up a complete observability stack
(Prometheus, Loki, Grafana, Alertmanager, Telegraf, Infrahub, Prefect) plus a
synthetic telemetry generator ([sonda](https://github.com/davidban77/sonda)) that
stands in for a small network.
No real or containerized network devices required.

> 📖 **Browse it as a website:** <https://network-observability.github.io/workshops/> — the same content rendered as a searchable, mobile-friendly docs site (handy on a phone during the workshop).

## Why this repo exists

The companion repo [`network-observability-lab`][lab] grew out of the book's
chapter exercises.
It is excellent if you want depth — every chapter, every variant, every collector — but the surface area is large and the setup assumes you can run cEOS / SR Linux containers locally.

This repo is the opposite trade-off: **one CLI, one `docker compose` per workshop,
one observability stack**, and `sonda` doing the network-shaped telemetry instead of real devices.

[lab]: https://github.com/network-observability/network-observability-lab

## Repo layout

```text
pyproject.toml           # uv workspace root (members = packages/*, workshops/*)
.python-version          # Python version pin (uv reads this)
packages/
  nobs/                  # the single CLI for every workshop
                         #   nobs setup / preflight / workshops
                         #   nobs <workshop> up / down / status / alerts / ...
notes/                   # local-only scratchpad — gitignored, see notes/README.md
workshops/
  autocon5/              # AutoCon5 — 4-hour in-person workshop
    README.md            # attendee-facing instructions
    pyproject.toml       # workshop's Python deps (uv workspace member)
    docker-compose.yml
    .env.example
    lab_vars.yml         # source-of-truth data fed into Infrahub
    src/autocon5_workshop/  # workshop-specific commands, registered with nobs
    sonda/               # synthetic telemetry scenarios
    prometheus/          # config + alert/recording rules
    loki/                # config + alert/recording rules
    alertmanager/        # routing config
    grafana/             # provisioning + dashboards
    telegraf/            # scrape config for sonda-server
    vector/              # syslog -> Loki shipper (srl2 log leg)
    infrahub/            # schema YAML
    webhook/             # FastAPI receiver for Alertmanager
    automation/          # Prefect flows (alert -> evidence -> decision -> action -> RCA)
  packt/                 # Packt — 3-hour online workshop
    README.md            # attendee-facing instructions
    guides/              # trimmed to three hours, plus take-home.md
    src/packt_workshop/  # same command surface, registered as `nobs packt`
    …                    # same stack layout as autocon5/ above
```

The two workshops share container names and host ports, so only one can run at a
time. `nobs <workshop> up` refuses to start if the other one's containers are
still around — `nobs <other> down` first (or `destroy` to drop its volumes too).

**One CLI: `nobs`.**
Workshops are subcommand groups (`nobs autocon5 ...`).
Each workshop ships a small Python plugin under `workshops/<name>/src/<name>_workshop/` that registers itself with `nobs` at import time and contributes its workshop-specific commands.
The bare root surface keeps three workshop-agnostic commands — `nobs setup`, `nobs preflight`, `nobs workshops` — and stops there. Workshop ops (`status`, `alerts`, `maintenance`, `schema load`, plus the docker-compose lifecycle) live on the workshop's subgroup. From inside a workshop directory you can drop the prefix entirely: `cd workshops/autocon5 && nobs alerts` is the same as `nobs autocon5 alerts`.

```bash
nobs setup                                          # uv sync + bootstrap + preflight
nobs preflight                                      # generic env check
nobs autocon5 up                                    # bring up the AutoCon5 stack
nobs autocon5 down
nobs autocon5 flap-interface --device srl1 --interface ethernet-1/1
```

## Prerequisites

- A laptop with **Docker** (or Docker Desktop / Colima / Rancher Desktop) and
  **Docker Compose v2** — `docker compose version` should report v2+.
- **[uv](https://docs.astral.sh/uv/)** for the Python tooling
  (`curl -LsSf https://astral.sh/uv/install.sh | sh`).
  uv handles Python installation too, so you don't need a system Python.
- **Git** to clone the repo and a few GB of free disk for container images.
- Approximately **8 GB of free RAM** while the stack is running.
- Outbound HTTPS to `github.com`, `ghcr.io`, `docker.io`, `registry.opsmill.io`
  (Infrahub) and `grafana.com` (a Grafana plugin baked in at build time) for image
  pulls, plus `deb.debian.org` and `pypi.org` for the locally-built images.

If Docker or uv aren't already installed, the next section walks through each.

## Installing Docker and uv

The workshop assumes you can run `docker compose` and `uv` from a terminal. New to either? Pick the path for your platform:

### Docker

- **macOS** — install [Docker Desktop](https://www.docker.com/products/docker-desktop/) (the easy default), [Colima](https://github.com/abiosoft/colima), or [Rancher Desktop](https://rancherdesktop.io/). For Docker Desktop, run the installer and open the Docker app once so the daemon starts. The official setup guide: <https://docs.docker.com/desktop/setup/install/mac-install/>.
- **Linux** — follow the [Docker Engine install guide](https://docs.docker.com/engine/install/) for your distro (Ubuntu, Debian, Fedora, RHEL, etc.). Add your user to the `docker` group afterwards so commands don't need `sudo`:
  ```bash
  sudo usermod -aG docker $USER
  newgrp docker
  ```
- **Windows** — install [Docker Desktop with the WSL 2 backend](https://docs.docker.com/desktop/setup/install/windows-install/) and run every workshop command inside a WSL 2 shell, not from PowerShell. (Note: the workshop hasn't been tested on Windows; macOS or Linux is the recommended path.)

Verify the install:

```bash
docker compose version
# Docker Compose version v2.x.x
docker ps
# (an empty table is a healthy result — daemon's up, no containers yet)
```

If `docker compose version` reports v2+, you're set. If you only see `docker-compose` (with a hyphen) reporting v1.x, install Compose v2 alongside it — the workshop expects v2.

### uv

One install command works on macOS, Linux, and WSL:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
uv --version
```

uv installs its own pinned Python from `.python-version`, so you don't need a system Python.

### One last sanity check

Once both are installed, clone this repo and run the preflight from anywhere inside it:

```bash
uv run nobs preflight
```

It checks Docker, Compose v2, RAM, free disk, and outbound reachability to the image registries the workshop pulls from. Run it the night before the workshop to catch issues with time to fix them.

## Quickstart

The very first time, in this order:

```bash
git clone https://github.com/network-observability/workshops.git
cd workshops

uv sync --all-packages          # install workspace deps into .venv/
source .venv/bin/activate       # put nobs on PATH for the rest of the session
nobs setup                      # bootstrap .env + preflight
nobs autocon5 up                # first run pulls images, ~5–10 min
nobs autocon5 status            # repeat until every row says 'ok'
nobs autocon5 load-infrahub
# ... when you're done ...
nobs autocon5 down              # stop everything but keep volumes
nobs autocon5 destroy           # full reset (drops volumes too)
```

Activating `.venv/` is what lets you drop the `uv run` prefix — `nobs` lives in `.venv/bin/` once `uv sync` finishes. If you'd rather skip the activation step, prefix every command with `uv run` (`uv run nobs setup`, `uv run nobs autocon5 up`, ...) and the rest of this guide reads the same.

From inside a workshop directory the workshop name is optional too: `cd workshops/autocon5 && nobs up` is the same as `nobs autocon5 up`.

Each workshop's own README walks through the agenda and the hands-on parts.

## Available workshops

| Workshop | Format | Outline |
|----------|--------|---------|
| [`autocon5`](workshops/autocon5/README.md) | 4 h · in-person | Telemetry & queries → dashboards → alerts, automation, AI-assisted ops |
| [`packt`](workshops/packt/README.md) | 3 h · online | Telemetry & queries → dashboards (guided demo) → alerts, automation, AI-assisted ops |

## License

[MIT](LICENSE).

workshops

Owner Repos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

workshops

Owner Repos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README