netbox

Netbox module.

exception spicerack.netbox.NetboxAPIError[source]

Bases: NetboxError

Usually a wrapper for pynetbox.RequestError, errors that occur when accessing the API.

exception spicerack.netbox.NetboxError[source]

Bases: SpicerackError

General errors raised by this module.

exception spicerack.netbox.NetboxHostNotFoundError[source]

Bases: NetboxError

Raised when a host is not found for an operation.

class spicerack.netbox.Netbox(url: str, token: str, *, dry_run: bool = True)[source]

Bases: object

Class which wraps Netbox API operations.

Create Netbox instance.

Parameters:

  • url (str) -- The Netbox top level URL (with scheme and port if necessary).

  • token (str) -- A Netbox API token.

  • dry_run (bool, default: True) -- set to False to cause writes to Netbox to occur.

fetch_host_detail(hostname: str) → dict[source]

Return a dict containing details about the host.

Deprecated since version v0.0.50: use spicerack.netbox.NetboxServer instead.

Parameters:

hostname (str) -- the name of the host to retrieve.

Raises:
Return type:

dict

fetch_host_status(hostname: str) → str[source]

Return the current status of a host as a string.

Deprecated since version v0.0.50: use spicerack.netbox.NetboxServer instead.

Parameters:

hostname (str) -- the name of the host status

Raises:
Return type:

str

get_server(hostname: str) → spicerack.netbox.NetboxServer[source]

Return a NetboxServer instance for the given hostname.

Parameters:

hostname (str) -- the device hostname.

Raises:
Return type:

spicerack.netbox.NetboxServer

put_host_status(hostname: str, status: str) → None[source]

Set the device status.

Deprecated since version v0.0.50: use spicerack.netbox.NetboxServer instead.

Note

This method does not operate on virtual machines since they are updated automatically from Ganeti into Netbox.

Parameters:

  • hostname (str) -- the name of the host to operate on.

  • status (str) -- A status label or name.

Raises:
Return type:

None

property api: Api

Get the pynetbox instance to interact directly with Netbox APIs.

Caution

When feasible use higher level functionalities.

class spicerack.netbox.NetboxServer(*, api: pynetbox.core.api.Api, server: pynetbox.models.dcim.Devices | pynetbox.models.virtualization.VirtualMachines, dry_run: bool = True)[source]

Bases: object

Represent a Netbox device of role server or a virtual machine.

Initialize the instance.

Parameters:

  • api (pynetbox.core.api.Api) -- the API instance to connect to Netbox.

  • server (typing.Union[pynetbox.models.dcim.Devices, pynetbox.models.virtualization.VirtualMachines]) -- the server object.

Raises:

spicerack.netbox.NetboxError -- if the device is not of type server.

as_dict() → dict[source]

Return a dict containing details about the server.

Return type:

dict

allowed_status_transitions: dict[str, tuple[str, ...]] = {'active': ('failed', 'decommissioned'), 'decommissioned': ('planned', 'spare'), 'failed': ('spare', 'planned', 'active', 'decommissioned'), 'planned': ('active', 'failed', 'decommissioned'), 'spare': ('planned', 'failed', 'decommissioned')}

Allowed transition between Netbox statuses. See https://wikitech.wikimedia.org/wiki/Server_Lifecycle#/media/File:Server_Lifecycle_Statuses.png

property asset_tag_fqdn: str

Return the management FQDN for the asset tag of the device.

Raises:

spicerack.netbox.NetboxError -- for virtual servers or the server has no management FQDN defined in Netbox.

property fqdn: str

Return the FQDN of the device.

Raises:

spicerack.netbox.NetboxError -- if the server has no FQDN defined in Netbox.

property mgmt_fqdn: str

Return the management FQDN of the device.

Raises:

spicerack.netbox.NetboxError -- for virtual servers or the server has no management FQDN defined in Netbox.

property status: str

Get and set the server status.

Modifying its value can be done only on physical devices and only between allowed transitions.

The allowed transitions are defined in spicerack.netbox.Netbox.allowed_status_transitions.

Parameters:

value -- the name of the status to be set. It will be lower cased automatically.

Raises:

spicerack.netbox.NetboxError -- if trying to set it on a virtual device or the status transision is not allowed.

property virtual: bool

Getter to check if the server is physical or virtual.

Returns:

True if the server is virtual, False if physical.

spicerack.netbox.MANAGEMENT_IFACE_NAME: str = 'mgmt'

The interface name used in Netbox for the OOB network.

spicerack.netbox.SERVER_ROLE_SLUG: str = 'server'

Netbox role to identify servers.