Upgrading from Nautobot v1.X

Pre-migration validation

In Nautobot 1.x, starting with 1.5.22, there is a nautobot-server pre_migrate command that can be run to check your existing data for compatibility with the data model changes introduced in Nautobot 2.0. You are highly encouraged to run this command before beginning to migrate to Nautobot 2.x as it will catch and report certain data-sanitization issues that cannot be remediated automatically during the migration and will need to be manually corrected before you upgrade.

For example, if any of the pre-migration checks fail, you may see an error message like this:

$ nautobot-server pre_migrate
>>> Running check: check_configcontext_uniqueness...
>>> Running check: check_exporttemplate_uniqueness...
>>> Running check: check_virtualchassis_uniqueness...
CommandError: One or more pre-migration checks failed:
    You cannot migrate ConfigContext or ConfigContextSchema objects that have non-unique names:
    - ConfigContext: [{'name': 'cc1', 'count': 2}]
    - ConfigContextSchema: [{'name': 'ccs1', 'count': 2}]

    You cannot migrate VirtualChassis objects with non-unique names:
     - [{'name': 'vc1', 'count': 2}]

Otherwise, a clean exit displays "All pre-migration checks passed." indicating that your Nautobot instance is ready to be upgraded to Nautobot 2.0:

$ nautobot-server pre_migrate
>>> Running check: check_configcontext_uniqueness...
>>> Running check: check_exporttemplate_uniqueness...
>>> Running check: check_virtualchassis_uniqueness...
All pre-migration checks passed.

Permission Constraint Migration

Permission constraints that contain references to fields or models that were changed or removed in Nautobot 2.0 will have to be updated manually after the upgrade. For example, any permission constraints that reference a Site will need to be updated to reference the Location model instead. The nautobot-server pre_migrate command will output a list of all permission constraints that need to be updated after the upgrade.

>>> Running permission constraint checks...

One or more permission constraints may be affected by the Nautobot 2.0 migration.
These permission constraints will have to be updated manually after upgrading to
Nautobot 2.0 to reference new models and/or values. Please review the following
warnings and make sure to document the objects referenced by these constraints
before upgrading:

ObjectPermission 'backbone devices' (id: ced686c3-2b34-4612-974a-bad766512661) has a constraint that references a model (nautobot.dcim.models.devices.DeviceRole) that will be migrated to a new model by the Nautobot 2.0 migration.
{
    "device_role": "e99adc77-40ef-4a0f-b2c1-26dbf6648ef1"
}

ObjectPermission 'example job run' (id: 41c6d03e-6388-47eb-b575-1c7a21725bc3) has a constraint that references a model field (nautobot.extras.models.jobs.Job.name) that may be changed by the Nautobot 2.0 migration.
{
    "name": "Example job, does nothing"
}

ObjectPermission 'emea' (id: 2d3b7aae-98ab-44ec-af89-43d3002a1b7d) has a constraint that references a model (nautobot.dcim.models.sites.Region) that will be migrated to a new model by the Nautobot 2.0 migration.
[
    {
        "site__region__slug": "emea"
    },
    {
        "id": "4c9f3e5c-2dc6-46f6-95ac-ac778369edfc"
    }
]

We recommend taking inventory of any objects referenced by primary key in permission constraints for the following models:

• dcim.DeviceRole
• dcim.RackRole
• extras.TaggedItem
• ipam.Aggregate
• ipam.IPAddress
• ipam.Prefix
• ipam.Role

This is because the primary key for these objects may be changed during the migration. You will not be able to use the primary key value from the old object in the constraint to find the new object.

Note

This pre-migration check only checks the last model referenced in a constraint filter. If you have nested filters (device_role__devices) they may not be reported by this check. You should review all of your permission constraints after the upgrade to ensure that they are still valid.

Examples

Primary keys for the migrated Site and Region objects were retained in the Location model, so you do not need to update the primary key value in any Site or Region constraints:

Old Constraint

{
    "site": "4c9f3e5c-2dc6-46f6-95ac-ac778369edfc"
}

New Constraint

{
    "location": "4c9f3e5c-2dc6-46f6-95ac-ac778369edfc"
}

Other models such as the DeviceRole that was migrated to Role did not retain the original primary key. In this case you will need to find the new object's primary key and update the constraint to reference the new model and new primary key value:

Old Constraint

{
    "device_role": "00000000-0000-0000-0000-000000000000"
}

New Constraint

{
    "role": "11111111-1111-1111-1111-111111111111"
}

You may also need to update field names in your permission constraints. For example, if you have a permission constraint that references the slug field on a model that was removed in Nautobot 2.0, you will need to update the constraint to reference a different field instead:

Old Constraint

{
    "slug": "router-01"
}

New Constraint

{
    "id": "5f96ac85-32d4-435d-84e4-66e631ae133f"
}

Some fields were only renamed without making any changes to the data so the constraint update will be a simple matter of updating the field name:

Old Constraint

{
    "circuit__type__name": "metro-ethernet-1000mb"
}

New Constraint

{
    "circuit__circuit_type__name": "metro-ethernet-1000mb"
}

Dependency Changes

• Nautobot no longer uses or supports the use of django-cryptography.
• Nautobot no longer uses or supports the use of django-mptt.
• Nautobot no longer uses or supports the use of django-rq.

App Developer Interface

All imports for app developers should now be sourced from nautobot.apps.* or provided models, as this is the supported public interface. This will help ensure proper SemVer is kept intact and provide a place to add new features without breaking existing integrations.

Database (ORM) Changes

Warning

Changes were made to model and related model fields. In some cases this may invalidate or make subtle changes to existing Permission Constraint filter data. Please review the Permission Constraint Migration section above for more information. These changes might also affect Filter Extensions you have written in your apps.

Database Field Behavior Changes

Most of the database field behavior changes in Nautobot 2.0 fall into the following general categories:

1. The created field on models has changed from a date only ("2023-04-06") to being a date/time ("2023-04-06T19:57:45.320232Z")
2. Various models that had a required site field and an optional location field now have a required location field.

Full table of database field behavior changes

Model	Field	Changes
(all)	created	Changed from DateField to DateTimeField
ConfigContext	name	Now must be globally unique
ConfigContextSchema	name	Now must be globally unique
Device	location	No longer optional/nullable, must now be set
Device	primary_ip4	No longer one-to-one, now one-to-many (ForeignKey)
Device	primary_ip6	No longer one-to-one, now one-to-many (ForeignKey)
IPAddress	role	Changed from CharField to a ForeignKey to the new Role model.
IPAddress	primary_ip4_for	Now a list as the reverse relation for the Device.primary_ip4 foreign key
IPAddress	primary_ip6_for	Now a list as the reverse relation for the Device.primary_ip6 foreign key
JobLogEntry	absolute_url	No longer accepts null values, use "" instead
JobLogEntry	log_object	No longer accepts null values, use "" instead
ObjectPermission	name	Now must be globally unique
PowerPanel	location	No longer optional/nullable, must now be set
Prefix	is_pool	Replaced by new field type, valid choices are "Container", "Network" and "Pool"
Prefix	namespace	New required foreign key to Namespace, defaulting to 'Global'
Prefix	status	"Container" status has been replaced by new field type
Rack	location	No longer optional/nullable, must now be set
RackGroup	location	No longer optional/nullable, must now be set
ScheduledJob	name	Now must be globally unique
ScheduledJob	queue	No longer accepts null values, use "" instead
VirtualChassis	name	Now must be globally unique
VirtualMachine	primary_ip4	No longer one-to-one, now one-to-many (ForeignKey). Remote side is now a list.
VirtualMachine	primary_ip6	No longer one-to-one, now one-to-many (ForeignKey). Remote side is now a list.
VRF	namespace	New required foreign key to Namespace, defaulting to 'Global'
Webhook	ca_file_path	No longer accepts null values, use "" instead

Renamed Database Fields

Most renamed database fields in Nautobot 2.0 fall into the following general categories:

