Deployments

A deployment is how you keep managing what a design built. You name it when you deploy, and Designs remembers which objects in NetBox it created and which it adopted. Come back to it later to change it, check it for drift, or tear it down, and nothing it doesn't own is touched.

That's what lets one design be deployed many times. A rack design builds every rack in a row, each rack its own deployment, and changing rack R1 never touches rack R2:

tutorial/compute_rack              one design, in the catalogue
 ├─ rack-r1   rack_name: R1   →   owns rack R1 and everything in it
 └─ rack-r2   rack_name: R2   →   owns rack R2 and everything in it

If you've used Helm, a deployment is a release: one install of a chart, under a name, that you upgrade or uninstall on its own. A Pulumi stack is the same idea. The tutorial deploys the rack twice in A second rack.

New deployment or existing one

A new deployment leaves every other deployment alone. Changing an existing deployment makes NetBox match the design for that deployment, and that includes deleting what it created and the design no longer describes. The deploy page asks which you mean, and suggests a new name that no deployment on that NetBox has.

Several designs in one

A deployment can hold more than one design, so designs that belong together, such as a site and its racks, are managed under one name. Each design in it has its own variables and history, and is planned on its own. Planning one never deletes what another created, and what two designs share stays while either describes it. The Deployments page lists the deployment once, with all its designs, and each design has its own actions. Several designs as one builds one.

The same design many times

A deployment can also hold one design many times: a data hall is its site design, its IPAM design and a hundred racks from one rack design, each with its own variables. Each is an instance of the design, and a record of its own under the deployment's name, planned, checked and torn down on its own like any design in the deployment.

What tells one instance from another is the value of one variable, which the design names at its top level:

name: NVL72 rack
instance_key: rack_name
variables:
  rack_name: {type: netbox_new, model: Rack, field: name}

Deploying the design into a deployment with rack_name: dh3-r235 records the instance dh3-r235; deploying it again with dh3-r236 adds a second instance rather than changing the first, and the plan says so. Planning with a rack_name the deployment already has plans that instance again. Nothing renames an instance: a plan with a new value is a new instance, and the old one stands until it is torn down. From the CLI, nbd plan --deployment dh3 --design nbd:racks/nvl72 --var rack_name=dh3-r235 records the instance from the variable, and --instance <label> names one outright; deployment show, release and teardown take --instance to choose among them.

A design with no instance_key has one instance under each name, as before, and nothing in it changes.

Created and adopted

When a design describes an object NetBox doesn't have, applying creates it, and the deployment records that it created it. When a design describes an object NetBox already has, the plan matches it and changes only the fields the design declares; the deployment records that it adopted it. The Deployments page shows how many objects each deployment owns, and hovering over the count splits it into created and adopted.

The distinction decides what a deployment may delete:

• It deletes only what it created. When a deployment stops describing an object it created, the next plan deletes it.
• It never deletes what it adopted. An adopted object stays in NetBox whatever the design does later.
• It never deletes what another deployment still describes. That object is released from this deployment instead, and stays.

Two deployments may describe the same object, and the fields each declares are its own to write. When they declare the same field with different values, a plan says so, naming the other deployment and both values, because each apply would write its own and the object would change back and forth.

So the second rack adopts the device types the first rack created, tearing down the second rack leaves them, and tearing down the first rack deletes them only once nothing else describes them. The tutorial's Tear down and release and Clean up show each case.

Redeploy, check drift, release, tear down

Open a deployment on the Deployments page for its actions:

• Redeploy opens the deploy page for that deployment, starting from the variables it was applied with and the version of the design it applied. Change what you want and plan it: objects the new variables no longer produce are deleted. If the catalogue's current version is not the one the deployment applied, the page says so, and Plan the current version moves the deployment to it; it never moves on its own. Current, not newer: a version put back is the current one too. If a plan of the deployment is already waiting to be applied, the page says so, with who made it and when, and offers to open it; planning the same design again replaces that plan rather than leaving two waiting.
• Check drift plans the deployment again in the background and says whether NetBox still matches it. It compares NetBox against what was applied: the design at the version the deployment applied, the designs it was built from at the versions they resolved to then, and the variables it was applied with. So a change someone made in NetBox shows as drift, and an edit to the design since does not; the row says when the design has changed, and Redeploy is how you follow that change. A deployment of several designs has Check drift of all, which checks each and sums them up. Check for drift walks through it.
• Release stops Designs managing the deployment. Its objects stay in NetBox, and no deployment owns them afterwards, so nothing will change or delete them.
• Tear down plans deleting what the deployment created. It asks you to confirm, and nothing is deleted then: you review the plan like any other and apply it from the deploy page. What another deployment also describes is released rather than deleted, and what this deployment adopted stays in NetBox.

