NetBox Custom Script Development Environment

If you click on this blog post, you most likely already know that NetBox is awesome. The only downside is that you have to click… like a lot. In the past few days, I gained a lot of experience with writing Custom NetBox Scripts. And in this blog post, I want to share some of my findings.

But before we start, let’s have a look at a common NetBox workflow. If you only have to perform small changes, clicking on the GUI is fine. But let’s consider the simple use case of creating a VM and assigning an IP to that VM. First, you have to create the VM, next add an interface, and also reserve an IP address. But then you also have to link the IP address to the interface and the interface to the VM. So there are 5 steps involved in creating a “simple” VM. And now imagine that you have to do that several times. Sooner or later you’ll forget something and have inconsistent data.

And that’s where Custom Scripts can help us. Custom scripts are just Python scripts that you can run inside of NetBox. They allow you to access the NetBox data model directly, and you can even create a form that your users can use to input the data. It even includes a dry run mode so that you can test what your script would do before you corrupt your database. Therefore, I highly recommend that you have a look at NetBox Custom Scripts!

So the benefits of writing custom scripts were clear to me. But then I began the painful journey of figuring out how to actually write these scripts…

Initial Ideas

Writing Scripts Locally

Before I started writing my first script, I watched the NetBox Zero to Hero video about custom script. Rich Bibby does a great job with explaining how the script works and how you can figure out which models to use. But you just receive the script as well as an explanation of where you can find more information about the data models. But in my opinion it’s quite hard developing the actual script by yourself, especially without having proper IDE support. I mean, sure, you can just create a Python script on your Desktop and start coding.

That was actually my first approach. However, sooner or later you’ll run into issues. First of all, your IDE doesn’t find the references to the NetBox models. So you’ll have a lot of red lines in your editor. And then you will start questioning your life. There’s so much red, how is this ever going to work? What am I doing wrong? You don’t even need an IDE with this approach, you could just use vim. When you’re finished, copy the script to your NetBox, run it and pray that it will work. But of course it doesn’t work on the first try… it never does. So you go back, fix your bugs and repeat…

If you think “this doesn’t sound very pleasant” you’re absolutely right! So I was looking for a better approach to develop my scripts.

Using the VSCode Remote Explorer Extension

The next idea I came up with is to use the VSCode Remote Explorer. This extension allows me to connect to my NetBox VM via SSH and edit scripts directly on that VM.

This approach worked better than the first one, but I was still not happy. At least the editor was finally able to resolve the references to the models, so no more red lines. But somehow I was still not able to jump to the models by pressing control and clicking on a class. So I had to manually search and open the models every time.

The biggest problem with this approach is that I couldn’t version the scripts properly. We have several NetBox instances running so that we can test everything properly. If I write scripts locally on a NetBox every time, I never know where which version is deployed… It might work on one NetBox, but not on the other one…

Therefore I was still not happy with that approach. And that’s what led me to my current approach where I feel I don’t have to be embarrassed to show it to others…

My NetBox Custom Script Development Environment

My current approach (at least for now) looks like this. First I clone the official NetBox community repository to my local machine. Inside of that repository I’m going to add a new Git submodule. This allows me to version my custom scripts in my own repository without having to push them to the official NetBox repository. And if NetBox releases a new version, all I have to do is to git pull to get the new changes. There’s still a little bit praying involved that they didn’t change the model and thus breaking the scripts…

Finally I’m going to define a new data source in NetBox. This allows me to sync the scripts from my Git repo to NetBox. If I make some chances to my custom script, all I have to do is to sync the new files and NetBox is ready to run!

This sounds more complicated than it actually is. So here’s a step by step description on how you can do that yourself!

Clone the Official NetBox Repository

First we need the NetBox code on our local machine.

git clone https://github.com/netbox-community/netbox.git        

Now we have to add a virtual environment and install the requirements. Luckily, it’s quite easy to do that. Just make sure that your Python version is somewhat up to date. I think first I used Python 3.9 and had some issues with that. As far as I know, Python 3.11 works fine.

# Switch into the NetBox directory
cd netbox/

# Verify Python Version is 3.11 or larger
python3 --version

# Create a new virtual environment
python3 -m venv venv

# Activate the virtual environment
source venv/bin/activate

# Install all requirements
pip install -r requirements.txt        

Create the Custom Script Submodule

First, we need to create a folder for our custom scripts.

mkdir netbox/custom-scripts/
cd netbox/custom-scripts/        