1. Renaming of foreign keys and reverse relations to more consistently and specifically match the related model name or plural name (for example, Circuit.terminations to Circuit.circuit_terminations, Rack.group to Rack.rack_group)
2. Renaming of tree model fields for consistency and due to the change from django-mptt to django-tree-queries (for example, InventoryItem.child_items to InventoryItem.children and InventoryItem.level to InventoryItem.tree_depth)

Full table of renamed database fields

Model	Renamed Field	New Name
CablePath	circuittermination	circuit_terminations
CablePath	consoleport	console_ports
CablePath	consoleserverport	console_server_ports
CablePath	interface	interfaces
CablePath	powerfeed	power_feeds
CablePath	poweroutlet	power_outlets
CablePath	powerport	power_ports
Circuit	termination_a	circuit_termination_a
Circuit	termination_z	circuit_termination_z
Circuit	terminations	circuit_terminations
Circuit	type	circuit_type
Cluster	group	cluster_group
Cluster	type	cluster_type
ComputedField	slug	key
ConfigContext	schema	config_context_schema
ConfigContextSchema	device_set	devices
ConfigContextSchema	virtualmachine_set	virtual_machines
ContentType	computedfield_set	computed_fields
ContentType	configcontext_set	config_contexts
ContentType	configcontextschema_set	config_context_schemas
ContentType	customlink_set	custom_links
ContentType	dcim_device_related	devices
ContentType	dynamicgroup_set	dynamic_groups
ContentType	exporttemplate_set	export_templates
ContentType	imageattachment_set	image_attachments
ContentType	note_set	notes
ContentType	virtualization_virtualmachine_related	virtual_machines
CustomFieldChoice	field	custom_field
CustomField	choices	custom_field_choices
CustomField	slug	key
Device	consoleports	console_ports
Device	consoleserverports	console_server_ports
Device	devicebays	device_bays
Device	device_role	role
Device	frontports	front_ports
Device	inventoryitems	inventory_items
Device	local_context_data	local_config_context_data
Device	local_context_data_owner_content_type	local_config_context_data_owner_content_type
Device	local_context_data_owner_object_id	local_config_context_data_owner_object_id
Device	local_context_schema	local_config_context_schema
Device	poweroutlets	power_outlets
Device	powerports	power_ports
Device	rearports	rear_ports
DeviceRedundancyGroup	members	devices
DeviceType	consoleporttemplates	console_port_templates
DeviceType	consoleserverporttemplates	console_server_port_templates
DeviceType	devicebaytemplates	device_bay_templates
DeviceType	frontporttemplates	front_port_templates
DeviceType	interfacetemplates	interface_templates
DeviceType	instances	devices
DeviceType	poweroutlettemplates	power_outlet_templates
DeviceType	powerporttemplates	power_port_templates
DeviceType	rearporttemplates	rear_port_templates
FrontPortTemplate	rear_port	rear_port_template
InventoryItem	child_items	children
InventoryItem	level	tree_depth
IPAddress	family	ip_version
IPAddress	prefix_length	mask_length
Job	job_hook	job_hooks
Job	result	job_results
JobResult	created	date_created
JobResult	completed	date_done
JobResult	job_kwargs	task_kwargs
JobResult	logs	job_log_entries
JobResult	schedule	scheduled_job
Location	powerpanels	power_panels
PowerOutletTemplate	power_port	power_port_template
PowerPanel	powerfeeds	power_feeds
PowerPort	poweroutlets	power_outlets
PowerPortTemplate	poweroutlet_templates	power_outlet_templates
Prefix	family	ip_version
Rack	group	rack_group
Rack	powerfeed_set	power_feeds
Rack	reservations	rack_reservations
RackGroup	level	tree_depth
RackGroup	powerpanel_set	power_panels
RearPort	frontports	front_ports
RearPortTemplate	frontport_templates	front_port_templates
Relationship	associations	relationship_associations
Relationship	name	label
Relationship	slug	key
RIR	aggregates	prefixes
Secret	groups	secrets_groups
Secret	secretsgroupassociation_set	secrets_group_associations
SecretsGroup	device_set	devices
SecretsGroup	deviceredundancygroup_set	device_redundancy_groups
SecretsGroup	gitrepository_set	git_repositories
SecretsGroup	secretsgroupassociation_set	secrets_group_associations
SecretsGroupAssociation	group	secrets_group
Service	ipaddresses	ip_addresses
Status	circuits_circuit_related	circuits
Status	dcim_cable_related	cables
Status	dcim_device_related	devices
Status	dcim_deviceredundancygroup_related	device_redundancy_groups
Status	dcim_interface_related	interfaces
Status	dcim_location_related	locations
Status	dcim_powerfeed_related	power_feeds
Status	dcim_rack_related	racks
Status	ipam_ipaddress_related	ip_addresses
Status	ipam_prefix_related	prefixes
Status	ipam_vlan_related	vlans
Status	virtualization_virtualmachine_related	virtual_machines
Status	virtualization_vminterface_related	vm_interfaces
Tenant	group	tenant_group
Tenant	rackreservations	rack_reservations
TenantGroup	level	tree_depth
User	changes	object_changes
User	note	notes
User	rackreservation_set	rack_reservations
VirtualMachine	local_context_data	local_config_context_data
VirtualMachine	local_context_data_owner_content_type	local_config_context_data_owner_content_type
VirtualMachine	local_context_data_owner_object_id	local_config_context_data_owner_object_id
VirtualMachine	local_context_schema	local_config_context_schema
VLAN	group	vlan_group

Removed Database Fields

Most removed database fields in Nautobot 2.0 fall into the following general categories:

1. Removal of references to removed models such as Site and Region
2. Removal of slug fields in preference to the use of natural keys.
3. Removal of django-mptt internal fields (lft, rght, tree_id)

Full table of removed database fields

Model	Removed Field	Comments
CircuitTermination	site	Use location instead
CircuitType	slug
Cluster	site	Use location instead
ClusterGroup	slug
ClusterType	slug
ConfigContext	regions	Use locations instead
ConfigContext	sites	Use locations instead
ConfigContextSchema	slug
CustomField	name	Use label or key as appropriate
CustomLink	slug
Device	site	Use location instead
DeviceRedundancyGroup	slug
DeviceType	slug
DynamicGroup	slug
GitRepository	_token	Use Secrets feature instead
GitRepository	username	Use Secrets feature instead
GraphQLQuery	slug
InventoryItem	lft	Made irrelevant by django-tree-queries
InventoryItem	rght	Made irrelevant by django-tree-queries
InventoryItem	tree_id	Made irrelevant by django-tree-queries
IPAddress	assigned_object	Replaced by interfaces and vm_interfaces many-to-many relations
IPAddress	broadcast	Use parent Prefix's broadcast instead
IPAddress	vrf	VRF is now related to the assigned Interface(s), as well as the parent Prefix
Job	git_repository	Can be retrieved from the instance if desired, but is no longer a database field.
Job	slug
Job	source	Now implied by the Job's module_name field.
JobHook	slug
JobResult	job_id
JobResult	obj_type
Location	site
Location	slug
LocationType	slug
Manufacturer	slug
Note	slug
Platform	slug
Provider	slug
ProviderNetwork	slug
PowerFeed	site	Use location instead
PowerPanel	site	Use location instead
Prefix	is_pool	Replaced by new type field
Prefix	site	Use location instead
Prefix	vrf	Replaced by vrf_assignments many-to-many relation
Rack	site	Use location instead
RackGroup	lft	Made irrelevant by django-tree-queries
RackGroup	rght	Made irrelevant by django-tree-queries
RackGroup	site	Use location instead
RackGroup	slug
RackGroup	tree_id	Made irrelevant by django-tree-queries
RIR	slug
RelationshipAssociation	slug
RouteTarget	slug
ScheduledJob	job_class	Use task instead
Secret	slug
SecretsGroup	slug
SecretsGroupAssociation	slug
Status	slug
Tag	slug
Tenant	slug
TenantGroup	lft	Made irrelevant by django-tree-queries
TenantGroup	rght	Made irrelevant by django-tree-queries
TenantGroup	slug
TenantGroup	tree_id	Made irrelevant by django-tree-queries
VLAN	site	Use location instead
VLANGroup	site	Use location instead
VLANGroup	slug
VRF	enforce_unique	Uniqueness of Prefixes and IPAddresses is now enforced by the database
Webhook	slug

