Home › Topics › Monitoring as Code › Templated Onboarding

Templated Device Onboarding: One Definition, Many Devices


A new branch office opens next month. It gets a router, a firewall, two switches, four access points, and a UPS (the battery backup). And every one of them needs to be in monitoring before the first user sits down. You have done this before, by hand, in the console. You add the device, set the address, pick the checks, type the thresholds, set the dependency on the router, pick the notification group, and repeat. It took most of a day, and three weeks later you found the second switch's uplink was never actually being watched.


The problem is not that you were careless. The problem is that you were asked to make the same forty decisions nine times and get every one right. Templated onboarding takes those decisions out of the loop. You decide once what "an access switch" means in monitoring terms and write it down as a template. Each real switch becomes that template plus a handful of facts about itself. Those are its name, its address, its site, what it plugs into. A script does the repeating.


This guide shows you how to think in roles and variables. It explains where the variables come from and what a template looks like. It shows how a small generator turns an inventory into device definitions your monitoring tool can import. And it covers — the part people skip — how to handle the device that genuinely needs to be different without wrecking the pattern.


In this guide

  • The role template idea
  • Where the variables come from
  • What goes in a template: a role-by-role table
  • An illustrative template
  • The generator: inventory in, import file out
  • Naming conventions that make templates work
  • Handling exceptions without hand edits
  • Rolling it out the first time
  • Where to go next

The role template idea


Look at the devices you monitor and most of them fall into a small number of kinds. Access switches. Core switches. Branch routers. Firewalls. Wireless access points. Windows servers, perhaps split into file servers, domain controllers, and application servers. Printers, if you must. UPS units. Each kind is monitored in a characteristic way. Within a kind the differences between individual devices are tiny. There is a different name, a different address, a different site, a different upstream device.


A role template captures the characteristic way. For an access switch it might say to ping it every minute and alert after three misses. It might say to watch the uplink interface for going down and for rising error counts. It might say to watch CPU with a warning at a sustained high level. It might say to mark the switch as depending on its core switch. That way, a core outage does not produce thirty separate switch alerts. It might say to route alerts to the site's team during business hours and to the network on-call rota after hours. None of that depends on which access switch you are talking about.


A device is then a role plus variables — the small set of facts that differ per device. For the access switch: its name, its management address, its site code, the device it depends on, and which port is the uplink. Five facts. Everything else comes from the template. When you want every access switch to start watching a second metric, you change the template once and regenerate. When you want a new switch, you add one row of five facts.


This is the same idea as a form letter. The letter's wording is fixed; the name and address are filled in per recipient. Nobody retypes the letter for each person, and nobody worries that the fortieth copy accidentally says something different from the first.


Where the variables come from


The variables should not be typed into a spreadsheet by the monitoring admin from memory. They already exist in whatever you use as your inventory. That might be a CSV file (a plain-text spreadsheet, one row per device), a database, an IP address management tool, a network documentation system. Or it might be the output of your monitoring tool's own auto-discovery once someone has assigned roles to what it found. The principle that the inventory decides what gets monitored is covered in inventory-driven monitoring. This guide picks up at the point where the inventory can produce a list with one row per device.


Keep the variable list short and honest. A good test for whether something is a variable or belongs in the template is this. If two devices of the same role would ever legitimately have different values, it is a variable. If they would not, it is part of the template. Address is a variable. Ping interval is not. The temptation is to make everything a variable "for flexibility." That quietly recreates the forty-decisions-per-device problem in a spreadsheet instead of a console.


A typical minimum set of variables is: name, address, site, role, and uplink (the device this one depends on). Roles that watch a specific interface add the interface name. Servers might add the operating system flavour so the template can choose the collector. That could be WMI, the built-in management interface on Windows. Or it could be SNMP and SSH, the standard query protocol and remote command channel that network gear and other systems speak. That is usually the whole list.


What goes in a template: a role-by-role table


The table below is a starting point, not a standard. Your thresholds will differ, and that is fine — the point is that each role has a definite answer to each column, written down once.


RoleWhat the template watchesDependenciesAlert routingVariables per device
Branch routerReachability; WAN interface status, traffic, and errors; CPU and memory; uptime resetsNone (it is the top of the site)Network on-call, alwaysname, address, site, wan_port
Core switchReachability; every uplink and server-facing port; error counters; CPU; temperature and fans if exposedSite routerNetwork on-callname, address, site, uplink, uplink_port
Access switchReachability; uplink port status and errors; CPUCore switchSite team in hours, network on-call aftername, address, site, uplink, uplink_port
FirewallReachability; WAN and LAN ports; CPU, memory, session count; site-to-site VPN tunnel statusRouter or ISP handoffNetwork on-call, alwaysname, address, site, uplink
Wireless APReachability; client count against a normal rangeAccess switch it hangs offSite team, business hours onlyname, address, site, uplink
Windows file serverReachability; disk on every volume; memory; CPU; key servicesAccess or core switchServer team in hours, server on-call aftername, address, site, uplink, os
UPSOn-battery state; battery health; runtime; temperatureAccess switchSite team and facilities, alwaysname, address, site, uplink

