netbox-disk-manager 0.1.0__py3-none-any.whl

netbox_disk_manager/__init__.py

@@ -0,0 +1,56 @@
+"""NetBox plugin tracking disk PSIDs independently of module placement.
+
+NetBox models a disk as a ``dcim.Module`` sitting in a module bay. A module
+cannot be moved to another bay or detached without being deleted, so anything
+stored *on* the module - the PSID in particular - is lost the moment the disk
+is reseated in another chassis. This plugin keeps one record per physical
+drive, keyed by manufacturer and serial, and matches it to whatever module
+currently carries that serial.
+"""
+
+from netbox.plugins import PluginConfig
+
+__version__ = '0.1.0'
+
+
+class DiskManagerConfig(PluginConfig):
+    name = 'netbox_disk_manager'
+    verbose_name = 'Disk Manager'
+    description = 'Track disk PSIDs by manufacturer, model and serial, independent of module placement'
+    version = __version__
+    author = 'SF Compute'
+    base_url = 'disk-manager'
+
+    # 4.7 is the line this plugin is developed and tested against. The upper
+    # bound is deliberate: a new minor should be tested before it is allowed.
+    min_version = '4.7.0'
+    max_version = '4.7.99'
+
+    menu = 'navigation.menu'
+    search_indexes = 'search.indexes'
+    # Points at the list inside the module, not the module itself.
+    graphql_schema = 'graphql.schema.schema'
+
+    default_settings = {
+        # Show a top-level "Disks" entry in the sidebar. False tucks the plugin
+        # under the generic Plugins menu instead.
+        'top_level_menu': True,
+        # Names of the dcim.ModuleTypeProfile entries whose modules count as
+        # disks. Drives the panels on device and module pages and the backfill
+        # command. NetBox ships a profile called "Hard disk".
+        'module_profiles': ['Hard disk'],
+        # A PSID must fully match this pattern after surrounding whitespace is
+        # stripped. The default is permissive on purpose: vendors differ on
+        # length, and a label that cannot be recorded is worse than a lax check.
+        'psid_regex': r'^[A-Za-z0-9]+$',
+    }
+
+    def ready(self):
+        super().ready()
+
+        from .config import validate_config
+
+        validate_config()
+
+
+config = DiskManagerConfig

netbox_disk_manager/api/serializers.py

@@ -0,0 +1,35 @@
+"""REST API serializers."""
+
+from dcim.api.serializers import ManufacturerSerializer
+from netbox.api.serializers import PrimaryModelSerializer
+from rest_framework import serializers
+
+from ..models import Disk
+
+__all__ = ('DiskSerializer',)
+
+
+class DiskSerializer(PrimaryModelSerializer):
+    url = serializers.HyperlinkedIdentityField(view_name='plugins-api:netbox_disk_manager-api:disk-detail')
+    manufacturer = ManufacturerSerializer(nested=True)
+
+    class Meta:
+        model = Disk
+        fields = (
+            'id',
+            'url',
+            'display_url',
+            'display',
+            'manufacturer',
+            'model',
+            'serial',
+            'psid',
+            'description',
+            'comments',
+            'owner',
+            'tags',
+            'custom_fields',
+            'created',
+            'last_updated',
+        )
+        brief_fields = ('id', 'url', 'display', 'manufacturer', 'model', 'serial')

netbox_disk_manager/api/urls.py

@@ -0,0 +1,11 @@
+"""API routing. Mounts at /api/plugins/disk-manager/."""
+
+from netbox.api.routers import NetBoxRouter
+
+from . import views
+
+router = NetBoxRouter()
+router.register('disks', views.DiskViewSet)
+
+app_name = 'netbox_disk_manager-api'
+urlpatterns = router.urls

netbox_disk_manager/api/views.py

