netbox-loadbalancer-plugin 0.1.0__py3-none-any.whl

netbox_loadbalancer/__init__.py

@@ -0,0 +1,34 @@
+"""NetBox plugin for managing load balancers, virtual servers, pools, and pool members.
+
+This is the plugin entry point. NetBox discovers plugins by looking for a module-level
+``config`` variable that points to a PluginConfig subclass. The PluginConfig class
+declares metadata (name, version, author) and settings (base_url, min_version) that
+NetBox uses when loading the plugin.
+
+When NetBox starts, it imports this module, reads the ``config`` variable, and uses it
+to register the plugin's models, views, API endpoints, navigation menu, and search
+indexes — all of which are defined in sibling modules within this package.
+"""
+
+from netbox.plugins import PluginConfig
+
+
+class NetBoxLoadBalancerConfig(PluginConfig):
+    """Declares plugin metadata and compatibility requirements.
+
+    NetBox reads these attributes at startup to register the plugin. The ``name``
+    must match the Python package name (``netbox_loadbalancer``). The ``base_url``
+    determines the URL prefix for all plugin views (e.g. ``/plugins/loadbalancer/``).
+    The ``min_version`` prevents the plugin from loading on incompatible NetBox releases.
+    """
+    name = 'netbox_loadbalancer'
+    verbose_name = 'Load Balancer'
+    description = 'Manage load balancers, virtual servers, pools, and pool members'
+    version = '0.1.0'
+    author = 'David Johnnes'
+    author_email = 'david.johnnes@gmail.com'
+    base_url = 'loadbalancer'
+    min_version = '4.0.0'
+
+
+config = NetBoxLoadBalancerConfig

netbox_loadbalancer/api/serializers.py

@@ -0,0 +1,86 @@
+"""REST API serializers for the netbox_loadbalancer plugin.
+
+Each serializer extends ``NetBoxModelSerializer``, which is a DRF ModelSerializer
+pre-configured with NetBox's conventions for nested object representation, tag
+handling, and custom field support.
+
+Key concepts:
+- ``Meta.fields``: the complete list of fields included in the full (detail) API
+  response. This includes computed fields like ``url`` and ``display`` (provided
+  by NetBoxModelSerializer), standard model fields, and audit fields (``created``,
+  ``last_updated``).
+- ``Meta.brief_fields``: the subset of fields returned when the ``?brief=true``
+  query parameter is used on the API. Brief mode returns a minimal representation
+  (typically just id, url, display, and name) and is used when the object appears
+  as a nested related object inside another serializer's response, to avoid deeply
+  nested JSON.
+"""
+
+from netbox.api.serializers import NetBoxModelSerializer
+
+from ..models import LoadBalancer, VirtualServer, Pool, PoolMember
+
+
+class LoadBalancerSerializer(NetBoxModelSerializer):
+    """Serializer for load balancer API responses.
+
+    Related objects (device, site, tenant, management_ip) are automatically serialized
+    as nested objects in full mode, or as brief references when this serializer is
+    used as a nested serializer inside another response.
+    """
+    class Meta:
+        model = LoadBalancer
+        fields = (
+            'id', 'url', 'display', 'name', 'platform', 'status',
+            'device', 'site', 'tenant', 'management_ip', 'description',
+            'tags', 'custom_fields', 'created', 'last_updated',
+        )
+        brief_fields = ('id', 'url', 'display', 'name')
+
+
+class PoolSerializer(NetBoxModelSerializer):
+    """Serializer for pool API responses.
+
+    The loadbalancer field is serialized as a nested object in full mode, showing
+    the parent load balancer's details inline within the pool response.
+    """
+    class Meta:
+        model = Pool
+        fields = (
+            'id', 'url', 'display', 'name', 'loadbalancer', 'method',
+            'protocol', 'description',
+            'tags', 'custom_fields', 'created', 'last_updated',
+        )
+        brief_fields = ('id', 'url', 'display', 'name')
+
+
+class VirtualServerSerializer(NetBoxModelSerializer):
+    """Serializer for virtual server API responses.
+
+    Includes nested representations for loadbalancer, ip_address, pool, and tenant.
+    The port and protocol fields are serialized as simple values.
+    """
+    class Meta:
+        model = VirtualServer
+        fields = (
+            'id', 'url', 'display', 'name', 'loadbalancer', 'ip_address',
+            'port', 'protocol', 'status', 'pool', 'tenant', 'description',
+            'tags', 'custom_fields', 'created', 'last_updated',
+        )
+        brief_fields = ('id', 'url', 'display', 'name')
+
+
+class PoolMemberSerializer(NetBoxModelSerializer):
+    """Serializer for pool member API responses.
+
+    Includes nested representations for pool, ip_address, and device. Numeric fields
+    (port, weight, priority) are serialized as plain integers.
+    """
+    class Meta:
+        model = PoolMember
+        fields = (
+            'id', 'url', 'display', 'name', 'pool', 'ip_address', 'device',
+            'port', 'weight', 'priority', 'status', 'description',
+            'tags', 'custom_fields', 'created', 'last_updated',
+        )
+        brief_fields = ('id', 'url', 'display', 'name')

