Skip to content

vmware: derive the NetBox VM name and description with vm_name_regex - #590

Merged
semx merged 1 commit into
developmentfrom
feature/vm-name-regex
Oct 10, 2026
Merged

semx merged 1 commit into
developmentfrom
feature/vm-name-regex

Conversation

@semx

@semx semx commented Oct 10, 2026

Copy link
Copy Markdown
Collaborator

vm_name_regex for #465: a regex applied to the vCenter VM name before any other name handling. Its named group name becomes the NetBox VM name; an optional named group description fills the VM's description. A name the regex does not match is used unchanged (one debug2 line says so), and strip_vm_domain_name still runs afterwards. The option is unset by default, so nothing changes without it.

The example from the issue, ^(?P<name>[^ (]+)(?: \((?P<description>.*)\))?$, turns web01 (production) into the VM web01 with description production. A regex without a name group, or one that does not compile, is rejected when the config is loaded. A name group that takes no part in the match (an optional group) or matches only whitespace leaves the name unchanged with a warning, so a permissive pattern cannot produce a VM without a name. An empty description group sets nothing; a description already in NetBox is kept in that case, the way comments are. A result longer than the NetBox field (64 for the name, 200 for the description) is reported before NetBox cuts it. The description is only sent to NetBox 3.4 and later, where the field exists.

Renaming matters for matching: a VM whose NetBox name changes is no longer found by name + cluster and falls back to the MAC, IP and serial matching that already exists. The resulting name is also what vm_include_filter, vm_exclude_filter and the vm_*_relation options see, and it has to stay unique per cluster: two VMs that rewrite to the same name are reported as duplicates (the warning names the option) and the second is skipped, as before. On a live NetBox 4.7.2 with the vc001 inventory and ^(?P<name>vm\d+)_(?P<description>.*)$, the 18 VMs the regex matched were renamed in place (18 PATCH, no POST, 34 VMs before and after) and got their description; the second run wrote nothing. Users who enable this on an existing NetBox should expect that one-off rename.

Tests: tests/test_vmware_vm_name_regex.py (16): match with and without the description group, a non-matching name, the optional and the blank name group, the empty description group, anchoring at the start of the name, the length warnings, the strip_vm_domain_name order, the unset default, load-time rejection of a regex without the name group and of one that does not compile, and one vcsim run asserting the description lands on the VM object. All 15 test runs fail on development without this change (the vcsim one is skipped on the second capture). Full suite: 295 passed, 1 skipped (development: 280). With the option unset the handler produces the same inventory as development on vc001: 324 objects, byte-identical canonical dump.

@semx
semx requested a review from bb-Ricardo as a code owner October 10, 2026 01:40
The new option vm_name_regex is applied to the vCenter VM name before
any other name handling. Its named group "name" becomes the NetBox VM
name and an optional named group "description" fills the VM's
description. A name the regex does not match is used unchanged, and so
is a name whose "name" group takes no part in the match or matches only
whitespace; strip_vm_domain_name still runs afterwards. The regex is
compiled when the config is loaded and must contain the "name" group.

The resulting name is what the VM filters and relations see and what
NetBox VMs are matched by, so it has to stay unique per cluster; the
warning about a duplicate VM name says so when the option is in use. A
name or description longer than the NetBox field is reported before it
is cut.

The description field is added to the VM data model and is only sent to
NetBox 3.4 and later, which is where the field appeared.

Fixes #465
@semx
semx force-pushed the feature/vm-name-regex branch from 659e126 to b17d3f5 Compare October 10, 2026 01:53
@semx
semx merged commit 24b796d into development Oct 10, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant