proxsync 2.0.0__py3-none-any.whl

pve_sync_plugin/__init__.py

@@ -0,0 +1,46 @@
+"""NetBox plugin entrypoint for Proxmox Sync."""
+
+from netbox.plugins import PluginConfig
+
+__version__ = "2.1.0"
+
+
+class PveSyncPluginConfig(PluginConfig):
+
+    name = "pve_sync_plugin"
+    verbose_name = "Proxmox Sync"
+    description = "Synchronize Proxmox VE and Proxmox Backup Server inventory into NetBox."
+    author = "Proxmox Sync Maintainers"
+    author_email = ""
+    version = __version__
+    base_url = "pve-sync"
+    min_version = "4.5.0"
+    max_version = "4.6.99"
+
+    middleware = []
+    queues = ["default"]
+
+    required_settings = []
+    default_settings = {
+        "netbox_url": "",
+        "netbox_token": "",
+        "telegram_bot_token": "",
+        "telegram_chat_id": "",
+        "webhook_secret": "",
+        "default_cluster_name": "default",
+        "default_netbox_cluster": "Proxmox Cluster",
+        "default_site": "Main Datacenter",
+        "default_cluster_type": "Proxmox",
+        "default_node_role": "PVE",
+        "default_node_type": "Standard Server",
+        "state_db_path": "/var/lib/netbox/pve-sync-state.db",
+        "enable_backup_sync": True,
+    }
+
+    def ready(self):
+        super().ready()
+        from pve_sync_plugin.signals import register_signals
+        register_signals()
+
+
+config = PveSyncPluginConfig

pve_sync_plugin/api/__init__.py

@@ -0,0 +1 @@
+"""PVE Sync Plugin API package."""

pve_sync_plugin/api/serializers.py

@@ -0,0 +1,161 @@
+"""API serializers for PVE Sync plugin models."""
+
+from rest_framework import serializers
+
+from netbox.api.serializers import NetBoxModelSerializer
+
+from pve_sync_plugin.models import (
+    PveBackupStatus,
+    PveClusterConfig,
+    PvePluginSettings,
+    PveSyncJob,
+    PveWebhookEvent,
+)
+
+
+class PveSyncJobSerializer(NetBoxModelSerializer):
+    url = serializers.HyperlinkedIdentityField(
+        view_name="plugins-api:pve_sync_plugin-api:pvesyncjob-detail",
+    )
+    duration = serializers.FloatField(read_only=True)
+    success_rate = serializers.FloatField(read_only=True)
+
+    class Meta:
+        model = PveSyncJob
+        fields = [
+            "id",
+            "url",
+            "display",
+            "cluster_name",
+            "status",
+            "trigger",
+            "start_time",
+            "end_time",
+            "duration",
+            "total_vms",
+            "success_vms",
+            "failed_vms",
+            "success_rate",
+            "nodes_offline",
+            "config_drifts",
+            "tag_changes",
+            "resource_alerts",
+            "details",
+            "triggered_by",
+            "created",
+            "last_updated",
+        ]
+
+
+class PveWebhookEventSerializer(NetBoxModelSerializer):
+    url = serializers.HyperlinkedIdentityField(
+        view_name="plugins-api:pve_sync_plugin-api:pvewebhookevent-detail",
+    )
+
+    class Meta:
+        model = PveWebhookEvent
+        fields = [
+            "id",
+            "url",
+            "display",
+            "event_type",
+            "node",
+            "vmid",
+            "vm_name",
+            "raw_data",
+            "processed",
+            "processed_at",
+            "processing_error",
+            "sync_job",
+            "received_at",
+            "created",
+            "last_updated",
+        ]
+
+
+class PveClusterConfigSerializer(NetBoxModelSerializer):
+    url = serializers.HyperlinkedIdentityField(
+        view_name="plugins-api:pve_sync_plugin-api:pveclusterconfig-detail",
+    )
+
+    class Meta:
+        model = PveClusterConfig
+        fields = [
+            "id",
+            "url",
+            "display",
+            "name",
+            "description",
+            "pve_host",
+            "pve_user",
+            "pve_token",
+            "pve_secret",
+            "pve_verify_ssl",
+            "netbox_site",
+            "netbox_cluster_type",
+            "netbox_cluster",
+            "enabled",
+            "sync_schedule",
+            "last_sync",
+            "last_sync_status",
+            "created",
+            "last_updated",
+        ]
+        # Never expose credentials in API responses
+        extra_kwargs = {
+            "pve_token": {"write_only": True},
+            "pve_secret": {"write_only": True},
+        }
+
+
+class PveBackupStatusSerializer(NetBoxModelSerializer):
+    url = serializers.HyperlinkedIdentityField(
+        view_name="plugins-api:pve_sync_plugin-api:pvebackupstatus-detail",
+    )
+    backup_age_days = serializers.IntegerField(read_only=True)
+    is_stale = serializers.BooleanField(read_only=True)
+
+    class Meta:
+        model = PveBackupStatus
+        fields = [
+            "id",
+            "url",
+            "display",
+            "vm",
+            "last_backup",
+            "backup_size",
+            "backup_status",
+            "backup_path",
+            "next_backup",
+            "pve_backup_id",
+            "backup_age_days",
+            "is_stale",
+            "created",
+            "last_updated",
+        ]
+
+
+class PvePluginSettingsSerializer(NetBoxModelSerializer):
+    url = serializers.HyperlinkedIdentityField(
+        view_name="plugins-api:pve_sync_plugin-api:pvepluginsettings-detail",
+    )
+
+    class Meta:
+        model = PvePluginSettings
+        fields = [
+            "id",
+            "url",
+            "pve_api_host",
+            "pve_api_user",
+            "pve_api_verify_ssl",
+            "netbox_url",
+            "default_cluster_name",
+            "default_netbox_cluster",
+            "default_site",
+            "default_cluster_type",
+            "default_node_role",
+            "default_node_type",
+            "state_db_path",
+            "enable_backup_sync",
+        ]
+        # Never expose secrets via API