Notice how few variables each role needs, and how consistently the same five or six appear. That is what makes a single inventory export able to feed every template.


An illustrative template


Here is an access-switch template written as a YAML-style document. This is a plain-text format of indented key: value lines that is easy for people to read and for scripts to parse. The exact keys are invented for the example. Your tool's import format will have its own field names, and part of the generator's job is to translate. Placeholders use the ${name} style, which a standard-library template class in most scripting languages understands without any extra tooling.


# roles/access-switch.yaml -- one definition for every access switch
role: access-switch
description: Edge switch serving user ports at a site
variables: [name, address, site, uplink, uplink_port]

device:
  name: ${name}
  address: ${address}
  site: ${site}
  group: switches-${site}
  credential: snmp-readonly-${site}      # looked up by name, never a value
  depends_on: ${uplink}
  checks:
    reachability:
      method: ping
      interval_minutes: 1
      alert_after_failures: 3
    uplink_status:
      method: snmp
      interface: ${uplink_port}
      alert_on: down
    uplink_errors:
      method: snmp
      interface: ${uplink_port}
      warn_errors_per_hour: 50
    cpu_percent:
      method: snmp
      warn: 80
      critical: 95
      sustained_minutes: 10
  alert_routing:
    business_hours: site-${site}-team
    after_hours: network-oncall

Three things to point out. First, the credential is a name, not a community string. The value lives in a secret store and is supplied when the configuration is applied. The template file can be shared, printed, or attached to a ticket without leaking anything. Second, the dependency is expressed as a device name, which is why naming conventions matter so much — more on that shortly. Third, the site code appears inside other names (the group, the credential, the routing target), so one variable drives several settings consistently.


The generator: inventory in, import file out


The generator is a small script. It reads the inventory, one row per device. For each row it opens the template named by the row's role, fills in the variables, and writes the result. In its simplest form it is a loop around a substitution:


import csv
from string import Template
from pathlib import Path

with open("inventory/devices.csv", newline="") as f:
    for row in csv.DictReader(f):
        template = Template(Path("roles/" + row["role"] + ".yaml").read_text())
        rendered = template.substitute(row)        # fails loudly if a variable is missing
        out = Path("build/" + row["name"] + ".yaml")
        out.write_text(rendered)
        print("generated", out)

Fed an inventory like this:


name,role,address,site,uplink,uplink_port
bru-core-01,core-switch,10.20.0.2,bru,bru-rtr-01,Te1/1/1
bru-asw-01,access-switch,10.20.0.11,bru,bru-core-01,Gi1/0/48
bru-asw-02,access-switch,10.20.0.12,bru,bru-core-01,Gi1/0/48
bru-asw-03,access-switch,10.20.0.13,bru,bru-core-01,Gi1/0/48

it produces one complete device definition per row, each identical to the others except for the five facts. The substitute call is deliberately strict. If a row is missing uplink_port, the script stops with an error instead of quietly producing a switch whose uplink check points at nothing. That strictness is a feature. A generator that fills in blanks with defaults is how devices end up half-monitored.


The last step — getting the generated definitions into the monitoring tool — is where products differ, and this guide will not pretend otherwise. Some tools import a CSV of devices with a column per setting. In that case the "template" may simply be a set of default columns the generator fills in. Some have a bulk-add feature that takes a list of addresses and applies a device group's settings. Some expose an API — an application programming interface. This is a way for scripts to talk to the tool directly. For these tools, the generator ends with a call per device. Some accept a file you upload through the console. Check your product's documentation for which of these it offers, and write the last stage of the generator to match. The important design decision is the same regardless: the tool receives what the files say, and the files are the truth.


Tip: generate for a single device first and compare the result, field by field, with a device you configured by hand and trust. Differences are either a bug in the template or a decision that was never written down. Both are worth finding before you generate two hundred devices.


Naming conventions that make templates work


Templates lean on names. The dependency field names a device; the routing target names a group; the credential names a secret. If names are inconsistent, the generator produces definitions that point at things that do not exist. In that case, the tool either rejects them or, worse, accepts them and silently monitors a switch with no dependency and no notification group.


A convention that works well is site-role-number: a short site code, a role abbreviation, and a two-digit sequence. An example is bru-asw-03 for the third access switch at the Brussels office. The name alone then tells you the site, the template, and roughly where the device sits. It sorts sensibly and is easy to type. It survives being read out over the phone. And a script can parse it with a single split on the hyphen. Other conventions are fine. The property that matters is that every name is predictable from facts about the device. That way, a person and a script would produce the same name.


