-
Notifications
You must be signed in to change notification settings - Fork 1
Module Development
This page is for writing a module, not for using one. For what modules are for and how a topology loads them, see Module System.
A module lives under mod/<name>/ and is registered in pkg/model/module.go.
It is a Go type embedding types.StandardModule, and what it does is decided by
which interfaces it implements.
A module must supply UpdateConfig, where it registers what it adds to the
configuration — file definitions, classes, format styles, parameter rules. The
rest are optional, and a module implements only the ones it needs. Each runs at
a fixed point while the model is built, which is what decides what it can see.
| Interface | When it runs | What it is for |
|---|---|---|
UpdateConfig (required) |
before the model exists, with the topology's configuration already loaded | register the module's own files, classes and formats. A module can read the topology here — which is how the containerlab module knows whether to write one topology file or one per machine |
ObjectClassifier |
after the topology is built, before class labels are resolved | attach the module's classes to the objects that need them, and reshape the topology if it must. A label attached later would never become a class |
ParameterProvider |
after objects are named, before addresses and param_rule are assigned |
supply parameters that depend on the model — the endpoint names containerlab needs, the collision domain each Kathara interface sits on |
RequirementChecker |
after the model is complete, before files are generated | report what the platform cannot express, in the topology's own words: a device name Kathara rejects, a directory it was not told it owns |
ParameterGenerator |
while param_rules of attach mode are evaluated |
produce the value sets behind a rule the module registered, such as the bind mounts of a node |
The line between a module and a topology is a design rule, not a convention — see Where a module and a topology meet. For a module author it comes to this:
- Publish class names and value names. These are what a topology writes, so they are the module's public surface and have to stay stable
-
Keep block names to yourself. Name them so that nobody is tempted:
_clabNode,_katharaInterface. A topology naming one of a module's blocks is a path that has to keep working forever -
Read the hooks, and add to them when there is something the module has to
do.
startupandteardownare dot2net's, not any module's -
Report what the platform cannot express, in
CheckModuleRequirements, naming the topology's own object. Do not work around it silently: a value a module forces is a value the author cannot see
A class a module registers is weaker than anything the author writes, so a
module's values are defaults and never override a topology. A module that must
force a value should check and report instead — which is why asking Kathara for
an interface prefix other than eth is an error rather than a setting quietly
ignored. See
When several classes apply to one object.
- Module System - Using modules
- Architecture Overview - Where modules sit in the whole
- Development Guide - Building and testing