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
- 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.
- 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.
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.
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.
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 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 |
Applying is refused, and you plan again, when NetBox changed after you planned, or when a newer plan in the same session replaced this one.
Design structure explains how values and empty fields are read.