From 0ba45caabf9ad26f51d19687ee6108f80eef5d1a Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Tue, 16 Aug 2022 15:57:29 -0400 Subject: [PATCH] Update virtualization models documentation --- docs/models/dcim/device.md | 7 +++ docs/models/virtualization/cluster.md | 27 +++++++++- docs/models/virtualization/clustergroup.md | 12 ++++- docs/models/virtualization/clustertype.md | 12 ++++- docs/models/virtualization/virtualmachine.md | 57 ++++++++++++++++---- docs/models/virtualization/vminterface.md | 54 ++++++++++++++++++- 6 files changed, 154 insertions(+), 15 deletions(-) diff --git a/docs/models/dcim/device.md b/docs/models/dcim/device.md index ddf1bfb09..33d07e07e 100644 --- a/docs/models/dcim/device.md +++ b/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.) diff --git a/docs/models/virtualization/cluster.md b/docs/models/virtualization/cluster.md index 3e3516cd6..50b5dbd1d 100644 --- a/docs/models/virtualization/cluster.md +++ b/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. diff --git a/docs/models/virtualization/clustergroup.md b/docs/models/virtualization/clustergroup.md index 6dd0f9688..bae177792 100644 --- a/docs/models/virtualization/clustergroup.md +++ b/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.) diff --git a/docs/models/virtualization/clustertype.md b/docs/models/virtualization/clustertype.md index cee557df3..51eed5ec4 100644 --- a/docs/models/virtualization/clustertype.md +++ b/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.) diff --git a/docs/models/virtualization/virtualmachine.md b/docs/models/virtualization/virtualmachine.md index 4ddffb99a..769d49154 100644 --- a/docs/models/virtualization/virtualmachine.md +++ b/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. diff --git a/docs/models/virtualization/vminterface.md b/docs/models/virtualization/vminterface.md index 7f1a5082d..264fb95ba 100644 --- a/docs/models/virtualization/vminterface.md +++ b/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.