Limitations

Designs is in preview. These are the known gaps, and what to do about each until it's closed.

What Designs manages

Designs works from the data model of NetBox itself, so it manages the objects NetBox ships, and only those.

• Custom field definitions aren't managed by designs yet. A design sets custom field values under custom_fields (see Design structure). Defining a new custom field, or changing one, is done in NetBox; a design that declares a CustomField object is untested.
• Custom objects aren't supported. The object types you define in NetBox yourself aren't part of NetBox's own data model, so a design can't describe them.
• Plugins' models aren't supported. A design can't describe what a plugin adds, such as netbox-branching's own objects. Planning into a branch still works: see Plan into a branch.

The catalogue

• A design can't be renamed. Its name is how other designs and its deployments refer to it. To put a design under another name, save it as a new design and delete the old one once nothing uses it. See Edit a design.
• A design that other designs include can't be deleted. It can be edited.
• A deployment can't be renamed.

Writing designs

• Designs don't allocate from pools. No function picks the next free ASN, VLAN id or single address from a range: a design states the ones it wants. A free port on a device, or a free prefix of a given length inside a parent, can be found, and the deployment keeps the one found: see Selectors.
• An assertion counts. What a design says must hold (see What must hold) is a count of objects compared with a number; it can't compare two fields with each other or do arithmetic. Only the design being deployed is held to its assertions: those of a design it includes aren't checked.
• Device types from NetBox Data Exchange are planned for general availability.

Deployments

• Two deployments that set the same field to different values overwrite each other. Each plan writes its own value back, and no plan says another deployment sets that field. Keep a field in one deployment.
• Designs learns that a NetBox branch was merged or deleted when it next looks, which is when you open the Deployments page or use the branch, not at the moment it happens. Until then a deployment on the branch is listed as it was. See Plan into a branch.

Planning

• The first plan against a NetBox reads all of it, and can take a minute on a large one. Later plans read only what changed.
• A plan of a few thousand objects can outlast the five minutes the CLI waits. nbd plan --timeout <seconds>, or NBD_CLIENT_TIMEOUT, waits longer. The server finishes either way and keeps the plan with its session; the CLI says so and where to find it. While a plan runs, the Deploy page and nbd plan say how far it has got: reading the NetBox, rendering, comparing, saving.
• A move is kept only where the deployment knows the object's NetBox id. Designs knows an object by the facts that identify it in NetBox: an interface by its name and device, a device by its name and site. Change one of those in a design and the plan pairs the delete and the create it sees as a move. The deployment knows the id of what it created and of what it adopted, learned at the apply that adopted it whether or not it wrote anything; for those the move is one update of the object NetBox has, and it keeps its id and what hangs off it. An adopted object whose id the deployment does not know, because it was adopted before Designs learned ids at adoption and never updated since, is not renamed: the plan says it leaves the deployment and that the renamed object is created beside it. Apply any update to it first, or plan once and apply so the id is learned, if you want a later move kept.
• An interface can't be moved to another device, nor a cable to another port. NetBox doesn't allow an existing interface's device, or a cable's terminations, to change, so those moves are applied as a delete and a create whatever the plan knows: the interface or cable gets a new NetBox id, and what hung off the old one goes with it. The plan says so, and lists what the delete takes.
• A move on a branch is kept the same way as on main, but the branch has to be merged for NetBox proper to see it.