pve_sync_plugin/api/urls.py

@@ -0,0 +1,27 @@
+"""NetBox REST API routes for the PVE Sync plugin.
+
+Mounted by NetBox under /api/plugins/pve-sync/.
+"""
+
+from django.urls import path
+from netbox.api.routers import NetBoxRouter
+
+from pve_sync_plugin import views as plugin_views
+
+from . import views as api_views
+
+app_name = "pve_sync_plugin-api"
+
+router = NetBoxRouter()
+router.APIRootView.cls_name = "PveSyncPluginRootView"
+
+router.register("jobs", api_views.PveSyncJobViewSet)
+router.register("events", api_views.PveWebhookEventViewSet)
+router.register("clusters", api_views.PveClusterConfigViewSet)
+router.register("backup-status", api_views.PveBackupStatusViewSet)
+router.register("settings", api_views.PvePluginSettingsViewSet)
+
+urlpatterns = [
+    path("webhook/", plugin_views.webhook_receiver, name="webhook"),
+    *router.urls,
+]

pve_sync_plugin/api/views.py

@@ -0,0 +1,94 @@
+"""API ViewSets for PVE Sync plugin models."""
+
+from rest_framework.decorators import action
+from rest_framework.response import Response
+from rest_framework import status as drf_status
+
+from netbox.api.viewsets import NetBoxModelViewSet
+
+from pve_sync_plugin.filtersets import (
+    PveBackupStatusFilterSet,
+    PveClusterConfigFilterSet,
+    PveSyncJobFilterSet,
+    PveWebhookEventFilterSet,
+)
+from pve_sync_plugin.models import (
+    PveBackupStatus,
+    PveClusterConfig,
+    PvePluginSettings,
+    PveSyncJob,
+    PveWebhookEvent,
+)
+
+from .serializers import (
+    PveBackupStatusSerializer,
+    PveClusterConfigSerializer,
+    PvePluginSettingsSerializer,
+    PveSyncJobSerializer,
+    PveWebhookEventSerializer,
+)
+
+
+class PveSyncJobViewSet(NetBoxModelViewSet):
+    queryset = PveSyncJob.objects.all()
+    serializer_class = PveSyncJobSerializer
+    filterset_class = PveSyncJobFilterSet
+
+    @action(detail=False, methods=["post"], url_path="trigger")
+    def trigger_sync(self, request):
+        """POST /api/plugins/pve-sync/jobs/trigger/ — start a new sync."""
+        from pve_sync_plugin.tasks import enqueue_sync
+
+        cluster_name = request.data.get("cluster", "default")
+
+        if cluster_name != "default":
+            if not PveClusterConfig.objects.filter(
+                name=cluster_name, enabled=True
+            ).exists():
+                return Response(
+                    {"detail": f"Cluster '{cluster_name}' not found or disabled."},
+                    status=drf_status.HTTP_404_NOT_FOUND,
+                )
+
+        job = PveSyncJob.objects.create(
+            cluster_name=cluster_name,
+            status="pending",
+            trigger="api",
+            triggered_by=request.user if request.user.is_authenticated else None,
+            details={},
+        )
+
+        try:
+            enqueue_sync(job)
+        except Exception as exc:
+            return Response(
+                {"detail": f"Failed to enqueue: {exc}"},
+                status=drf_status.HTTP_500_INTERNAL_SERVER_ERROR,
+            )
+
+        job.refresh_from_db()
+        serializer = self.get_serializer(job)
+        return Response(serializer.data, status=drf_status.HTTP_202_ACCEPTED)
+
+
+class PveWebhookEventViewSet(NetBoxModelViewSet):
+    queryset = PveWebhookEvent.objects.all()
+    serializer_class = PveWebhookEventSerializer
+    filterset_class = PveWebhookEventFilterSet
+
+
+class PveClusterConfigViewSet(NetBoxModelViewSet):
+    queryset = PveClusterConfig.objects.all()
+    serializer_class = PveClusterConfigSerializer
+    filterset_class = PveClusterConfigFilterSet
+
+
+class PveBackupStatusViewSet(NetBoxModelViewSet):
+    queryset = PveBackupStatus.objects.select_related("vm")
+    serializer_class = PveBackupStatusSerializer
+    filterset_class = PveBackupStatusFilterSet
+
+
+class PvePluginSettingsViewSet(NetBoxModelViewSet):
+    queryset = PvePluginSettings.objects.all()
+    serializer_class = PvePluginSettingsSerializer

