NetBox modules for Ansible using Ansible Collections
NetBox modules for Ansible using Ansible Collections
The NetBox Ansible project provides an Ansible collection for interacting with NetBox, the leading solution for modeling and documenting modern networks. By combining the traditional disciplines of IP address management (IPAM) and datacenter infrastructure management (DCIM) with powerful APIs and extensions, NetBox provides the ideal "source of truth" to power network automation.
This Ansible collection consists of a set of modules to define the intended network state in NetBox, along with plugins to drive automation of the network using data from NetBox.
nb_lookup and nb_inventory plugins.pip install pytz
pip install pynetboxBefore using this collection, you need to install it with the Ansible Galaxy command-line tool:
ansible-galaxy collection install netbox.netboxYou can also include it in a requirements.yml file and install it with ansible-galaxy collection install -r requirements.yml, using the format:
collections:
- name: netbox.netboxTo upgrade the collection to the latest available version, run the following command:
ansible-galaxy collection install netbox.netbox --upgradeYou can also install a specific version of the collection, for example, if you need to downgrade when something is broken in the latest version (please report an issue in this repository). Use the following syntax to install version 3.19.1:
ansible-galaxy collection install netbox.netbox:==3.19.1See using Ansible collections for more details.
Follow these steps to install from source:
git clone [email protected]:netbox-community/ansible_modules.gitcd ansible_modulesansible-galaxy collection build .ansible-galaxy collection install netbox-netbox*.tar.gzThis is useful to test code within PRs.
git clone [email protected]:netbox-community/ansible_modules.gitcd ansible_modulesgit fetch origin pull//head:git checkout ansible-galaxy collection build .ansible-galaxy collection install netbox-netbox*.tar.gzNote: This GitHub link provides detailed information on checking out pull requests locally.
Define the intended state of your network in NetBox, by interacting with the NetBox database to define objects and their associated state in the following ways:
For example, to make sure a new aggregate network prefix exists:
tasks:
- name: Create aggregate within NetBox with only required information
netbox.netbox.netbox_aggregate:
netbox_url: http://netbox.local
netbox_token: thisIsMyToken
data:
prefix: 192.168.0.0/16
rir: Test RIR
state: presentUse the Inventory Plugin to dynamically generate Ansible inventory from device data in NetBox. Use query filters, groups and mappings to tailor the generated inventory to your specific needs.
The following example builds an Ansible inventory that groups devices by role, and filters for only devices that have the network-edge-router role, have a primary IP address and belong to the internal tenant:
# netbox_inventory.yml file in YAML format
# Example command line: ansible-inventory -v --list -i netbox_inventory.yml
plugin: netbox.netbox.nb_inventory
api_endpoint: http://localhost:8000
validate_certs: True
config_context: False
group_by:
- device_roles
query_filters:
- role: network-edge-router
device_query_filters:
- has_primary_ip: 'true'
- tenant__n: internalUse the Lookup plugin to query NetBox and return data to drive network automation, such as lists of devices, device configurations, prefixes and IP addresses etc.
The following example returns a list of devices and their manufacturers, using an API filter to only return devices with the management role and the NetBox tag of Dell:
tasks:
# query a list of devices
- name: Obtain list of devices from NetBox
debug:
msg: >
"Device {{ item.value.display }} (ID: {{ item.key }}) was
manufactured by {{ item.value.device_type.manufacturer.name }}"
loop: "{{ query('netbox.netbox.nb_lookup', 'devices',
api_endpoint='http://localhost/',
api_filter='role=management tag=Dell'),
token='') }}"
Tested with Ansible Core v2.15+ Ansible Core versions prior to 2.15 are not supported.
If you would to contribute to the project then you can find out how to get started here.
There are various options to get support for the collection:
#ansible Slack Channel on netdev-community.slack.comCustomers of NetBox Labs and Ansible using the officially certified version of the collection can get support via the usual Ansible channels. Escalation to the NetBox Labs support team will be provided as needed.
The collection release notes and changelog can be found here.
Some extra resources you might find useful for both the Ansible collection and for NetBox itself:
GNU General Public License v3.0 or later.
See LICENSE for the full text of the license.
No open issues yet, or sync has not completed.