v2.0.0 - 2023-09-29

[glennmatthews]

!!! note
Please thoroughly review the release overview below to see what changes may affect you during upgrade. Our "Upgrading from Nautobot v1.X" guide provides a lot of information around pre- and post-migration helpers we have written that should assist you in a successful 2.0 upgrade. If you have any questions, please reach out to us on the #nautobot channel on Network to Code's Slack community or GitHub Discussions.

Release Overview

Added

Alpha UI 2.0 (#3142)

Nautobot 2.0 includes an "alpha" version of a new user interface (UI) for Nautobot, based on the React web framework.

Users can switch between the existing UI and new UI for views supported in the new UI via a "View in New UI" link in the page footer of the existing UI and a "Return to Legacy UI" link in the left sidebar of the new UI.

!!! tip
The new UI also includes a "Submit Feedback" link that can be used to easily submit feedback regarding the new UI to the Nautobot maintainers.

As of Nautobot release 2.0.0, the new UI supports read-only access to Locations, Device Types, Devices, Prefixes, and IP Addresses; these views will be enhanced and refined, and support for additional models and workflows will be added, throughout the Nautobot 2.x release lifecycle.

!!! info
As of Nautobot release 2.0.0, the new UI, as an alpha feature, does not yet support Nautobot Apps (plugins), but this capability will be added and supported in a future release.

Assign an IP Address to Multiple Interfaces (#2403)

Introduced the ability to assign one IPAddress to multiple Interfaces/Devices and VMInterfaces/VirtualMachines by creating a many to many relationship between IPAddress and Interface/VMInterface models represented as a through table model IPAddressToInterface. This feature allows you to model a network environment where you have anycast IPAddresses are shared extensively among a large number of Devices/VirtualMachines.

As a result of this feature and associated changes, you can no longer assign Interfaces/VMInterfaces during bulk creation of IPAddresses, but a separate bulk-create endpoint has been introduced to allow the bulk import of IPAddressToInterface assignments.

Generic Role Model (#1063)

DeviceRole, RackRole, IPAM Role, and IPAddressRoleChoices have all been merged into a single generic Role model. A Rolecan now be created and associated to one or more of the content-types that support reference to a role. These model content-types include dcim.device, dcim.rack, virtualization.virtualmachine, ipam.ipaddress, ipam.prefix, and ipam.vlan.

IPAM Namespaces (#3337)

The new Namespace model expands on the functionality previously provided by VRF.enforce_unique and the ENFORCE_GLOBAL_UNIQUE settings flag, both of which have now been removed. Within a namespace, all VRFs, prefixes, and IP addresses must be unique and non-duplicated. For more details please refer to the documentation.

Natural Key Support Across Nautobot Models (#2900)

Nautobot's BaseModel base class and related classes now implement automatic support for Django natural keys for lookup and referencing. For example:

>>> DeviceType.objects.first().natural_key()
['MegaCorp', 'Model 9000']

>>> DeviceType.objects.get_by_natural_key("MegaCorp", "Model 9000")
<DeviceType: Model 9000>

Developers can refer to the documentation on natural keys for details on how to support and use this feature.

Two new configuration settings, DEVICE_NAME_AS_NATURAL_KEY and LOCATION_NAME_AS_NATURAL_KEY, have been added to allow an administrator to customize the natural-key behavior of these two widely-used models.

REST API Query Depth Parameter (#3042)

Added the ?depth query parameter in Nautobot v2.X to replace the ?brief parameter in the REST API. It enables nested serialization functionality and offers a more dynamic and comprehensive browsable API. It allows users greater control of the API response data and it is available for both retrieving a single object and a list of objects. This parameter is a positive integer value that can range from 0 to 10. To learn more more, check out the documentation on the ?depth query parameter.

Site Fields Added to Location (#2954)

Added Site Model Fields to Location. Location Model now has asn, comments, contact_email, contact_name, contact_phone, facility, latitude, longitude, physical_address, shipping_address and time_zone fields.

Changed

Aggregate Model Migrated to Prefix (#3302)

The ipam.Aggregate model has been removed and all existing aggregates will be migrated to ipam.Prefix with type set to "Container". The Aggregate.date_added field will be migrated to Prefix.date_allocated and changed from a Date field to a DateTime field with the time set to 00:00. Aggregate.tenant, Aggregate.rir and Aggregate.description will be migrated over to the same fields on Prefix.

See the upgrade guide for more details on the data migration.

Changed created Field to DateTimeField for ChangeLoggedModel (#2076)

The created field of all models that inherit from ChangedLoggedModel, which includes OrganizationalModel and PrimaryModel and therefore most objects in the core data model, has been changed from a DateField to a DateTimeField for added granularity. Preexisting records will show as created at midnight UTC on their original creation date.

All such objects may now be filtered by date or time or a combination of both. All other date-based behavior such as filtering works as it did before.

Collapsed nautobot.utilities into nautobot.core (#2721)

nautobot.utilities no longer exists as a separate Python module or Django app. Its functionality has been collapsed into the nautobot.core app. See details at Python Code Location Changes.

Collapsed Region and Site Models into Location (#2517)

Initial Data Migration

The Site and Region models have been removed in v2.0 and have been replaced with Location of specific LocationType. As a result, the existing Site and Region data will be migrated to corresponding LocationType and Location objects. Here is what to expect:

1. If you do not have any Site and Region instances in your existing database, running this data migration will do nothing.

2. If you only have Region instances in your existing database, a LocationType named Region will be created and for each legacy Region instance, a corresponding Location instance with the same attributes (id, name, description, etc.) and hierarchy will be created.

3. If you only have Site instances in your existing database:

   • A LocationType named Site will be created and every preexisting root level LocationType in your database will be updated to have the new Site LocationType as their parent.

   • For each legacy Site instance, a corresponding Location instance with the same attributes (id, name, description, tenant, facility, asn, latitude, longitude, etc.) will be created, and any preexisting Locations in your database will be updated to have the appropriate "site" Locations as their parents.

   • Model instances that had a site field (CircuitTermination, Device, PowerPanel, RackGroup, Rack, Prefix, VLANGroup, VLAN, Cluster) assigned and did not have a location attribute assigned will be updated to have their location point to the new Location corresponding to that Site. All other attributes on these models will remain unchanged.

   • Model instances that were previously associated to the ContentType for Site (ComputedField, CustomField, CustomLink, ExportTemplate, ImageAttachment, JobHook, Note, Relationship, Status, Tag and Webhook) will have their ContentType replaced with Location. All other attributes on these models will remain unchanged.

   For Example:

   • We will start with a Site instance with name AMS01 as the base Site for two top-level Location objects with names root-01 and root-02 respectively.

   • During the data migration, a LocationType named Site will be created, and a Location of Site LocationType named AMS01 with all the information (asn, latitude, etc.) from the base Site will be created.

   • The Location objects named root-01 and root-02 will have this AMS01 Location set as their parent.

4. If you have both Site and Region instances in your existing database:

   • A LocationType named Region will be created.

   • For each legacy Region instance, a corresponding Location instance with the same attributes (id, name, description, etc.) will be created.

   • A LocationType named Site will be created with the new LocationType named Region set as its parent.

   • Every pre-existing root-level LocationType in your database will be updated to have the new LocationType named Site as its parent.

   • For each legacy Site instance, a corresponding "site" Location instance with the same attributes (id, name, description, tenant, facility, asn, latitude, longitude, etc.) will be created with its parent set to the corresponding "region" Location if any.

     • If you have Site instances in your database without a Region assigned to them, one additional Location named Global Region of LocationType Region will be created and each Location of LocationType Site created from the legacy region-less Site instances will have the Global Region Location as their parent.

   • Model instances that had a site attribute (CircuitTermination, Device, Location, PowerPanel, Rack, RackGroup, Prefix, VLANGroup, VLAN, Cluster) assigned and did not have a location attribute assigned will be updated to have their location point to the new Location of LocationType Site. All other attributes on these models will remain unchanged.

   • Model instances that were previously associated to the ContentType for Site or Region (ComputedField, CustomField, CustomLink, ExportTemplate, ImageAttachment, JobHook, Note, Relationship, Status, Tag and Webhook) will have their ContentType replaced with Location. All other attributes on these models will remain unchanged.

   For Example:

   • There are two Site instances and one Region instance in your existing database. The Region with name America has one child Site instance named AMS01. And the other Site instance named AUS01 is not associated with any Region (region attribute is set to None).

   • The Site AMS01 is the base Site for two top-level Location objects with names root-01 and root-02 respectively.

   • During the data migration, a LocationType named Region and a Location of this LocationType named America with all the same information will be created.

   • The LocationType named Site with its parent set as the new LocationType Region and a Location of LocationType named AMS01 with all the same information (asn, latitude, etc.) will be created. The Location AMS01 will have Location America as its parent and each - Location root-01 and root-02 will have Location AMS01 as its parent.

   • Finally, the Site instance AUS01, since it does not have a Region instance associated with it, its corresponding Location AUS01 will have a new Location named Global Region of LocationType Region as its parent.

   • In addition, legacy Site instance with name AMS01 also has three Device instances associated with it named ams01-edge-01, ams01-edge-02, and ams01-edge-03.

   • However, ams01-edge-01 only has its site attribute set as Site AMS01 whereas ams01-edge-02 and ams01-edge-03 have both its site and location attributes set Site AMS01 and Location root-01 respectively.

   • During the data migration, ams01-edge-01's location attribute will point to the new Location of LocationType Site with name AMS01 while devices ams01-edge-02 and ams01-edge-03 will remain unchanged.

Remove Site and Region Related Fields from Models

Region and Site relationships are being removed from these models: CircuitTermination, Device, Location, Rack, RackGroup, PowerFeed, PowerPanel, ConfigContext, Prefix, VLAN, VLANGroup, Cluster.

The ContentType for Region and Site are being replaced with Location on these models: ComputedField, CustomField, CustomLink, ExportTemplate, ImageAttachment, JobHook, Note, Relationship, Status, Tag and Webhook.

The region and site fields are being removed in the filter data of DynamicGroup objects. The previously associated values are being added to the existing location field and its associated list of filter values or to a new location key with an empty list if one does not exist.

Check out the API and UI endpoints changes incurred by the changes stated above in the "Upgrading from Nautobot v1.X" guide.

Check out the Region and Site Related Data Model Migration Guide to learn how to migrate your Nautobot Apps and data models from Site and Region to Location.

Corrected Filter Fields (#2804)

!!! warning
This change may introduce breaking changes to your existing DynamicGroup filters, ObjectPermission filters, Relationship filters, and any other saved references to these fields. You should review any existing instances of these models before and after upgrading your production environment for any potentially subtle change. Please refer to the Upgrading from Nautobot v1.X guide for more details.

There were also instances where a foreign-key related field (e.g. console_ports) was incorrectly mapped to a boolean membership filter (e.g. has_console_ports), making it impossible to filter based on specific values of the foreign key:

For example in v1.x:

/dcim/devices/?console_ports=True and /dcim/devices/?has_console_ports=True are functionally the same and this behavior is incorrect.

This has been addressed in v2.x as follows:

console_ports and similar filters are taking foreign key UUIDs as input values and can be used in this format: /dcim/devices/?console_ports=<uuid> whereas has_console_ports and similar filters remain the same.

Check out the specific changes documented in the table at UI and REST API Filter Changes

Enhanced Filter Fields (#2804)

!!! warning
This change may introduce breaking changes to your existing DynamicGroup filters, ObjectPermission filters, Relationship filters, and any other saved references to these fields. You should review any existing instances of these models before and after upgrading your production environment for any potentially subtle change. Please refer to the Upgrading from Nautobot v1.X guide for more details.

Many filter fields have been enhanced to enable filtering by both names and UUID primary keys.

For example in v1.X, to filter RackGroups with a specific parent value in the UI or make changes to them via the REST API, you could only to input slugs as the filter values:

/dcim/rack-groups/?parent=<slug>

Now in v2.x, you are able to filter those RackGroups by their parent(s) names or UUID primary keys:

/dcim/rack-groups/?parent=<name> or /dcim/rack-groups/?parent=<uuid>

Check out the specific changes documented in the table at UI and REST API Filter Changes

Generic Role Model (#1063)

The DeviceRole, RackRole, ipam.Role, and IPAddressRoleChoices have all been removed and replaced with a extras.Role model, This means that all references to any of the replaced models and choices now points to this generic role model.

In addition, the role field of the IPAddress model has also been changed from a choice field to a foreign key related field to the extras.Role model.

Job Overhaul (#765)

Within Nautobot 2.0, Jobs has undergone significant changes within the overall functionality of Jobs along with migration for existing 1.x Jobs operation. Database changes for Jobs will affect DryRun functionality. Other significant changes to Jobs in 2.0 provide greater interoperability with Celery for registering, logging, and tracking however 2.0 will be moving away from previous backwards compatibility scripts. These improvements will simplify Job implementation and help reduce administration overhead for status tracking on completions and/or failures. For more details, refer to Migrating Jobs from Nautobot v1.X to Nautobot v2.0.

Prefix is_pool Field and "Container" Status replaced by New Field Prefix.type (#1362)

A new type field was added to Prefix to replace the is_pool boolean field and the "Container" status. The type field can be set to "Network", "Pool" or "Container", with "Network" being the default.

Existing prefixes with a status of "Container" will be migrated to the "Container" type. Existing prefixes with is_pool set will be migrated to the "Pool" type. Prefixes with both is_pool set and a status of "Container" will be migrated to the "Pool" type.

The "Container" status will be removed and all prefixes will be migrated to the "Active" status if it exists. If the "Active" status was deleted, prefixes will be migrated to the first available prefix status in the database that is not "Container".

Renamed Database Foreign Keys and Related Names (#2520)

!!! warning
This change may introduce breaking changes to your existing DynamicGroup filters, ObjectPermission filters, Relationship filters, and any other saved references to these fields. You should review any existing instances of these models before and after upgrading your production environment for any potentially subtle change. Please refer to the Upgrading from Nautobot v1.X guide for more details.

Some Foreign Key fields have been renamed to follow a more self-consistent pattern across the Nautobot app. This change is aimed to offer more clarity and predictability when it comes to related object database operations:

For example in v1.x to create a circuit object with type "circuit-type-1", you would do:

Circuit.objects.create(
    cid="Circuit 1",
    provider="provider-1",
    type="circuit-type-1",
    status="active",
)

and to filter Circuit objects of type "circuit-type-2", you would do:

Circuit.objects.filter(type="circuit-type-2")

Now in v2.x, we have renamed the Foreign Key field type on Circuit Model to circuit_type, because this naming convention made it clearer that this Foregin Key field is pointing to the model CircuitType. The same operations would look like:

Circuit.objects.create(
    cid="Circuit 1",
    provider="provider-1",
    circuit_type="circuit-type-1",
    status="active",
)

Circuit.objects.filter(circuit_type="circuit-type-2")

Check out more Foreign Key related changes documented in the table Renamed Database Fields

In addition to the changes made to Foreign Key fields' own names, some of their related_names are also renamed:

For example in v1.x, to query Circuit objects with CircuitTermination instances located in sites ["ams01", "ams02", "atl03"], you would do:

Circuit.objects.filter(terminations__site__in=["ams01", "ams02", "atl03"])

Now in v2.x, we have renamed the Foreign Key field circuit's related_name attribute terminations on CircuitTermination Model to circuit_terminations, the same operations would look like:

Circuit.objects.filter(circuit_terminations__site__in=["ams01", "ams02", "atl03"])

Check out more related-name changes documented in the table Renamed Database Fields

Renamed Filter Fields (#2804)

!!! warning
This change may introduce breaking changes to your existing DynamicGroup filters, ObjectPermission filters, Relationship filters, and any other saved references to these fields. You should review any existing instances of these models before and after upgrading your production environment for any potentially subtle change. Please refer to the Upgrading from Nautobot v1.X guide for more details.

Some filter fields have been renamed to reflect their functionalities better.

For example in v1.X, to filter FrontPorts that has a cable attached in the UI or make changes to them via Rest API, you would use the cabled filter:

/dcim/front-ports/?cabled=True

Now in v2.x, you would instead use the has_cable filter which has a more user-friendly name:

/dcim/front-ports/?has_cable=True

Check out the specific changes documented in the table at UI and REST API Filter Changes

REST API Versioning Behavior (#2799)

In Nautobot 2.0 and later, the REST API defaults, when the caller doesn't request a specific API version, to using the latest available version of the REST API. This is a change from Nautobot 1.x, where the default behavior was to use the 1.2 version of the REST API even when newer versions were available.

Revamped CSV Import and Export (#254)

Exporting objects and lists of objects to CSV format has been totally reimplemented in a new framework for ease of use and maintainability. Instead of accessing http://nautobot/<app>/<model>/?export users can now use the URL pattern http://nautobot/api/<app>/<model>/?format=csv (the "Export" links in the UI have of course been updated accordingly), as the new CSV rendering for exports is based on the REST API serializer definitions. This results in substantially more comprehensive CSV representations of many models.

Conversely, importing objects from CSV format has also been reimplemented in the same new framework. The REST API can now accept CSV files as well as the existing JSON support, and the UI for importing CSVs uses this same framework behind the scenes.

!!! warning
The Nautobot 2.0 CSV formats for exports and imports are not backwards-compatible with the Nautobot 1.x CSV formats. In general, the CSV formats are subject to refinement in future releases, and should not be considered a stable API for data portability between differing Nautobot versions.

An immediate benefit users can notice from this reimplementation is that CSVs should now generally be "round-trip" capable, meaning that you can export a set of records to CSV format and then import that CSV into a different Nautobot instance (or delete the records and use the CSV to recreate them) without needing to "massage" the CSV into a different set of columns or fields. One caveat to this is many-to-many fields (such as VRF.import_targets or Interface.tagged_vlans), which are not currently included in CSV exports or supported for CSV import, with the exception of object tags which are supported. Support for many-to-many export and import via CSV may be added in a future release.

A benefit to App developers is that data models no longer need to define a csv_headers attribute or implement a to_csv method, because implementing the REST API for a model is now sufficient to enable CSV import/export support for that model. Similarly, there is no longer a need to implement a CSVForm for each model in order to support CSV import.

In addition to the above improvements, you can now reference related objects in your CSV by using a combination of unique fields. For instance:

Instead of:

name,rack
Device one,7f3ca431-8103-45cc-a9ce-b94c1f784a1d

you can use:

name,rack__location__name,rack__name
Device one,Equinix DC6,R204

This enhancement allows you to specify related objects using their unique attributes, making data import even more intuitive and flexible.

Removed

Brief REST API Query Parameter (#3042)

Support for ?brief REST API query parameter and Nested*Serializers have been removed in Nautobot v2.X. They are replaced by the new ?depth query parameter.

django-cacheops (#1721)

Nautobot no longer uses django-cacheops for caching of database queries or other information. In some cases this has been replaced by the use of Django's native Redis caching capabilities.

The configuration settings CACHEOPS, CACHEOPS_DEFAULTS, CACHEOPS_DEGRADE_ON_FAILURE, CACHEOPS_ENABLED, CACHEOPS_HEALTH_CHECK_ENABLED, CACHEOPS_REDIS, etc. are now unused by Nautobot and may be removed from your configuration.

Legacy manage.py Removed (#1634)

When we launched Nautobot we introduced the nautobot-server command as the primary entrypoint to managing your application, replacing the legacy manage.py script that is common with Django-based applications. The original manage.py was left there initially in v1.0.0 as a fallback, however it is no longer needed, so we have removed it in Nautobot 2.0.

Redundant Filter Fields (#2804)

!!! warning
This change may introduce breaking changes to your existing DynamicGroup filters, ObjectPermission filters, Relationship filters, and any other saved references to these fields. You should review any existing instances of these models before and after upgrading your production environment for any potentially subtle change. Please refer to the Upgrading from Nautobot v1.X guide for more details.

As a part of breaking changes made in v2.X, shadowed filter/filterset fields are being removed throughout Nautobot.

In Nautobot 1.x, for some of the foreign-key related fields:
- The field was shadowed for the purpose of replacing the PK filter with a lookup-based on a more human-readable value (typically slug, if available).
- A PK-based filter was available as well, generally with a name suffixed by _id

Now these two filter fields will be replaced by a single filter field that can support both names and UUID primary keys as inputs; As a result, PK-based filters suffixed by _id will no longer be supported in v2.0.

For example in v1.X, to filter Circuits with a specific provider value in the UI or make changes to them via the REST API with a UUID primary key, you would use:

/circuits/circuits/?provider_id=<uuid>

Now in v2.x, that format is no longer supported. Instead, you would use:

/circuits/circuits/?provider=<uuid>

Check out the specific changes documented in the table at UI and REST API Filter Changes

RQ support (#2523)

Support for RQ and django-rq, deprecated since Nautobot 1.1.0, has been fully removed from Nautobot 2.0.

Slug Fields (#2662)

The slug field has been removed from all core models except for GitRepository. Generally, Nautobot URLs that referenced the slug field have been changed to use the primary key instead. For example, the URL for https://nautobot/dcim/locations/building-01 would change to a URL similar to https://nautobot/dcim/locations/e41f381a-a53b-485a-886f-9d36859b47a1. There are a small number of URLs that still reference a value that's not the primary key, including some URLs related to secrets providers, cables and jobs.

A natural_slug property has been added to all models that inherit from BaseModel to provide a human-readable value for use in tools that require a loose reference to a Nautobot object, but this value is not equivalent to the slug field and is not guaranteed to be unique.

A natural key interface has been provided for most models to allow for uniquely referencing objects by a name that is friendlier than the primary key. For more information on the usage of natural keys vs primary keys see the documentation for Uniquely Identifying a Nautobot Object.

Contributors

• @bile0026
• @bryanculver
• @dependabot
• @DistantVoyager
• @glennmatthews
• @grelleum
• @gsnider2195
• @HanlinMiao
• @itdependsnetworks
• @jamesharr
• @jathanism
• @jeffkala
• @jfach
• @jmcgill298
• @joewesch
• @jvanderaa
• @Kircheneer
• @lampwins
• @matt852
• @MeganerdDev
• @nniehoff
• @norbert-mieczkowski-codilime
• @PavelSafronov
• @renovate
• @romanukes
• @scetron
• @slash-24
• @smk4664
• @snaselj
• @timizuoebideri1
• @u1735067
• @whitej6

New Contributors

• @PavelSafronov made their first contribution in Update assertInstanceEqual to fix JSON comparison of 'data_schema' keys. #3568
• @MeganerdDev made their first contribution in Add Markdown custom field type #4007
• @jamesharr made their first contribution in Add url field to GraphQL output #4163
• @slash-24 made their first contribution in Jobs Overhaul release-note #4554

Full Changelog: v1.6.2...v2.0.0

---

This discussion was created from the release v2.0.0 - 2023-09-29.