search

ugenk / netbox-proxbox-stable

this is a stable working version of proxbox netbox plugin with custom patches to support modern netbox
Apache License 2.0
2 stars 1 forks source link

readme

Netbox Plugin which integrates Proxmox and Netbox!

This is a fork from original repository netdevopsbr/netbox-proxbox intended to maintain stable version of proxbox plugin, without FastAPI and async stuff.

Proxbox is currently able to get the following information from Proxmox:

### Versions The following table shows the Netbox and Proxmox versions compatible (tested) with Proxbox plugin. | netbox version | proxmox version | proxbox version | |------------------|-----------------|-------------| | >= v4.1.6 | up to 8.2 | =v0.0.6 | | >= v3.4.0 | >= v6.2.0 | =v0.0.5 | | >= v3.2.0 | >= v6.2.0 | =v0.0.4 | | >= v3.0.0 < v3.2 | >= v6.2.0 | =v0.0.3 |

Summary

1. Installation

2. Configuration Parameters

3. Custom Fields

4. Usage

5. Enable Logs

6. Contributing

7. Roadmap

8. Get Help from Community!

1. Installation

The instructions below detail the process for installing and enabling Proxbox plugin. The plugin is available as a Python package in pypi and can be installed with pip.

1.1. Install package

1.1.1. Using git

Move to netbox main folder

cd /opt/netbox/netbox

Clone netbox-proxbox-stable repository

git clone https://github.com/ugenk/netbox-proxbox-stable.git

Install netbox-proxbox

cd netbox-proxbox-stable
source /opt/netbox/venv/bin/activate
pip3 install -r requirements.txt && pip3 install .

1.2. Enable the Plugin

Enable the plugin in /opt/netbox/netbox/netbox/configuration.py:

PLUGINS = ['netbox_proxbox']

1.3. Configure Plugin

1.3.1. Change Netbox 'configuration.py' to add PLUGIN parameters

The plugin's configuration is also located in /opt/netbox/netbox/netbox/configuration.py:

Replace the values with your own following the Configuration Parameters section.

OBS: You do not need to configure all the parameters, only the one's different from the default values. It means that if you have some value equal to the one below, you can skip its configuration. For netbox you should ensure the domain/port either targets gunicorn or a true http port that is not redirected to https.

PLUGINS_CONFIG = {
    'netbox_proxbox': {
        'proxmox': [
            {
                'domain': 'proxmox1.example.com',    # May also be IP address
                'http_port': 8006,
                'user': 'root@pam',   # always required
                'password': 'Strong@P4ssword', # only required, if you don't want to use token based authentication
                'token': {
                    'name': 'tokenID',  # Only type the token name and not the 'user@pam:tokenID' format
                    'value': '039az154-23b2-4be0-8d20-b66abc8c4686'
                },
                'ssl': False  # validate ssl cert
            },
            # The following json is optional and applies only for multi-cluster use
            {
                'domain': 'proxmox2.example.com',    # May also be IP address
                'http_port': 8006,
                'user': 'root@pam',   # always required
                'password': 'Strong@P4ssword', # only required, if you don't want to use token based authentication
                'token': {
                    'name': 'tokenID',  # Only type the token name and not the 'user@pam:tokenID' format
                    'value': '039az154-23b2-4be0-8d20-b66abc8c4686'
                },
                'ssl': False  # validate ssl cert
            }
        ],
        'netbox': {
            'domain': 'localhost',     # Ensure localhost is added to ALLOWED_HOSTS
            'http_port': 8001,     # Gunicorn port.
            'token': '0dd7cddfaee3b38bbffbd2937d44c4a03f9c9d38',
            'ssl': False,   # There is no support to SSL on Netbox yet, so let it always False.
            'settings': {
                'virtualmachine_role_id' : 0,
                'node_role_id' : 0,
                'site_id': 0
            }
      }
 }

1.4. Run Database Migrations

cd /opt/netbox/netbox/
python3 manage.py migrate
python3 manage.py collectstatic --no-input

1.5. Restart WSGI Service

Restart the WSGI service to load the new plugin:

systemctl restart netbox

2. Configuration Parameters

The following options are available:

3. Custom Fields

To get Proxmox ID, Node and Type information, is necessary to configure Custom Fields. Below the parameters needed to make it work:

3.1. Custom Field Configuration

3.1.1. Proxmox ID

Required values (must be equal)

Optional values (may be different)

3.1.2. Proxmox Node

Required values (must be equal)

Optional values (may be different)

3.1.3. Proxmox Type (qemu or lxc)

Required values (must be equal)

Optional values (may be different)

3.1.4. Proxmox Keep Interface

Required values (must be equal)

3.2. Custom Field Example

custom field image

4. Usage

If everything is working correctly, you should see in Netbox's navigation the Proxmox VM/CT button in Plugins dropdown list.

On Proxmox VM/CT page, click button full update button

It will redirect you to a new page and you just have to wait until the plugin runs through all Proxmox Cluster and create the VMs and CTs in Netbox.

OBS: Due the time it takes to full update the information, your web browser might show a timeout page (like HTTP Code 504) even though it actually worked. You can try to configure proxy_read_timeout on your netbox nginx, and timeout in gunicorn.

5. Enable Logs

So that Proxbox plugin logs what is happening to the terminal, copy the following code and paste to configuration.py Netbox configuration file:

LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'handlers': {
        'console': {
            'class': 'logging.StreamHandler',
        },
    },
    'root': {
        'handlers': ['console'],
        'level': 'INFO',
    },
}

You can customize this using the following link: Django Docs - Logging. Although the above standard configuration should do the trick to things work.

6. Contributing

This project is based on commits and pull requests from netdevopsbr/netbox-proxbox

Developing tools for this project based on ntc-netbox-plugin-onboarding repo.

Issues and pull requests are welcomed.