Apply the same discipline to the things names refer to. Site codes are short, unique, and used identically in device names, group names, credential names, and routing targets. Role abbreviations are listed in one place, with one spelling each — not "asw" in some files and "access" in others. Interface names are written exactly as the device reports them over SNMP. A check that asks for an interface by name will not find Gi1/0/48 if the device calls it GigabitEthernet1/0/48. If your monitoring tool matches interfaces by description or index instead, the template should use whichever identifier is stable across reboots and firmware changes.


Finally, make the monitoring name and the real hostname the same thing. When an alert says bru-asw-03 uplink down, the person on call should be able to log into bru-asw-03 without a lookup table. Where the inventory and the device disagree about a name, fix the inventory or the device; do not add a third name in monitoring.


Consistency as the payoff


The benefit that arrives first is speed: a site with nine devices is nine rows and one run of the generator. The benefit that lasts is consistency. Every branch router is monitored the same way. So when one of them pages the on-call person, the alert looks like every other router alert. In that case, the dashboard shows the same metrics, and the runbook applies without a footnote. A new team member learns "how we monitor a firewall" once, not once per firewall.


Consistency also makes auditing trivial. "Are all the file servers watching every volume?" stops being a question that requires opening each device in the console. It is answered by the template, because every file server is the template. "Which devices do not depend on anything?" becomes a search of the inventory for an empty uplink column. Reviewing coverage turns into reviewing a handful of templates plus a spreadsheet, which is a job for an hour rather than a week.


Handling exceptions without hand edits


Real networks have exceptions. The warehouse switch has a long copper run to the core and a permanently non-zero error count. The archive server is supposed to be almost full. One branch router is on a satellite link and pings slowly. The moment you edit those devices by hand in the console, the template stops describing reality. Then the next regeneration overwrites your fix, and you are back to mystery settings. The answer is an override: a small file, per device, that says only what differs and why.


# overrides/bru-asw-03.yaml -- only what differs from the role
reason: Serves the warehouse scanners over a long copper run; errors are expected
ticket: 4512
review_by: next quarterly threshold review
checks:
  uplink_errors:
    warn_errors_per_hour: 500

The generator applies the template first, then merges any override for that device on top. So the override wins for the keys it mentions and the template supplies everything else. The override is committed to the repository like any other file, which means the exception is visible, reviewed, attributed, and explained. Contrast that with a threshold changed in the console by someone who has since left.


Two rules keep overrides honest. First, every override carries a reason and a review date. An exception nobody can explain should be deleted. And an exception that has been true for a year probably belongs in the template or in a new role. Second, count them. If a third of your access switches have overrides, the template is wrong, not the switches. In that case, either the threshold needs to change for everyone or you have two kinds of access switch and need two roles. A short list of overrides is normal; a long one is a template asking to be split.


Rolling it out the first time


Converting an existing, hand-built monitoring setup to templates is a project, but it is a bounded one. A sequence that works:


  • List your roles. Go through the current device list and assign each device a role. Aim for under a dozen roles; a role with one member is usually just a device with an override.
  • Write one template. Start with the role that has the most members and the most obvious standard, typically access switches. Base it on a device you trust.
  • Build the inventory extract. Produce the CSV with the variables for that role only. Fix naming inconsistencies as you go; this is where you discover the switch called "SWITCH-old-do-not-remove."
  • Generate for one device and compare against the hand-built version, field by field. Fix the template, not the output.
  • Generate for one site, import it, and watch the alert volume for a few days. Differences from the old configuration will show up as new or missing alerts.
  • Generate for every device in the role, then repeat for the next role. Servers usually come last because they have the most variety.
  • Retire hand edits. Once a role is templated, the rule is that its devices are changed only through the template, the inventory, or an override. Say so in the team's written standard.

The first template takes the longest, because it forces the decisions that were never made explicitly. Each later role goes faster, and the last few are usually done in an afternoon. When the new branch office opens, it is nine rows and one command. And the second switch's uplink is watched, because the template does not know how to forget it.


Where to go next


Templates turn onboarding from a day of careful clicking into a loop, and the loop is what makes every site look the same. The templates, the inventory extract, the overrides, and the generator all belong in a repository, which is the subject of Version-Controlling Your Checks and Thresholds. Once the generator exists, applying it to an empty monitoring server is most of a rebuild, covered in Reproducible Setups. For the bigger picture and the maturity ladder, the pillar page Monitoring as Code ties the guides together.


Put this into practice with SysPeep Monitor

The template-and-generator pattern is a habit that applies to any monitoring tool. The import step at the end depends on the product, so check the product documentation for its import and backup options. SysPeep Monitor's auto-discovery can populate the inventory your templates read from. The settings a template captures — thresholds, dependencies, and alert rules built to keep noise down — are the settings it uses on each device. The free trial installs on a Windows machine in minutes.

Download Free TrialLearn About SysPeep