@@ -0,0 +1,16 @@
+"""REST API viewsets. Standard NetBox CRUD; permissions come from NetBox's
+ObjectPermission machinery via NetBoxModelViewSet."""
+
+from netbox.api.viewsets import NetBoxModelViewSet
+
+from .. import filtersets
+from ..models import Disk
+from .serializers import DiskSerializer
+
+__all__ = ('DiskViewSet',)
+
+
+class DiskViewSet(NetBoxModelViewSet):
+    queryset = Disk.objects.select_related('manufacturer')
+    serializer_class = DiskSerializer
+    filterset_class = filtersets.DiskFilterSet

netbox_disk_manager/config.py

@@ -0,0 +1,56 @@
+"""Access to and validation of PLUGINS_CONFIG.
+
+Nothing here touches the database: ``validate_config()`` runs from
+``PluginConfig.ready()``, which happens before the database necessarily exists
+on a fresh install.
+"""
+
+import re
+
+from django.conf import settings
+from django.core.exceptions import ImproperlyConfigured
+
+PLUGIN_NAME = 'netbox_disk_manager'
+
+
+def get_config():
+    """Return this plugin's merged configuration.
+
+    ``PluginConfig.validate()`` has already layered ``default_settings`` under
+    the user's ``PLUGINS_CONFIG`` entry by the time anything calls this, so the
+    result always has every key.
+    """
+    return settings.PLUGINS_CONFIG[PLUGIN_NAME]
+
+
+def get_module_profiles():
+    """The configured ModuleTypeProfile names, as a tuple."""
+    return tuple(get_config()['module_profiles'])
+
+
+def get_psid_pattern():
+    """The compiled PSID pattern. Cheap enough to compile per call; it is only hit on save."""
+    return re.compile(get_config()['psid_regex'])
+
+
+def validate_config():
+    """Fail loudly at startup rather than confusingly at first use."""
+    config = get_config()
+
+    profiles = config.get('module_profiles')
+    if isinstance(profiles, str) or not isinstance(profiles, list | tuple):
+        raise ImproperlyConfigured(f"{PLUGIN_NAME}: 'module_profiles' must be a list of profile names.")
+    for name in profiles:
+        if not isinstance(name, str) or not name.strip():
+            raise ImproperlyConfigured(f"{PLUGIN_NAME}: 'module_profiles' entries must be non-empty strings.")
+
+    pattern = config.get('psid_regex')
+    if not isinstance(pattern, str) or not pattern:
+        raise ImproperlyConfigured(f"{PLUGIN_NAME}: 'psid_regex' must be a non-empty regular expression string.")
+    try:
+        re.compile(pattern)
+    except re.error as exc:
+        raise ImproperlyConfigured(f"{PLUGIN_NAME}: 'psid_regex' is not a valid regular expression: {exc}") from exc
+
+    if not isinstance(config.get('top_level_menu'), bool):
+        raise ImproperlyConfigured(f"{PLUGIN_NAME}: 'top_level_menu' must be True or False.")

netbox_disk_manager/filtersets.py

@@ -0,0 +1,52 @@
+"""Filtersets.
+
+Registered with ``@register_filterset`` so the UI filter form offers lookup
+modifiers (``__ic``, ``__n``, ``__empty`` and friends) rather than bare
+equality.
+"""
+
+import django_filters
+from dcim.models import Manufacturer
+from django.db.models import Q
+from netbox.filtersets import NetBoxModelFilterSet
+from utilities.filters import MultiValueCharFilter
+from utilities.filtersets import register_filterset
+
+from .models import Disk
+
+__all__ = ('DiskFilterSet',)
+
+
+@register_filterset
+class DiskFilterSet(NetBoxModelFilterSet):
+    manufacturer_id = django_filters.ModelMultipleChoiceFilter(
+        queryset=Manufacturer.objects.all(),
+        label='Manufacturer (ID)',
+    )
+    manufacturer = django_filters.ModelMultipleChoiceFilter(
+        field_name='manufacturer__slug',
+        queryset=Manufacturer.objects.all(),
+        to_field_name='slug',
+        label='Manufacturer (slug)',
+    )
+    # Case-insensitive on purpose: the same drive is reported in different
+    # cases by different tools, and the uniqueness rule is case-insensitive.
+    serial = MultiValueCharFilter(lookup_expr='iexact')
+    has_psid = django_filters.BooleanFilter(
+        method='filter_has_psid',
+        label='Has PSID',
+    )
+
+    class Meta:
+        model = Disk
+        fields = ('id', 'model', 'psid', 'description')
+
+    def search(self, queryset, name, value):
+        if not value.strip():
+            return queryset
+        return queryset.filter(Q(serial__icontains=value) | Q(model__icontains=value) | Q(description__icontains=value))
+
+    def filter_has_psid(self, queryset, name, value):
+        if value:
+            return queryset.exclude(psid='')
+        return queryset.filter(psid='')

