Rapport clair de migration — analyse validée sur les tags Git

NetBox 3.7.8 → 4.0.11

Ce site synthétise les différences réelles entre les deux versions : changements de code, dépendances, architecture, API REST/GraphQL, interface, plugins et risques de migration.

Voir la checklist migration Sources analysées

Résumé exécutif

Ce n’est pas une simple mise à jour mineure : c’est une vraie migration majeure.

Risque principal

Python 3.8/3.9 ne sont plus supportés, GraphQL change de moteur, l’API REST retire/renomme plusieurs champs et l’ancien système de reports disparaît.

Gain principal

UI modernisée avec Tabler/Bootstrap 5.3, champs dynamiques REST API, GraphQL plus performant et vues admin migrées vers l’interface principale.

À tester avant prod

Plugins, scripts/reports, intégrations REST/GraphQL, permissions, filtres Location, custom fields et authentification distante.

Analyse du code

Volume et zones touchées

Comparaison directe entre les tags v3.7.8 et v4.0.11.

Fichiers changés1 228
Insertions376 271
Suppressions237 655
Migrations DB194

Statuts Git

Répertoires NetBox les plus impactés

Lecture du diff

  • Templates + assets très touchés : refonte UI complète.
  • extras fortement modifié : scripts, custom fields, object types, event rules.
  • dcim/ipam/vpn : modèles, filtres, serializers, migrations et tests changés.
  • API serializers réorganisés : 62 fichiers sous api/serializers_/.
  • GraphQL : 10 nouveaux fichiers graphql/filters.py.

Dépendances clés

Django
4.2.11 → 5.0.9
DRF
3.14.0 → 3.15.2
GraphQL
Graphene-Django 3.0.0 → Strawberry GraphQL 0.239.2 + strawberry-django 0.47.1
UI
Bootstrap ~5.0.2 + slim-select → Bootstrap 5.3.3 + Tabler + Tom Select
HTMX
1.8.0 → 1.9.12

Breaking changes

Points bloquants à vérifier avant upgrade

Élevé

Python 3.8/3.9 supprimés

NetBox 4.0 retire le support Python 3.8 et 3.9. Prévoir Python 3.10+ et idéalement valider 3.11/3.12 selon votre OS.

Élevé

GraphQL : Graphene → Strawberry

Le format des filtres GraphQL change. Les requêtes existantes doivent être testées et parfois réécrites.

Moyen

Reports supprimés

La fonctionnalité legacy reports disparaît. Les reports sont convertis automatiquement en custom scripts lors de l’upgrade.

Moyen

CustomField object_type renommé

object_type devient related_object_type. Les intégrations et exports qui consomment ce champ doivent être adaptés.

Moyen

Location parent filters

parent/parent_id ne retournent plus que les enfants directs. Utiliser ancestor/ancestor_id pour tous les descendants.

Faible

Configuration nettoyée

ENABLE_LOCALIZATION et les formats date/heure custom sont supprimés ; les dates/heures passent en ISO 8601.

API & données

REST API, GraphQL, modèles et migrations

REST API

  • /api/extras/content-types/ devient /api/extras/object-types/.
  • /api/extras/reports/ est supprimé.
  • Mode brief : le champ description est désormais inclus pour les modèles concernés.
  • Device : retrait de l’attribut obsolète device_role, remplacé par role.
  • VirtualChassis : nouveau champ members.
  • User/Group : ajout du champ permissions.
  • Nouveau paramètre ?fields=... pour contrôler les champs retournés et optimiser les requêtes DB.

GraphQL

NetBox remplace Graphene-Django par Strawberry-Django. C’est un changement structurel, pas seulement une dépendance.

  • Format des filtres et lookups modifié.
  • GraphiQL Browser mis à jour.
  • Queryset Optimizer pour réduire le nombre de requêtes SQL.
  • Les plugins doivent adapter schema.py, types.py et ajouter/mettre à jour filters.py.

Modèles et DB

  • 194 fichiers de migrations changés, avec squashing des migrations antérieures à v3.7.
  • NetBox utilise désormais des modèles User et Group custom plutôt que les modèles Django stock.
  • Custom scripts suivis comme objets en base.
  • Renommage des références ContentType → ObjectType et standardisation des noms de champs.
  • Location gagne un champ facility.
  • Virtual machines : support des image attachments.

Configuration

  • LOGIN_REQUIRED passe de False à True dans l’exemple de configuration.
  • ENABLE_LOCALIZATION supprimé.
  • DATE_FORMAT, TIME_FORMAT et variantes supprimés.
  • DJANGO_ADMIN_ENABLED peut être activé si des plugins dépendent encore de l’admin legacy.
  • uWSGI documenté comme alternative à Gunicorn.

Plugins

La compatibilité plugin est la zone à plus fort risque

1

Ressources déplacées

Les imports depuis extras.plugins ne sont plus compatibles ; utiliser netbox.plugins.

2

ContentType → ObjectType

Les modèles, serializers et filtres qui exposent des content types doivent être ajustés.

3

Forms et UI

BootstrapMixin disparaît. Les Fieldsets deviennent plus structurés et la refonte Tabler peut casser des templates custom.

4

REST et GraphQL

Les serializers brief mode et la couche GraphQL Strawberry imposent une revue spécifique des plugins exposant des APIs.

Plan migration

Checklist opérationnelle 3.7.8 → 4.0.11

Avant

  1. Faire un backup PostgreSQL + media + configuration.
  2. Auditer Python : supprimer 3.8/3.9, préparer 3.10+.
  3. Lister plugins et confirmer leur compatibilité NetBox 4.0.
  4. Inventorier scripts, reports, jobs planifiés et webhooks/event rules.
  5. Rechercher dans vos intégrations : device_role, content-types, object_type, parent_id, requêtes GraphQL.

Pendant

  1. Faire l’upgrade sur un clone/staging, jamais directement en prod.
  2. Exécuter les migrations et vérifier la conversion reports → scripts.
  3. Contrôler les permissions User/Group custom et la connexion SSO/remote auth.
  4. Valider les endpoints REST/GraphQL critiques.
  5. Vérifier l’UI : pages custom/plugin, dropdowns, widgets dashboard.

Après

  1. Comparer les logs d’erreur et jobs RQ.
  2. Réindexer la recherche si plugins retirés ou gros changements de données.
  3. Mettre à jour docs internes et clients API.
  4. Activer progressivement HTMX navigation si souhaité.
  5. Garder un rollback testé jusqu’à validation métier.

Synthèse décisionnelle

Faut-il migrer ? Oui, mais avec une phase de test dédiée.

Arguments pour migrer

  • Django 5 et Python 3.12 supporté.
  • Interface beaucoup plus moderne et maintenable.
  • REST API plus efficace grâce aux champs dynamiques.
  • GraphQL potentiellement plus performant.
  • Meilleure cohérence ObjectType/ContentType.

Points de prudence

  • Plugins non compatibles = risque majeur.
  • Requêtes GraphQL anciennes à réécrire.
  • Automatisations REST à vérifier champ par champ.
  • Reports historiques convertis en scripts : valider le résultat.
  • Templates custom potentiellement cassés par la refonte UI.

Traçabilité

Sources analysées

Repository : github.com/netbox-community/netbox

Tags comparés : v3.7.8 (be903a64a) vs v4.0.11 (0b120e6ad)

Commandes d’analyse : git diff --shortstat v3.7.8 v4.0.11, git diff --name-status, lecture de docs/release-notes/version-4.0.md, docs/plugins/development/migration-v4.md, base_requirements.txt, requirements.txt, configuration_example.py.

Date de génération : 2026-04-29 UTC