netbox_loadbalancer/api/urls.py

@@ -0,0 +1,23 @@
+"""API URL routing for the netbox_loadbalancer plugin.
+
+Uses ``NetBoxRouter`` (a subclass of DRF's DefaultRouter) to automatically generate
+REST API URL patterns for all four model viewsets. The router creates standard
+endpoints like ``/api/plugins/loadbalancer/loadbalancers/`` and
+``/api/plugins/loadbalancer/loadbalancers/<id>/``.
+
+NetBox discovers this module automatically because the plugin package contains an
+``api/`` sub-package with a ``urls.py`` module. The ``urlpatterns`` variable is
+included under the plugin's API namespace by NetBox's plugin loading machinery.
+"""
+
+from netbox.api.routers import NetBoxRouter
+
+from . import views
+
+router = NetBoxRouter()
+router.register('loadbalancers', views.LoadBalancerViewSet)
+router.register('pools', views.PoolViewSet)
+router.register('virtual-servers', views.VirtualServerViewSet)
+router.register('pool-members', views.PoolMemberViewSet)
+
+urlpatterns = router.urls

netbox_loadbalancer/api/views.py

@@ -0,0 +1,72 @@
+"""REST API viewsets for the netbox_loadbalancer plugin.
+
+Each viewset extends ``NetBoxModelViewSet``, which is a DRF (Django REST Framework)
+ModelViewSet pre-configured with NetBox's authentication, permission checking,
+pagination, and nested serializer support. A single viewset provides all standard
+REST actions: list, retrieve, create, update, partial_update, and destroy.
+
+The three class attributes on each viewset control its behaviour:
+- ``queryset``: the base database query (can include annotations like Count).
+- ``serializer_class``: the serializer used to convert model instances to/from JSON.
+- ``filterset_class``: the FilterSet that enables URL query parameter filtering
+  (e.g. ``GET /api/plugins/loadbalancer/pools/?method=round-robin``).
+
+These viewsets are registered with the ``NetBoxRouter`` in ``api/urls.py``, which
+generates the standard REST URL patterns (list, detail, etc.) automatically.
+"""
+
+from django.db.models import Count
+from netbox.api.viewsets import NetBoxModelViewSet
+
+from ..models import LoadBalancer, VirtualServer, Pool, PoolMember
+from ..filtersets import (
+    LoadBalancerFilterSet, VirtualServerFilterSet, PoolFilterSet, PoolMemberFilterSet,
+)
+from .serializers import (
+    LoadBalancerSerializer, VirtualServerSerializer, PoolSerializer, PoolMemberSerializer,
+)
+
+
+class LoadBalancerViewSet(NetBoxModelViewSet):
+    """API endpoint for managing load balancers.
+
+    Supports ``GET /``, ``POST /``, ``GET /<id>/``, ``PUT /<id>/``, ``PATCH /<id>/``,
+    and ``DELETE /<id>/`` under the ``/api/plugins/loadbalancer/loadbalancers/`` path.
+    """
+    queryset = LoadBalancer.objects.all()
+    serializer_class = LoadBalancerSerializer
+    filterset_class = LoadBalancerFilterSet
+
+
+class PoolViewSet(NetBoxModelViewSet):
+    """API endpoint for managing pools.
+
+    The queryset includes ``.annotate(member_count=Count('members'))`` so that the
+    pool member count is available in the serialized response without requiring a
+    separate database query for each pool.
+    """
+    queryset = Pool.objects.annotate(member_count=Count('members'))
+    serializer_class = PoolSerializer
+    filterset_class = PoolFilterSet
+
+
+class VirtualServerViewSet(NetBoxModelViewSet):
+    """API endpoint for managing virtual servers.
+
+    Supports full CRUD and filtering by load balancer, status, protocol, pool, and
+    tenant via the ``VirtualServerFilterSet``.
+    """
+    queryset = VirtualServer.objects.all()
+    serializer_class = VirtualServerSerializer
+    filterset_class = VirtualServerFilterSet
+
+
+class PoolMemberViewSet(NetBoxModelViewSet):
+    """API endpoint for managing pool members.
+
+    Supports full CRUD and filtering by pool, status, device, IP address, port,
+    weight, and priority via the ``PoolMemberFilterSet``.
+    """
+    queryset = PoolMember.objects.all()
+    serializer_class = PoolMemberSerializer
+    filterset_class = PoolMemberFilterSet

