Feature: Zero-touch Zabbix provisioning via NetBox site inheritance + regex template rules

[berlikm]

Motivation

In deployments with hundreds or thousands of devices across multiple sites, configuring per-device Zabbix assignments (proxy, templates, tags, hostgroups, interfaces) does not scale. We need zero-touch provisioning: when a device or VM appears in NetBox (via netbox-sync, NAPALM, or manual entry), it should automatically be synced to Zabbix with the correct proxy, templates, tags, hostgroups, and interface — without any per-device configuration in nbxSync.

Problem

nbxSync currently requires a ZabbixServerAssignment (proxy) on every individual device or VM. For 2,000+ devices across 20+ sites, this means 2,000+ manual assignments. Similarly, templates need to be assigned per-platform, but platforms are dynamic — vCenter creates dozens of variants (e.g. "Windows Server 2022 (Build 20348.5400)") that all need the same Zabbix template.

Proposed Solution

A set of features that work together to achieve zero-touch provisioning:

1. Site-level inheritance (PR #115)

Assignments (proxy, templates, tags, hostgroups, interfaces, inventory) made at the Site, SiteGroup, or Region level are inherited by all devices and VMs at that site or below. This means:

• One ZabbixServerAssignment per site → all devices at that site get the correct Zabbix proxy
• One ZabbixHostgroupAssignment per site → all devices inherit the site hostgroup
• SiteGroup parent traversal → assignments on a parent SiteGroup (e.g. "CH") are inherited by all child sites (e.g. "CH-STA-L26")

Example: Assigning a proxy to SiteGroup "CH" covers all Swiss sites. A new site "CH-STA-L99" automatically inherits the proxy when it's created — no configuration needed.

2. Regex-based template rules (PRs #117, #118, #119)

A ZabbixTemplateRule model that matches the device's platform name against a regex pattern and automatically assigns the correct Zabbix template (+ optionally hostgroup and tag). This solves the platform-variant explosion:

• Pattern Windows matches "Windows Server 2019", "Windows Server 2022 (Build 20348.5400)", etc.
• Pattern Ubuntu|Debian|Linux matches all Linux variants
• Each rule can also assign a hostgroup (e.g. "Windows") and a tag (e.g. os_family=Windows) in the same rule

Rules include a 2-second regex timeout to prevent catastrophic backtracking (ReDoS), with patterns validated at save time.

3. Device-context Jinja2 rendering (PRs #110, #111)

When tags and hostgroups are inherited from a Site, Platform, or Role, Jinja2 templates are now rendered against the actual device/VM (not the Site or Role). This enables:

• environment tag that detects Prod/Dev/QA from the device name pattern
• critical tag that reads the device's NetBox native tag
• Hostgroup values like {{ object.name }} that resolve to the device name

4. Tag-based host exclusion (PR #113)

A do_not_monitor tag (configurable via exclude_tag setting) assigned to any object in the inheritance chain (Role, Platform, Site, etc.) excludes the host from sync entirely. Previously-synced hosts are deleted from Zabbix. Useful for excluding device classes that should never be monitored (e.g. 1,400 desktop PCs).

5. Additional fixes (PRs #112, #114, #116)

• SiteGroup parent traversal (Fix: Add SiteGroup parent traversal to inheritance chain #112): Inheritance chain traverses the full SiteGroup hierarchy
• Inherited sync status (Fix: Show neutral indicator for inherited sync status #114): UI shows a neutral indicator for inherited assignments instead of the misleading "Never synced" red X
• ConfigGroup form (Feature: Add Site/SiteGroup/Region to ConfigGroupAssignment form #116): Site/SiteGroup/Region added to the ConfigGroupAssignment form

Architecture

Device/VM appears in NetBox (via netbox-sync, NAPALM, etc.)
    |
nbxSync resolves via get_assigned_zabbixobjects():
    Layer 1 (regex rule): Platform "Windows" -> template + hostgroup + tag
    Layer 2 (role): Role "MSSQL" -> template + hostgroup + tag
    Layer 3 (site): Site "CH-ZRH-ZH4" -> proxy + hostgroup + interface
    Layer 4 (site group): Parent SiteGroup "CH" -> proxy (if not on site)
    |
    _is_excluded() -- checks do_not_monitor tag -> skip if present
    |
HostSync -- POST to Zabbix with:
    Templates (from regex rules + role assignments)
    Tags (rendered with device context, deduplicated)
    Hostgroups (from site + role + regex rules)
    Interface (cloned from ConfigGroup with device's primary IP)
    Proxy (inherited from Site/SiteGroup)
    Inventory (from Platform)

Our Use Case

We operate ~2,000 devices across 23 sites in 6 countries. We use:

• Site-level proxy assignments (one per site, inherited by all devices)
• ZabbixTemplateRule for OS-family template matching (Windows, Linux, EXOS, IQ Engine, FortiOS, ESXi)
• do_not_monitor tag on the "Desktop PC" role to exclude 1,400 PCs
• Jinja2 environment tag for Prod/Dev/QA detection from device name patterns
• ConfigGroup at SiteGroup level for SNMP/agent interfaces

PRs

PR	Title	Review order
#115	Site, SiteGroup, Region as assignment targets with inheritance	1st (foundation)
#116	ConfigGroupAssignment form for Site/SiteGroup/Region	2nd (independent)
#117	ZabbixTemplateRule: regex-based template assignment	2nd (independent)
#118	Fix ZabbixTemplateRule: create wrapper	3rd (after #117)
#119	Extend ZabbixTemplateRule: hostgroup + tag	4th (after #118)
#110	Pass device context to tag render	3rd (after #115)
#111	Render tag values with device context in ObjectViewTable	4th (after #110)
#112	SiteGroup parent traversal	3rd (after #115)
#113	Tag-based host exclusion (exclude_tag)	3rd (after #115)
#114	Neutral indicator for inherited sync status	3rd (after #115)

Recommended review order: #115 first, then #116/#117 independently, then the rest in dependency order.

After #115 is merged, dependent PRs can be rebased on development to show only their own commits.

Testing

All PRs have been tested end-to-end on our dev NetBox + Zabbix 7.0.28:

• Device sync: proxy, hostgroups, tags, and interface correctly inherited from Site/SiteGroup
• VM sync: regex template rule matched "Windows" platform, assigned template + hostgroup + tag
• Jinja2 tags rendered with device context (environment tag detected from VM name)
• Exclusion: do_not_monitor tag correctly excludes host from sync and deletes existing Zabbix host
• SiteGroup parent inheritance: device inherits proxy from parent SiteGroup

All 1,076 existing tests pass + 24 new tests across the PRs.

We're happy to adjust the approach based on feedback. The goal is to reduce per-device configuration to zero while staying within nbxSync's existing patterns.

[berlikm]

Complete zero-touch implementation update

All open contributor PRs were re-inventoried. The feature set spans #110-#119 and #122-#125; the merge plan below includes every PR and the migration collisions between the stacks.

Complete open PR inventory

PR	State	Role / dependency
#110	Ready, mergeable	Device/VM context for inherited Jinja2 tag rendering; rebase after #115
#111	Ready, mergeable	Device/VM context in tag tables; depends on #110
#112	Ready, mergeable	Legacy one-hop SiteGroup parent path; functionally superseded by recursive #124 and should not be merged independently
#113	Ready, mergeable	Tag-based exclusion; rebase after #115 and merge before lifecycle PR #125
#114	Ready, mergeable	Neutral inherited sync status; rebase after #115
#115	Ready, mergeable	Site/SiteGroup/Region inheritance foundation; includes missing assignment-choice migration 0013
#116	Ready, mergeable	ConfigGroup Site/SiteGroup/Region form; rebase after #115
#117	Ready, mergeable	Regex template-rule foundation; rebase after #115 and renumber its current 0013 migration
#118	Ready, mergeable	Correct template-assignment wrapper; depends on #117
#119	Ready, mergeable	Template-rule hostgroup/tag extension; depends on #118 and renumbering its current 0014 migration
#122	Ready, mergeable	Enables CI for pushes/PRs targeting development; must merge first
#123	Ready, mergeable	Periodic Device/VM reconciliation, stable model references, deterministic RQ IDs, active-job deduplication and metrics
#124	Draft, mergeable	Recursive SiteGroup/Region/DeviceRole ancestry; depends on #115 and supersedes #112
#125	Draft, mergeable	Durable ZabbixHostBinding lifecycle; integrates #123/#124 and should incorporate #113 after dependencies merge

No PR currently has a status check because #122 has not yet landed on development.

Durable lifecycle correction

The earlier hostname-based inherited-host deletion approach has been removed. PR #125 now persists immutable Zabbix identity as:

(Zabbix server, NetBox content type, NetBox object ID) -> Zabbix hostid

This provides rename on the same host ID, delete/exclusion/decommission/hard-delete by host ID, managed-tag adoption, fail-closed unmanaged-name handling, duplicate-identity conflict detection, legacy host-ID migration, missing-remote recovery and assignment-removal retirement.

Periodic reconciliation uses:

currently covered objects UNION objects with durable bindings

It skips already queued/running jobs across overlapping runs and reloads targets from (app_label, model, pk) instead of pickled model instances. Production remains configured for a recommended 360-minute interval because a full 1,127-host run takes about 80 minutes.

Migration sequencing

The open branches currently contain overlapping migration numbers:

• Feature: Add Site, SiteGroup, and Region as assignment targets with inheritance #115: 0013_alter_zabbixhostgroupassignment...
• Feature: Add ZabbixTemplateRule for regex-based template assignment by platform name #117: 0013_zabbixtemplaterule.py
• Feature: Extend ZabbixTemplateRule with optional hostgroup and tag assignment #119: 0014_zabbixtemplaterule_hostgroup_tag.py
• fix(delete): lifecycle handling for inherited hosts #125: 0014_zabbixhostbinding.py

These are valid only on their isolated branches. After #115 merges, dependent branches must be rebased and migrations renumbered in final merge order. Recommended sequence:

1. Feature: Add Site, SiteGroup, and Region as assignment targets with inheritance #115 keeps 0013.
2. Rebase Feature: Add ZabbixTemplateRule for regex-based template assignment by platform name #117; rename its template-rule migration to 0014 and point it at Feature: Add Site, SiteGroup, and Region as assignment targets with inheritance #115's 0013.
3. Rebase Fix: Create ZabbixTemplateAssignment wrapper for regex rules #118 on merged Feature: Add ZabbixTemplateRule for regex-based template assignment by platform name #117.
4. Rebase Feature: Extend ZabbixTemplateRule with optional hostgroup and tag assignment #119; rename its extension migration to 0015.
5. Rebase fix(delete): lifecycle handling for inherited hosts #125 after the template chain and rename the binding migration to 0016.

If #125 is intentionally merged before #117-#119, reverse the later numbers instead; do not merge parallel 0013/0014 leaves without an explicit merge migration.

Verification

Final integrated lifecycle stack (fix/inherited-host-lifecycle, head 6bbcb94):

• 80 focused zero-touch/regression tests passed;
• full CI-isolated nbxSync suite: 1,104 tests passed;
• makemigrations --check: No changes detected;
• ruff format --check nbxsync: all 367 files formatted.

Architecture correction: tags, macros and inventory render against the actual Device/VM; hostgroups intentionally render against their assigned Site/Role/etc.

Recommended merge order

1. Maintainer merges ci: run CI on development branch pushes and PRs #122; contributor lacks MergePullRequest permission.
2. Re-trigger CI on all open PRs.
3. Merge Feature: Add Site, SiteGroup, and Region as assignment targets with inheritance #115 and independent fix(systemjobs): expand SyncObjectsJob to enumerate Device/VM descendants #123 after green CI.
4. Rebase and merge Feature: Add Site/SiteGroup/Region to ConfigGroupAssignment form #116, Fix: Pass device context to tag render for Jinja2 values #110 -> Fix: Render tag values with device context in ObjectViewTable #111, Feature: Add tag-based host exclusion via exclude_tag setting #113, and Fix: Show neutral indicator for inherited sync status #114.
5. Close or replace Fix: Add SiteGroup parent traversal to inheritance chain #112 with fix(inheritance): recursive SiteGroup/Region/Role ancestor traversal #124; rebase fix(inheritance): recursive SiteGroup/Region/Role ancestor traversal #124 onto development, mark ready and merge.
6. Rebase/renumber and merge Feature: Add ZabbixTemplateRule for regex-based template assignment by platform name #117 -> Fix: Create ZabbixTemplateAssignment wrapper for regex rules #118 -> Feature: Extend ZabbixTemplateRule with optional hostgroup and tag assignment #119.
7. Rebase fix(delete): lifecycle handling for inherited hosts #125 onto the resulting development, incorporate any Feature: Add tag-based host exclusion via exclude_tag setting #113 conflict resolution, rename its migration to the next number, mark ready and merge.
8. Enable backgroundsync.objects.enabled=True with interval=360 in production.