netbox_disk_manager/forms.py

@@ -0,0 +1,97 @@
+"""Forms.
+
+Three things are deliberate here:
+
+* ``manufacturer`` is a dynamic select backed by ``dcim.Manufacturer``, so the
+  record shares the vocabulary modules already use.
+* The bulk edit form has no ``model`` field. ``NetBoxModelBulkEditForm`` uses a
+  class attribute of that name for the model class, and rewriting the model
+  string across many drives at once is not a thing anyone wants anyway.
+* The filter form has no ``model`` field for the same reason; ``q`` searches
+  it.
+"""
+
+from dcim.models import Manufacturer
+from django import forms
+from django.utils.translation import gettext_lazy as _
+from netbox.forms import NetBoxModelBulkEditForm, NetBoxModelFilterSetForm, NetBoxModelForm, NetBoxModelImportForm
+from utilities.forms import BOOLEAN_WITH_BLANK_CHOICES
+from utilities.forms.fields import (
+    CommentField,
+    CSVModelChoiceField,
+    DynamicModelChoiceField,
+    DynamicModelMultipleChoiceField,
+    TagFilterField,
+)
+from utilities.forms.rendering import FieldSet
+
+from .models import Disk
+
+__all__ = ('DiskBulkEditForm', 'DiskFilterForm', 'DiskForm', 'DiskImportForm')
+
+
+class DiskForm(NetBoxModelForm):
+    manufacturer = DynamicModelChoiceField(
+        queryset=Manufacturer.objects.all(),
+        label=_('Manufacturer'),
+    )
+    comments = CommentField()
+
+    fieldsets = (FieldSet('manufacturer', 'model', 'serial', 'psid', 'description', 'tags', name=_('Disk')),)
+
+    class Meta:
+        model = Disk
+        fields = ('manufacturer', 'model', 'serial', 'psid', 'description', 'comments', 'tags')
+
+
+class DiskImportForm(NetBoxModelImportForm):
+    manufacturer = CSVModelChoiceField(
+        queryset=Manufacturer.objects.all(),
+        to_field_name='name',
+        help_text=_('Manufacturer name'),
+    )
+
+    class Meta:
+        model = Disk
+        fields = ('manufacturer', 'model', 'serial', 'psid', 'description', 'comments', 'tags')
+
+
+class DiskBulkEditForm(NetBoxModelBulkEditForm):
+    manufacturer = DynamicModelChoiceField(
+        queryset=Manufacturer.objects.all(),
+        required=False,
+        label=_('Manufacturer'),
+    )
+    description = forms.CharField(
+        max_length=200,
+        required=False,
+        label=_('Description'),
+    )
+    comments = CommentField()
+
+    model = Disk
+    fieldsets = (FieldSet('manufacturer', 'description', name=_('Disk')),)
+    nullable_fields = ('description', 'comments')
+
+
+class DiskFilterForm(NetBoxModelFilterSetForm):
+    model = Disk
+    fieldsets = (
+        FieldSet('q', 'filter_id', 'tag'),
+        FieldSet('manufacturer_id', 'serial', 'has_psid', name=_('Attributes')),
+    )
+    manufacturer_id = DynamicModelMultipleChoiceField(
+        queryset=Manufacturer.objects.all(),
+        required=False,
+        label=_('Manufacturer'),
+    )
+    serial = forms.CharField(
+        required=False,
+        label=_('Serial number'),
+    )
+    has_psid = forms.NullBooleanField(
+        required=False,
+        label=_('Has PSID'),
+        widget=forms.Select(choices=BOOLEAN_WITH_BLANK_CHOICES),
+    )
+    tag = TagFilterField(model)

