Nautobot Apps - Lab 01: Installing a Nautobot Plugin¶
In our first lab, we'll walk through the process of installing and enabling a Nautobot plugin.
Note: Throughout this course we will be using the terms "Nautobot App" and "Nautobot Plugin" interchangeably.
- Nautobot Apps - Lab 01: Installing a Nautobot Plugin
- Task 0 - Optional: Set up VSCode for Remote SSH
- Task 1: Set up the Server for Development - Part 1
- Step 1-1 - Access the Nautobot Server
- Step 1-2 - Log in
- Step 1-3 - Verify Currently Installed Plugins
- Step 1-4 - Stop the Nautobot Service
- Step 1-5 - Determine Your Two Public Facing IP Addresses
- Step 1-6 - Use Your Nautobot Host's Public Facing IP Address
- Step 1-7 - Use Your Workstation's Public Facing IP Address
- Task 2: Set up the Server for Development - Part 2
- Task 3: Install a Plugin
- Task 4 - Use a Plugin
Task 0 - Optional: Set up VSCode for Remote SSH¶
Visual Studio code is a popular code editor that has a "Remote - SSH" extension that allows you to work remotely taking full advantage of its feature set. All the info to set it up is here and you can also get extra tips about VSCode in this blog.
Note: this is an optional step as you may use your preferred editor. Many students already interested in learning VSCode use this time as an opportunity to do that as it is demonstrated to them.
Step 0-1 - Install VSCode¶
- Installing an OpenSSH compatible SSH client if one is not already present.
- Installing Visual Studio Code or Visual Studio Code Insiders.
- Installing the Remote Development extension pack.
Step 0-2 - Verify Connectivity¶
Verify you can connect to the SSH host by running: ssh user@hostname with the hostname/IP address and credentials provided for this training.
Step 0-3 - Establish an SSH Connection¶
In VSCode, select Remote-SSH: Connect to Host... from the Command Palette (F1) and use the same user@hostname as in step 1 (it will ask for the password).
After a moment, VSCode will connect to the SSH server and set itself up, and you will see in the bottom-left corner a message such as SSH: hostname.
It will also open a remote terminal to the remote host and you will also be able to browse and edit the files remotely. Click "Terminal > New Terminal" if the terminal prompt does not open for you.
Step 0-4 - Open the Remote Folder¶
At first login, if you do not get prompted to open a folder, click on the Open Folder at the top left of the new VSCode window. The default folder to open during this course will be /home/ntc/. Additionally, select File > Add Folder to Workspace and paste the path of the Nautobot installation, /opt/nautobot/. You will now have two folders open in VSCode. VSCode Folders
If you find any issues during this process, please refer to the extension documentation.
Task 1: Set up the Server for Development - Part 1¶
Step 1-1 - Access the Nautobot Server¶
The Nautobot installation on you student pod is mimicking a production style deployment, with an active nginx configuration. If you access the Public IP of your droplet via web browser, you will be re-directed to Nautobot. You should expect to see a Certificate warning as we are using a self-signed certificate.
Click the Advanced button. Depending on your browser you should click Proceed to ..., Continue to ..., or Accept the Risk and Continue.
Step 1-2 - Log in¶
Locate the Log in button in the upper right hand corner of the page.
Click the button and log in with the credentials you have been provided.
Step 1-3 - Verify Currently Installed Plugins¶
Navigate to Plugins > Installed Plugins.
Check if any plugins are installed on your pod.
Note: your display output may differ from the list that is depicted.
Step 1-4 - Stop the Nautobot Service¶
For development of a plugin, we don't want to run a production setup of Nautobot and so we will need to stop the Nautobot service and invoke a development server.
Throughout this course we will be using the bash shell on the pod to execute various commands. For demonstration purposes, we will be using the Terminal > New Terminal feature in VS Code, however you can use any method you prefer to connect to a terminal on the server.
Open a bash prompt and stop the nautobot service using the command: systemctl stop nautobot.
NOTE: You may be prompted in a similar manner throughout the course, so keep the password provided to authenticate into the development server handy. However, if you do a sudo before the command, you do not need to input a password.
ntc@nautobot:~$ systemctl stop nautobot
==== AUTHENTICATING FOR org.freedesktop.systemd1.manage-units ===
Authentication is required to stop 'nautobot.service'.
Authenticating as: ntc
Password:
==== AUTHENTICATION COMPLETE ===
Step 1-5 - Determine Your Two Public Facing IP Addresses¶
Switch to the nautobot user. The sudo -iu nautobot command will run the login profile, which will change into the /opt/nautobot home directory and activate the virtual environment.
You will need to determine two public facing IP addresses:
- The public IP address of your Nautobot host and
- The public IP address of your workstation running your web browser.
You can use an external service, like ipinfo.io to query the public IP address of your Nautobot host.
You can also get the public IP address of your workstation in your browser by visiting a website such as WhatisMyIP?
Step 1-6 - Use Your Nautobot Host's Public Facing IP Address¶
On the server, locate and edit the /opt/nautobot/nautobot_config.py file.
Next, locate each of the below configuration values within the /opt/nautobot/nautobot_config.py file. Within the nautobot_config.py file, the all-caps variable names are mostly in alphabetical order.
Allow development server to listen on the public IP address
Update the ALLOWED_HOSTS to include the Public IP of your Nautobot Instance.
Change to:
Step 1-7 - Use Your Workstation's Public Facing IP Address¶
Allow development server to accept requests from your public IP address when running in DEBUG mode.
Add the public IP of your workstation to the INTERNAL_IPS tuple.
Change to:
Task 2: Set up the Server for Development - Part 2¶
Step 2-1 - Set the DEBUG Parameter to True¶
Finally, set the DEBUG parameter to True. This will allow the Django Debug Toolbar to display.
Locate this line:
Change to:
Save your file, but keep it open in your editor for the next step.
Step 2-2 - Create a Super User (Optional)¶
Your student pod should have the admin user already created for you with superuser privilege. In case you don't have a superuser Nautobot user or if you want to create a new one, you can use the createsuperuser built-in command that will create a new user with the is_superuser boolean. In Django there are two special types for the User model:
is_superuser: Designates that this user has all permissions without explicitly assigning them.is_staff: Designates whether this user can access the admin site.
This is an optional step
Step 2-3 - Install the Django Debug Toolbar¶
Almost there! Lets now install the Django Debug Toolbar to enhance our ability to debug app development. Make sure to do this as the nautobot user and within the correct virtual environment, which is activated upon correctly switching to the nautobot user, using the following method
Note: Be sure to install version 3.2.4 of the django-debug-toolbar, as the latest version requires Django 4.x. Nautobot 1.2 is built on Django 3.x.
ntc@nautobot:/opt/nautobot$ sudo -iu nautobot
nautobot@nautobot:~$ pip install django-debug-toolbar==3.2.4
Collecting django-debug-toolbar
Downloading django_debug_toolbar-3.2.4-py3-none-any.whl (216 kB)
|████████████████████████████████| 216 kB 7.1 MB/s
Requirement already satisfied: Django>=2.2 in /opt/nautobot/lib/python3.8/site-packages (from django-debug-toolbar) (3.1.14)
Requirement already satisfied: sqlparse>=0.2.0 in /opt/nautobot/lib/python3.8/site-packages (from django-debug-toolbar) (0.4.2)
Requirement already satisfied: pytz in /opt/nautobot/lib/python3.8/site-packages (from Django>=2.2->django-debug-toolbar) (2021.3)
Requirement already satisfied: asgiref<4,>=3.2.10 in /opt/nautobot/lib/python3.8/site-packages (from Django>=2.2->django-debug-toolbar) (3.4.1)
Installing collected packages: django-debug-toolbar
Successfully installed django-debug-toolbar-3.2.4
Step 2-4 - Update nautobot_config.py for the Django Toolbar¶
Return to your editor where you have the /opt/nautobot/nautobot_config.py open. In order to use the newly installed Django Debug Toolbar you need to tell Nautobot to use it. Add the following lines at the end nautobot_config.py file:
EXTRA_INSTALLED_APPS = ["debug_toolbar"]
EXTRA_MIDDLEWARE = ["debug_toolbar.middleware.DebugToolbarMiddleware"]
Step 2-5 - Start the Development Server¶
Now we will start a Development Server using the nautobot-server command.
nautobot@nautobot:~$ nautobot-server runserver 0.0.0.0:8080 --insecure
Watching for file changes with StatReloader
Performing system checks...
System check identified no issues (0 silenced).
January 10, 2022 - 19:28:29
Django version 3.1.14, using settings 'nautobot_config'
Starting development server at http://0.0.0.0:8080/
Quit the server with CONTROL-C.
Step 2-6 - Verify the Django Toolbar¶
To verify installation of the Django Toolbar, open the Nautobot home page in your web browser using the public IP address of your Nautobot instance. Since we are passing the --insecure argument to the nautobot-server, we must use 'http and not https.
http://<PublicIPAddress>:8080/.
Note: If you are using VS Code, click on the
Open in Browserbutton.
Click the Django Debug Toolbar (DjDT) tab along the right side of the screen.
Note: If you don't see the toolbar or button, check that
DEBUG = Trueis set in/opt/nautobot/nautobot_config.pyand the source IP address of your browser is listed inINTERNAL_IPS = ("127.0.0.1", "123.45.67.89")Note: Find your public IP using a website, such as WhatIsMyIP?. Copy and paste your public IP address into the
/opt/nautobot/nautobot_config.pyfile as show below
Task 3: Install a Plugin¶
Step 3-1 - Verify the Virtual Environment's User Name¶
Your lab host has been preinstalled with Nautobot following the guidelines in the installation guide. This means that there is a nautobot user that has a Python virtual environment, which gets activated upon login. As we stated above, by running the command sudo -iu nautobot you will switch to the nautobot user and activate the virtual environment.
Step 3-2 - Verify the Virtual Environment's Current Working Directory¶
You can verify the working directory using the command pwd (print working directory). Notice the command output is /opt/nautobot.
Step 3-3 - Verify the Virtual Environment's Python Version¶
The command which python will indicate the location of the Python virtual environment.
Step 3-4 - Run the Web Server¶
Django includes a small built-in HTTP server that we'll use for testing and development. The development server is preferable to a complete installation because it automatically reloads when it detects a change to the code base.
Start the development server using the nautobot-server management command. By default, the development server will only bind to the local loopback IP, so we specify 0.0.0.0 as the bind address to ensure it's remotely accessible. Additionally, we pass the --insecure argument to enable serving static files. (As you've likely inferred, the development server should never be used in production.)
nautobot@nautobot:~$ nautobot-server runserver 0.0.0.0:8080 --insecure
Performing system checks...
System check identified no issues (0 silenced).
January 05, 2022 - 18:11:25
Django version 3.1.14, using settings 'nautobot_config'
Starting development server at http://0.0.0.0:8080/
Quit the server with CONTROL-C.
18:11:25.707 INFO nautobot :
Nautobot initialized!
The development server will continue running until stopped by pressing ctrl+c. You may find it advantageous to open a second terminal window or use a terminal multiplexer such as screen so that you can continue working while the server is running. (Remember to sudo -iu nautobot for each new console session.)
Step 3-5 - Install a Plugin¶
Install the plugin's Python package using pip. Issue the command pip install nautobot-golden-config==0.9.10
nautobot@nautobot:~$ pip install nautobot-golden-config==0.9.10
Collecting nautobot-golden-config==0.9.10
Downloading nautobot_golden_config-0.9.10-py3-none-any.whl (105 kB)
|████████████████████████████████| 105 kB 10.0 MB/s
<---OMITTED--->
Note: To ensure compatibility and a stable environment, Nautobot plugins usually have their version pinned to a specific version. In the case of Golden Config, we have pinned version
0.9.10.
Step 3-6 - Update Local Requirements¶
The Nautobot upgrade process involves rebuilding the Python virtual environment. To ensure that the plugin persists after an upgrade, we'll add it to the local list of required Python packages, local_requirements.txt.
Note: Use of the double arrow (
>>) will append contents to an existing file or create a new file if one does not exist. A single arrow (>) in the above command would overwrite the file contents if the file already exists.
Task 4 - Use a Plugin¶
Step 4-1 - Enable the Plugins¶
Now that the plugin package is installed, we need to enable it. Uncomment and modify the PLUGINS configuration parameter inside of nautobot/nautobot_config.py. Since Golden Config Plugin requires Nautobot Nornir Plugin to be installed, we will also need to enable the additional dependency plugin.
Open the /opt/nautobot/nautobot_config.py file in VSCode and edit the PLUGINS configuration line to include the newly installed plugins. There may be previously installed plugins and we want to add to the list.
Note: When enabling a plugin, be sure to use the Python package name, not the name of the plugin itself, which may be different. (Python package names cannot contain hyphens.)
Step 4-2 - Configure the Plugins¶
Also in nautobot_config.py, we can set any plugin-specific configuration parameters under PLUGINS_CONFIG['nautobot_golden_config']. We'll designate a few plugin specific parameters. Uncomment and modify the following below PLUGINS inside of nautobot/nautobot_config.py. Remember, we are modifying two different plugins configurations:
PLUGINS_CONFIG = {
"nautobot_plugin_nornir": {
"nornir_settings": {
"credentials": "nautobot_plugin_nornir.plugins.credentials.env_vars.CredentialsEnvVars",
"runner": {
"plugin": "threaded",
"options": {
"num_workers": 20,
},
},
},
},
"nautobot_golden_config": {
"per_feature_bar_width": 0.15,
"per_feature_width": 13,
"per_feature_height": 4,
"enable_backup": True,
"enable_compliance": True,
"enable_intended": True,
"enable_sotagg": True,
"sot_agg_transposer": None,
"platform_slug_map": None,
},
}
The specific configuration parameters supported are unique to each plugin. When installing a Nautobot plugin, be sure to check its documentation to see all available options. As you saw above, we had to provide plugin specific configurations for both nautobot_golden_config and nautobot_plugin_nornir.
Step 4-3 - Run the Post Upgrade Command¶
Some plugins include their own data models that require the execution of database migrations before the plugin will work correctly. Once the plugin has been enabled, you should always run nautobot-server post_upgrade. This command will ensure that any necessary post-installation tasks are run.
The post_upgrade management command will execute the following:
- migrate
- trace_paths
- collectstatic
- remove_stale_contenttypes
- clearsessions
- invalidate all
If there is ever a need to not perform all the above commands, you can append the following flags to the post_upgrade command to prevent execution:
--no-clearsessions
Do not automatically clean out expired sessions.
--no-collectstatic
Do not automatically collect static files into a single location.
--no-invalidate-all
Do not automatically invalidate cache for entire application.
--no-migrate
Do not automatically perform any database migrations.
--no-remove-stale-contenttypes
Do not automatically remove stale content types.
--no-trace-paths
Do not automatically generate missing cable paths.
Apply the post_upgrade command to our Nautobot installation
nautobot@nautobot:~$ nautobot-server post_upgrade
Performing database migrations...
Operations to perform:
Apply all migrations: admin, auth, circuits, contenttypes, database, dcim, django_celery_beat, extras, ipam, nautobot_golden_config, sessions, social_django, taggit, tenancy, users, virtualization
Running migrations:
Applying nautobot_golden_config.0005_json_compliance_rule... OK
Generating cable paths...
Found no missing circuit termination paths; skipping
Found no missing console port paths; skipping
Found no missing console server port paths; skipping
Found no missing interface paths; skipping
Found no missing power feed paths; skipping
Found no missing power outlet paths; skipping
Found no missing power port paths; skipping
Finished.
Collecting static files...
9 static files copied to '/opt/nautobot/static', 974 unmodified.
Removing stale content types...
Removing expired sessions...
Invalidating cache...
This particular Nautobot plugin had several migrations to apply and 2 static files were copied.
Step 4-4 - Restart the Server¶
Anytime you install new packages or make changes to the nautobot_config.py file, you will need to restart the server. On a production server that is usually performed with the command sudo systemctl restart nautobot nautobot-worker, which restarts both the Nautobot server and the job runner process.
When you run the development server with the command nautobot-server runserver 0.0.0.0:8080 --insecure you may notice the output Watching for file changes with StatReloader. This means that the development server watches the file system and checks for files whose modified timestamp is more recent that the last server reload. When it sees newer files, it restarts the server. This is a great convenience, but it is not perfect. As the nautobot_config.py file is a configuration file that is only read at startup time, the file is not monitored for changes. Additionally, any Python files that were not loaded into the running server are also not monitored. So when we pip install a new plugin, the development server will not monitor those files until after we configure the plugin and manually restart the development server.
Open the terminal where your development server is running and hit <CTRL> C to stop the server, and then issue the command to start the server.
Quit the server with CONTROL-C.
^C
nautobot@ntc-nautobot-apps:~$ nautobot-server runserver 0.0.0.0:8080 --insecure
Watching for file changes with StatReloader
Performing system checks...
...
Step 4-5 - Verify the Installed Plugin¶
Log into the Nautobot UI, and select the click the Plugins menu. Here you can see the functionality provided by the plugin, under the plugin name.
This lab has demonstrated the process for installing an existing plugin. The remainder of the labs for this course will walk you through building a new custom plugin.