netbox_loadbalancer/choices.py

@@ -0,0 +1,185 @@
+"""Choice sets for the netbox_loadbalancer plugin.
+
+Each class in this module extends NetBox's ``ChoiceSet`` base class to define the
+valid options for a CharField on one of the plugin's models. A ChoiceSet works like
+a Django choices tuple but adds colour-coded badges in the UI (the optional third
+element in each CHOICES entry).
+
+The ``key`` attribute (e.g. ``'LoadBalancer.platform'``) allows NetBox administrators
+to override or extend the default choices at runtime through the FIELD_CHOICES
+configuration setting, without modifying the plugin source code.
+
+Convention: class constants (e.g. ``STATUS_ACTIVE = 'active'``) are used throughout
+the codebase to reference choices by name instead of hardcoding string values.
+"""
+
+from utilities.choices import ChoiceSet
+
+
+class LoadBalancerPlatformChoices(ChoiceSet):
+    """Platform types for load balancer appliances.
+
+    Identifies the vendor or technology stack running the load balancer. This is a
+    required field on the LoadBalancer model. Common platforms include hardware
+    appliances (F5 BIG-IP, Citrix ADC), software-based solutions (HAProxy, NGINX),
+    and cloud-native services (AWS ELB/ALB, Azure LB). Use 'Other' for platforms
+    not listed here.
+    """
+    key = 'LoadBalancer.platform'
+
+    PLATFORM_F5 = 'f5'
+    PLATFORM_HAPROXY = 'haproxy'
+    PLATFORM_CITRIX = 'citrix'
+    PLATFORM_NGINX = 'nginx'
+    PLATFORM_AWS = 'aws'
+    PLATFORM_AZURE = 'azure'
+    PLATFORM_OTHER = 'other'
+
+    CHOICES = [
+        (PLATFORM_F5, 'F5 BIG-IP'),
+        (PLATFORM_HAPROXY, 'HAProxy'),
+        (PLATFORM_CITRIX, 'Citrix ADC'),
+        (PLATFORM_NGINX, 'NGINX'),
+        (PLATFORM_AWS, 'AWS ELB/ALB'),
+        (PLATFORM_AZURE, 'Azure LB'),
+        (PLATFORM_OTHER, 'Other'),
+    ]
+
+
+class LoadBalancerStatusChoices(ChoiceSet):
+    """Operational lifecycle status for load balancers.
+
+    Tracks where a load balancer is in its lifecycle: planned (not yet deployed),
+    active (in production), maintenance (temporarily offline for work), or
+    decommissioned (retired). Each status has an associated colour that is displayed
+    as a badge in the NetBox UI.
+    """
+    key = 'LoadBalancer.status'
+
+    STATUS_ACTIVE = 'active'
+    STATUS_PLANNED = 'planned'
+    STATUS_MAINTENANCE = 'maintenance'
+    STATUS_DECOMMISSIONED = 'decommissioned'
+
+    CHOICES = [
+        (STATUS_ACTIVE, 'Active', 'green'),
+        (STATUS_PLANNED, 'Planned', 'cyan'),
+        (STATUS_MAINTENANCE, 'Maintenance', 'yellow'),
+        (STATUS_DECOMMISSIONED, 'Decommissioned', 'gray'),
+    ]
+
+
+class VirtualServerStatusChoices(ChoiceSet):
+    """Operational status for virtual servers.
+
+    Indicates whether a virtual server is actively accepting traffic (active),
+    not yet deployed (planned), or intentionally taken offline (disabled).
+    """
+    key = 'VirtualServer.status'
+
+    STATUS_ACTIVE = 'active'
+    STATUS_PLANNED = 'planned'
+    STATUS_DISABLED = 'disabled'
+
+    CHOICES = [
+        (STATUS_ACTIVE, 'Active', 'green'),
+        (STATUS_PLANNED, 'Planned', 'cyan'),
+        (STATUS_DISABLED, 'Disabled', 'red'),
+    ]
+
+
+class VirtualServerProtocolChoices(ChoiceSet):
+    """Network protocol that a virtual server listener accepts.
+
+    Determines what kind of traffic the virtual server handles. TCP and UDP are
+    layer-4 protocols, while HTTP and HTTPS are layer-7 (application-level).
+    The choice of protocol affects how the load balancer inspects and routes traffic.
+    """
+    key = 'VirtualServer.protocol'
+
+    PROTOCOL_TCP = 'tcp'
+    PROTOCOL_UDP = 'udp'
+    PROTOCOL_HTTP = 'http'
+    PROTOCOL_HTTPS = 'https'
+    PROTOCOL_OTHER = 'other'
+
+    CHOICES = [
+        (PROTOCOL_TCP, 'TCP'),
+        (PROTOCOL_UDP, 'UDP'),
+        (PROTOCOL_HTTP, 'HTTP'),
+        (PROTOCOL_HTTPS, 'HTTPS'),
+        (PROTOCOL_OTHER, 'Other'),
+    ]
+
+
+class PoolMethodChoices(ChoiceSet):
+    """Load balancing algorithm used to distribute traffic among pool members.
+
+    - Round Robin: requests are sent to each member in turn, cycling through the list.
+    - Least Connections: the member with the fewest active connections gets the next
+      request, which is useful when request processing times vary.
+    - IP Hash: the client's source IP determines which member receives the request,
+      providing session persistence (sticky sessions).
+    - Weighted: traffic is distributed proportionally based on each member's weight
+      value, allowing more powerful servers to handle more traffic.
+    """
+    key = 'Pool.method'
+
+    METHOD_ROUND_ROBIN = 'round-robin'
+    METHOD_LEAST_CONNECTIONS = 'least-connections'
+    METHOD_IP_HASH = 'ip-hash'
+    METHOD_WEIGHTED = 'weighted'
+    METHOD_OTHER = 'other'
+
+    CHOICES = [
+        (METHOD_ROUND_ROBIN, 'Round Robin'),
+        (METHOD_LEAST_CONNECTIONS, 'Least Connections'),
+        (METHOD_IP_HASH, 'IP Hash'),
+        (METHOD_WEIGHTED, 'Weighted'),
+        (METHOD_OTHER, 'Other'),
+    ]
+
+
+class PoolProtocolChoices(ChoiceSet):
+    """Network protocol used for communication between the load balancer and pool members.
+
+    This may differ from the virtual server's protocol. For example, a virtual server
+    might accept HTTPS traffic from clients while the pool communicates with backend
+    members over plain HTTP (SSL offloading).
+    """
+    key = 'Pool.protocol'
+
+    PROTOCOL_TCP = 'tcp'
+    PROTOCOL_UDP = 'udp'
+    PROTOCOL_HTTP = 'http'
+    PROTOCOL_HTTPS = 'https'
+    PROTOCOL_OTHER = 'other'
+
+    CHOICES = [
+        (PROTOCOL_TCP, 'TCP'),
+        (PROTOCOL_UDP, 'UDP'),
+        (PROTOCOL_HTTP, 'HTTP'),
+        (PROTOCOL_HTTPS, 'HTTPS'),
+        (PROTOCOL_OTHER, 'Other'),
+    ]
+
+
+class PoolMemberStatusChoices(ChoiceSet):
+    """Operational status for individual pool members.
+
+    - Active: the member is healthy and receiving new traffic.
+    - Drain: the member stops accepting new connections but finishes processing
+      existing ones. This is used for graceful removal during maintenance.
+    - Disabled: the member is completely offline and receives no traffic at all.
+    """
+    key = 'PoolMember.status'
+
+    STATUS_ACTIVE = 'active'
+    STATUS_DRAIN = 'drain'
+    STATUS_DISABLED = 'disabled'
+
+    CHOICES = [
+        (STATUS_ACTIVE, 'Active', 'green'),
+        (STATUS_DRAIN, 'Drain', 'yellow'),
+        (STATUS_DISABLED, 'Disabled', 'red'),
+    ]

