> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# NetBox

> Create and manage device inventory in Itential Gateway using the NetBox dynamic inventory plugin.

To create and manage device inventory via plugin, several steps are required. This guide covers the NetBox plugin.

> **Info**
>
> **Related reading:** [NetBox inventory source](https://docs.ansible.com/ansible/latest/collections/netbox/netbox/nb_inventory_inventory.html)

#### Install the plugin

There is an `ansible-galaxy` command that can install the plugin into the Gateway server. You will likely have to incorporate this command into your Gateway build plan so that you do not have to do this as a manual step. For NetBox the command looks like this:

`ansible-galaxy collection install netbox.netbox`

#### Configure Ansible to use the plugin

There are several ways to accomplish this step. Below is a suggested method for enabling a plugin. Make sure the `interpreter_python` is appropriate for the environment.

`/etc/ansible/ansible.cfg`

This example enables the NetBox dynamic inventory plugin.

```ini
[defaults]
collections_path=/opt/automation-gateway/ansible/collections:/usr/share/ansible/collections
host_key_checking = False
timeout = 900
# This might need adjusting depending on specifics
interpreter_python = /bin/python3.9
INVENTORY_ENABLED = "netbox.netbox.nb_inventory"

[persistent_connection]
command_timeout = 3600
connect_timeout = 900
```

#### Configure the host file

Use the [NetBox documentation](https://docs.ansible.com/ansible/latest/collections/netbox/netbox/nb_inventory_inventory.html) to determine the most appropriate way to configure the plugin to connect to and query from the source of truth system. The NetBox plugin configuration below connects to the public NetBox demo and returns all devices found there.

> **Info**
>
> Be sure to specify the host file as a `.yml` file.

`/opt/automation-gateway/ansible/inventory/hosts.yml`

```yaml
---
plugin: netbox.netbox.nb_inventory
# This is the public netbox demo website. You will need to create a temporary
# account to create an API token. Admin > Authentication > API Tokens
api_endpoint: "https://demo.netbox.dev"
token: aaaaaaaaaaaaaaaaaaaaaaaaaa
validate_certs: False
config_context: False
group_by:
  - device_roles
```

#### Confirm the plugin is working

Before invoking the plugin from Gateway, test it directly from the command line using Ansible. This command invokes the plugin and returns the devices it finds.

`ansible-inventory -vvv --list -i <path-to-plugin-host-file>`

#### Restart Gateway

Restarting Gateway triggers the plugin to execute. Once execution finishes, you should see NetBox devices in the Ansible inventory.