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.

exception spicerack.netbox.NetboxScriptError[source]

Bases: NetboxError

Raised when a Netbox script doesn't run properly.

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.

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

Return a NetboxServer instance for the given hostname.

Parameters:

hostname (str) -- the device hostname.

Raises:

spicerack.netbox.NetboxHostNotFoundError -- if the device can't be found among physical or virtual devices.
spicerack.netbox.NetboxError -- if the device is not a server.

Return type:

spicerack.netbox.NetboxServer

run_script(name: str, *, commit: bool = False, params: dict[str, Any]) → list[source]

Run a Netbox script and wait for its output.

Parameters:

name (str) -- Full name of the script to run (eg. import_server_facts.ImportPuppetDB).
commit (bool, default: False) -- save the script actions in the Netbox DB.
params (dict[str, typing.Any]) -- script parameters (passed as POST data).

Return type:

list

Returns:

The script execution logs in a list format.

Raises:

spicerack.netbox.NetboxScriptError -- If the script coudn't be ran or its result fetched.

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

property access_vlan: str

Get and set the server access vlan.

Can be done only on physical devices, requires the device to have a primary IP.

Parameters:: value -- the name of the vlan to be set.

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

Get and set the device primary IPs FQDN if one is already set.

Notes

If the FQDN for any of the primary IPs is not set it will not be updated. This is to prevent setting a IPv6 AAAA record by accident.

Parameters:: value -- the new FQDN for the host.
Raises:: spicerack.netbox.NetboxError -- if the server has no FQDN defined in Netbox.

property mgmt_fqdn: str

Get and set the management FQDN of the device.

Parameters:: value -- the new FQDN for the host.
Raises:: spicerack.netbox.NetboxError -- for virtual servers or the server has no management FQDN defined in Netbox.

property name: str

Get the server name. Set the server name, primary IP DNS name, management IP DNS name.

Modifying its value can be done only on physical devices.

Parameters:: new -- the new name for the host.
Raises:: spicerack.netbox.NetboxError -- if trying to set it on a virtual device or there is an issue renaming.

property primary_ip4_address: IPv4Interface | None

Get and set the server primary IPv4 address.

And not the Netbox ipam.IpAddresses object.

Parameters:: value -- the new IPv4 (CIDR) to be set.

property primary_ip6_address: IPv6Interface | None

Get and set the server primary IPv6 address.

And not the Netbox ipam.IpAddresses object.

Parameters:: value -- the new IPv6 (CIDR) to be set.

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.