Provide documentation explaining what fields should be used for (their purpose) #8911

New Issue

adam · 2025-12-29T20:42:46+01:00

adam commented

2025-12-29 20:42:46 +01:00

Originally created by @jwbensley on GitHub (Dec 4, 2023).

Change Type

Addition

Area

Getting started

Proposed Changes

My previous issue was closed without allowing me to respond?
This is not some sort of troll, this is a genuine request.

@chiniquy made a comment about tenants: https://github.com/netbox-community/netbox/issues/14417#issuecomment-1838443831. I had not mentioned tenants, nor any of the issues I was referring too, so, not sure what that was about?

@jeremystretch closed the ticket without allow me to respond so now I'm trying again.

Take VLAN for example, there is nothing which explains that VLAN names are limited to 64 characters or the logic of this 64 character discussion, in the existing documentation: https://docs.netbox.dev/en/stable/models/ipam/vlan/. The reason Jeremy gave in previous tickets is that it relates to the max VLAN length he has seen on some device: https://github.com/netbox-community/netbox/issues/6349. That does make sense if the job of NetBox is to store device configuration... Clarifying this, is the purpose of this issue / it's previous incarnation (https://github.com/netbox-community/netbox/issues/14417).

I thought the purpose of NetBox is, as per the documentation:

NetBox is the leading solution for modeling and documenting modern networks. By combining the traditional disciplines of IP address management (IPAM) and datacenter infrastructure management (DCIM) with powerful APIs and extensions, NetBox provides the ideal "source of truth" to power network automation.

Storing the actual configuration which is pushed to devices, is not the same as storing the the information required to generate the configuration (modeling and documenting). Having low max character limits on various field types makes sense if the job of NetBox is to store the data exactly as it is configured on the network. Low max character limits do not make sense if the job of NetBox is to store the data required to generate the config for the network. In the former case, one would be pushing the data verbatim to network devices. In the later case, one would be using an abstraction method to take data from NetBox, and convert the data into a form which is suitable for the network, and pushing the output of that process to the network.

This is a really important distinction because there are loads of vendors out there, with all kinds of crazy limitations, it would be madness for NetBox to try and cater to all the limitations of all the different vendors. Therefore, if the purpose of NetBox is to store network configuration as it should be on the devices, the former case given above, that should be documented in the public facing documentation. If the purpose of NetBox is to fulfil the later case, that should also be documented (it seems to be what is documented, modeling and documenting), and in this case, these low character limits do not make sense.

Hopefully you see the confusion I am facing now. I am opening issues, I am given a reason for them being closed, but it does not align to the documentation because, the documentation suggests the purpose of NetBox is to fulfil for the later case (store data required to create network configuration, not the actual network configuration).

Originally created by @jwbensley on GitHub (Dec 4, 2023). ### Change Type Addition ### Area Getting started ### Proposed Changes My previous [issue](https://github.com/netbox-community/netbox/issues/14417) was closed without allowing me to respond? This is not some sort of troll, this is a genuine request. @chiniquy made a comment about tenants: https://github.com/netbox-community/netbox/issues/14417#issuecomment-1838443831. I had not mentioned tenants, nor any of the issues I was referring too, so, not sure what that was about? @jeremystretch closed the ticket without allow me to respond so now I'm trying again. Take VLAN for example, there is nothing which explains that VLAN names are limited to 64 characters or the logic of this 64 character discussion, in the existing documentation: https://docs.netbox.dev/en/stable/models/ipam/vlan/. The reason Jeremy gave in previous tickets is that it relates to the max VLAN length he has seen on some device: https://github.com/netbox-community/netbox/issues/6349. That does make sense *if* the job of NetBox is to store device configuration... Clarifying this, is the purpose of this issue / it's previous incarnation (https://github.com/netbox-community/netbox/issues/14417). I thought the purpose of NetBox is, as per the [documentation](https://docs.netbox.dev/en/stable/): ``` NetBox is the leading solution for modeling and documenting modern networks. By combining the traditional disciplines of IP address management (IPAM) and datacenter infrastructure management (DCIM) with powerful APIs and extensions, NetBox provides the ideal "source of truth" to power network automation. ``` Storing the actual configuration which is pushed to devices, is not the same as storing the the information required to generate the configuration (`modeling and documenting`). Having low max character limits on various field types makes sense if the job of NetBox is to store the data _exactly_ as it is configured on the network. Low max character limits do not make sense if the job of NetBox is to store the data required to generate the config for the network. In the former case, one would be pushing the data verbatim to network devices. In the later case, one would be using an abstraction method to take data from NetBox, and convert the data into a form which is suitable for the network, and pushing the output of that process to the network. This is a really important distinction because there are loads of vendors out there, with all kinds of crazy limitations, it would be madness for NetBox to try and cater to all the limitations of all the different vendors. Therefore, if the purpose of NetBox is to store network configuration as it should be on the devices, the former case given above, that should be documented in the public facing documentation. If the purpose of NetBox is to fulfil the later case, that should also be documented (it seems to be what is documented, `modeling and documenting`), _and_ in this case, these low character limits do not make sense. Hopefully you see the confusion I am facing now. I am opening issues, I am given a reason for them being closed, but it does not align to the documentation because, the documentation suggests the purpose of NetBox is to fulfil for the later case (store data required to create network configuration, not the actual network configuration).

adam added the type: documentation label 2025-12-29 20:42:46 +01:00

adam closed this issue

2025-12-29 20:42:46 +01:00

Sign in to join this conversation.

Branches Tags

main

update-changelog-comments-docs

feature-removal-issue-type

20911-dropdown

20239-plugin-menu-classes-mutable-state

21097-graphql-id-lookups

feature

fix_module_substitution

20923-dcim-templates

20044-elevation-stuck-lightmode

feature-ip-prefix-link

v4.5-beta1-release

20068-import-moduletype-attrs

20766-fix-german-translation-code-literals

20378-del-script

7604-filter-modifiers-v3

circuit-swap

12318-case-insensitive-uniqueness

20637-improve-device-q-filter

20660-script-load

19724-graphql

20614-update-ruff

14884-script

02496-max-page

19720-macaddress-interface-generic-relation

19408-circuit-terminations-export-templates

20203-openapi-check

fix-19669-api-image-download

7604-filter-modifiers

19275-fixes-interface-bulk-edit

fix-17794-get_field_value_return_list

11507-show-aggregate-and-rir-on-api

9583-add_column_specific_search_field_to_tables

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/netbox#8911