Update virtualization models documentation

docs/models/dcim/device.md

@@ -72,6 +72,13 @@ The device's operational status.
 
 A device may be associated with a particular [platform](./platform.md) to indicate its operating system. Note that only platforms assigned to the associated manufacturer (or to no manufacturer) will be available for selection.
 
+### Primary IPv4 & IPv6 Addresses
+
+Each device may designate one primary IPv4 address and/or one primary IPv6 address for management purposes.
+
+!!! tip
+    NetBox will prefer IPv6 addresses over IPv4 addresses by default. This can be changed by setting the `PREFER_IPV4` configuration parameter.
+
 ### Cluster
 
 If this device will serve as a host for a virtualization [cluster](../virtualization/cluster.md), it can be assigned here. (Host devices can also be assigned by editing the cluster.)

docs/models/virtualization/cluster.md

@@ -1,5 +1,28 @@
 # Clusters
 
-A cluster is a logical grouping of physical resources within which virtual machines run. A cluster must be assigned a type (technological classification) and operational status, and may optionally be assigned to a cluster group, site, and/or tenant. Each cluster must have a unique name within its assigned group and/or site, if any.
+A cluster is a logical grouping of physical resources within which [virtual machines](./virtualmachine.md) run. Physical [devices](../dcim/device.md) may be associated with clusters as hosts. This allows users to track on which host(s) a particular virtual machine may reside.
 
