Netbox Webhooks with Ansible Tower

Network environments are constantly evolving and grow more complex on a daily basis. In many cases maintaining a structured IPAM solution or a consistent Source of Truth is an ongoing challenge. Netbox offers both and can be easily integrated into Ansible with the community authored collection available from Ansible Galaxy.

Lets assume you have gathered and populated Netbox with Ansible already. There are many great articles illustrating this. Josh VanDeraa's Netbox article is one of them which offers a Source of Truth (SoT) overview, and a look into the Ansible Content Collection.

At this point yo can leverage Netbox's Webhooks and API as an interface to push changes back to your network infrastructure. This increases adoption, speed of network changes and ease of use. In this example we will look at changing a vLAN assignment on a switch access port .

Ansible Playbook and Tower Template

The contents of my Ansible playbook are very simple.

---

- name: Netbox Webhook Testing
  hosts: 
    - "{{ device_id }}"
  gather_facts: no
  connection: network_cli

  tasks:

  - name: Nxos l2 Interface
    cisco.nxos.nxos_l2_interfaces:
      config:
      - name: "{{ interface_id }}"
        access:
          vlan: "{{ vlan_id }}"
      state: replaced

The only change that needs to be made within Ansible Tower is to ensure the Job template being used has the "PROMPT ON LAUNCH" box ticked. This will ensure that the environment variable "ask_variables_on_launch" will be marked as true, thus allowing us to accept extra_vars being passed in from Netbox.

Netbox REST API Data Structure

To change a vLAN assignment on a switch we need to gather three parameters, the switch name, the interface and the vLAN to be amended. The quickest way to get this data is to navigate the NetBox API.

We can use the built in web based API to gather the correct URL to use within Postman.

It's fairly straight forward to setup a Postman connection to Netbox, just ensure you have the correct values setup within the Authorisation tab.

Ensure you set the Authorization key value to be prepended by the keyword "Token" with your user generated token and Add to Header as above. You should now be able to issue REST API calls direct to Netbox.

Logging onto my Cisco switch SW1 shows the following vLAN port configurations which matches what has already been populated via Ansible into Netbox.

Now we know the data structure that a GET request returns we can start manipulating this within Postman to grab what we need to pass to Ansible via the extra_vars variable. Let's fire up Postman and pass in some parameters. Parse the data required to pass to Ansible. Remember we need device name, interface and vLAN details to set as variables for our play in Ansible.

By setting the above parameters in Postman we are able to filter data from the returned GET request as detailed below. Parameters device.name, name and untagged_vlan.vid return SW1, GigabitEthernet0/2 and Vlan_ID 2.

This will be the data structure regardless of what switch, interface or vLAN we target. By issuing a GET request we now know what the data structure looks like when returned. We can now use this to issue PUT requests to change details within Netbox and via Webhooks.

Netbox Configuration

Navigate to the Netbox administration page and click on Webhooks. Pick a name and select DCIM > interface and tick the enable box. Events should be Type update in our case. For the HTTP Request enter the URL of your Ansible Tower job template in our example its https://192.168.1.206/api/v2/job_templates/3/launch, where 3 is the template number to launch. HTTP method is POST with content type of application/json.

The body template is where the magic happens. We have to send the API structure to Ansible in JSON format as extra_vars. To do this my JSON file looks like this.

{   "extra_vars":   {
        "device_id": "{{ data['device']['name'] }}",
        "interface_id": "{{ data['name'] }}",
        "vlan_id": "{{ data['untagged_vlan']['vid'] }}"
                    }
}

Earlier in the article I mentioned the variables "device_id", "interface_id" and "vlan_id" are being used in my Ansible playbook and we have to prepend the API returned values with the "data" object as designated in the POST API. You can now save your Webhook.

Testing the Webhook

Now we are ready to test the Webhook. Navigate to the interface section of the device you want to change and click on edit. Click on untagged VLAN and lets pick vLAN 5 to change. Click update.

A Webhook call is now initiated to SW1 to amend the switch port GigabitEthernet0/2 to a vLAN ID of 5. On the Ansible Tower job now running we can see the extra_vars have been populated from Netbox to the job template.

The playbook successfully runs and notes one change.

PLAY [Netbox Webhook Testing] ********************
TASK [Nxos l2 Interface] *****************
changed: [SW1]
PLAY RECAP *********************************************************************
SW1                : ok=1    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0  

If we now log back onto SW1 we see that the vLAN has also been successfully changed.

Now every time an interface is updated on Netbox a Webhook will be sent to Ansible Tower which will then automatically configure the interface vLAN. This demo was provisioned in my home lab, if I were to run this on a production environment I would certainly look to build some checks to ensure the port was not a Trunk or a Tunnel etc.

Thanks for reading and happy automating.