How Designs works

Every change Designs makes goes through the same cycle: render, plan, review, apply.

1. Render. Designs fills the design's variables into its YAML, includes the designs it uses, and works out every object the design describes.
2. Plan. Designs reads the target NetBox and compares each rendered object with the one NetBox has. The result is a plan: what applying would create, change and delete.
3. Review. You read the plan. It says what each change is, what a delete would also take with it, and anything worth knowing before you apply.
4. Apply. Designs makes exactly the changes the plan shows, and nothing else.

A design that has been applied plans to nothing until the design or NetBox changes, so you can plan it at any time to see whether NetBox still matches it.

Plans stay true to NetBox

A plan is computed against NetBox as it was when you planned. If NetBox changes before you apply, applying is refused and you plan again, so you never apply changes worked out against a NetBox that no longer exists.

Some things are refused at plan time, before you get as far as reviewing them: a value NetBox wouldn't keep as written, a reference that names nothing, a delete NetBox would refuse, or a design that doesn't support the NetBox version. Each refusal says what to change. Read a plan lists them.

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. After you apply, Check drift on the deployment plans it again in the background and says whether NetBox has drifted from it. You can discard a plan you don't want; nothing in NetBox changes.

Deployments

A deployment is how you keep managing what a design built: you name it when you deploy, and Designs remembers what it created, so you can change it or tear it down later without touching anything else. The same design can be deployed many times, such as one rack design for each rack in a row. Deployments explains what one owns and what each action does.

What a design owns

• Only the fields it declares. A field the design leaves out is left alone in NetBox. It is never reported as drift and never written.
• Objects it created, or adopted. When a design describes an object NetBox already has, the plan matches it and only changes the fields the design declares. Designs records which objects each deployment created and which it adopted.
• It deletes only what it created. When a deployment stops describing an object it created, the next plan deletes it. An object it adopted is never deleted, and neither is one another deployment still describes: that is released instead, and stays in NetBox.

Through a compute rack

The rest of this section explains the compute rack the tutorial builds, one concept at a time:

1. Composition: how it's put together from other designs and the Device Type Library.
2. Variables: what it asks for, and what it passes to the designs it uses.
3. Functions: how its cables find the interfaces they connect.
4. Deployments: what a deployment of it owns, and what redeploy, release and tear down do.