Info

For more information on how to update your integrations after the removal of slug fields, see Uniquely Identifying a Nautobot Object.

Replaced Models

Generic Role Model

The ipam.Role, dcim.RackRole, and dcim.DeviceRole models have been removed and replaced by a single extras.Role model. This means that any references to the removed models in the code now use the extras.Role model instead.

Removed Model	Replaced With
dcim.DeviceRole	extras.Role
dcim.RackRole	extras.Role
ipam.Role	extras.Role

Site and Region Models

The dcim.Region and dcim.Site models have been removed and replaced by dcim.Location model. This means that any references to the removed models in the code now use the dcim.Location model instead with LocationType "Site" and "Region".

Important

If you are a Nautobot App developer, or have any Apps installed that include data models that reference Site or Region, please review the Region and Site Related Data Model Migration Guide to learn how to migrate your apps and models from Site and Region to Location.

Removed Model	Replaced With
dcim.Region	dcim.Location
dcim.Site	dcim.Location

Aggregate Migrated to Prefix

The ipam.Aggregate model has been removed and all existing Aggregates will be migrated to ipam.Prefix records with their 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 UTC. Aggregate.tenant, Aggregate.rir and Aggregate.description will be migrated over to the equivalent fields on the new Prefix. ObjectChanges, Tags, Notes, Permissions, Custom Fields, Custom Links, Computed Fields and Relationships will be migrated to relate to the new Prefix as well.

If a Prefix already exists with the same network and prefix length as a previous Aggregate, the rir and date_added fields will be copied to the rir and date_allocated fields on the existing Prefix object. Messages will be output during migration (nautobot-server migrate or nautobot-server post_upgrade) if the tenant, description or type fields need to be manually migrated.

Aggregate	Prefix
broadcast	broadcast
date_added	date_allocated
description	description
network	network
prefix_length	prefix_length
rir	rir
tenant	tenant

Prefix Parenting Concrete Relationship

The ipam.Prefix model has been modified to have a self-referencing foreign key as the parent field. Parenting of prefixes is now automatically managed at the database level to greatly improve performance especially when calculating tree hierarchy and utilization.

As a result of this change, it is no longer necessary nor possible to disable tree hierarchy using settings.DISABLE_PREFIX_LIST_HIERARCHY as this setting has been removed. Additionally it is no longer possible to disable global uniqueness using settings.ENFORCE_GLOBAL_UNIQUE as this setting has been removed.

The following changes have been made to the Prefix model.

Removed	Replaced With
get_child_prefixes()	descendants()

Prefix Parenting Guidance

The following guidance has been added for the Prefix model in order to ensure more accurate network modeling:

• A Prefix of type Container should only have a parent (if any) of type Container
• A Prefix of type Network should only have a parent (if any) of type Container
• A Prefix of type Pool should only have a parent (if any) of type Network
• Any Prefix can be a root prefix (i.e. have no parent)

In Nautobot 2.0, creating or updating prefixes that violate this guidance will result in a warning; in a future Nautobot release this will be changed to an enforced data constraint.

IPAddress Parenting Concrete Relationship

The ipam.IPAddress model has been modified to have a foreign key to ipam.Prefix as the parent field. Parenting of IP addresses is now automatically managed at the database level to greatly improve performance especially when calculating tree hierarchy and utilization.

IPAddress Parenting Guidance

The following guidance has been added to the IPAddress model:

• An IPAddress should have a parent Prefix of type Network
• An IPAddress should not be created if a suitable parent Prefix of type Network does not exist
• An IPAddress can be a member of a Pool but only if the Pool is a child of a Network

As with the Prefix parenting guidance above, violating this guidance in Nautobot 2.0 will result in a warning; in a future Nautobot release this will be changed to an enforced data constraint.

Prefix get_utilization Method

The get_utilization method on the ipam.Prefix model has been updated in 2.0 to account for the Prefix.type field. The behavior is now as follows:

• If the Prefix.type is Container, the utilization is calculated as the sum of the total address space of all child prefixes.
• If the Prefix.type is Pool, the utilization is calculated as the sum of the total number of IP addresses within the pool's range.
• If the Prefix.type is Network:
  • The utilization is calculated as the sum of the total address space of all child Pool prefixes plus the total number of child IP addresses.
  • For IPv4 networks larger than /31, if neither the first or last address is occupied by either a pool or an IP address, they are subtracted from the total size of the prefix.

Example

• 192.168.0.0/16 Container - 1024/65536 utilization
  • 192.168.1.0/24 Network - 1/254 utilization
    • 192.168.1.1 IP Address
  • 192.168.2.0/24 Network - 4/256 utilization
    • 192.168.2.0/30 Pool - 1/4 utilization
      • 192.168.2.1 IP Address
  • 192.168.3.0/24 Network - 5/254 utilization
    • 192.168.3.1 IP Address
    • 192.168.3.64/30 Pool - 0/4 utilization
  • 192.168.4.0/24 Network - 1/256 utilization
    • 192.168.4.255 IP Address

GraphQL and REST API Changes

API Behavior Changes

Most of the API behavior changes in Nautobot 2.0 fall into the following general categories:

1. The created field on most models has changed from a date only ("2023-04-06") to being a date/time ("2023-04-06T19:57:45.320232Z")
2. The status fields on various models has changed from a pseudo-enum value (containing a "value" and a "label") to referencing the related Status object in full, similar to other foreign-key fields.
3. Various models that had a required site field and an optional location field now have a required location field.

Full table of API behavior changes

Model	Field	Changes
(all)	created	Now is a date/time rather than only a date
Cable	status	Now is a foreign-key rather than a pseudo-enum
Circuit	status	Now is a foreign-key rather than a pseudo-enum
Device	config_context	Now is only included when specifically requested with ?include=config_context query parameter
Device	location	Now required, no longer optional
Device	status	Now is a foreign-key rather than a pseudo-enum
DeviceRedundancyGroup	status	Now is a foreign-key rather than a pseudo-enum
Interface	status	Now is a foreign-key rather than a pseudo-enum
IPAddress	namespace	A derived field. Required on creation, if parent isn't provided, to find a correct parent Prefix
IPAddress	parent	A new foreign-key to Prefix. Required on creation, if namespace isn't provided, to find a correct parent Prefix
IPAddress	role	Now is a foreign-key to Role rather than a string
IPAddress	status	Now is a foreign-key rather than a pseudo-enum
JobLogEntry	display	Now contains the message text rather than the message timestamp
Location	status	Now is a foreign-key rather than a pseudo-enum
PowerFeed	status	Now is a foreign-key rather than a pseudo-enum
PowerPanel	location	Now required, no longer optional
Prefix	namespace	New required foreign key to Namespace, defaulting to 'Global'
Prefix	status	Now is a foreign-key rather than a pseudo-enum
Rack	location	Now required, no longer optional
Rack	status	Now is a foreign-key rather than a pseudo-enum
RackGroup	location	Now required, no longer optional
RackGroup	rack_count	Now only counts Racks directly belonging to this RackGroup, not those belonging to its descendants
TenantGroup	tenant_count	Now only counts Tenants directly belonging to this TenantGroup, not those belonging to its descendants
VirtualMachine	status	Now is a foreign-key rather than a pseudo-enum
VLAN	status	Now is a foreign-key rather than a pseudo-enum
VMInterface	status	Now is a foreign-key rather than a pseudo-enum
VRF	namespace	New required foreign key to Namespace, defaulting to 'Global'

Renamed Serializer Fields

Most renamed API fields in Nautobot 2.0 fall into the following general categories:

1. Renaming of foreign keys and reverse relations to more consistently and specifically match the related model name or plural name (for example, Circuit.type to Circuit.circuit_type, Interface.count_ipaddresses to Interface.ip_address_count)
2. Renaming of tree model fields for consistency and due to the change from django-mptt to django-tree-queries (for example, InventoryItem._depth to InventoryItem.tree_depth)