netbox_disk_manager/graphql/filters.py

@@ -0,0 +1,25 @@
+"""GraphQL filters."""
+
+from typing import Annotated
+
+import strawberry
+import strawberry_django
+from netbox.graphql.filters import PrimaryModelFilter
+from strawberry_django import StrFilterLookup
+
+from .. import models
+
+__all__ = ('DiskFilter',)
+
+
+@strawberry_django.filter_type(models.Disk, lookups=True)
+class DiskFilter(PrimaryModelFilter):
+    model: StrFilterLookup | None = strawberry_django.filter_field()
+    serial: StrFilterLookup | None = strawberry_django.filter_field()
+    psid: StrFilterLookup | None = strawberry_django.filter_field()
+    manufacturer: Annotated['ManufacturerFilter', strawberry.lazy('dcim.graphql.filters')] | None = (  # noqa: F821
+        strawberry_django.filter_field()
+    )
+    manufacturer_id: Annotated['IntegerLookup', strawberry.lazy('netbox.graphql.filter_lookups')] | None = (  # noqa: F821
+        strawberry_django.filter_field()
+    )

netbox_disk_manager/graphql/schema.py

@@ -0,0 +1,18 @@
+"""GraphQL queries. Field names are prefixed so they cannot collide with core
+or with another plugin."""
+
+import strawberry
+import strawberry_django
+
+from .types import DiskType
+
+__all__ = ('schema',)
+
+
+@strawberry.type(name='Query')
+class DiskManagerQuery:
+    ndm_disk: DiskType = strawberry_django.field()
+    ndm_disk_list: list[DiskType] = strawberry_django.field()
+
+
+schema = [DiskManagerQuery]

netbox_disk_manager/graphql/types.py

@@ -0,0 +1,30 @@
+"""GraphQL types.
+
+Fields are enumerated rather than pulled in with ``__all__``, so adding a model
+field can never silently add it to the public schema.
+"""
+
+from typing import Annotated
+
+import strawberry
+import strawberry_django
+from netbox.graphql.types import PrimaryObjectType
+
+from .. import models
+from .filters import DiskFilter
+
+__all__ = ('DiskType',)
+
+
+@strawberry_django.type(
+    models.Disk,
+    fields=['id', 'model', 'serial', 'psid', 'description', 'comments', 'created', 'last_updated'],
+    filters=DiskFilter,
+    pagination=True,
+)
+class DiskType(PrimaryObjectType):
+    @strawberry_django.field(description='The manufacturer of the drive.')
+    def manufacturer(self) -> Annotated['ManufacturerType', strawberry.lazy('dcim.graphql.types')]:  # noqa: F821
+        # An explicit resolver both names the type and binds the relation;
+        # a bare annotation or a `fields` entry alone does only one of the two.
+        return self.manufacturer

netbox_disk_manager/management/commands/ndm_backfill_disks.py

