Inventaire dynamique NetBox avec netbox.netbox.nb

NetBox est la référence open-source en IPAM/DCIM : il gère vos racks, vos devices physiques, vos VMs, vos VLANs, vos prefixes IP. Si NetBox est déjà déployé chez vous, il est la source de vérité naturelle pour Ansible — pas la peine de dupliquer l’inventaire ailleurs.

Le plugin netbox.netbox.nb_inventory transforme votre instance NetBox en inventaire Ansible dynamique avec des filtres très fins (par site, par role, par status, par tag, par tenant). C’est le pattern recommandé dans les moyennes/grandes entreprises qui ont déjà investi dans NetBox.

Ce que vous allez apprendre

Configurer le plugin avec un token API NetBox.
Filtrer les hôtes par site, role, status, tag NetBox.
Grouper automatiquement par les attributs NetBox.
Récupérer les IPs depuis l’IPAM NetBox.
Combiner devices physiques et virtualization dans un même inventaire.

Prérequis

Une instance NetBox 3.x ou 4.x opérationnelle.
Token API NetBox créé.
Collection netbox.netbox installée.
pynetbox Python : pip install pynetbox.

Création d’un token NetBox

Sur l’UI NetBox : User → API Tokens → Add a token.

Champ	Valeur recommandée
User	`ansible-readonly` (créer ce user au préalable)
Description	`Inventaire dynamique Ansible`
Write enabled	❌ Décocher (lecture seule)
Allowed IPs	IP du control node Ansible (restriction réseau)
Expires	Date d’expiration (ex: 1 an)

Copier le token généré — il sera utilisé une seule fois (mais peut être recréé).

Installation

ansible-galaxy collection install netbox.netbox
pip install pynetbox

Activer dans ansible.cfg :

[inventory]
enable_plugins = host_list, script, auto, yaml, ini, netbox.netbox.nb_inventory

Configuration minimale

Créer inventory/netbox.yml :

---
plugin: netbox.netbox.nb_inventory
api_endpoint: https://netbox.example.com
token: !vault |
  $ANSIBLE_VAULT;1.1;AES256
  3736...
validate_certs: true

Le token chiffré avec Ansible Vault :

ansible-vault encrypt_string '<le-token>' --name token

Tester :

ansible-inventory -i inventory/netbox.yml --graph

Sortie : tous vos devices NetBox apparaissent comme des hôtes Ansible.

Filtrer par status, role, site

Sans filtre, le plugin retourne toutes les machines de NetBox. Pour ne garder que certaines :

plugin: netbox.netbox.nb_inventory
api_endpoint: https://netbox.example.com
token: !vault | ...

# Filtres NetBox (équivalent des filtres URL de l'API REST)
query_filters:
  - status: active
  - role: webserver
  - tag: managed-by-ansible

Avantage : la liste retournée par NetBox est déjà filtrée côté API — moins de payload, plus rapide.

# Multi-site
query_filters:
  - status: active
  - site: paris

Grouper par attributs NetBox

NetBox a déjà ses propres attributs structurés (site, role, manufacturer, status). Le plugin les expose automatiquement :

plugin: netbox.netbox.nb_inventory
api_endpoint: https://netbox.example.com
token: !vault | ...

group_by:
  - device_roles      # → groupe par role: webserver, dbserver, switch
  - sites             # → groupe par site: paris, londres
  - device_types      # → groupe par modèle: Dell-R740, HP-DL380
  - tags              # → groupe par tag NetBox
  - status            # → groupe par status: active, planned, decommissioning
  - regions           # → groupe par région
  - tenants           # → groupe par tenant (multi-tenant NetBox)

Résultat :

@all:
  |--@device_roles_webserver:
  |  |--web1.paris.example.com
  |  |--web2.paris.example.com
  |--@device_roles_dbserver:
  |  |--db1.paris.example.com
  |--@sites_paris:
  |  |--web1.paris.example.com
  |  |--db1.paris.example.com
  |--@status_active:
  |  |--... (toutes les machines actives)

Vous pouvez maintenant cibler device_roles_webserver:&sites_paris pour les webservers du site Paris uniquement.

Inclure les VMs (virtualization)

NetBox distingue les devices physiques des VMs (virtualization). Pour inclure les deux :

plugin: netbox.netbox.nb_inventory
api_endpoint: https://netbox.example.com
token: !vault | ...

config_context: false       # ne pas charger les config_contexts (alourdit)
fetch_all: true             # paginer pour gros parcs

# Inclure les VMs en plus des devices
plurals: true
fetch_virtual_chassis: true
include_status: true

Par défaut, le plugin inclut déjà les VMs. Mais sur des installations NetBox spécifiques, vérifier que fetch_all: true et que les VMs ont bien le statut active.