Full table of renamed API fields

Model	Renamed Field	New Name
Circuit	termination_a	circuit_termination_a
Circuit	termination_z	circuit_termination_z
Circuit	type	circuit_type
ConfigContext	schema	config_context_schema
Cluster	group	cluster_group
Cluster	type	cluster_type
ComputedField	slug	key
CustomField	slug	key
CustomFieldChoice	field	custom_field
Device	device_role	role
Device	local_context_data	local_config_context_data
Device	local_context_schema	local_config_context_schema
Device	parent_device	parent_bay
FrontPortTemplate	rear_port	rear_port_template
Interface	count_ipaddresses	ip_address_count
InventoryItem	_depth	tree_depth
IPAddress	family	ip_version
IPAddress	prefix_length	mask_length
JobResult	created	date_created
JobResult	completed	date_done
JobResult	job_kwargs	task_kwargs
JobResult	schedule	scheduled_job
Location	virtualmachine_count	virtual_machine_count
Manufacturer	devicetype_count	device_type_count
Manufacturer	inventoryitem_count	inventory_item_count
Platform	virtualmachine_count	virtual_machine_count
PowerOutletTemplate	power_port	power_port_template
PowerPanel	powerfeed_count	power_feed_count
Prefix	family	ip_version
Rack	group	rack_group
Rack	powerfeed_count	power_feed_count
RackGroup	_depth	tree_depth
Relationship	name	label
Relationship	slug	key
SecretsGroupAssociation	group	secrets_group
Service	ipaddresses	ip_addresses
Tenant	group	tenant_group
TenantGroup	_depth	tree_depth
VirtualMachine	local_context_data	local_config_context_data
VirtualMachine	local_context_schema	local_config_context_schema
VLAN	group	vlan_group

Removed Serializer Fields

Most removed database fields in Nautobot 2.0 fall into the following general categories:

1. Removal of references to removed models such as Site and Region
2. Removal of slug fields in preference to the use of natural keys.

Full table of removed API fields

Model/Endpoint	Removed Field	Comments
/api/plugins/installed-plugins	verison	Use version instead
/api/status/	rq-workers-running	Django-RQ is no longer supported
CircuitTermination	site	Use location instead
CircuitType	slug
Cluster	site	Use location instead
ClusterGroup	slug
ClusterType	slug
ConfigContext	regions	Use locations instead
ConfigContext	sites	Use locations instead
ConfigContextSchema	slug
CustomLink	slug
Device	primary_ip	Use primary_ip4 or primary_ip6instead
Device	site	Use location instead
DeviceRedundancyGroup	slug
DeviceType	slug
DynamicGroup	slug
GitRepository	token	Use Secrets instead
GitRepository	username	Use Secrets instead
GraphQLQuery	slug
IPAddress	assigned_object	Changed to many-to-many field. Use the REST API view for IPAddressToInterface(/api/ipam/ip-address-to-interface/) to create/modify/delete associations or interfaces/vm_interfaces on this model to retrieve a list of associated interfaces.
IPAddress	broadcast	Use parent Prefix's broadcast instead
IPAddress	vrf	VRF is now related to the assigned Interface(s), as well as the parent Prefix
JobHook	slug
JobResult	job_id
JobResult	obj_type
Location	site	Use parent instead
Location	slug
LocationType	slug
Manufacturer	slug
Note	slug
Platform	slug
PowerFeed	site	Use location instead
PowerPanel	site	Use location instead
Prefix	is_pool	Use type instead
Prefix	vrf	Prefixes are now assigned to a VRF in the same Namespace via a many-to-many relationship
Prefix	site	Use location instead
Provider	slug
ProviderNetwork	slug
Rack	site	Use location instead
RackGroup	site	Use location instead
RackGroup	slug
RelationshipAssociation	slug
RIR	slug
Role	slug
RouteTarget	slug
Secret	slug
SecretsGroup	slug
SecretsGroupAssociation	slug
Status	slug
Tag	slug
Tenant	slug
TenantGroup	slug
VirtualMachine	primary_ip	Use primary_ip4 or primary_ip6instead
VLAN	site	Use location instead
VLANGroup	site	Use location instead
VLANGroup	slug
VRF	enforce_unique	Uniqueness of Prefixes and IPAddresses is now enforced at the database level
Webhook	slug

Removed 1.X Version Endpoints and Serializer Representations

Nautobot 2.0 removes support for 1.X versioned REST APIs and their Serializers. Requesting older API versions will result in a 400 Bad Request error.

Please ensure you are using the latest representations of request/response representations as seen in the API docs or Swagger.

Replaced Endpoints

These endpoints /ipam/roles/, /dcim/rack-roles/ and /dcim/device-roles/ are no longer available. Instead, use the /extras/roles/ endpoint to retrieve and manipulate role data.

Removed Endpoints	Replaced With
/dcim/device-roles/	/extras/roles/
/dcim/rack-roles/	/extras/roles/
/ipam/roles/	/extras/roles/

New Interface to IP Address Relationship Endpoint

The through table (ipam.IPAddressToInterface) for the IPAddress to Interface/VMInterface many-to-many relationship has been exposed through the REST API at /api/ipam/ip-address-to-interface/. This endpoint must be used to create, retrieve, update, and delete relationships between IP addresses and interfaces through the REST API. Each ipam.IPAddressToInterface object maps a single ipam.IPAddress object to a single dcim.Interface or virtualization.VMInterface object. When creating relationships through this endpoint, the ip_address field is required and one of interface or vm_interface is required. There are additional boolean fields (is_primary, is_default, etc.) exposed through the REST API that may be used if desired but are not currently implemented in the Nautobot UI.

API Query Parameters Changes

Nautobot 2.0 removes the ?brief query parameter and adds support for the ?depth query parameter. As a result, the ability to specify brief_mode in DynamicModelChoiceField, DynamicModelMultipleChoiceField, and MultiMatchModelMultipleChoiceField has also been removed. For every occurrence of the aforementioned fields where you have brief_mode set to True/False (e.g. brief_mode=True), please remove the statement, leaving other occurrences of the fields where you do not have brief_mode specified as they are. Please see the documentation on the ?depth query parameter for more information.

UI, GraphQL, and REST API Filter Changes

Warning

Sweeping changes were made to model filter fields. In some cases this may invalidate or make subtle changes to existing DynamicGroup, GraphQLQuery or Relationship instances' filter data. Please utilize the nautobot-server audit_dynamic_groups and nautobot-server audit_graphql_queries helper commands when you are cleaning up DynamicGroup and GraphQLQuery filter data. You should run this command after your Nautobot instance is upgraded to v2.x successfully. The helper commands will not catch all possible issues, but they will catch some common ones. You should review all of your DynamicGroup filter data and GraphQLQuery query data after the upgrade to ensure that they are still valid. At the time of this writing, an audit helper command for Relationship filter data is not yet available.

Removed Changelog URL from View Context

changelog_url is no longer provided in the ObjectView context. To get a model instance's changelog URL, you can retrieve it from the instance itself if it supports it: model_instance.get_changelog_url().

Renamed Filter Fields

Most renamed filter fields in Nautobot 2.0 fall into the following general categories:

1. The tag filter is renamed to tags on all models supporting Tags.
2. Renames to match renamed model/serializer fields as described earlier in this document.
3. Related membership filters are renamed to has_<related> throughout, for example ConsolePort.cabled is renamed to ConsolePort.has_cable.
4. Most <related>_id filters have been merged into the corresponding <related> filter (see "Enhanced Filter Fields" below).

Full table of renamed filter fields

