Connect a NetBox

Designs plans each design against a NetBox you connect, and applies plans to it. An org admin connects one, and everyone the NetBox Labs console invites to your organization is an org admin. Everyone in the organization then sees and uses that NetBox, as they do its designs and deployments.

1. Go to Deploy Targets and select Connect a NetBox.
2. Fill in the dialog:
   • Connection Name: how Designs refers to this NetBox, such as netbox-test. You choose it when you plan.
   • NetBox URL: the address NetBox Cloud reaches it at, such as https://netbox-test.example.com. Without https://, Designs adds it. It has to be a public https:// address with a valid certificate: a NetBox on a private network, or one reached over plain http://, is refused with a message saying why.
   • API Token: the token Designs uses to read and write this NetBox. See what the token needs.
3. Select Connect.

Designs checks the URL and token, and asks NetBox which version it runs. A NetBox it cannot reach is refused with the cause in plain words: the hostname could not be resolved, the connection was refused, it did not answer in time, or its certificate was not accepted. A NetBox older than 4.6.0, or on a release newer than the newest Designs supports (the 4.7 releases, at the time of writing), is refused with a message naming the version it reported and the versions Designs supports. Designs works from a data model of each NetBox version, so a new NetBox release is supported once its data model is published, not on the day it ships: within five working days of the release. A NetBox on a release Designs does not support yet can be connected as soon as it is.

Delete a NetBox connection

Delete on a NetBox in Deploy Targets makes Designs stop planning against it. Nothing in NetBox changes. The confirmation names the active deployments on it: they and their history stay in Designs, and work again if a NetBox is connected under the same name, which is also how a token is rotated; until then they are shown as not connected and can only be released or removed. Plans still waiting to be applied against it are closed, since nothing can apply them now.

What the token needs

• A v2 token, which starts nbt_, with Write enabled. Create one in NetBox under your user's API Tokens, and paste the whole token, without Bearer or Token in front of it. Designs doesn't accept v1 tokens, which NetBox deprecates: a NetBox connected with one has to be deleted from Designs and connected again with a v2 token.
• Its user's permissions: to view, add, change and delete the object types your designs manage, and to view the changelog (Core > Object changes), which Designs reads to keep up with changes made in NetBox. On a NetBox you test with, a superuser's token is simplest.
• To plan into a branch, the user also needs netbox-branching's permissions to create and use branches.

Check the connection

1. In the Deploy Targets list, select the arrow beside your NetBox to open it.
2. Select Refresh from NetBox.

Designs reads the objects it manages from NetBox and lists how many of each type it found. The NetBox's status becomes ready, and Deploy a Design becomes available. The list and the panel say which NetBox version it runs, as it reported it.

The component templates of device types and module types (interface templates, power port templates and the rest) are not read at Refresh. A NetBox with the devicetype-library imported holds a hundred thousand of them, and a plan needs only those of the device types it creates devices of, so Designs reads a device type's templates the first time a plan needs them and keeps them from then on. The panel says so under the counts, and a template type's count there is what has been read so far.

A NetBox that holds more objects than the Designs service has room for is refused before anything is read, with a message that counts them ("holds 86,221 objects Designs would read (36,264 Interfaces, …); this service has room for about 65,000"). Nothing is wrong with the NetBox or the token: ask whoever runs Designs for a service sized for it; the message names the setting.

When the token is rotated

If the token is disabled or expires in NetBox, Designs says so the next time it reads or plans against this NetBox: "NetBox at … refused the API token", and the NetBox shows error in the list until the token is replaced. Nothing is lost: its deployments and the history of every plan stay as they are.

To replace it, open the NetBox from Deploy Targets, select Update token…, and paste the new token. Designs checks the new token against the NetBox before storing it, so a token NetBox refuses leaves the old one in place and tells you why. Once it is accepted the NetBox is ready again, and the next plan reads it afresh. From the command line: nbd service update <name> --token nbt_…; the same command takes --url if the NetBox has moved.

When your NetBox is upgraded

Designs works from the data model of the NetBox version it connected to. When the NetBox is upgraded (NetBox Cloud applies patch releases for you), the next plan, drift check or redeploy against it connects the NetBox again at the version it runs now and reads it again before planning, and the plan's warnings say so: which version it runs now and which Designs had connected it at. Nothing is asked of you. Its deployments, their history and its plans are all kept, as are any branches of it. Plans made before the upgrade are stale, since they were made against the old version: applying one is refused, and planning again is the whole remedy. Refresh from NetBox on Deploy Targets reconnects an upgraded NetBox too. A NetBox upgraded to a version Designs doesn't support yet is refused with a message saying so, and stays connected as it was.

A NetBox release can change how a kind of object is told apart, when a field joins or leaves what makes it unique. Designs keeps each deployment's record of its objects by those identifying facts, so after such an upgrade the first plan of a deployment re-reads its objects from the NetBox by their ids and records them as the new version identifies them. The plan's warnings say so, and nothing is created or deleted for it.

Next, add and apply your first design.