@@ -0,0 +1,86 @@
+"""Create disk records from the disk modules already in NetBox.
+
+Dry run by default: prints what it would do and writes nothing. ``--apply``
+performs the writes, in one transaction.
+
+One record per physical drive is the invariant. When a serial is already
+recorded under *any* manufacturer the module is skipped and reported, even if
+the module's own type names a different manufacturer; that mismatch is a
+module-type data problem to fix in NetBox, not a second drive.
+"""
+
+from django.core.management.base import BaseCommand
+from django.db import transaction
+from django.db.models.functions import Upper
+
+from netbox_disk_manager.config import get_module_profiles
+from netbox_disk_manager.models import Disk
+
+
+class Command(BaseCommand):
+    help = 'Create a Disk record (without PSID) for every disk module that does not have one yet.'
+
+    def add_arguments(self, parser):
+        parser.add_argument(
+            '--apply',
+            action='store_true',
+            help='Write the records. Without this flag the command only reports what it would do.',
+        )
+
+    def handle(self, *args, **options):
+        from dcim.models import Module
+
+        apply = options['apply']
+        profiles = get_module_profiles()
+
+        modules = (
+            Module.objects.filter(module_type__profile__name__in=profiles)
+            .exclude(serial='')
+            .select_related('device', 'module_bay', 'module_type__manufacturer', 'module_type__profile')
+            .order_by('pk')
+        )
+
+        # Every serial already recorded, uppercased, regardless of manufacturer.
+        recorded = {
+            serial: manufacturer
+            for serial, manufacturer in Disk.objects.annotate(serial_upper=Upper('serial')).values_list(
+                'serial_upper', 'manufacturer__name'
+            )
+        }
+
+        created = skipped = 0
+        verb = 'create' if apply else 'would create'
+
+        with transaction.atomic():
+            for module in modules:
+                key = module.serial.strip().upper()
+                where = f'{module.device.name}/{module.module_bay.name}'
+                if key in recorded:
+                    skipped += 1
+                    self.stdout.write(f'skip: {where} serial={module.serial} already recorded under {recorded[key]}')
+                    continue
+
+                manufacturer = module.module_type.manufacturer
+                self.stdout.write(
+                    f'{verb}: {where} manufacturer={manufacturer.name} model={module.module_type.model} '
+                    f'serial={module.serial}'
+                )
+                if apply:
+                    disk = Disk(
+                        manufacturer=manufacturer,
+                        model=module.module_type.model,
+                        serial=module.serial.strip(),
+                        psid='',
+                    )
+                    disk.full_clean()
+                    disk.save()
+                # Recorded either way so a second module with the same serial
+                # in the same run is reported as a skip, matching --apply.
+                recorded[key] = manufacturer.name
+                created += 1
+
+        self.stdout.write(
+            self.style.SUCCESS(f'{"created" if apply else "would create"}={created} skipped={skipped}')
+            if apply
+            else f'would create={created} skipped={skipped} (dry run; pass --apply to write)'
+        )

netbox_disk_manager/migrations/0001_initial.py

@@ -0,0 +1,69 @@
+# Generated by Django 6.1 on 2026-11-11 17:59
+
+import django.db.models.deletion
+import django.db.models.functions.text
+import netbox.models.deletion
+import taggit.managers
+import utilities.json
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    initial = True
+
+    dependencies = [
+        ('dcim', '0250_cooling_infrastructure'),
+        ('extras', '0144_customfield_status'),
+        ('users', '0016_default_ordering_indexes'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='Disk',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False)),
+                ('created', models.DateTimeField(auto_now_add=True, null=True)),
+                ('last_updated', models.DateTimeField(auto_now=True, null=True)),
+                (
+                    'custom_field_data',
+                    models.JSONField(blank=True, default=dict, encoder=utilities.json.CustomFieldJSONEncoder),
+                ),
+                ('description', models.CharField(blank=True, max_length=200)),
+                ('comments', models.TextField(blank=True)),
+                ('model', models.CharField(max_length=100)),
+                ('serial', models.CharField(db_index=True, max_length=100)),
+                ('psid', models.CharField(blank=True, max_length=64)),
+                (
+                    'manufacturer',
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.PROTECT, related_name='disks', to='dcim.manufacturer'
+                    ),
+                ),
+                (
+                    'owner',
+                    models.ForeignKey(
+                        blank=True,
+                        null=True,
+                        on_delete=django.db.models.deletion.PROTECT,
+                        related_name='+',
+                        to='users.owner',
+                    ),
+                ),
+                ('tags', taggit.managers.TaggableManager(through='extras.TaggedItem', to='extras.Tag')),
+            ],
+            options={
+                'verbose_name': 'disk',
+                'verbose_name_plural': 'disks',
+                'ordering': ('manufacturer', 'model', 'serial'),
+                'constraints': [
+                    models.UniqueConstraint(
+                        models.F('manufacturer'),
+                        django.db.models.functions.text.Upper('serial'),
+                        name='netbox_disk_manager_disk_unique_manufacturer_serial_ci',
+                        violation_error_message='A disk with this serial already exists for this manufacturer.',
+                    )
+                ],
+            },
+            bases=(netbox.models.deletion.DeleteMixin, models.Model),
+        ),
+    ]