Model	Renamed Filter	New Name
Cable	tag	tags
Circuit	tag	tags
Circuit	type	circuit_type
Cluster	tag	tags
ComputedField	slug	key
ConsolePort	cabled	has_cable
ConsoleServerPort	cabled	has_cable
CustomFieldChoice	field	custom_field
Device	cluster_id	cluster
Device	device_type_id	device_type
Device	local_context_data	local_config_context_data
Device	local_context_schema_id	local_config_context_schema_id
Device	local_context_schema	local_config_context_schema
Device	rack_group_id	rack_group
Device	rack_id	rack
Device	tag	tags
Device	virtual_chassis_id	virtual_chassis
DeviceBay	tag	tags
DeviceRedundancyGroup	tag	tags
DeviceType	has_instances	has_devices
DeviceType	instances	devices
DeviceType	tag	tags
FrontPort	cabled	has_cable
FrontPort	tag	tags
GitRepository	tag	tags
Interface	cabled	has_cable
Interface	tag	tags
InventoryItem	child_items	children
InventoryItem	has_child_items	has_children
InventoryItem	tag	tags
IPAddress	assigned_to_interface	has_interface_assignments
IPAddress	family	ip_version
IPAddress	parent	prefix
IPAddress	tag	tags
IPAddress	vrf	vrfs
Job	tag	tags
Location	tag	tags
ObjectPermission	group	groups
ObjectPermission	group_id	groups_id
ObjectPermission	user	users
PowerFeed	cabled	has_cable
PowerFeed	tag	tags
PowerOutlet	cabled	has_cable
PowerPanel	tag	tags
PowerPort	cabled	has_cable
Prefix	family	ip_version
Prefix	is_pool	type
Prefix	mask_length	prefix_length
Prefix	tag	tags
Prefix	vrf	vrfs
Provider	tag	tags
ProviderNetwork	tag	tags
Rack	group	rack_group
Rack	has_reservations	has_rack_reservations
Rack	reservations	rack_reservations
Rack	tag	tags
RackReservation	group	rack_group
RackReservation	tag	tags
RearPort	cabled	has_cable
RearPort	tag	tags
Relationship	name	label
Relationship	slug	key
RouteTarget	exporting_vrf	exporting_vrfs
RouteTarget	importing_vrf	importing_vrfs
RouteTarget	tag	tags
SecretsGroupAssociation	group	secrets_group
Service	port	ports
Service	tag	tags
Tenant	group	tenant_group
Tenant	tag	tags
User	changes	object_changes
User	has_changes	has_object_changes
User	group	groups
User	group_id	groups_id
VirtualMachine	local_context_data	local_config_context_data
VirtualMachine	local_context_schema_id	local_config_context_schema_id
VirtualMachine	local_context_schema	local_config_context_schema
VirtualMachine	tag	tags
VLAN	group	vlan_group
VLAN	tag	tags
VMInterface	tag	tags
VRF	export_target	export_targets
VRF	import_target	import_targets
VRF	tag	tags

Enhanced Filter Fields

Below is a table documenting enhanced filter field changes in Nautobot 2.0. These enhancements mostly fall into the following general categories:

1. Many filters are enhanced to permit filtering by UUID or by name.
2. Filters that previously only supported a single filter value can now filter on multiple values.

Full table of enhanced filter fields

Model	Filter	Enhancements
(all)	created[__(gte/lte)]	Filtering on multiple values, supports date-times
Cable	tenant	Filter by UUID or by name
Circuit	circuit_type	Filter by UUID or by name
Circuit	provider	Filter by UUID or by name
Circuit	tenant	Filter by UUID or by name
Circuit	tenant_group	Filter by UUID or by name
Cluster	cluster_group	Filter by UUID or by name
Cluster	cluster_type	Filter by UUID or by name
Cluster	tenant	Filter by UUID or by name
Cluster	tenant_group	Filter by UUID or by name
ConfigContext	cluster_group	Filter by UUID or by name
ConfigContext	device_redundancy_group	Filter by UUID or by name
ConfigContext	dynamic_groups	Filter by UUID or by name
ConfigContext	platform	Filter by UUID or by name
ConfigContext	tenant	Filter by UUID or by name
ConfigContext	tenant_group	Filter by UUID or by name
ConsolePort	device	Filter by UUID or by name
ConsoleServerPort	device	Filter by UUID or by name
Device	cluster (formerly cluster_id)	Filter by UUID or by name
Device	device_redundancy_group	Filter by UUID or by name
Device	device_type (formerly device_type_id)	Filter by UUID or by model
Device	manufacturer	Filter by UUID or by name
Device	platform	Filter by UUID or by name
Device	role	Filter by UUID or by name
Device	rack	Filter by UUID or by name
Device	rack_group	Filter by UUID or by name
Device	serial	Filtering on multiple values
Device	secrets_group	Filter by UUID or by name
Device	virtual_chassis	Filter by UUID or by name
DeviceBay	device	Filter by UUID or by name
DeviceType	manufacturer	Filter by UUID or by name
DeviceRedundancyGroup	secrets_group	Filter by UUID or by name
DynamicGroupMembership	group	Filter by UUID or by name
DynamicGroupMembership	parent_group	Filter by UUID or by name
FrontPort	device	Filter by UUID or by name
GitRepository	secrets_group	Filter by UUID or by name
Interface	device	Filter by UUID or by name
InventoryItem	device	Filter by UUID or by name
InventoryItem	manufacturer	Filter by UUID or by name
InventoryItem	serial	Filtering on multiple values
IPAddress	mask_length	Filtering on multiple integer values
IPAddress	rir	Filter by UUID or by name
IPAddress	tenant	Filter by UUID or by name
IPAddress	tenant_group	Filter by UUID or by name
Manufacturer	platforms	Filter by UUID or by name
Platform	manufacturer	Filter by UUID or by name
PowerOutlet	device	Filter by UUID or by name
PowerPort	device	Filter by UUID or by name
Prefix	rir	Filter by UUID or by name
Prefix	tenant	Filter by UUID or by name
Prefix	tenant_group	Filter by UUID or by name
Prefix	vlan_vid	Filtering on multiple values
ProviderNetwork	provider	Filter by UUID or by name
Rack	role	Filter by UUID or by name
Rack	serial	Filtering on multiple values
RackGroup	parent	Filter by UUID or by name
RackReservation	tenant	Filter by UUID or by name
RackReservation	tenant_group	Filter by UUID or by name
RackReservation	user	Filter by UUID or by username
RearPort	device	Filter by UUID or by name
RouteTarget	tenant	Filter by UUID or by name
RouteTarget	tenant_group	Filter by UUID or by name
SecretsGroupAssociation	secret	Filter by UUID or by name
SecretsGroupAssociation	secrets_group	Filter by UUID or by name
Tenant	tenant_group	Filter by UUID or by name
TenantGroup	parent	Filter by UUID or by name
TenantGroup	children	Filter by UUID or by name
TenantGroup	tenants	Filter by UUID or by name
VirtualChassis	master	Filter by UUID or by name
VirtualChassis	tenant	Filter by UUID or by name
VirtualMachine	cluster_group	Filter by UUID or by name
VirtualMachine	cluster_type	Filter by UUID or by name
VirtualMachine	platform	Filter by UUID or by name
VirtualMachine	tenant	Filter by UUID or by name
VirtualMachine	tenant_group	Filter by UUID or by name
VLAN	available_on_device	Filtering on multiple values
VLAN	tenant	Filter by UUID or by name
VLAN	tenant_group	Filter by UUID or by name
VLAN	vlan_group	Filter by UUID or by name
VRF	tenant	Filter by UUID or by name
VRF	tenant_group	Filter by UUID or by name

Corrected Filter Fields

Below is a table documenting corrected filter field changes in Nautobot 2.0. These corrections mostly involve filters that previously permitted filtering on related membership only (/api/dcim/devices/?console_ports=True) and have now been corrected into filters for related membership (/api/dcim/devices/?has_console_ports=True) as well as by actual related objects (/api/dcim/devices/?console_ports=<UUID>).

Full table of corrected filter fields

