How to Use NetBox as an Inventory in Ansible Core

Introduction to NetBox and Ansible Core

NetBox is an open-source tool designed for network automation and infrastructure management, specializing in managing IP address allocations and data center infrastructure. Ansible Core is a widely used automation tool that allows you to automate software provisioning, configuration management, and application deployment.

Integrating NetBox with Ansible Core can centralize your network inventory, making it easier to manage and automate your network devices. This integration leverages NetBox’s API to dynamically pull inventory data into Ansible using a YAML configuration file.

Prerequisites

Before starting, ensure you have the following:

• NetBox: Installed and configured. You can find installation instructions here
• Ansible Core: Installed on your control node. Install Ansible Core by following the official Ansible installation guide
• NetBox API Token: Generate an API token in NetBox for authentication purposes. NetBox API documentation

Configure NetBox as an Inventory Source Using YAML File

To use NetBox as an inventory source in Ansible, follow these steps:

1. Install the netbox.netbox Ansible Collection

Install the netbox.netbox collection which provides the inventory plugin:

   ansible-galaxy collection install netbox.netbox        

2. Create a YAML Configuration File

Create a YAML configuration file named netbox_inventory.yml in your Ansible directory. This file will define how Ansible pulls inventory data from NetBox.

nano /etc/ansible/netbox_inventory.yml        

Inventory file contents: update variables with information from your netbox installation

plugin: netbox.netbox.nb_inventory
api_endpoint: {{ netbox IP }}
token: {{ netbox Token. }}
validate_certs: false
config_context: false
flatten_custom_fields: true
group_by:
   # - sites
   # - device_roles
   # - platforms
   # - locations
query_filters:
    # restrict inventory to specific tenant
    # - tenants: {{ tenant name }}
device_query_filters:
    # - has_primary_ip: 'true'
    # You can also filter by platform, role, e.g.:
    # - platform: cisco-ios-xe
    # - role: router
    # - role: switch        

3. Update Ansible Configuration

Modify your ansible.cfg to use the YAML file as the inventory source:

Open your Ansible config file with your favorite editor. I'm using nano

nano /etc/ansible/ansible.cfg        

find the inventory line under [defaults] and update it with the location of your new inventory file

inventory=/etc/ansible/netbox_inventory.yml        

4. Test Your Inventory Configuration

   ansible-inventory --list        

This command should return your inventory in JSON format, showing the hosts pulled from NetBox.

4. Example Playbook Using NetBox Inventory

Create a sample Ansible playbook to ensure your inventory is working. Here’s a simple playbook that pings all devices:

nano playbook.yml        

playbook contents:

- name: Test NetBox Inventory
  hosts: all
  tasks:
    - name: Ping the hosts
      ansible.builtin.ping:        

Run the playbook:

ansible-playbook playbook.yml        

5. Enhancing Your Configuration

You can further enhance your configuration by adjusting the group_by, device_query_filters, and query_filters options to better fit your network environment. This helps in organizing your devices into relevant groups and filtering inventory based on specific criteria.

Here’s an example of grouping by device roles and platforms:

group_by:
  - device_roles
  - platforms        

And a filter to include only devices with a specific tenant:

query_filters:
  - tenants: YourTenantName        

You can also add device_query_filters to only include devices with specific details:

device_query_filters:
    - has_primary_ip: 'true'
    # You can also filter by platform, role, e.g.:
    - platform: cisco-ios-xe
    - role: router
    - role: switch        

6. Best Practices

• Security: Store your API token securely, and avoid hardcoding it in the YAML file.
• File Location: Place your inventory YAML file in a dedicated directory to keep your project organized.
• Documentation: Comment your configuration for better maintenance and collaboration.
• Testing: Regularly test your inventory configuration to ensure it reflects your network accurately.

Explore the NetBox and Ansible documentation for more advanced configurations and integrations. Happy automating!

References:

• NetBox Documentation
• Ansible Documentation
• NetBox Ansible Collection