Your first design

Your first design builds a region hierarchy in NetBox: the world, two continents, and two countries in each.

Read the design

name: World Regions
netbox_versions: ["4.6.*", "4.7.*"]
description: A region hierarchy of the world, its continents, and some of their countries.
variables: {}
infra:
- infra_type: Region
  name: World
  slug: world
  regions:
  - infra_type: Region
    name: Europe
    slug: europe
    parent: '{{ parent }}'
    regions:
    - infra_type: Region
      name: Latvia
      slug: latvia
      parent: '{{ parent }}'
    - infra_type: Region
      name: Germany
      slug: germany
      parent: '{{ parent }}'
  - infra_type: Region
    name: North America
    slug: north-america
    parent: '{{ parent }}'
    regions:
    - infra_type: Region
      name: United States
      slug: united-states
      parent: '{{ parent }}'
    - infra_type: Region
      name: Canada
      slug: canada
      parent: '{{ parent }}'

• name is the design's title, and description says what it builds.
• netbox_versions lists the NetBox versions the design works with. Designs refuses to plan it against any other.
• variables is empty: this design takes no input.
• infra lists what the design builds. Each item names its object type in infra_type, as NetBox's data model names it, then the object's fields.
• An object can contain others. Each country region sits inside its continent's regions, and parent: '{{ parent }}' makes the region that contains it its parent in NetBox.

Add it to the catalogue

1. Go to Design Catalogue and select Add design.
2. Paste the YAML above.
3. Set Catalogue name to tutorial/world_regions. The catalogue name is how other designs and deployments refer to this one, and it has to be exact. The YAML's name, World Regions, is only its title.
4. Leave Version at 1.0.0, and select Add to catalogue.

The catalogue checks the design before it accepts it.

Plan it

1. Open tutorial/world_regions in the catalogue and select Deploy.
2. Choose your NetBox as the Target NetBox.
3. Under Deployment, leave New deployment selected, with its suggested name, world_regions. The deployment is how you'll come back to what this design builds, to change it or tear it down. Deployments explains what one is.
4. Select Plan.

Designs renders the design, reads the regions NetBox has now, and works out what it must do to make NetBox match. Nothing is written yet.

Review the plan

The plan names its deployment, world_regions of tutorial/world_regions, as new, and counts its changes: 7 Create, 0 Update, 0 Delete. The changes are grouped by where they sit; select Flat for a plain list.

A plan only ever shows what applying it would do. If anything else changed in NetBox since you planned, applying it is refused and you plan again.

Apply it

Select Apply Changes. When it finishes, the page says Changes Applied.

In NetBox, go to Organization and then Regions. World is there, with Europe and North America under it, and their countries under them.

Plan it again

1. Go to Deployments and open world_regions. It lists the session you just applied.
2. Select Check drift.

It says In sync: NetBox already matches the design, so there is nothing to apply. A design always plans to nothing once it's applied, until the design or NetBox changes. That property is what lets you plan a design whenever you like to see whether NetBox has drifted from it.

Next, a second design puts a site in one of these countries.