pve_sync_plugin/apps.py

@@ -0,0 +1,5 @@
+"""
+Compatibility shim — NetBox uses the PluginConfig defined in __init__.py.
+This file is kept so Django does not auto-discover a conflicting AppConfig.
+"""
+from pve_sync_plugin import PveSyncPluginConfig  # noqa: F401

pve_sync_plugin/choices.py

@@ -0,0 +1,57 @@
+"""Enumerated choices for PVE Sync plugin models."""
+
+from django.db import models
+
+
+class SyncJobStatusChoices(models.TextChoices):
+    STATUS_PENDING = "pending", "Pending"
+    STATUS_RUNNING = "running", "Running"
+    STATUS_SUCCESS = "success", "Success"
+    STATUS_FAILED = "failed", "Failed"
+    STATUS_PARTIAL = "partial", "Partial Success"
+
+
+class SyncJobTriggerChoices(models.TextChoices):
+    TRIGGER_MANUAL = "manual", "Manual"
+    TRIGGER_SCHEDULED = "scheduled", "Scheduled"
+    TRIGGER_WEBHOOK = "webhook", "Webhook"
+    TRIGGER_API = "api", "API Call"
+
+
+class WebhookEventChoices(models.TextChoices):
+    VM_STARTED = "vm-started", "VM Started"
+    VM_STOPPED = "vm-stopped", "VM Stopped"
+    VM_MIGRATED = "vm-migrated", "VM Migrated"
+    NODE_ONLINE = "node-online", "Node Online"
+    NODE_OFFLINE = "node-offline", "Node Offline"
+    BACKUP_DONE = "backup-done", "Backup Completed"
+    BACKUP_FAILED = "backup-failed", "Backup Failed"
+    CONFIG_CHANGE = "configuration-change", "Configuration Change"
+
+
+class BackupStatusChoices(models.TextChoices):
+    STATUS_SUCCESS = "success", "Success"
+    STATUS_FAILED = "failed", "Failed"
+    STATUS_RUNNING = "running", "Running"
+    STATUS_UNKNOWN = "unknown", "Unknown"
+
+
+class SyncScheduleChoices(models.TextChoices):
+    DISABLED = "disabled", "Disabled"
+    HOURLY = "hourly", "Hourly"
+    EVERY_3H = "every_3h", "Every 3 hours"
+    EVERY_6H = "every_6h", "Every 6 hours"
+    DAILY = "daily", "Daily"
+    WEEKLY = "weekly", "Weekly"
+
+
+class DriftTypeChoices(models.TextChoices):
+    HARDWARE = "hardware", "硬體配置變更"
+    MIGRATION = "migration", "VM 遷移"
+    IP_CHANGE = "ip_change", "IP 位址變更"
+    TAG_CHANGE = "tag_change", "標籤變更"
+    VM_CREATED = "vm_created", "VM 新增"
+    VM_DELETED = "vm_deleted", "VM 刪除"
+    VM_RENAMED = "vm_renamed", "VM 更名"
+    DISK_CHANGE = "disk_change", "磁碟配置變更"
+    DESCRIPTION_CHANGE = "description_change", "描述變更"

pve_sync_plugin/filtersets.py