Model	Filter	Correction
CustomFieldChoice	custom_field	Filter by UUID or key
Device	console_ports	Split into has_console_ports and console_ports filters
Device	console_server_ports	Split into has_console_server_ports and console_server_ports filters
Device	device_bays	Split into has_device_bays and device_bays filters
Device	front_ports	Split into has_front_ports and front_ports filters
Device	interfaces	Split into has_interfaces and interfaces filters
Device	power_outlets	Split into has_power_outlets and power_outlets filters
Device	power_ports	Split into has_power_ports and power_ports filters
Device	rear_ports	Split into has_rear_ports and rear_ports filters
IPAddress	parent	The parent filter now checks for an exact match of the parent Prefix; for legacy net_host_contained behavior now use the new prefix filter instead

Removed Filter Fields

Below is a table documenting removed filter field changes in v2.x. Most removed database fields in Nautobot 2.0 fall into the following general categories:

1. Removal of *_id=<uuid> filters as they have have been merged into filters that support both uuid and name/slug (for example, instead of /api/circuits/circuits/?provider_id=<UUID>, use /api/circuits/circuits/?provider=<uuid>).
2. Removal of filtering on removed models such as Region and Site. (Use location filters instead.)
3. Removal of slug filters from models that no longer have a slug field.

Full table of removed filter fields

Model	Removed Filter	Comments
Circuit	provider_id
Circuit	provider_network_id
Circuit	region
Circuit	region_id
Circuit	site
Circuit	site_id
Circuit	tenant_group_id
Circuit	type_id
CircuitTermination	circuit_id
CircuitTermination	provider_network_id
CircuitTermination	region_id
CircuitTermination	region
CircuitTermination	site_id
CircuitTermination	site
CircuitType	slug
Cluster	region
Cluster	region_id
Cluster	site
Cluster	site_id
Cluster	tenant_group_id
ClusterGroup	slug
ClusterType	slug
ConfigContext	region
ConfigContext	region_id
ConfigContext	role_id
ConfigContext	site
ConfigContext	site_id
ConsolePort	device_id
ConsolePort	region
ConsolePort	region_id
ConsolePort	site
ConsolePort	site_id
ConsoleServerPort	device_id
ConsoleServerPort	region
ConsoleServerPort	region_id
ConsoleServerPort	site
ConsoleServerPort	site_id
CustomFieldChoice	field_id	Use custom_field filter
CustomLink	slug
Device	manufacturer_id
Device	model	Use device_type filter
Device	pass_through_ports	Use has_front_ports or has_rear_ports filters
Device	platform_id
Device	region
Device	region_id
Device	role_id
Device	secrets_group_id
Device	site
Device	site_id
Device	tenant_group_id
DeviceBay	device_id
DeviceBay	region
DeviceBay	region_id
DeviceBay	site
DeviceBay	site_id
DeviceRedundancyGroup	slug
DeviceType	manufacturer_id
DeviceType	slug
DynamicGroup	slug
FrontPort	device_id
FrontPort	region
FrontPort	region_id
FrontPort	site
FrontPort	site_id
GraphQLQuery	slug
Interface	bridge_id
Interface	device_id
Interface	lag_id
Interface	parent_interface_id
Interface	region
Interface	region_id
Interface	site
Interface	site_id
InventoryItem	device_id
InventoryItem	manufacturer_id
InventoryItem	parent_id
InventoryItem	region
InventoryItem	region_id
InventoryItem	site
InventoryItem	site_id
IPAddress	tenant_group_id
Job	slug
Job	source
JobHook	slug
Location	region
Location	region_id
Location	site
Location	site_id
Location	slug
Location	tenant_group_id
LocationType	slug
Manufacturer	slug
ObjectPermission	user_id	Use users filter
Platform	manufacturer_id
Platform	slug
PowerFeed	power_panel_id
PowerFeed	rack_id
PowerFeed	region
PowerFeed	region_id
PowerFeed	site
PowerFeed	site_id
PowerOutlet	device_id
PowerOutlet	region
PowerOutlet	region_id
PowerOutlet	site
PowerOutlet	site_id
PowerPanel	rack_group_id
PowerPanel	region
PowerPanel	region_id
PowerPanel	site
PowerPanel	site_id
PowerPort	device_id
PowerPort	region
PowerPort	region_id
PowerPort	site
PowerPort	site_id
Prefix	region
Prefix	region_id
Prefix	site
Prefix	site_id
Prefix	vrf_id	Use vrf filter instead
Provider	region
Provider	region_id
Provider	site
Provider	site_id
Provider	slug
ProviderNetwork	provider_id
ProviderNetwork	slug
Rack	group_id	Use rack_group filter
Rack	region
Rack	region_id
Rack	role_id
Rack	site
Rack	site_id
Rack	tenant_group_id
RackGroup	parent_id
RackGroup	region
RackGroup	region_id
RackGroup	site
RackGroup	site_id
RackGroup	slug
RackReservation	group_id	Use rack_group filter
RackReservation	rack_id
RackReservation	site
RackReservation	site_id
RackReservation	tenant_group_id
RackReservation	user_id
RearPort	device_id
RearPort	region
RearPort	region_id
RearPort	site
RearPort	site_id
RelationshipAssociation	slug
RIR	slug
RouteTarget	exporting_vrf_id	Use exporting_vrfs filter
RouteTarget	importing_vrf_id	Use importing_vrfs filter
RouteTarget	slug
RouteTarget	tenant_group_id
Secret	slug
SecretsGroup	slug
SecretsGroupAssociation	group_id	Use secrets_group filter
SecretsGroupAssociation	slug
Service	device_id
Service	virtual_machine_id
Status	slug
Tag	slug
Tenant	aggregates	Use prefixes filter
Tenant	group_id	Use tenant_group filter
Tenant	has_aggregates	Use has_prefixes filter
Tenant	has_sites
Tenant	sites
Tenant	slug
TenantGroup	parent_id
TenantGroup	slug
VirtualChassis	master_id
VirtualChassis	region
VirtualChassis	region_id
VirtualChassis	site
VirtualChassis	site_id
VirtualChassis	tenant_id
VirtualMachine	tenant_group_id
VLAN	group_id	Use vlan_group filter
VLAN	region
VLAN	region_id
VLAN	site
VLAN	site_id
VLAN	tenant_group_id
VLANGroup	region
VLANGroup	region_id
VLANGroup	site
VLANGroup	site_id
VLANGroup	slug
VMInterface	bridge_id
VMInterface	parent_interface_id
VRF	tenant_group_id
VRF	export_target_id	Use export_targets filter
VRF	import_target_id	Use import_targets filter
Webhook	slug

Python Code Location Changes

The below is mostly relevant only to authors of Jobs and Nautobot Apps. End users should not be impacted by the changes in this section. Most changes in code location arise from the merging of the nautobot.utilities module into the nautobot.core module.

Full table of code location changes

