Skip to content

vmware: resolve the VM tenant from resource pool, folder and cluster #589

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
semx merged 1 commit into from
Oct 10, 2026
Merged

vmware: resolve the VM tenant from resource pool, folder and cluster #589

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -296,8 +296,9 @@ Check out the documentations for the different sources
netbox-sync provides various filtering capabilities to control what objects are synced from sources to NetBox:

1. **General VM filtering**: Use `vm_include_filter` and `vm_exclude_filter` to include or exclude VMs by name.
2. **Tag-based VM filtering**: Use `vm_exclude_by_tag_filter` to exclude VMs with specific vCenter tags.
3. **Partial information filtering**:
2. **Resource pool filtering**: Use `vm_include_by_resource_pool_filter` and `vm_exclude_by_resource_pool_filter` to include or exclude VMs by the resource pool they are organized in.
3. **Tag-based VM filtering**: Use `vm_exclude_by_tag_filter` to exclude VMs with specific vCenter tags.
4. **Partial information filtering**:
- Use `vm_exclude_disk_sync` to exclude disk synchronization for VMs matching specific name patterns.
- Use `vm_exclude_disk_sync_by_tag` to exclude disk synchronization for VMs with specific vCenter tags.

Expand Down
29 changes: 29 additions & 0 deletions docs/source_vmware.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -99,15 +99,44 @@ First VM is filtered:
* VM has a cluster and is it permitted
* skip VMs with same name and cluster if already parsed
* does the VM pass the `vm_include_filter` and `vm_exclude_filter`
* does the VM pass the `vm_include_by_resource_pool_filter` and `vm_exclude_by_resource_pool_filter`

Then all necessary VM data will be collected:<br>
platform, virtual interfaces, virtual cpu/disk/memory interface VLANs, IP addresses

Primary IPv4/6 will be determined by interface that provides the default route for this VM.

The resource pool filters are applied to the resource pool path (i.e. `Parent/Child`, the
cluster root pool `Resources` excluded) and to the plain resource pool name of the VM: the VM
is kept when either matches the include filter and skipped when either matches the exclude
filter. A VM placed directly in the cluster root pool has an empty pool path and is matched by
its plain pool name `Resources` only. A VM without a resource pool (a template) passes both
filters.

**Note:**<br>
IP address information can only be extracted if guest tools are installed and running.

#### 5b. Resolve the tenant of a VM

The tenant of a VM is resolved from different sources. The first match wins:

