Get started with network design repositories

This tutorial goes from the idea to certified changes, one chapter at a time. The full reference is [Network design repository](/docs/en/network-design). ## 1. What a network design repository is ```diagram type: flow title: The network's source of truth, as text --- Text | Sites, devices, ports, links, circuits, ducts in `.zevtopo` files | accent | 📐 ~ versioned Reviewed | Every change a commit with an author and a reason, in a pull request | | ⎇ ~ checked Trusted | Compared with the devices, tested against promises you wrote down | good | ✓ ``` A **network design repository** holds what your network is supposed to be: its sites, devices, ports, the links between them, the circuits you buy and the ducts they run through. It's plain text, versioned like code, so every change has an author, a reason and a review. Zaryn then checks it against the real network and against promises you write down. ## 2. Why drawings lie ```diagram type: graph title: Redundant on the drawing, one cut in practice alt: Two sites joined by two circuits that both run through the same duct; one cut takes both circuits down legend: down=Cut start: The drawing height: 46 --- box Headquarters | 3 6 36 34 | accent box Data center | 61 6 36 34 | good node hq1 | hq1 | 14 16 | router node hq2 | hq2 | 14 32 | router node dc1 | dc1 | 86 16 | router node dc2 | dc2 | 86 32 | router link hq1 hq2 link dc1 dc2 link hq1 dc1 | circuit A link hq2 dc2 | circuit B step One duct, two circuits | Both circuits run through the same duct under one bridge. The drawing doesn't know. note 50 44 | both in duct-north | warn step A backhoe | One cut, both circuits down, the sites apart. A design that names the duct finds this before it happens. link hq1 dc1 | down link hq2 dc2 | down node dc1 | bad node dc2 | bad ``` Every network has a design somewhere, a diagram or a spreadsheet, and within months it's wrong: a device added in a hurry, a link moved to another port. Worse, a drawing can't show **shared risk**: two "redundant" links in one duct fail together. ## 3. Design, reality, prediction ```diagram type: flow title: Three views of one network, kept in step loop: every merged change updates the design; every device report checks it --- Design | What it should be: this repository | accent | 📐 ~ compared with Reality | What the devices say: a site's collector | good | 📡 ~ predicts Prediction | What a change would do: the digital twin | warn | 🔮 ``` This tutorial is about the first view. [Sites](/docs/en/network-sites) give you the second, and the [twin](/docs/en/network-twin) the third. ## 4. Create the repository ```diagram type: flow title: Two ways to start or: or --- New repository | On zaryn.xyz/repos, kind **Topology**; or `zev new` and choose topology | accent | ➕ ~ then From scratch | Write `topology/main.zevtopo` by hand or on the canvas | | ✎ ? From a running site | `zev topo import <owner>/<site>`: every device and link the collector sees ``` Already have a [site](/docs/en/network-sites)? Import it instead of typing: ```bash zev clone you/network-design && cd network-design zev topo import you/hq zev add topology && zev commit -m "Design from the live network" && zev push ``` The import has every device (vendor, model, management address) and every link the devices see, with its ports. Then you make it a design: roles, circuit names, shared risks. ## 5. Your first design ```toml [[device]] name = "hq1" vendor = "cisco" role = "core" site = "hq" [[device]] name = "dc1" vendor = "cisco" role = "core" site = "dc" [[link]] a = "hq1" b = "dc1" a_if = "Te1/0/1" b_if = "Te1/0/1" provider = "TIC" circuit = "TIC-4411" srlg = ["duct-north"] ``` ```diagram type: cards title: The blocks you'll use most --- 🏢 | [[site]] | A place: name, address, coordinates | 🖧 | [[device]] | name, vendor, role (core, distribution, access, edge…), site, model, management address | accent 🔗 | [[link]] | Its two ends and ports, kind, capacity, provider, circuit, and `srlg`: what it shares | good 🏷 | [[vlan]], [[interface]], [[static_route]] | Addressing and routing, when you want them | ``` Only a device's `name` and a link's `a` and `b` are required. Split the design into as many files under `topology/` as suits your team, one per site for example. [The full format](/docs/en/network-design#the-zevtopo-format). ## 6. Code or canvas, your choice ```diagram type: graph title: One design, two editors, always in step alt: The .zevtopo file and the canvas show the same design; typing redraws the canvas, and changing the canvas edits only those lines of the file height: 32 --- node code | .zevtopo file | 14 16 | file | accent | Type a block: the canvas redraws as you type node canvas | canvas | 86 16 | router | good | Add, link, rename, delete: only those lines of the file change link code canvas | same design | path link canvas code | same design | path2 ``` The repository's **Design editor** tab shows the file and the drawing side by side. `n` adds a device, `l` links two, the inspector edits details, and mistakes are listed with their line. **Save** proposes the change as a pull request by default, so it's checked before it lands. [Every shortcut](/docs/en/network-design#edit-it-code-and-canvas). ## 7. See it four ways ```diagram type: cards --- 🕸 | Logical | Devices and links, single points of failure and critical links marked | accent 🏢 | Sites | Devices grouped by site, so your WAN stands out | 🎨 | Shared risk | Links coloured by what they share: one colour, one failure | warn 🔁 | Design and reality | The design drawn over what the linked site reports | good ``` Open the repository's **Network overview**. Click a device for its model, site, management address, ports and circuits. ## 8. Design and reality ```diagram type: graph title: What the comparison shows alt: A designed link no device reports is dashed red; a link the devices report that the design lacks is dotted amber legend: path=Both agree; down=Designed, not on the network; warn=On the network, not in the design height: 40 --- node core1 | core1 | 20 10 | switch node core2 | core2 | 80 10 | switch node acc1 | acc1 | 20 32 | switch node acc9 | acc9 | 80 32 | switch | warn | Plugged in, never documented link core1 core2 | | path link core1 acc1 | designed, not seen | down link core2 acc9 | not in the design | warn ``` On a site, **Collector and settings → Design repository** links the two. From then on the design can't quietly drift: anything designed but not built, built but not designed, or on different ports than planned shows up, on the design and on the site's map. ## 9. Intents: promises the design must keep ```text # topology/wan.zevintent ducts = survive site:hq site:dc srlg hq-to-dc = max-hops hq1 dc1 3 no-spof ``` ```diagram type: cards title: The promises you can write --- 🔗 | reach A B | A and B are connected | 🛡 | survive A B [link, srlg, device, any] | Still connected after any single failure of that kind | accent 📏 | max-hops A B N | The shortest path is at most N links | 🎯 | no-spof, no-bridge, no-shared-risk | No single device, link or shared risk splits the network | good ``` When an intent fails, Zaryn doesn't just say "failed", it names the failure that does it: `shared risk group duct-north (2 links) → site:hq and site:dc are cut apart`. ## 10. Pull requests that can't break a promise ```diagram type: flow title: The target branch's intents are the contract --- Pull request | A branch that changes the design | accent | ⎇ ~ checked against Intents | The target's, plus any the change adds | | ✓ ~ each one Still holds | Nothing to say | good | ✓ ? Held, now broken | Blocks the merge and names the failure | bad ? Already failing | A warning, debt the change didn't cause | warn ``` The pull request also draws the change: added devices and links in green, removed in dashed red, changed in amber. Deleting an intent in the same pull request doesn't excuse breaking it. ## 11. What if, and the link that would help ```diagram type: graph title: The best link to add alt: core1 is a single point of failure for dist1 and two access switches; adding a link from core2 to acc1 gives them a second way out legend: down=Single point of failure; new=The suggested link start: Today height: 44 --- node core1 | core1 | 30 8 | switch | warn | If it fails, dist1, acc1 and acc2 are cut off node core2 | core2 | 70 8 | switch node dist1 | dist1 | 30 22 | switch node acc1 | acc1 | 18 36 | switch node acc2 | acc2 | 42 36 | switch link core1 core2 link core1 dist1 link dist1 acc1 link dist1 acc2 link core2 acc1 | | hidden step The suggestion | Zaryn tries every link you don't have and ranks them: this one removes the single point of failure. **Add it in the editor** opens it ready for a pull request. link core2 acc1 | new | suggested node core1 | normal ``` - **What if these fail?** on the **Intents** tab: pick ducts, links and devices and see what's left and which intents stop holding. - **Resilience**: the share of single failures that cut nobody off, the worst ones, and a heat view of the graph. - **The links that would help**, ranked as an engineer would: what each removes, a short run before a new circuit. ## 12. Availability, capacity and disjoint paths ```diagram type: stats title: What the nines mean in a year --- 99.9% | three nines | about 8 h 46 min down | 73 | warn 99.99% | four nines | about 53 min down | 47 | accent 99.999% | five nines | about 5 min down | 19 | good ``` ```text up = availability edge dc 99.95 uplinks = capacity edge dc 10000 link two-ways = disjoint edge dc device ``` With Premium, three more intents answer what "redundant" doesn't: how often A can't reach B (from each part's `mtbf` and `mttr`), whether the backup can carry the traffic after a failure, and the two paths to build that share nothing. On Free they're listed as waiting, never as failures. [In depth](/docs/en/network-design#availability-capacity-and-disjoint-paths). ## 13. History, and help from an AI ```diagram type: cards --- 🕰 | The design over time | Today against any recent commit, with who changed what; Play walks through it | accent 🤖 | Copy for an AI agent | The design, its weak points and the fixes as short Markdown | good 🔌 | zev mcp | Agents read intents and what-if failures themselves | ``` "What did we change since the outage?" is one slider away. ## 14. Run it as a lab ```diagram type: flow title: From a design to a running lab or: or --- Design | The `.zevtopo` files | accent | 📐 ~ Download Containerlab | `.clab.yml`: `containerlab deploy -t …` | | 📄 ? GNS3 | `.gns3`: File → Open project ~ deploy Lab | Containers or VMs wired as designed: ping, pull a link, compare with your intents | good | ▶ ``` A design that has never run is a hypothesis. The Network overview exports it for [Containerlab or GNS3](/docs/en/network-design#run-the-design-as-a-lab), with each device's kind and image chosen from its vendor. ## 15. Certificates, and where to go next ```diagram type: flow title: A chain of signed changes --- #1 · Second uplink | Merged by sara, approved by omid, intents held | good | 1 ~ prev #2 · Riser repair | Merged, intents held | good | 2 ~ prev #3 · One uplink | Merged past failing checks: recorded as forced | bad | 3 ``` With Premium, every merged design change gets a **change certificate**: who changed what, who approved, what was checked, signed and chained to the one before, checkable in your browser without trusting Zaryn. [How to verify one](/docs/en/network-design#change-certificates). The design is the start of the loop: the [digital twin](/docs/en/network-twin) predicts what a config change does, and [rollouts](/docs/en/network-rollouts) make it on the devices with automatic rollback.