tests/e2e: provision NetBox with docker compose

Add the infrastructure side of the SONiC config-generation E2E
golden test: tests/e2e/compose.yaml, tests/e2e/deploy_netbox.sh and
tests/e2e/sonic_golden_test.sh, plus the Makefile target and
.gitignore entry that drive them.

compose.yaml defines three services (NetBox, its Postgres database
and Redis) -- no Kubernetes, so there is no kind/kubectl dependency
and no cluster bring-up latency. NetBox is configured entirely
through the environment variables its own baked-in configuration.py
already reads; nothing is templated or mounted over it.
API_TOKEN_PEPPERS is deliberately left unset so that a plain v1 API
token can be minted for the test run instead of the peppered v2
format. NETBOX_PORT is the only variable interpolated into the
compose file, because compose re-interpolates the whole file on
every subcommand (up, ps, down, ...): keeping the rest of the
configuration in the container environment avoids re-resolving values
on each invocation.

deploy_netbox.sh brings the stack up, waits for the healthchecks and
mints/prints the API token. sonic_golden_test.sh is the harness
entrypoint: it provisions NetBox via deploy_netbox.sh, then seeds it
by installing netbox-manager into a dedicated venv (so its package
pins never mutate this project's venv) and running it against the
fixtures under tests/e2e/scenario/ -- netbox-manager's own bundled
example/ data is not used. Concurrent seeding is disabled by default
(SEED_PARALLEL=1) because seeding files in the same numeric group
take KEY SHARE locks on shared parent dcim_device rows and can
deadlock; the script documents the observed error and the condition
that still causes it (200-fabric.yml cabling both leaves to a shared
spine). Finally it runs sync_sonic() via generate.py and compares the
result against tests/e2e/golden/.

make sonic-e2e wires the above together; make sonic-e2e-regen adds
--regenerate to rewrite the goldens.

--regenerate refuses to run against a reused stack (CREATED_STACK==0)
unless ALLOW_WARM_REGEN=1 is set: applying the fixtures as an UPDATE
over whatever is already in a reused database can produce goldens a
fresh stack -- the only kind CI ever uses -- would not reproduce, and
nothing would otherwise say so. sonic_golden_test.sh also now accepts
--allow-coverage-loss and forwards it to tests.e2e.compare, so an
intentional fixture removal can get a green regen without editing the
script by hand.

Assisted-by: Claude:claude-sonnet-5
Signed-off-by: Roger Luethi <luethi@osism.tech>

Author: ideaship

.gitignore

@@ -1,4 +1,5 @@
 *.egg-info
+.venv-sonic-e2e/
 *.pyc
 *.swp
 __pycache__

Makefile

@@ -0,0 +1,24 @@
+NETBOX_MANAGER_DIR ?= $(abspath ../netbox-manager)
+
+# SONiC config-generation E2E golden test (see tests/e2e/sonic_golden_test.sh).
+
+# Full cycle: start the NetBox compose stack (an existing stack is reused
+# and left in place), seed, generate, compare against tests/e2e/golden/.
+sonic-e2e:
+	NETBOX_MANAGER_DIR=$(NETBOX_MANAGER_DIR) tests/e2e/sonic_golden_test.sh
+
+# Regenerate the golden files after an intentional generator change,
+# then review and commit the diff.
+sonic-e2e-regen:
+	NETBOX_MANAGER_DIR=$(NETBOX_MANAGER_DIR) tests/e2e/sonic_golden_test.sh --regenerate
+
+# Start the NetBox stack and leave it running for debugging. Export a
+# NETBOX_TOKEN beforehand to get a known API token minted.
+sonic-e2e-up:
+	tests/e2e/deploy_netbox.sh
+
+# Stop the NetBox stack and remove its volumes.
+sonic-e2e-down:
+	docker compose -f tests/e2e/compose.yaml down --volumes --remove-orphans
+
+.PHONY: sonic-e2e sonic-e2e-regen sonic-e2e-up sonic-e2e-down

tests/e2e/compose.yaml

@@ -0,0 +1,93 @@
+---
+# NetBox fixture for the SONiC config-generation E2E golden test.
+#
+# Three services, no Kubernetes: the test only needs a NetBox REST API,
+# its PostgreSQL and its Valkey. See
+# docs/superpowers/specs/2026-07-29-sonic-e2e-compose-design.md.
+#
+# NetBox is configured through the environment variables its own baked
+# /etc/netbox/config/configuration.py reads, so no configuration file is
+# mounted. API_TOKEN_PEPPERS is deliberately NOT set: the image's
+# super_user.py only creates a token when a pepper is configured, and then
+# only a v2 one, which pynetbox / netbox.netbox cannot use. deploy_netbox.sh
+# mints a v1 token instead. ("No API token will be created" in the netbox
+# log is therefore expected, not an error.)
+#
+# The secret key and superuser password are fixed literals, not
+# interpolated variables. This stack is ephemeral, published on loopback
+# only, and thrown away after each run, so they are not credentials. Keeping
+# them out of ${...} matters because docker compose interpolates the whole
+# file on *every* subcommand -- a `${VAR:?}` here would make plain
+# `docker compose down` fail whenever the caller's shell lacked the value.
+#
+# The NetBox version is pinned because the golden files were generated
+# against it -- changing it can change generated configs. postgres and
+# valkey are pinned to a patch level; they are tags, not digests, so this
+# bounds rather than freezes them.
+
+name: sonic-e2e
+
+services:
+  postgres:
+    image: postgres:17.10-alpine
+    environment:
+      # Must match netbox's DB_NAME / DB_USER / DB_PASSWORD below. The
+      # official image mandates POSTGRES_PASSWORD and would otherwise
+      # default the database and role to "postgres".
+      POSTGRES_DB: netbox
+      POSTGRES_USER: netbox
+      POSTGRES_PASSWORD: netbox
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U netbox -d netbox"]
+      interval: 5s
+      timeout: 5s
+      retries: 24
+
+  valkey:
+    image: valkey/valkey:8.1-alpine
+    # No authentication: valkey is reachable only on the compose-private
+    # network and publishes no port, so netbox needs no REDIS_PASSWORD.
+    healthcheck:
+      test: ["CMD", "valkey-cli", "ping"]
+      interval: 5s
+      timeout: 5s
+      retries: 24
+
+  netbox:
+    image: ghcr.io/netbox-community/netbox:v4.5.10
+    depends_on:
+      postgres:
+        condition: service_healthy
+      valkey:
+        condition: service_healthy
+    environment:
+      DB_HOST: postgres
+      DB_NAME: netbox
+      DB_USER: netbox
+      DB_PASSWORD: netbox
+      # NetBox needs two logical Redis databases; one valkey serves both.
+      REDIS_HOST: valkey
+      REDIS_PORT: "6379"
+      REDIS_DATABASE: "0"
+      REDIS_CACHE_HOST: valkey
+      REDIS_CACHE_PORT: "6379"
+      REDIS_CACHE_DATABASE: "1"
+      # Django wants >= 50 characters. Not a credential -- see the header.
+      SECRET_KEY: "insecure-sonic-e2e-secret-key-not-used-outside-tests"
+      SUPERUSER_NAME: admin
+      SUPERUSER_EMAIL: admin@example.com
+      SUPERUSER_PASSWORD: "insecure-sonic-e2e-admin-password"
+      ALLOWED_HOSTS: "*"
+    ports:
+      # Published on loopback only; the seeding and generation phases talk
+      # to http://127.0.0.1:${NETBOX_PORT}. No port-forward involved.
+      - "127.0.0.1:${NETBOX_PORT:-8080}:8080"
+    healthcheck:
+      # First boot runs the full migration set, which takes minutes; the
+      # start_period covers that without the container being marked
+      # unhealthy. Subsequent boots skip migrations and come up in ~1 min.
+      test: ["CMD", "curl", "-fsS", "-o", "/dev/null", "http://localhost:8080/login/"]
+      interval: 10s
+      timeout: 5s
+      retries: 3
+      start_period: 600s

tests/e2e/deploy_netbox.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+#
+# Provision NetBox for the SONiC E2E golden test (phase 1), using docker
+# compose. See docs/superpowers/specs/2026-07-29-sonic-e2e-compose-design.md.
+#
+# This script starts the stack and mints the API token. It deliberately
+# installs NO teardown trap: sonic_golden_test.sh owns the lifecycle, and a trap here
+# would fire when this script exits -- before seeding and generation.
+#
+# Safe to run standalone for debugging (`make sonic-e2e-up`), which leaves
+# the stack running.
+#
+# The NetBox secret key and superuser password are fixed literals in
+# compose.yaml (ephemeral loopback-only fixture); only the API token and the
+# published port are parameterised here.
+#
+# Environment overrides:
+#   NETBOX_TOKEN            v1 API token to mint (default: random)
+#   NETBOX_PORT             host port for the NetBox API (default: 8080)
+#   PRINT_NETBOX_TOKEN=0    suppress echoing the token (set by sonic_golden_test.sh)
+
+set -euo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+COMPOSE_FILE="${HERE}/compose.yaml"
+
+# Only generated when unset, so sonic_golden_test.sh's value wins when it calls us.
+export NETBOX_TOKEN="${NETBOX_TOKEN:-$(openssl rand -hex 20)}"
+# Guard against two failure modes of a caller-supplied token: it is
+# interpolated into a Python string literal in the heredoc below, so a
+# quote or newline would break out of that literal; and a token that is
+# not 40 hex characters is otherwise accepted here but silently rejected
+# by NetBox much later, far from this, the actual cause.
+[[ "${NETBOX_TOKEN}" =~ ^[0-9a-f]{40}$ ]] || {
+  echo "error: NETBOX_TOKEN must be 40 hex characters" >&2
+  exit 2
+}
+export NETBOX_PORT="${NETBOX_PORT:-8080}"
+
+compose() { docker compose -f "${COMPOSE_FILE}" "$@"; }
+
+echo ">>> Starting the NetBox stack (postgres, valkey, netbox)"
+# --wait blocks until every service is healthy. First boot runs the full
+# NetBox migration set, hence the generous timeout.
+compose up --detach --wait --wait-timeout 900
+
+# Mint a deterministic v1 API token for the superuser. NetBox 4.5 introduced
+# peppered "v2" API tokens; the image's bootstrap only ever creates a v2 one,
+# and only when API_TOKEN_PEPPERS is set (compose.yaml leaves it unset, so it
+# creates none). pynetbox / netbox.netbox authenticate with
+# `Authorization: Token <key>`, i.e. a v1 token, which NetBox accepts through
+# v4.6 -- legacy v1 support is removed in v4.7, so re-check this on a bump.
+#
+# The delete-then-create makes this idempotent: re-running against a reused
+# stack replaces the old token instead of colliding with it. Keep the delete.
+#
+# The script is fed over stdin (not `shell -c`) so the token never lands on a
+# command line inside the container.
+echo ">>> Creating a deterministic v1 API token for the superuser"
+compose exec -T netbox /opt/netbox/netbox/manage.py shell --interface python <<PYEOF
+from django.contrib.auth import get_user_model
+from users.models import Token
+from users.choices import TokenVersionChoices
+user = get_user_model().objects.get(username="admin")
+Token.objects.filter(user=user).delete()
+Token.objects.create(user=user, version=TokenVersionChoices.V1, token="${NETBOX_TOKEN}")
+print("Created v1 token for", user.username)
+PYEOF
+
+echo
+echo "NetBox is deployed."
+echo
+echo "  API       : http://127.0.0.1:${NETBOX_PORT}"
+# Echo the token only for the standalone debug workflow; sonic_golden_test.sh sets
+# PRINT_NETBOX_TOKEN=0 to keep it out of CI logs that may be retained.
+if [[ "${PRINT_NETBOX_TOKEN:-1}" != "0" ]]; then
+  echo "  API token : ${NETBOX_TOKEN}"
+fi
+echo