netbox_loadbalancer/filtersets.py

@@ -0,0 +1,127 @@
+"""Filter sets for querying and filtering load balancer objects.
+
+Each FilterSet class defines the fields that can be used to filter a model's queryset
+in both the web UI list views and the REST API. They extend NetBox's
+``NetBoxModelFilterSet``, which provides built-in support for tags, custom fields,
+and the ``q`` search parameter.
+
+Filter types used:
+- ``MultipleChoiceFilter``: allows filtering by one or more choice values
+  (e.g. ``?status=active&status=planned``).
+- ``ModelMultipleChoiceFilter``: allows filtering by one or more related object IDs
+  (e.g. ``?loadbalancer_id=1&loadbalancer_id=2``).
+
+The ``search()`` method on each FilterSet handles the ``q`` parameter from the search
+box on list views. It defines which model fields are searched when a user types a
+free-text query.
+"""
+
+import django_filters
+from netbox.filtersets import NetBoxModelFilterSet
+
+from .models import LoadBalancer, VirtualServer, Pool, PoolMember
+from .choices import (
+    LoadBalancerPlatformChoices,
+    LoadBalancerStatusChoices,
+    VirtualServerStatusChoices,
+    VirtualServerProtocolChoices,
+    PoolMethodChoices,
+    PoolProtocolChoices,
+    PoolMemberStatusChoices,
+)
+
+
+class LoadBalancerFilterSet(NetBoxModelFilterSet):
+    """Filters load balancers by platform, status, device, site, and tenant.
+
+    The Meta.fields tuple lists all fields that can be filtered via URL query
+    parameters. Fields like ``device_id``, ``site_id``, and ``tenant_id`` are
+    automatically handled by NetBoxModelFilterSet because they are standard
+    ForeignKey fields on the model.
+    """
+
+    platform = django_filters.MultipleChoiceFilter(choices=LoadBalancerPlatformChoices)
+    status = django_filters.MultipleChoiceFilter(choices=LoadBalancerStatusChoices)
+
+    class Meta:
+        model = LoadBalancer
+        fields = ('id', 'name', 'platform', 'status', 'device_id', 'site_id', 'tenant_id')
+
+    def search(self, queryset, name, value):
+        """Handle the ``q`` search parameter from the list view search box.
+
+        Performs a case-insensitive substring match on the load balancer's name field.
+        For example, searching for "prod" would match "Production-LB-01".
+        """
+        return queryset.filter(name__icontains=value)
+
+
+class PoolFilterSet(NetBoxModelFilterSet):
+    """Filters pools by load balancer, method, and protocol.
+
+    The ``loadbalancer_id`` filter uses ``ModelMultipleChoiceFilter`` which accepts
+    one or more load balancer IDs and returns only pools belonging to those load
+    balancers.
+    """
+
+    loadbalancer_id = django_filters.ModelMultipleChoiceFilter(
+        queryset=LoadBalancer.objects.all(),
+    )
+    method = django_filters.MultipleChoiceFilter(choices=PoolMethodChoices)
+    protocol = django_filters.MultipleChoiceFilter(choices=PoolProtocolChoices)
+
+    class Meta:
+        model = Pool
+        fields = ('id', 'name', 'loadbalancer_id', 'method', 'protocol')
+
+    def search(self, queryset, name, value):
+        """Handle the ``q`` search parameter by matching against the pool name."""
+        return queryset.filter(name__icontains=value)
+
+
+class VirtualServerFilterSet(NetBoxModelFilterSet):
+    """Filters virtual servers by load balancer, status, protocol, port, pool, and tenant.
+
+    This is the most feature-rich FilterSet in the plugin, reflecting the number of
+    filterable attributes on the VirtualServer model. The ``pool_id`` filter allows
+    finding all virtual servers that point to a specific pool.
+    """
+
+    loadbalancer_id = django_filters.ModelMultipleChoiceFilter(
+        queryset=LoadBalancer.objects.all(),
+    )
+    status = django_filters.MultipleChoiceFilter(choices=VirtualServerStatusChoices)
+    protocol = django_filters.MultipleChoiceFilter(choices=VirtualServerProtocolChoices)
+    pool_id = django_filters.ModelMultipleChoiceFilter(
+        queryset=Pool.objects.all(),
+    )
+
+    class Meta:
+        model = VirtualServer
+        fields = ('id', 'name', 'loadbalancer_id', 'status', 'protocol', 'port', 'pool_id', 'tenant_id')
+
+    def search(self, queryset, name, value):
+        """Handle the ``q`` search parameter by matching against the virtual server name."""
+        return queryset.filter(name__icontains=value)
+
+
+class PoolMemberFilterSet(NetBoxModelFilterSet):
+    """Filters pool members by pool, status, device, IP address, port, weight, and priority.
+
+    This FilterSet exposes the widest range of filterable fields, allowing operators
+    to find members by their parent pool, operational status, associated device or
+    IP, specific port numbers, or weight/priority values.
+    """
+
+    pool_id = django_filters.ModelMultipleChoiceFilter(
+        queryset=Pool.objects.all(),
+    )
+    status = django_filters.MultipleChoiceFilter(choices=PoolMemberStatusChoices)
+
+    class Meta:
+        model = PoolMember
+        fields = ('id', 'name', 'pool_id', 'ip_address_id', 'device_id', 'port', 'weight', 'priority', 'status')
+
+    def search(self, queryset, name, value):
+        """Handle the ``q`` search parameter by matching against the pool member name."""
+        return queryset.filter(name__icontains=value)