netbox_disk_manager/models.py

@@ -0,0 +1,104 @@
+"""The Disk model.
+
+One row per physical drive, keyed by manufacturer and serial. The record is
+deliberately *not* a foreign key to ``dcim.Module``: a module is deleted when a
+disk leaves a bay, and the whole point is to outlive that. Instead the link is
+computed at render time by matching the serial (and manufacturer) against
+whatever module currently carries it.
+"""
+
+from django.core.exceptions import ValidationError
+from django.db import models
+from django.db.models.functions import Upper
+from django.utils.translation import gettext_lazy as _
+from netbox.models import PrimaryModel
+
+from .config import get_psid_pattern
+
+__all__ = ('Disk',)
+
+
+class Disk(PrimaryModel):
+    manufacturer = models.ForeignKey(
+        to='dcim.Manufacturer',
+        on_delete=models.PROTECT,
+        related_name='disks',
+        verbose_name=_('manufacturer'),
+    )
+    model = models.CharField(
+        max_length=100,
+        verbose_name=_('model'),
+        help_text=_('Model as printed on the label or reported by the drive, e.g. SSDPF2KX038T1.'),
+    )
+    serial = models.CharField(
+        max_length=100,
+        db_index=True,
+        verbose_name=_('serial number'),
+        help_text=_('Matched case-insensitively against the serial of modules in NetBox.'),
+    )
+    psid = models.CharField(
+        max_length=64,
+        blank=True,
+        verbose_name=_('PSID'),
+        help_text=_('Physical Security ID printed on the drive label. Leave blank if not yet collected.'),
+    )
+
+    clone_fields = ('manufacturer', 'model')
+
+    class Meta:
+        ordering = ('manufacturer', 'model', 'serial')
+        constraints = [
+            # Case-insensitive: vendors print serials in one case and tooling
+            # reports them in another, and both refer to the same drive.
+            models.UniqueConstraint(
+                models.F('manufacturer'),
+                Upper('serial'),
+                name='%(app_label)s_%(class)s_unique_manufacturer_serial_ci',
+                violation_error_message=_('A disk with this serial already exists for this manufacturer.'),
+            ),
+        ]
+        verbose_name = _('disk')
+        verbose_name_plural = _('disks')
+
+    def __str__(self):
+        return f'{self.manufacturer} {self.model} ({self.serial})'
+
+    def clean(self):
+        super().clean()
+
+        self.serial = (self.serial or '').strip()
+        self.psid = (self.psid or '').strip()
+        self.model = (self.model or '').strip()
+
+        if not self.serial:
+            raise ValidationError({'serial': _('A serial number is required.')})
+
+        if self.psid and not get_psid_pattern().fullmatch(self.psid):
+            raise ValidationError({'psid': _('PSID contains characters that are not allowed.')})
+
+        # Django validates the functional unique constraint too, but it reports
+        # against the whole form; this pins the message to the serial field.
+        if self.manufacturer_id is not None:
+            duplicates = Disk.objects.filter(manufacturer_id=self.manufacturer_id, serial__iexact=self.serial)
+            if self.pk:
+                duplicates = duplicates.exclude(pk=self.pk)
+            if duplicates.exists():
+                raise ValidationError({'serial': _('A disk with this serial already exists for this manufacturer.')})
+
+    @property
+    def has_psid(self):
+        return bool(self.psid)
+
+    def get_modules(self):
+        """Modules in NetBox that currently carry this drive.
+
+        Normally zero or one. More than one means the same drive was recorded
+        in two places, which is a data problem worth surfacing, not hiding.
+        """
+        from dcim.models import Module
+
+        return (
+            Module.objects.filter(serial__iexact=self.serial, module_type__manufacturer_id=self.manufacturer_id)
+            .select_related('device', 'module_bay', 'module_type')
+            .order_by('device__name', 'module_bay__name')
+        )