Récupérer les IPs

NetBox stocke les IPs primaires sur chaque device/VM. Le plugin les utilise automatiquement comme ansible_host si configuré :

plugin: netbox.netbox.nb_inventory
api_endpoint: https://netbox.example.com
token: !vault | ...

compose:
  ansible_host: primary_ip4.address.split('/')[0] | default(name)
  ansible_user: "'admin' if 'switch' in tags else 'ansible'"

compose: est puissant : il calcule des variables Ansible à partir des données NetBox. Ici on extrait l’IPv4 (sans le CIDR) et on choisit l’utilisateur SSH selon le tag.

Variables exposées par le plugin

Pour chaque host, le plugin expose tous les attributs NetBox :

- debug:
    msg: |
      Device {{ inventory_hostname }} :
      - Site         : {{ site.name }}
      - Role         : {{ device_role.name }}
      - Manufacturer : {{ device_type.manufacturer.name }}
      - Model        : {{ device_type.model }}
      - Serial       : {{ serial }}
      - Status       : {{ status.label }}
      - Primary IP   : {{ primary_ip4.address }}
      - VLAN         : {{ vlan.vid }}
      - Tags         : {{ tags | map(attribute='name') | list }}

C’est ce qui rend NetBox si puissant : vos playbooks ont accès à toute la donnée IPAM/DCIM sans dupliquer ailleurs.

Cache — mandatory

NetBox peut être lent sur de gros parcs (300+ devices). Cache obligatoire :

plugin: netbox.netbox.nb_inventory
api_endpoint: https://netbox.example.com
token: !vault | ...

cache: true
cache_plugin: jsonfile
cache_timeout: 600
cache_connection: /tmp/ansible_netbox_cache

Pour rafraîchir après modification dans NetBox :

ansible-inventory -i inventory/netbox.yml --list --refresh-cache

Patterns courants

Patcher tous les serveurs RHEL d’un site

ansible-playbook -i inventory/netbox.yml \
  --limit 'sites_paris:&device_types_dell-r740' \
  patch-rhel.yml

Configurer uniquement les machines en statut “planned”

ansible-playbook -i inventory/netbox.yml \
  --limit 'status_planned' \
  bootstrap.yml

NetBox suit le cycle de vie : planned → active → decommissioning → decommissioned. Cibler les planned permet de bootstrap uniquement les nouvelles machines.

Audit complet à partir des tags

ansible-playbook -i inventory/netbox.yml \
  --limit 'tags_pci-dss' \
  audit-pci.yml

Toutes les machines taggées pci-dss dans NetBox sont auditées. Aucune liste à maintenir — la source de vérité est NetBox.

Pièges courants

Symptôme	Cause	Fix
`pynetbox not found`	Module Python manquant	`pip install pynetbox`
`401 Unauthorized`	Token expiré ou mal écrit	Recréer le token, vérifier les permissions
Inventaire incomplet	`fetch_all: false` (défaut)	`fetch_all: true` pour > 1000 devices
Lent (>10s)	Pas de cache	`cache: true` mandatory
`Allowed IPs` bloque	Token configuré avec IP allowed	Ajouter l’IP du control node
Tags absents	`plurals: true` non configuré	`plurals: true` pour grouper par `tags`

Quand préférer NetBox

Critère	NetBox recommandé	Autre solution
Source de vérité IPAM/DCIM existante	✅	—
Petit parc (< 50 hôtes)	Surdimensionné	Statique YAML
Cloud public (AWS/Azure/GCP)	Plugin cloud direct	NetBox redondant
Mix on-prem + cloud	Possible (NetBox sync)	Plusieurs `-i`
Audit conformité (tags, owners)	✅ excellence	Galère sans NetBox

À retenir

NetBox = source de vérité IPAM/DCIM unifiée — pas de duplication d’inventaire.
netbox.netbox.nb_inventory = plugin officiel maintenu par NetBox Labs.
Token chiffré Vault + restriction Allowed IPs au token.
query_filters: = filtrer côté API (status, role, site, tag).
group_by: = grouper par attributs NetBox natifs.
compose: = calculer ansible_host, ansible_user depuis NetBox.
Cache mandatory dès qu’on dépasse quelques centaines de devices.

Prochaines étapes

Plugin Proxmox Si NetBox est votre IPAM mais Proxmox votre virtu — combiner les deux

Plugin AWS EC2 Pour la partie cloud public — peut être combiné avec NetBox via plusieurs -i

Écrire un script custom Quand NetBox est trop lourd ou que vous avez une CMDB maison

Modules runtime (add_host, group_by) Compléter NetBox avec un add_host pour des hôtes provisionnés à la volée

Inventaire dynamique NetBox avec netbox.netbox.nb_inventory