Old Module	Class/Function(s)	New Module
nautobot.core.api.utils	TreeModelSerializerMixin	nautobot.core.api.serializers
nautobot.core.fields	(all)	nautobot.core.models.fields
nautobot.core.forms	SearchForm	nautobot.core.forms.search
nautobot.core.utilities	(all)	nautobot.core.views.utils
nautobot.dcim.fields	MACAddressCharField	nautobot.core.models.fields
nautobot.dcim.forms	MACAddressField	nautobot.core.forms
nautobot.extras.api.customfields	CustomFieldModelSerializerMixin	nautobot.core.api.serializers
nautobot.extras.api.relationships	RelationshipModelSerializerMixin	nautobot.core.api.serializers
nautobot.extras.api.serializers	NautobotModelSerializer	nautobot.core.api.serializers
nautobot.extras.api.serializers	NotesSerializerMixin	nautobot.core.api.serializers
nautobot.extras.api.serializers	TaggedModelSerializerMixin	nautobot.extras.api.mixins
nautobot.extras.utils	is_taggable	nautobot.core.models.utils
nautobot.utilities.api	(all)	nautobot.core.api.utils
nautobot.utilities.apps	(all)	nautobot.core.apps
nautobot.utilities.checks	(all)	nautobot.core.checks
nautobot.utilities.choices	(all)	nautobot.core.choices
nautobot.utilities.config	(all)	nautobot.core.utils.config
nautobot.utilities.constants	(all)	nautobot.core.constants
nautobot.utilities.deprecation	(all)	nautobot.core.utils.deprecation
nautobot.utilities.error_handlers	(all)	nautobot.core.views.utils
nautobot.utilities.exceptions	(all)	nautobot.core.exceptions
nautobot.utilities.factory	(all)	nautobot.core.factory
nautobot.utilities.fields	(all)	nautobot.core.models.fields
nautobot.utilities.filters	(all)	nautobot.core.filters
nautobot.utilities.forms	(all)	nautobot.core.forms
nautobot.utilities.git	(all)	nautobot.core.utils.git
nautobot.utilities.logging	(all)	nautobot.core.utils.logging
nautobot.utilities.management	(all)	nautobot.core.management
nautobot.utilities.ordering	(all)	nautobot.core.utils.ordering
nautobot.utilities.paginator	(all)	nautobot.core.views.paginator
nautobot.utilities.permissions	(all)	nautobot.core.utils.permissions
nautobot.utilities.query_functions	(all)	nautobot.core.models.query_functions
nautobot.utilities.querysets	(all)	nautobot.core.models.querysets
nautobot.utilities.tables	(all)	nautobot.core.tables
nautobot.utilities.tasks	(all)	nautobot.core.tasks
nautobot.utilities.templatetags	(all)	nautobot.core.templatetags
nautobot.utilities.testing	(all)	nautobot.core.testing
nautobot.utilities.tree_queries	(all)	nautobot.core.models.tree_queries
nautobot.utilities.utils	array_to_string	nautobot.core.models.utils
nautobot.utilities.utils	convert_querydict_to_factory_formset_acceptable_querydict	nautobot.core.utils.requests
nautobot.utilities.utils	count_related	nautobot.core.models.querysets
nautobot.utilities.utils	csv_format	nautobot.core.views.utils
nautobot.utilities.utils	deepmerge	nautobot.core.utils.data
nautobot.utilities.utils	dict_to_filter_params	nautobot.core.api.utils
nautobot.utilities.utils	dynamic_import	nautobot.core.api.utils
nautobot.utilities.utils	ensure_content_type_and_field_name_inquery_params	nautobot.core.utils.requests
nautobot.utilities.utils	flatten_dict	nautobot.core.utils.data
nautobot.utilities.utils	flatten_iterable	nautobot.core.utils.data
nautobot.utilities.utils	foreground_color	nautobot.core.utils.color
nautobot.utilities.utils	get_all_lookup_expr_for_field	nautobot.core.utils.filtering
nautobot.utilities.utils	get_api_version_serializer	nautobot.core.api.utils
nautobot.utilities.utils	get_changes_for_model	nautobot.core.utils.lookup
nautobot.utilities.utils	get_filterset_field	nautobot.core.utils.filtering
nautobot.utilities.utils	get_filterset_for_model	nautobot.core.utils.lookup
nautobot.utilities.utils	get_filterable_params_from_filter_params	nautobot.core.utils.requests
nautobot.utilities.utils	get_form_for_model	nautobot.core.utils.lookup
nautobot.utilities.utils	get_model_from_name	nautobot.core.utils.lookup
nautobot.utilities.utils	get_related_class_for_model	nautobot.core.utils.lookup
nautobot.utilities.utils	get_route_for_model	nautobot.core.utils.lookup
nautobot.utilities.utils	get_table_for_model	nautobot.core.utils.lookup
nautobot.utilities.utils	hex_to_rgb	nautobot.core.utils.color
nautobot.utilities.utils	is_taggable	nautobot.core.models.utils
nautobot.utilities.utils	is_uuid	nautobot.core.utils.data
nautobot.utilities.utils	lighten_color	nautobot.core.utils.color
nautobot.utilities.utils	normalize_querydict	nautobot.core.utils.requests
nautobot.utilities.utils	prepare_cloned_fields	nautobot.core.views.utils
nautobot.utilities.utils	pretty_print_query	nautobot.core.models.utils
nautobot.utilities.utils	render_jinja2	nautobot.core.utils.data
nautobot.utilities.utils	rgb_to_hex	nautobot.core.utils.color
nautobot.utilities.utils	SerializerForAPIVersions	nautobot.core.api.utils
nautobot.utilities.utils	serialize_object	nautobot.core.models.utils
nautobot.utilities.utils	serialize_object_v2	nautobot.core.models.utils
nautobot.utilities.utils	shallow_compare_dict	nautobot.core.utils.data
nautobot.utilities.utils	slugify_dots_to_dashes	nautobot.core.models.fields
nautobot.utilities.utils	slugify_dashes_to_underscores	nautobot.core.models.fields
nautobot.utilities.utils	to_meters	nautobot.core.utils.data
nautobot.utilities.utils	UtilizationData	nautobot.core.utils.data
nautobot.utilities.utils	versioned_serializer_selector	nautobot.core.api.utils
nautobot.utilities.validators	(all)	nautobot.core.models.validators
nautobot.utilities.views	(all)	nautobot.core.views.mixins

Removed Python Code

• Because of the replacement of the ?brief REST API query parameter with ?depth and the removal of all Nested*Serializers, some of the classes and mixins are removed because they are no longer needed.
• With the reimplementation of CSV import and export, CSVForm classes are generally no longer needed, and so a number of related mixin classes have been removed.

Full table of code removals

Module	Class/Function(s)
nautobot.apps.forms	StatusModelCSVFormMixin
nautobot.core.filters	NameSlugSearchFilterSet
nautobot.core.forms.utils	parse_csv
nautobot.core.forms.utils	validate_csv
nautobot.circuits.api.nested_serializers	(all)
nautobot.dcim.api.nested_serializers	(all)
nautobot.dcim.form_mixins	LocatableModelCSVFormMixin
nautobot.extras.api.customfields	CustomFieldModelSerializer
nautobot.extras.api.fields	RoleSerializerField
nautobot.extras.api.fields	StatusSerializerField
nautobot.extras.api.nested_serializers	(all)
nautobot.extras.api.serializers	RoleModelSerializerMixin
nautobot.extras.api.serializers	RoleRequiredRoleModelSerializerMixin
nautobot.extras.api.serializers	StatusModelSerializerMixin
nautobot.extras.api.serializers	TagSerializerField
nautobot.extras.api.serializers	TaggedObjectSerializer
nautobot.extras.constants	JOB_MAX_SOURCE_LENGTH
nautobot.extras.forms.mixins	RoleModelCSVFormMixin
nautobot.extras.forms.mixins	RoleRequiredRoleModelCSVFormMixin
nautobot.extras.forms.mixins	StatusModelCSVFormMixin
nautobot.extras.jobs	get_jobs
nautobot.extras.jobs	get_job_classpaths
nautobot.extras.plugins	PluginMenuButton
nautobot.extras.plugins	PluginMenuItem
nautobot.ipam.api.nested_serializers	(all)
nautobot.tenancy.api.nested_serializers	(all)
nautobot.users.api.nested_serializers	(all)
nautobot.virtualization.api.nested_serializers	(all)

Renamed Python Code

The below is mostly relevant only to authors of Jobs and Nautobot Apps. End users should not be impacted by the changes in this section. Most of the code renames are only relevant to Job related classes.

Full table of code renames

Old Name	New Name
nautobot.extras.views.JobDetailView	nautobot.extras.views.JobView
nautobot.extras.views.JobView	nautobot.extras.views.JobRunView

Git Data Source Changes

The Configuration Contexts Metadata key schema has been replaced with config_context_schema. This means that any schema references in your git repository's data must be updated to reflect this change.

GitRepository sync operations are now Jobs. As a result, when creating a new GitRepository it is not automatically synchronized. A GitRepository.sync() method has been implemented that will execute the sync job on a worker and return the JobResult for the operation. This method takes dry_run and user arguments. The dry_run argument defaults to False; if set to True will cause the sync to dry-run. The user argument is required if a sync is performed.

Additionally, the GitRepository.save() method no longer takes a trigger_resync=<True|False> argument as it is no longer required. The act of creating a new GitRepository no longer has side effects.