And now we can add our own repo as a Git submodule.

git submodule add https://git.devnet-academy.com/custom-scripts.git custom-scripts        

At this point, you might be wondering what git submodule add actually does. In simple terms, a Git submodule allows you to keep a Git repository as a subdirectory of another Git repository. This means you can have your custom scripts in a separate repository but include them inside the NetBox repository. It’s like embedding one project within another. This way, you can manage your scripts independently while still keeping them connected to the NetBox codebase.

I had never used Git submodules before, but it’s a cool feature to know about. It allows you to use a project inside of another project. So we can have the “custom-scripts” project inside of the “netbox” project. Both projects are independent of each other, but we still need both to work. Well, maybe we need NetBox a bit more than NetBox needs us…

So this custom-scripts directory is like a normal Git repo for you. You can add branches, commits, and push/pull as much as you want. You won’t interfere with NetBox itself.

Write The Custom Script

Now is the time where you can write your own custom scripts with proper IDE support, awesome! In this blog post I won’t go over the details of writing the scripts. So for now, let’s just use this simple script to create a new Tenant.

Now add this script to your repository and push all the changes.

git add .
git commit -am "Add custom script to create tenants"
git push        

Define NetBox Data Sources

Right now the script is in your repository. But somehow we need to load those scripts to your NetBox instance so that you can run the script. NetBox allows us to add a repository and track files. All we have to do is to go to Operations → Data Sources and add the git repository as a new data source.

NetBox requires the additional “dulwich” library installed if you want to use Git as a remote data source. Please make sure that this is installed using the command pip freeze | grep dulwich. If it’s not present, you can install it with pip install dulwich. For more information have a look at the NetBox documentation.

In this screenshot above you can see all the settings I used to add my Git repo as a data source. The password is needed so that Git can pull the data files. This is a token that I generated on my Bitbucket.

In this screenshot above you can see all the settings I used to add my Git repo as a data source. The password is needed so that Git can pull the data files. This is a token that I generated on my Bitbucket.

Now you can see that we have the new data source specified. It’s quite cool that Bitbucket warns me when I create a new token that I can only see it once and never again. And NetBox then displays it as clear text for everyone to see :D

If we press sync we should see that the Status switches from New to Completed and at the bottom we should see a list of files.

Now we’re ready to add our script. Go to Customization → Scripts and add a new Script. For this example we’re using the Data Source. So select the NetBox Custom Script as Data Source and then select the script that you want to add.

Inside the scripts we should now see this new script. Click on “Run Script”.

As you can see our script has two input fields, one for the tenant name and one for a description. Just add something to test, it doesn’t really matter. Because at the bottom you can see the “Commit changes” checkbox. If we unselect that checkbox, NetBox will perform a dry run and we can test if our script is working or not.Execute the script

And now you should see something like this. This means that we successfully loaded the script and executed it.

Benefits of This New Workflow

As I said before, I’m pretty happy with my current setup. I can write the scripts on my local machine. I can use autocompletion, type hints, and jump straight to the data model classes if I need to check something. And I can even version my scripts and clone them to NetBox using Data Sources.

This setup makes my development process a lot more efficient and also makes it easier to deploy scripts consistently and reliably across different NetBox instances. I no longer have to wonder which version is deployed where, and I no longer have to waste time copying and pasting scripts.

By using Git submodules and data sources, we can keep NetBox code and our custom scripts totally separate while making sure they’re always up to date. This approach saves time, reduces errors, and makes it much easier to work with other team members.

Conclusion

It can be a bit tricky to get started with writing custom scripts in NetBox, but with the right setup, it actually becomes enjoyable process. By cloning the NetBox repository, using git submodules for your scripts, and using the NetBox Data Source feature, you can set up a great development environment that’ll really help you get things done!

I hope this blog post helps you get started with setting up your own environment. The most important thing is to find a workflow that works best for you and your team. Feel free to try it out and make adjustments if needed.

If you’ve made it this far, I’m guessing you’re either writing your own scripts or planning to do so in the near future. Please feel free to share your experiences, ask questions, or provide feedback. I’m always happy to learn from others and help out where I can.

Also, if you want to build on your skills, I’d recommend checking out the courses on my DevNet Academy website. I run e-learning for the Cisco Certified DevNet Expert certification. If you’re just starting out or looking to deepen your network automation skills, I’ve got you covered with both DevNet Expert Full Course and a sample course to help you on your journey!