Getting started¶

General deployment notes
Python virtualenv support
Internal application server
manage.py for NetBox power users
Example inventory
Example playbook
Ansible tags

General deployment notes ¶

The application will be by default 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.

Python virtualenv support ¶

The NetBox application will be deployed in a Python virtualenv 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:
        - '{{ gunicorn__apt_preferences__dependent_list }}'
        - '{{ postgresql__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.

Getting started¶

General deployment notes¶

Python virtualenv support¶

Internal application server¶

manage.py for NetBox power users¶

Example inventory¶

Example playbook¶

Ansible tags¶