1. `vm_tenant_relation` matched against the VM name
2. `vm_tenant_resource_pool_relation` matched against the resource pool path and then
against the plain resource pool name of the VM
3. `vm_tenant_folder_relation` matched against the VM folder path (relative to the
datacenter's VM folder) and then against the plain folder name of the VM

An empty path (a VM in the cluster root pool, or directly in the datacenter's VM folder)
is not matched; such a VM is matched by its plain pool name `Resources` or folder name
`vm` only.
4. if `vm_tenant_inherit_from_cluster` is enabled: the tenant resolved via
`cluster_tenant_relation` for this cluster or, if that relation matched nothing, the
tenant assigned to the cluster in NetBox

A tenant already set on an existing NetBox VM is kept if `overwrite_vm_tenant` is disabled.
If a tenant was resolved for the VM, its IP addresses inherit it through the `device` step
of `ip_tenant_inheritance_order`.

#### 6. Sync VMware Tools guest hostname to a custom field

The vCenter VM name (used as the NetBox VM `name`) and the hostname reported from inside the
Expand Down
66 changes: 65 additions & 1 deletion module/sources/vmware/config.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,7 +106,20 @@ def __init__(self):
ConfigOption("host_include_filter", str),
ConfigOption("vm_exclude_filter",
str, description="simply include/exclude VMs"),
ConfigOption("vm_include_filter", str)
ConfigOption("vm_include_filter", str),
ConfigOption("vm_exclude_by_resource_pool_filter",
str,
description="""This will only exclude VMs from sync based on the resource
pool they are organized in. A VM matching this filter is skipped entirely,
the same way a matching 'vm_exclude_filter' skips it. The regex is applied
to the resource pool path (i.e. "Parent/Child", the cluster root pool
"Resources" is excluded from the path) and to the plain resource pool name
of the VM; a VM is skipped when either matches. A VM placed directly in
the cluster root pool has an empty pool path and is matched by its plain
pool name "Resources" only. A VM without a resource pool (a template)
passes the filter. 'vm_include_by_resource_pool_filter' works the same
way, a VM is kept when its pool path or its plain pool name matches."""),
ConfigOption("vm_include_by_resource_pool_filter", str)
]),
ConfigOption("vm_exclude_by_tag_filter",
str,
Expand Down Expand Up @@ -192,6 +205,50 @@ def __init__(self):
config_example="Cluster_NYC.* = Customer A"),
ConfigOption("host_tenant_relation", str, config_example="esxi300.* = Infrastructure"),
ConfigOption("vm_tenant_relation", str, config_example="grafana.* = Infrastructure"),
ConfigOption("vm_tenant_resource_pool_relation",
str,
description="""This option defines which tenant is assigned to a VM based on the
vCenter resource pool it is organized in. This is done with a comma
separated key = value list.
key: defines the resource pool path as regex. The path is the resource
pool hierarchy up to (excluding) the cluster root pool, i.e.
"Parent/Child". The plain resource pool name of the VM is matched
as well. A VM placed directly in the cluster root pool has an
empty pool path, which is not matched, and the plain pool name
"Resources".
value: defines the NetBox tenant name (use quotes if name contains commas)
The tenant of a VM is resolved in this order: 'vm_tenant_relation',
'vm_tenant_resource_pool_relation', 'vm_tenant_folder_relation' and
finally, if 'vm_tenant_inherit_from_cluster' is enabled, the tenant of
the cluster. The first match wins.
""",
config_example="Customers/.* = Customer A, Sandbox = Test"),
ConfigOption("vm_tenant_folder_relation",
str,
description="""This option defines which tenant is assigned to a VM based on the
vCenter VM folder it is organized in. This is done with a comma
separated key = value list.
key: defines the VM folder path as regex. The path is the folder
hierarchy relative to the datacenter's VM folder, i.e.
"Dept-A/Prod". The plain folder name of the VM is matched as
well. A VM placed directly in the datacenter's VM folder has an
empty folder path, which is not matched, and the plain folder
name "vm".
value: defines the NetBox tenant name (use quotes if name contains commas)
The tenant of a VM is resolved in this order: 'vm_tenant_relation',
'vm_tenant_resource_pool_relation', 'vm_tenant_folder_relation' and
finally, if 'vm_tenant_inherit_from_cluster' is enabled, the tenant of
the cluster. The first match wins.
""",
config_example="Customers/.* = Customer A, Templates = Infrastructure"),
ConfigOption("vm_tenant_inherit_from_cluster",
bool,
description="""define if a VM inherits the tenant of its cluster if no tenant
could be resolved via 'vm_tenant_relation', 'vm_tenant_resource_pool_relation'
or 'vm_tenant_folder_relation'. The inherited tenant is the one resolved
through 'cluster_tenant_relation' for this cluster or, if that relation
matched nothing, the tenant assigned to the cluster in NetBox.""",
default_value=False),
ConfigOption("host_platform_relation",
str,
description="""\
Expand Down Expand Up @@ -498,6 +555,13 @@ def __init__(self):
description="""define if the platform of the VM discovered overwrites the VM
platform in NetBox.""",
default_value=True),
ConfigOption("overwrite_vm_tenant",
bool,
description="""define if the tenant resolved for a VM overwrites the tenant of the
VM in NetBox. If disabled, a tenant that is already set on an existing NetBox VM
is kept, even if a different tenant was resolved. A VM without a tenant in NetBox
still gets the resolved tenant.""",
default_value=True),
ConfigOption("host_management_interface_match",
str,
description="""set a matching value for ESXi host management interface description
Expand Down
Loading
Loading