Below is a table documenting changes in names for Git-related Jobs. There should NOT be a need to ever manually execute the jobs due to the addition of GitRepository.sync(), but this is being provided for clarity.

Old Job Location	New Job Location
nautobot.extras.datasources.git.pull_git_repository_and_refresh_data	nautobot.core.jobs.GitRepositorySync
nautobot.extras.datasources.git.git_repository_diff_origin_and_local	nautobot.core.jobs.GitRepositoryDryRun

Logging Changes

Where applicable, logging.getLogger("some_arbitrary_name") is replaced with logging.getLogger(__name__) or logging.getLogger(__name__ + ".SpecificFeature").

Below is a table documenting changes in logger names that could potentially affect existing deployments with expectations around specific logger names used for specific purposes.

Full table of logger name changes

Old Name	New Name
nautobot.authentication	nautobot.core.authentication
nautobot.datasources.git	nautobot.extras.datasources.git
nautobot.datasources.utils	nautobot.extras.datasources.utils
nautobot.dcim.cable	nautobot.dcim.signals.cable
nautobot.graphql.generators	nautobot.core.graphql.generators
nautobot.graphql.schema	nautobot.core.graphql.schema
nautobot.jobs	nautobot.extras.jobs
nautobot.jobs.*	nautobot.extras.jobs.*
nautobot.releases	nautobot.core.releases, nautobot.utilities.tasks
nautobot.plugins	nautobot.extras.templatetags.plugins, nautobot.extras.plugins.utils
nautobot.views.*	nautobot.core.views.generic.*

Job Database Model Changes

The Job name field has been changed to a unique field and the name + grouping uniqueness constraint has been removed. The processes that refresh jobs (nautobot-server post_upgrade and nautobot-server migrate) have been updated to gracefully handle duplicate job names.

Example

class NautobotJob1(Job):
    class Meta:
        name = "Sample job"

class NautobotJob2(Job):
    class Meta:
        name = "Sample job"

These jobs would be named Sample job and Sample job (2)

The Job slug, source and git_repository fields have been removed. The Job module_name field will automatically be updated, for Jobs derived from a Git repository, from <submodule_name> to <git_repository_slug>.jobs.<submodule_name>. This also changes the secondary uniqueness constraint for Jobs to simply [module_name, job_class_name].

The Job class_path attribute has been simplified correspondingly, to simply <module>.<ClassName> instead of the former <source>/<module>/<ClassName>. For example, the Nautobot Golden Config backup job's class_path will change from plugins/nautobot_golden_config.jobs/BackupJob to nautobot_golden_config.jobs.BackupJob.

The Job commit_default field has been renamed to dryrun_default and the default value has been changed from True to False. This change is a result of the fundamental job changes mentioned in the Job Changes section below.

JobResult Database Model Changes

The JobResult objects for which results from Job executions are stored are now automatically managed. Therefore job authors must never manipulate or save() these objects as they are now used internally for all state transitions and saving the objects yourself could interfere with and cause Job execution to fail or cause data loss.

Therefore all code that is calling JobResult.set_status() (which has been removed) or JobResult.save() must be removed.

Job Changes

Migrating Jobs From v1 to v2

Changed in version 2.0.0

See Migrating Jobs From Nautobot v1 for more information on how to migrate your existing jobs to Nautobot v2.

Fundamental Changes

Changed in version 2.2.3

In Nautobot 2.0.0 through 2.2.2, Nautobot's BaseJob class was made to be a subclass of Celery's Task class. The implications of this change are outside the scope of this document, but this change has been reverted in Nautobot 2.2.3 and later.

• The test_* and post_run methods for backwards compatibility to NetBox scripts and reports were removed. In their place, Nautobot Jobs now have before_start, on_success, on_failure, and after_return methods that can be used by job authors to perform similar functions.

Important

Be sure to call the super() method when overloading any of the job's before_start, on_success, on_retry, on_failure, or after_return methods

• The run method signature now includes each of the input variables defined on the Job. This means that the data and commit arguments are no longer passed to the job by default and the job's run method signature should match the the job's input variables.

Example

class ExampleJob(Job):
    var1 = StringVar()
    var2 = IntegerVar(required=True)
    var3 = BooleanVar()
    var4 = ObjectVar(model=Role)

    def run(self, *, var1, var2, var3, var4):
        ...

Database Transactions

Nautobot no longer wraps the job run method in an atomic database transaction. As a result, jobs that need to roll back database changes will have to decorate the run method with @transaction.atomic or use the with transaction.atomic() context manager in the job code.

With the removal of the atomic transaction, the commit flag has been removed. The ability to bypass job approval on dryrun can be achieved by using an optional dryrun argument. Job authors who wish to allow users to bypass approval when the dryrun flag is set should set a dryrun attribute with a value of DryRunVar() on their job class. DryRunVar can be imported from nautobot.extras.jobs.

Example

from nautobot.extras.jobs import DryRunVar, Job

class ExampleJob(Job):
    dryrun = DryRunVar()

    def run(self, dryrun):
        ...

A new supports_dryrun field has been added to the Job model and Job class that returns true if the Job class implements the dryrun = DryRunVar() attribute. This is used to determine if jobs that require approval can be dry run without prior approval.

The commit_default job field has been renamed to dryrun_default and the default value has been changed from True to False.

Important

The read_only job field no longer changes the behavior of Nautobot core and is left to the job author to decide whether their job is read only.

Important

Nautobot no longer enforces any job behavior when dryrun is set. It is now the job author's responsibility to define and enforce the execution of a "dry run".

Request Property

The request property has been changed to a Celery request instead of a Django web request and no longer includes the information from the web request that initiated the Job. The user object is now available as self.user instead of self.request.user.

URL Changes

The Job URL path jobs/results/<uuid:pk>/ and URL pattern name job_jobresult are removed. Use URL path job-results/<uuid:pk>/ and URL pattern name jobresult instead. Any extras:job_jobresult references should be removed and be replaced by extras:jobresult.

The Job URL path /extras/jobs/<str:class_path>/ and associated URL pattern name extras:job are changed to URL path /extras/jobs/<str:class_path>/run/ and the URL pattern is renamed to extras:job_run_by_class_path. Conversely, the Job detail view URL pattern name extras:job_detail has been renamed to extras:job for consistency with other object detail view URL patterns.

Function Changes

Changed as_form_class, as_form and validate_data functions on BaseJob Model to classmethods so that they can be called directly from the class without needing to instantiate the Job in order to access them.

Function Renames

JobDetailView is renamed to JobView.

JobView is renamed to JobRunView.

Settings Changes

Added Settings

These settings are new in Nautobot 2.0 and can be changed in your nautobot_config.py file or via environment variables if desired:

• CELERY_WORKER_REDIRECT_STDOUTS (env: NAUTOBOT_CELERY_WORKER_REDIRECT_STDOUTS)
• CELERY_WORKER_REDIRECT_STDOUTS_LEVEL (env: NAUTOBOT_CELERY_WORKER_REDIRECT_STDOUTS_LEVEL)

Removed Settings

These settings are no longer in use and should be removed from your nautobot_config.py file and environment variables if present:

• CACHEOPS_DEFAULTS (env: NAUTOBOT_CACHEOPS_TIMEOUT)
• CACHEOPS_ENABLED (env: NAUTOBOT_CACHEOPS_ENABLED)
• CACHEOPS_HEALTH_CHECK_ENABLED
• CACHEOPS_REDIS (env: NAUTOBOT_CACHEOPS_REDIS)
• CACHEOPS_SENTINEL
• DISABLE_PREFIX_LIST_HIERARCHY
• ENFORCE_GLOBAL_UNIQUE (env: NAUTOBOT_ENFORCE_GLOBAL_UNIQUE)
• RQ_QUEUES

Changed Settings

These settings are no longer user servicable and should be removed from your nautobot_config.py file and environment variables if present:

• CELERY_RESULT_BACKEND (env: NAUTOBOT_CELERY_RESULT_BACKEND)
• CELERY_RESULT_BACKEND_TRANSPORT_OPTIONS