Tutorial
What you'll build in this tutorial, who can do what, and what to have ready.
This tutorial takes you from a blank Designs organization through everything Designs does, and back to blank. You connect a NetBox, build a region hierarchy, a site and a compute rack from designs, then change the rack, catch drift, deploy a second site with its rack under one name, and tear it all down again. Each chapter does one thing and says what you'll see, so you can check as you go.
- Connect a NetBox for Designs to plan against.
- Your first design: a region hierarchy. Plan it, review the plan, apply it, and plan it again to see nothing left to do.
- A second design: a site in one of those regions, with a /16 supernet. It introduces variables.
- The compute rack: a 42U rack built from other designs. Read it, and add it to the catalogue.
- Deploy into a branch: deploy the rack into a NetBox branch and look at it there before it touches main.
- A second rack: deploy the same design again alongside the first, and see what each deployment owns.
- Change the design: remove a server from the rack, and follow the deletes through to NetBox.
- Change a design the rack uses: change the server design, see which racks follow it and why, and how to pin one.
- Check for drift: change something in NetBox by hand, see Designs find it, and put it back.
- Several designs as one: a second site and its rack, managed under one name.
- Tear down and release: take deployments apart in the right order, and see what stays.
- Clean up: back to where you started.
- Where next.
Each chapter links out to Concepts for how things work and to Reference for everything a design can say. You don't need either to finish the tutorial.
Designs writes to NetBox
Applying a plan creates, changes and deletes objects in the NetBox you connect. Follow this tutorial against an empty NetBox that isn't in production. The counts each chapter gives you assume one; on a NetBox that already has some of the objects the designs describe, the plans adopt those instead of creating them, and the numbers differ. Chapter 5 shows how to plan into a NetBox branch instead of main, which is the safe way to try Designs against a NetBox you care about.
Who can do what
What you can do depends on your role in the organization:
| Role | Can |
|---|---|
| Org admin | Everything below, plus connect and remove NetBoxes |
| Member | Add designs to the catalogue and delete them, plan, apply, and release or tear down deployments |
| Viewer | See NetBoxes, designs, plans and deployments |
A button you can't use is greyed out, and hovering over it says which permission it needs. Chapter 1 connects the NetBox, which needs an org admin; everything after that, a member can do.
What you need
- Designs enabled for your organization. Ask your NetBox Labs contact if the Designs pages aren't there.
- An empty NetBox at version 4.6.0 or later, and its URL as NetBox Cloud reaches it.
- A v2 API token for that NetBox, which starts
nbt_. The NetBox user it belongs to needs permission to view the objects Designs reads, and to add, change and delete the ones the tutorial's designs describe: regions, sites, prefixes, racks, devices, modules, interfaces and cables, and their types. - For chapter 5, the NetBox Branching plugin on that NetBox, and the token's user allowed to create and use branches. Without it, the chapter says what to do instead.
Next, connect a NetBox.