Topomatik automatically reflects your underlying infrastructure in Kubernetes node topology labels, because manually updating topology is about as fun as untangling holiday lights 🎄
Learn more about topology in Kubernetes:
- [https://kubernetes.io/docs/reference/labels-annotations-taints/#topologykubernetesiozone]
- [https://kubernetes.io/docs/concepts/scheduling-eviction/topology-spread-constraints/]
- Automagically updates the
topology.kubernetes.io/zoneandtopology.kubernetes.io/regionnode labels based on autodiscovered infrastructure - Multiple auto-discovery engines. Currently only LLDP is supported (more coming soon™)
- Works with both virtualised and bare-metal nodes
- Runs as a DaemonSet; updates topology even when nodes are live-migrated
helm install my-release oci://quay.io/enix/charts/topomatikWhen using Flux, you can use this HelmRepository object as repository for all ENIX projects:
apiVersion: source.toolkit.fluxcd.io/v1
kind: HelmRepository
metadata:
name: enix
namespace: default
spec:
interval: 24h
type: oci
url: oci://quay.io/enix/chartsThen, you can create a HelmRelease object pointing to this repository:
apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
name: topomatik
namespace: topomatik
spec:
interval: 1m0s
chart:
spec:
chart: topomatik
sourceRef:
kind: HelmRepository
name: enix
namespace: default
version: 1.*- Refactor discovery engine reconciliation loop #1
- DMI/BIOS discovery engine #2
- Local file / HTTP discovery engine #3
- Hostname / node name discovery engine #4
- Network config discovery engine #5
- Taint management #6
- Prometheus Exporter #7
- Better RBAC / admission webhook #8
Topomatik is configured using a YAML file. Here's an example configuration:
minimumReconciliationInterval: 1s
labelTemplates:
topology.kubernetes.io/zone: "{{ .files.zone }}-{{ .lldp.hostname }}"
topology.kubernetes.io/region: "{{ .files.region }}-{{ .lldp.description | regexp.Find "location: [^ ]" }}
lldp:
enabled: true
interface: auto
files:
zone:
path: /etc/zone
region:
path: /etc/region
interval: 5sThe labelsTemplates section defines which Kubernetes labels Topomatik will manage. Each value is a Go template that will be rendered to determine the label value.
The Sprig library is available for advanced template operations, giving you access to string manipulation, regular expressions, and more.
Each auto-discovery engine has its own configuration section.
All engines share a common enabled key that allows you to enable or disable the engine. The remaining configuration keys are specific to each engine.
Below you'll find detailed information about each supported engine
LLDP (Link Layer Discovery Protocol) is a vendor-neutral Layer 2 protocol that enables network devices to automatically discover and share information about their identity, capabilities, and neighboring devices on a local network.
It can be used in both bare-metal and virtualised environments to inform nodes about the underlying topology (eg: Proxmox PVE). In bare-metal environments, it must be enabled at the network device level (e.g., switches). In virtualised environments, you'll need to install the lldpd service on your hypervisors.
| Name | Description | Default value |
|---|---|---|
| enabled | Enable or disable this auto discovery engine | true |
| interface | Interface name to use for listen to LLDP frames or auto to use any interface with default gateway | auto |
| Name | Description |
|---|---|
| lldp.hostname | The SysName TLV |
| lldp.description | The SysDescription |
Topomatik can be used with Proxmox PVE using the lldpd. Just install it using apt install lldpd. The default configuration should be sufficient to advertise the TLV handled by Topomatik.
Reads the contents of a file. It supports reading files over http(s). It supports either watching or polling files. However, watch is supported for local files only using inotify.
| Name | Description | Default value |
|---|---|---|
| path | Path or url of the file to watch | <required> |
| interval | Use polling instead of watching (using inotify) | <required_for_remote_files> |
Example:
files:
# watching a local file
zone:
path: /etc/zone
# polling a local file
region:
path: /etc/region
interval: 5s
# polling a remote file
rack:
path: http://localhost:8080/rackname
interval: 1m # this is required for remote filesTemplate variables are defined by the name of each file entry in the configuration. For instance, with the above configuration, this engine exposes .files.zone, .files.region and .files.rack.
This engine allows to read information about the hardware (equivalent to dmidecode on Linux, but it also supports MacOS and Windows).
| Name | Description | Default value |
|---|---|---|
| enabled | Enable or disable this auto discovery engine | false |
| interval | Polling interval of the hardware information | <required> |
| Name | Description |
|---|---|
| hardware.chassis_serial | The chassis serial number |
| hardware.chassis_asset_tag | The chassis asset tag |
This engine allows to read the name of the host and parse it using regexps.
Example parsing the hostname EU-R1-42
hostname:
enabled: true
pattern: "(?P<zone>[A-Z]{2})-(?P<region>R[0-9])-(?P<node>[0-9]+)$"| Name | Description | Default value |
|---|---|---|
| enabled | Enable or disable this auto discovery engine | false |
| interval | Polling interval of the hostname information | <required> |
| pattern | Regexp with named groups | - |
Template variables are defined by the name of an file entry in the configuration. For instance, with the above configuration, this engine exposes .hostname.zone, .hostname.region and .hostname.node, but since the pattern in the configuration is optional, it also exposes the whole hostname as .hostname.value.
Found a bug? Want to add support for another discovery engine? We welcome contributions! Just be sure your code is as clean as your commit messages.
Topomatik is open-source software licensed under MIT. Use it, modify it, love it!