DEBOPS.NETBOX(5)

NAME
debops.netbox - Deploy and manage NetBox, IPAM/DCIM management tool

SYNOPSIS

debops run service/netbox [--limit group,host,...] [--diff] [--check] [--tags tag1,tag2,...] [--skip-tags tag1,tag2,...] [<ansible-playbook options>] ...

DESCRIPTION

NetBox <https://github.com/digitalocean/netbox/> is an IP address management (IPAM <https://en.wikipedia.org/wiki/IP_address_management>) and data center infrastructure management (DCIM <https://en.wikipedia.org/wiki/Data_center_infrastructure_management>) application developed by DigitalOcean <https://digitalocean.com/>.

GETTING STARTED

  General deployment notes

The application will by default be deployed both on ipam.{{ ansible_domain }} as well as dcim.{{ ansible_domain }} DNS domains, for convenience. You should either point these domains to the deployment host via DNS, or change the netbox__fqdn to set a desired subdomain.

By default NetBox will allow connections only to the specified DNS domains and deny any other domain that might point to the host it's deployed on.

After the database initialization, the role will create an initial superuser account with random password stored in the DebOps secret/ directory. The username will be the first admin user defined by the debops.core Ansible role.

By default anonymous access to NetBox is disabled.

  NetBox configuration

Since NetBox v3.1, some settings that traditionally could only be changed from the configuration.py file can now be changed without requiring a restart of NetBox from within the web UI. Settings in the config file take priority.

This is not supported by this role. Support for it would require changes to the role. No valid use case has been presented to justify those changes.

The role is designed to manage multiple NetBox instances and allow to keep the configuration in git. Both is not easily doable with dynamic configuration settings.

For more details, refer to dynamic configuration settings <https://netbox.readthedocs.io/en/stable/configuration/dynamic-settings/>.

The trend to move away from git by NetBox is observed closely and additionally support for Nautobot <https://github.com/nautobot/nautobot> might get added to DebOps at some point because Nautobot takes git-like-version-control to the next level with Dolt.

  Python virtualenv support

The NetBox application will be deployed in a Python virtualenv <http://virtualenv.org/> environment to separate it from the system Python installation. By default the environment will be created and maintained in the /usr/local/lib/netbox/ directory using an unprivileged netbox account.

The NetBox Python requirements will be installed in the requested versions from PyPI; this might take a while.

The role will install additional Python modules, gunicorn and setproctitle, to support internal application server and/or management by the system-wide gunicorn service.

  Internal application server

The debops.netbox role can deploy NetBox with either a system-wide gunicorn service (default), or with an internal gunicorn application sever using its own netbox systemd unit file. The role automatically detects if the debops.gunicorn role has been deployed on a host and switches between these modes as needed.

  manage.py for NetBox power users

The NetBox goody manage.py is conveniently accessible using a script that the role installs called netbox-manage. It uses sudo to switch to the NetBox user, activates the virtualenv and run manage.py. Call it without parameters to see the available subcommands. The user calling the script must have privileges to run commands as the NetBox system user.

  Example inventory

The NetBox application uses a PostgreSQL database as its backend, therefore you need to setup a PostgreSQL server which the application can access. To configure one on the same host as NetBox, add that host to the [debops_service_postgresql_server] Ansible inventory group. See the debops.postgresql_server role documentation to see how to use the database server remotely.

The Redis service is used for caching and is now required by NetBox as well. The netbox__redis_* variables in the debops.netbox role can be used to point NetBox to a remote Redis service; by default the role expects Redis to be installed locally. You can deploy a Redis Server or cluster using the debops.redis_server (and optionally debops.redis_sentinel) Ansible roles. See their documentation for more details.

To deploy NetBox on a given host, you need to add that host to the [debops_service_netbox] Ansible inventory group. Complete, example inventory:

[debops_all_hosts]
hostname
[debops_service_redis_server]
hostname
[debops_service_postgresql_server]
hostname
[debops_service_netbox]
hostname

  Example playbook

If you are using this role without DebOps, here's an example Ansible playbook that uses the debops.netbox role:

---
- name: Manage NetBox IPAM/DCIM application
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_service_netbox' ]
  become: True
  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'
  roles:
    - role: keyring
      tags: [ 'role::keyring', 'skip::keyring',
              'role::postgresql', 'role::nginx', 'role::netbox' ]
      keyring__dependent_apt_keys:
        - '{{ postgresql__keyring__dependent_apt_keys }}'
        - '{{ nginx__keyring__dependent_apt_keys }}'
      keyring__dependent_gpg_keys:
        - '{{ netbox__keyring__dependent_gpg_keys }}'
    - role: apt_preferences
      tags: [ 'role::apt_preferences', 'skip::apt_preferences' ]
      apt_preferences__dependent_list:
        - '{{ nginx__apt_preferences__dependent_list }}'
    - role: cron
      tags: [ 'role::cron', 'skip::cron' ]
    - role: logrotate
      tags: [ 'role::logrotate', 'skip::logrotate' ]
      logrotate__dependent_config:
        - '{{ gunicorn__logrotate__dependent_config }}'
    - role: ferm
      tags: [ 'role::ferm', 'skip::ferm' ]
      ferm__dependent_rules:
        - '{{ nginx__ferm__dependent_rules }}'
    - role: python
      tags: [ 'role::python', 'skip::python', 'role::postgresql', 'role::gunicorn', 'role::netbox' ]
      python__dependent_packages3:
        - '{{ gunicorn__python__dependent_packages3 }}'
        - '{{ ldap__python__dependent_packages3 }}'
        - '{{ netbox__python__dependent_packages3 }}'
        - '{{ nginx__python__dependent_packages3 }}'
        - '{{ postgresql__python__dependent_packages3 }}'
      python__dependent_packages2:
        - '{{ gunicorn__python__dependent_packages2 }}'
        - '{{ ldap__python__dependent_packages2 }}'
        - '{{ netbox__python__dependent_packages2 }}'
        - '{{ nginx__python__dependent_packages2 }}'
        - '{{ postgresql__python__dependent_packages2 }}'
    - role: ldap
      tags: [ 'role::ldap', 'skip::ldap' ]
      ldap__dependent_tasks:
        - '{{ netbox__ldap__dependent_tasks }}'
    - role: postgresql
      tags: [ 'role::postgresql', 'skip::postgresql' ]
      postgresql__dependent_roles:
        - '{{ netbox__postgresql__dependent_roles }}'
      postgresql__dependent_groups:
        - '{{ netbox__postgresql__dependent_groups }}'
      postgresql__dependent_databases:
        - '{{ netbox__postgresql__dependent_databases }}'
      postgresql__dependent_pgpass:
        - '{{ netbox__postgresql__dependent_pgpass }}'
    - role: gunicorn
      tags: [ 'role::gunicorn', 'skip::gunicorn' ]
      gunicorn__dependent_applications:
        - '{{ netbox__gunicorn__dependent_applications }}'
    - role: nginx
      tags: [ 'role::nginx', 'skip::nginx' ]
      nginx__dependent_upstreams:
        - '{{ netbox__nginx__dependent_upstreams }}'
      nginx__dependent_servers:
        - '{{ netbox__nginx__dependent_servers }}'
    - role: netbox
      tags: [ 'role::netbox', 'skip::netbox' ]

  Ansible tags

You can use Ansible --tags or --skip-tags parameters to limit what tasks are performed during Ansible run. This can be used after host is first configured to speed up playbook execution, when you are sure that most of the configuration has not been changed.

Available role tags:

role::netbox
    Main role tag, should be used in the playbook to execute all of the role tasks as well as role dependencies.

role::netbox:config
    Generate NetBox configuration file and restart the service if necessary.

DEFAULT VARIABLE DETAILS

Some of debops.netbox default variables have more extensive configuration than simple strings or lists, here you can find documentation and examples for them.

  netbox__virtualenv_pip_packages

This is a list of additional Python modules that will be installed in the NetBox virtualenv environment using pip. Each element is either a string which specifies a Python module name, or a YAML dictionary with specific parameters:

name
    Name of the Python module to install.

version
    Optional. Specific version of the module to install.

state
    Optional. If not specified or present, the Python module will be installed. If ignore, the specified Python module will be ignored.

    The Python modules will be installed or updated as needed when the NetBox checked out code is updated.

  netbox__config_plugins_config

YAML dictionary where the key is the plugin name. The value can be any nested data structure. What is supported as value is defined by the individual plugin.

Example:

netbox__config_plugins_config:
  netbox_topology_views:
    preselected_device_roles:
      - 'Access point'
      - 'Firewall'
      - 'Peripheral'
      - 'Power'
      - 'Server'
      - 'Switch'

AUTHOR
Maciej Delmanowski, Robin Schneider

COPYRIGHT
2014-2024, Maciej Delmanowski, Nick Janetakis, Robin Schneider and others