@@ -0,0 +1,137 @@
+"""FilterSets for PVE Sync plugin models (used by list views and API)."""
+
+import django_filters
+
+from netbox.filtersets import NetBoxModelFilterSet
+
+from .choices import (
+    BackupStatusChoices,
+    DriftTypeChoices,
+    SyncJobStatusChoices,
+    SyncJobTriggerChoices,
+    SyncScheduleChoices,
+    WebhookEventChoices,
+)
+from .models import (
+    PbsServerConfig,
+    PveBackupStatus,
+    PveClusterConfig,
+    PveDriftEvent,
+    PveSyncJob,
+    PveWebhookEvent,
+)
+
+
+class PveSyncJobFilterSet(NetBoxModelFilterSet):
+    """Filter sync jobs by status, trigger, cluster, and time range."""
+
+    status = django_filters.MultipleChoiceFilter(choices=SyncJobStatusChoices.choices)
+    trigger = django_filters.MultipleChoiceFilter(choices=SyncJobTriggerChoices.choices)
+    cluster_name = django_filters.CharFilter(lookup_expr="icontains")
+    start_time_after = django_filters.DateTimeFilter(
+        field_name="start_time", lookup_expr="gte"
+    )
+    start_time_before = django_filters.DateTimeFilter(
+        field_name="start_time", lookup_expr="lte"
+    )
+
+    class Meta:
+        model = PveSyncJob
+        fields = ["id", "status", "trigger", "cluster_name"]
+
+    def search(self, queryset, name, value):
+        if not value.strip():
+            return queryset
+        return queryset.filter(cluster_name__icontains=value)
+
+
+class PveWebhookEventFilterSet(NetBoxModelFilterSet):
+    """Filter webhook events by type, processing state, and VM."""
+
+    event_type = django_filters.MultipleChoiceFilter(
+        choices=WebhookEventChoices.choices
+    )
+    processed = django_filters.BooleanFilter()
+    vmid = django_filters.NumberFilter()
+    node = django_filters.CharFilter(lookup_expr="icontains")
+
+    class Meta:
+        model = PveWebhookEvent
+        fields = ["id", "event_type", "processed", "vmid", "node"]
+
+    def search(self, queryset, name, value):
+        if not value.strip():
+            return queryset
+        return queryset.filter(vm_name__icontains=value)
+
+
+class PveClusterConfigFilterSet(NetBoxModelFilterSet):
+    """Filter cluster configs by name, enabled state, and schedule."""
+
+    enabled = django_filters.BooleanFilter()
+    sync_schedule = django_filters.MultipleChoiceFilter(
+        choices=SyncScheduleChoices.choices
+    )
+
+    class Meta:
+        model = PveClusterConfig
+        fields = ["id", "name", "enabled", "sync_schedule"]
+
+    def search(self, queryset, name, value):
+        if not value.strip():
+            return queryset
+        return queryset.filter(name__icontains=value) | queryset.filter(
+            description__icontains=value
+        )
+
+
+class PbsServerConfigFilterSet(NetBoxModelFilterSet):
+    """Filter PBS server configs by name and enabled state."""
+
+    enabled = django_filters.BooleanFilter()
+
+    class Meta:
+        model = PbsServerConfig
+        fields = ["id", "name", "enabled"]
+
+    def search(self, queryset, name, value):
+        if not value.strip():
+            return queryset
+        return queryset.filter(name__icontains=value) | queryset.filter(
+            description__icontains=value
+        )
+
+
+class PveDriftEventFilterSet(NetBoxModelFilterSet):
+    """Filter drift events by type, VM name, cluster, and notification state."""
+
+    drift_type = django_filters.MultipleChoiceFilter(choices=DriftTypeChoices.choices)
+    vm_name = django_filters.CharFilter(lookup_expr="icontains")
+    cluster_name = django_filters.CharFilter(lookup_expr="icontains")
+    notified_telegram = django_filters.BooleanFilter()
+
+    class Meta:
+        model = PveDriftEvent
+        fields = ["id", "drift_type", "vmid", "cluster_name", "notified_telegram"]
+
+    def search(self, queryset, name, value):
+        if not value.strip():
+            return queryset
+        return queryset.filter(vm_name__icontains=value) | queryset.filter(cluster_name__icontains=value)
+
+
+class PveBackupStatusFilterSet(NetBoxModelFilterSet):
+    """Filter backup statuses by state."""
+
+    backup_status = django_filters.MultipleChoiceFilter(
+        choices=BackupStatusChoices.choices
+    )
+
+    class Meta:
+        model = PveBackupStatus
+        fields = ["id", "backup_status"]
+
+    def search(self, queryset, name, value):
+        if not value.strip():
+            return queryset
+        return queryset.filter(vm__name__icontains=value)