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 sessions, 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.

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 has a newer version of the design, the page says so, and Plan the newer version moves the deployment to it; it never moves on its own.
• Check drift plans the deployment again in the background and says whether NetBox still matches it. 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 sessions; 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.

Sessions

A session is one round of planning: you plan, perhaps change a variable and plan again, and apply. Only a session's newest plan can be applied. Each deployment lists its sessions, which is its history: who planned what, when, and whether it was applied.

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 newer 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.