Read a plan
What a plan shows, what its warnings and effects mean, and why a plan is refused.
A plan shows what applying it would do, and nothing else happens when you apply it. This page covers what you see on the review step, and the reasons a plan is refused before you get there.
The review has its own address: the page's URL names the plan while you review it, so a reload brings the same plan back with the variables it was made from, the browser's Back returns to Configure with what you filled in, and the link can be sent to a colleague, who sees the plan read-only once it has been applied.
The review
- Deployment names the deployment the plan is for, and whether it's new. A new deployment is recorded when the plan is applied. When the plan adds a design to a deployment that already deploys others, the line says which.
- Create, Update and Delete count the plan's changes. Adopt counts objects the design describes that NetBox already has and this deployment doesn't yet own: nothing is written to NetBox for them, but applying records them as the deployment's, so a later redeploy can change them and a tear down releases them. A plan with nothing to change can still adopt, or record a new deployment; the Apply button says which.
- Changes lists them, grouped by where each object sits: a rack's devices under the rack, its cables by the devices they connect. Flat shows a plain list. Open a change to see its fields: a field that refers to another object shows that object's name as the plan knows it, such as
worldfor a region's parent, and fields with nothing in them are left out until you ask for them. Open an update to see each changed field's current and new value.
Finding a change in a large plan
Under the counts, a line says how many changes there are of each object type, most first: Interface 1,620 · Cable 258 · Device 237 .... It shows the shape of the plan at a glance, and each type is a toggle: select one and the changes below show that type alone, select several and they show those types. The box beside Grouped and Flat filters by name or key: type part of a device's name or an address and both views narrow to the changes whose key or name contains it, whatever the case. While a filter is on, the review says how much of the plan is shown, such as Showing 42 of 2,595, and Clear brings the whole plan back. A delete's effects stay with the delete: filter for an interface that a device's delete takes with it, and the delete is shown with that effect under it.
Warnings
Warnings are worth reading before you apply, but don't stop you:
- This plan starts a new deployment of a design that already has deployments on that NetBox. If you meant to change one of those, plan it with Redeploy instead.
- Released, not deleted: an object the deployment created and no longer describes, but another deployment still does. It stays in NetBox, and this deployment stops owning it.
- Not one of the known values: a field set to a value outside its known choices. NetBox rejects it at apply unless that NetBox has added the value to the field's choices.
- Another deployment also declares a field, with a different value. Each apply writes its own value, so the object changes back and forth. Stop declaring the field in one of the deployments, or make them agree; if the field is being handed from one deployment to the other, apply and let the first stop declaring it on its next plan.
- A key that is not a field of the object's type, on a design version that has already been applied: it was never written then and is not written now. Remove it from the design when you next edit it. On a design that has not been applied, the same key is refused when the design is added or edited, so a typo is caught before it is deployed.
What the design chose
A design that finds a value rather than stating it (see Selectors) lists each choice on the plan, by the name the design gave it: server-port: Ethernet1/7 on tor-r12 - chosen on this plan; 11 others free. Once applied, the choice is the deployment's: the next plan says kept from the deployment's last apply, or, when the port has been taken by something else since, re-chosen with the new port. A design's assertions (see What must hold) that don't hold refuse the plan with the design's own message; one the design marks as a warning is listed here among the warnings instead.
What a delete takes with it
NetBox deletes some objects along with others: a device's interfaces and modules, a site's locations and the prefixes scoped to it. It clears others: a VLAN's delete clears it from every interface that used it. A cable that loses an end stays in NetBox, unterminated.
The plan lists every such effect under the delete that causes it, with who owns the object. When a plan's deletes reach objects it doesn't list as its own changes, applying needs you to accept them: tick the box beneath them, and Apply becomes Apply and also delete them. Who accepted, and when, is recorded on the plan.
A cable the design wants on a port another cable still holds, often one left with a single end after a device was deleted outside Designs, is listed the same way. Accepting it deletes that cable first.
NetBox also deletes what hangs off a deleted object that Designs doesn't track: its journal entries, tags, image attachments and port mappings. The review notes that once for the whole plan, under the effects, with a breakdown by object type behind By object type. There is nothing to accept, since nothing is reached beyond the objects the plan already deletes.
A move
Designs knows an object by the facts that identify it in NetBox: a site by its slug, a device by its name and site, an interface by its name and device. Change one of those in a design and the differ sees the old object gone and a new one arrived. The plan pairs the two and shows them as a move, with the key change spelled out.
Where the deployment knows the object's NetBox id, because it created it or has updated it before, the move is kept: one update of the object NetBox has, which keeps its id and everything hanging off it. Renaming a site is then one update, and the devices, interfaces and cables under it are not touched at all; a warning says how many are kept without a write, since NetBox carries them with their site. The deployment's record of what it owns moves to the new names with them. Where the design changes something else on a carried object along with the rename, as a rack's cables labelled after the rack change label when it is renamed, that object is kept too, as one update of the field that changed. An adopted object is kept through a rename the same way, by the id the deployment learned when it adopted it, and stays adopted.
An adopted object the design stops describing is never deleted: it leaves the deployment, and a line in the plan says so (Site tallinn-dc leaves deployment 'tallinn-main': it was adopted, so it stays in NetBox and nothing owns it afterwards). Where the design renamed it and the rename could not be kept, the line says why, and that the renamed object is created beside it.
A move is applied as a delete and a create when it cannot be kept, and the plan says why on both halves: the ledger has no id for the object, or the fact that changes can't be changed on an existing object, as an interface's device can't. Then what the delete takes with it is listed as for any delete, the object's NetBox id first. Read that line before applying.
nbd plan --moves recreate applies every move as a delete and a create, for when a fresh object is wanted and what hangs off the old one should go. The API option is moves: "recreate".
What a create makes
NetBox gives a new device the components its device type's templates describe: an interface per interface template, a console port per console port template, and so on. The plan says so under the device, with a count per kind, and these objects belong to the deployment from then on: they go when the device is dropped from the design. Nothing is deleted or changed outside the plan, so there is nothing to accept.
A design that declares one of those components, say eth1 with a description, isn't asking for a second eth1. The plan shows it as an update to the one NetBox will make, applied after the device, writing what the design declares that the template doesn't already give. The data model states which of a template's fields NetBox copies to the component, so a declared type that restates the template's is nothing to do, and an enabled that differs is shown changing from the template's value. A template's description is never copied, so a declared one is written even when the template holds the same. A declared component that asks for nothing the template doesn't give is no change at all. The same device type's templates created in the same plan are written before the device, so the device gets them.
A template's name may carry {vc_position}, as a stackable switch's do (GigabitEthernet{vc_position:1}/0/1). NetBox fills it in when it makes the component: the device's own vc_position when the device is in a virtual chassis, else the number after the colon, else 0. The plan names the component the same way, so a design that declares GigabitEthernet1/0/1 on a standalone switch, or GigabitEthernet2/0/1 on the second member of a stack, is updating the one NetBox makes.
A module makes its components the same way, from its module type's templates, on the module's device. Their names carry {module}, which NetBox fills in with the position of the bay the module is in (Ethernet{module}/1 in bay 3 is Ethernet3/1), and the plan reads the bay's position wherever the bay is: declared in the design, made by the device's type in the same plan, or already in NetBox. A design that declares Ethernet3/1 on the device is updating the interface the module makes, written after the module; the module's other components are counted under the module and belong to the deployment, so dropping the module takes them. Inventory items a device type makes, each under its parent item, and the port mappings of its front and rear ports are identified the same way. Where the plan cannot read what it needs (a bay it can find nowhere, a template a reference names that does not exist), the component is counted and left alone, as before.
Refused before review
Some problems refuse the plan outright, with a message saying what to change:
| Refused because | What to do |
|---|---|
| The design doesn't support the NetBox's version | Add the version to netbox_versions, once the design works with it |
| A value NetBox wouldn't keep as written: a blank name, text it would trim, a MAC address in another form | Write the value as the message says NetBox stores it |
A value outside a bound NetBox enforces: a name longer than its field holds, a VLAN vid above 4094, a slug with a space | Change the value to fit the bound the message gives, or remove the line |
A value of the wrong type for its field: text in a VLAN vid or a rack's u_height, maybe where NetBox wants true or false, soon for a date | Write a value of the type the message names: "42" is a whole number to NetBox, abc is not; dates are YYYY-MM-DD |
| A device racked where NetBox has no room: a unit another device covers, or above the rack's top | Choose a free position, move the other device, or make the rack taller; the message names the device in the way and its height |
| A value NetBox keeps unique that another object already has: a new site named like one in NetBox, under a different slug | Change the value, or make the design a deployment of the object that has it; the message names that object |
A create that leaves out a field NetBox requires, such as a Site whose name comes from an optional variable you didn't give | Give the field a value, or give the variable. Leaving a field out only leaves it alone on an object NetBox already has |
A key that isn't a field of the object's type, such as descripton on a Site | Write the field the message suggests, or remove the line. Object types lists each type's fields |
| The NetBox requires a custom field, with no default, on a type the design creates | Give the custom field a default in NetBox, or make it optional. Designs can't set custom fields yet: see Limitations |
| A reference names no object, or more than one | Name an object that exists, in NetBox or in the design, by its name, slug or key |
| A delete NetBox would refuse, such as a site that still has racks | Delete or move what's in the way first, or keep the object in the design |
| An expression the render can't work out, such as a variable the design doesn't have | Fix the expression the message names |
An object type in the form designs used to write it, such as device_role or NetBoxDeviceRole | Write the type the message names, such as DeviceRole. Object types explains the names |
| The NetBox was upgraded to a version Designs doesn't support yet | Nothing until Designs supports it; the message names the version. A supported upgrade isn't a refusal: the plan reconnects the NetBox and says so in its warnings. See When your NetBox is upgraded |
Applying is refused, and you plan again, when NetBox changed after you planned, when a newer plan in the same session replaced this one, or when the NetBox was upgraded after you planned (the new plan reconnects it).
When NetBox changed after you planned, the page plans again for you and compares the new plan with the one you reviewed. If it is the same plan, which it is whenever the change was elsewhere in NetBox, it is applied without asking you again. If it differs, the new plan replaces the one on screen with a note saying where it differs: a change that was not in the plan you reviewed, one no longer needed, one that writes different values, a different number of objects affected outside the plan, or a new warning. Look there, then Apply. If NetBox keeps changing under every attempt, after two rounds the page stops and offers Plan again instead.
An apply that was interrupted
If Designs restarts while a plan is being applied, the writes to NetBox still finish, but the part of Designs that records them may not hear how they went. The plan reads Applying until no apply could still be running (six minutes), then Interrupted. At that point Designs asks the service that did the writing for the outcome it kept, and in the usual case gets it: the plan then reads Applied, with the deployment owning what the apply created, exactly as if nothing had happened. Nothing is asked of you.
When the outcome cannot be recovered (the restart took the writing service too, before it had finished), the plan stays Interrupted, and applying it is refused: "The apply of this plan was interrupted; NetBox may hold some or all of these objects. Plan again." Plan again, and the new plan finds the objects already in NetBox. Because the interrupted plan set out to create them, the new plan records them as created by this deployment, not adopted, and says so in its warnings; applying it records the deployment, and tearing it down later deletes them as it would anything else the deployment created.
Design structure explains how values and empty fields are read.