A deployment that holds several designs has a Tear down all as well. Tearing down one of its designs on its own is refused while another still needs what it created: a site cannot go while the rack design's devices stand in it, and the refusal names that design. Tear down all plans removing everything the deployment's designs created as one plan, in an order NetBox accepts.

A released or torn-down deployment owns nothing. Remove on it makes Designs forget it and its history; nothing in NetBox changes. It's offered on the page that says the tear down is applied, and on the deployment's row under All, Released or Torn down on the Deployments page.

On a NetBox branch

A deployment planned into a NetBox branch is the branch's, separate from deployments on main, until the branch ends. Designs asks NetBox about the branch whenever you open the Deployments page or use the branch. Merged, the deployment moves to main with everything it owns: NetBox keeps the objects' ids across a merge, so the deployment created them there as far as Designs is concerned, and can tear them down. Deleted, the objects went with the branch, and the deployment is listed as Branch gone, owning nothing, with Remove to forget it. Plan into a branch has the details.

A deployment outlives its NetBox connection too. Deleting a NetBox from Deploy Targets changes nothing in NetBox and keeps the deployments on it, with their history, marked not connected: they can only be released or removed until a NetBox is connected under the same name, when they work again.

History

Each deployment lists its history: every plan made of it, newest first. Each entry says what the plan was for (Deployed, Redeployed, Checked for drift, Torn down; while still waiting, Deploy planned and so on), what it proposed (the counts of creates, updates and deletes), what became of it (applied, by whom and when, and how many objects were written; failed, with what failed; superseded by a later plan; discarded), and who made it. Open shows the plan as it was reviewed. An entry that wrote to NetBox has Changelog, which opens NetBox's own changelog over the minutes of that apply: the field-by-field record of what was written is NetBox's to show, and a plan is what it proposed. A plan still pending opens to its review with Apply, and if applying is refused because NetBox has changed since, Plan again plans it again with its design, variables and deployment, as it would on the page it was made on; any other opens read-only, with what became of it in place of the button.

An apply can carry a note on why: Note for the history under the Apply button takes one line of up to 72 characters (the CLI's nbd apply -m "…"), and the history shows it with the entry, cut to the row with the whole on hover. The Deployments page shows the note of the latest apply under when it was applied. A note is a record and can't be edited afterwards; an apply without one says nothing.

A round of planning is a session: you plan, perhaps change a variable and plan again, and apply. Only a session's newest plan can be applied, so planning again supersedes the plan before. Discard plan is offered on a deploy or redeploy that is planned and not applied: it closes the session, and nothing in NetBox changes. A drift check is a reading and has nothing to discard; the next check, or the next plan of the deployment that is applied, replaces it.

When a design changes, or is deleted

A deployment records which version of its design it applied. Edit the design, and each deployment of it says on the Deployments page that the design has changed since, naming the version it applied and the version the catalogue has now. Nothing in NetBox changes until you redeploy it and choose the current version. Check drift compares NetBox with the version the deployment applied, so a changed design is never mistaken for drift. Edit a design has the steps.

Deleting a design from the catalogue doesn't delete its deployments, or anything they own. The confirmation names the deployments that stay, and the catalogue refuses the delete until they are acknowledged, in the GUI by confirming and from the CLI or API with --force or acknowledge_deployments=true; each of them then says the design is gone. A single version a deployment applied can't be removed from the catalogue at all while that deployment is active. Tear down and Release still work, from what the deployment owns; Redeploy and Check drift need the design, so add one under the same catalogue name again to change those deployments as before.