-Physical devices may be associated with clusters as hosts. This allows users to track on which host(s) a particular virtual machine may reside. However, NetBox does not support pinning a specific VM within a cluster to a particular host device.
+## Fields
+
+### Name
+
+A human-friendly name for the cluster. Must be unique within the assigned group and site.
+
+### Type
+
+The [cluster type](./clustertype.md) assigned for this cluster.
+
+### Group
+
+The [cluster group](./clustergroup.md) to which this cluster belongs.
+
+### Status
+
+The cluster's operational status.
+
+!!! tip
+    Additional statuses may be defined by setting `Cluster.status` under the [`FIELD_CHOICES`](../../configuration/data-validation.md#field_choices) configuration parameter.
+
+### Site
+
+The [site](../dcim/site.md) with which the cluster is associated.

docs/models/virtualization/clustergroup.md

@@ -1,3 +1,13 @@
 # Cluster Groups
 
-Cluster groups may be created for the purpose of organizing clusters. The arrangement of clusters into groups is optional.
+Cluster groups may be created for the purpose of organizing [clusters](./cluster.md). The arrangement of clusters into groups is optional.
+
+## Fields
+
+### Name
+
+A unique human-friendly name.
+
+### Slug
+
+A unique URL-friendly identifier. (This value can be used for filtering.)

docs/models/virtualization/clustertype.md

@@ -1,3 +1,13 @@
 # Cluster Types
 
-A cluster type represents a technology or mechanism by which a cluster is formed. For example, you might create a cluster type named "VMware vSphere" for a locally hosted cluster or "DigitalOcean NYC3" for one hosted by a cloud provider.
+A cluster type represents a technology or mechanism by which a [cluster](./cluster.md) is formed. For example, you might create a cluster type named "VMware vSphere" for a locally hosted cluster or "DigitalOcean NYC3" for one hosted by a cloud provider.
+
+## Fields
+
+### Name
+
+A unique human-friendly name.
+
+### Slug
+
+A unique URL-friendly identifier. (This value can be used for filtering.)

docs/models/virtualization/virtualmachine.md

@@ -1,16 +1,53 @@
 # Virtual Machines
 
-A virtual machine represents a virtual compute instance hosted within a cluster. Each VM must be assigned to a site and/or cluster, and may optionally be assigned to a particular host device within a cluster.
+A virtual machine (VM) represents a virtual compute instance hosted within a [cluster](./cluster.md). Each VM must be assigned to a [site](../dcim/site.md) and/or cluster, and may optionally be assigned to a particular host [device](../dcim/device.md) within a cluster.
 
-Like devices, each VM can be assigned a platform and/or functional role, and must have one of the following operational statuses assigned to it:
+Virtual machines may have virtual [interfaces](./vminterface.md) assigned to them, but do not support any physical component. When a VM has one or more interfaces with IP addresses assigned, a primary IP for the device can be designated, for both IPv4 and IPv6.
 
-* Active
-* Offline
-* Planned
-* Staged
-* Failed
-* Decommissioning
+## Fields
 
-Additional fields are available for annotating the vCPU count, memory (GB), and disk (GB) allocated to each VM. A VM may be allocated a partial vCPU count (e.g. 1.5 vCPU).
+### Name
 
-Each VM may optionally be assigned to a tenant. Virtual machines may have virtual interfaces assigned to them, but do not support any physical component.
+The virtual machine's configured name. Must be unique to the assigned cluster and tenant.
+
+### Role
+
+The functional [role](../dcim/devicerole.md) assigned to the VM.
+
+### Status
+
+The VM's operational status.
+
+!!! tip
+    Additional statuses may be defined by setting `VirtualMachine.status` under the [`FIELD_CHOICES`](../../configuration/data-validation.md#field_choices) configuration parameter.
+
+### Site & Cluster
+
+The [site](../dcim/site.md) and/or [cluster](./cluster.md) to which the VM is assigned.
+
+### Device
+
+The physical host [device](../dcim/device.md) within the assigned site/cluster on which this VM resides.
+
+### Platform
+
+A VM may be associated with a particular [platform](../dcim/platform.md) to indicate its operating system.
+
+### Primary IPv4 & IPv6 Addresses
+
+Each VM may designate one primary IPv4 address and/or one primary IPv6 address for management purposes.
+
+!!! tip
+    NetBox will prefer IPv6 addresses over IPv4 addresses by default. This can be changed by setting the `PREFER_IPV4` configuration parameter.
+
+### vCPUs
+
+The number of virtual CPUs provisioned. A VM may be allocated a partial vCPU count (e.g. 1.5 vCPU).
+
+### Memory
+
+The amount of running memory provisioned, in megabytes.
+
+### Disk
+
+The amount of disk storage provisioned, in gigabytes.

docs/models/virtualization/vminterface.md

@@ -1,3 +1,55 @@
 ## Interfaces
 
-Virtual machine interfaces behave similarly to device interfaces, and can be assigned to VRFs, and may have IP addresses, VLANs, and services attached to them. However, given their virtual nature, they lack properties pertaining to physical attributes. For example, VM interfaces do not have a physical type and cannot have cables attached to them.
+[Virtual machine](./virtualmachine.md) interfaces behave similarly to device [interfaces](../dcim/interface.md): They can be assigned to VRFs, may have IP addresses, VLANs, and services attached to them, and so on. However, given their virtual nature, they lack properties pertaining to physical attributes. For example, VM interfaces do not have a physical type and cannot have cables attached to them.
+
+## Fields
+
+### Virtual Machine
+
+The [virtual machine](./virtualmachine.md) to which this interface is assigned.
+
+### Name
+
+The interface's name. Must be unique to the assigned VM.
+
+### Parent Interface
+
+Identifies the parent interface of a subinterface (e.g. used to employ encapsulation).
+
+### Bridged Interface
+
+An interface on the same VM with which this interface is bridged.
+
+### Enabled
+
+If not selected, this interface will be treated as disabled/inoperative.
+
+### MAC Address
+
+The 48-bit MAC address (for Ethernet interfaces).
+
+### MTU
+
+The interface's configured maximum transmissible unit (MTU).
+
+### 802.1Q Mode
+
+For switched Ethernet interfaces, this identifies the 802.1Q encapsulation strategy in effect. Options include:
+
+* **Access:** All traffic is assigned to a single VLAN, with no tagging.
+* **Tagged:** One untagged "native" VLAN is allowed, as well as any number of tagged VLANs.
+* **Tagged (all):** Implies that all VLANs are carried by the interface. One untagged VLAN may be designated.
+
+This field must be left blank for routed interfaces which do employ 802.1Q encapsulation.
+
+### Untagged VLAN
+
+The "native" (untagged) VLAN for the interface. Valid only when one of the above 802.1Q mode is selected.
+
+### Tagged VLANs
+
+The tagged VLANs which are configured to be carried by this interface. Valid only for the "tagged" 802.1Q mode above.
+
+### VRF
+
+The [virtual routing and forwarding](../ipam/vrf.md) instance to which this interface is assigned.