Inventory
Inventory is an abstract service layer for consistently configuring distributed services across machine boundaries.
See Inventory API Documentation
This guide will walk you through setting up a backup-service, where the inventory becomes useful.
Prerequisites Meta (optional)
Metadata about the clan, will be displayed upfront in the upcomming clan-app, make sure to choose a unique name.
Make sure to set name either via inventory.meta OR via clan.meta.
buildClan {
inventory = {
meta = {
name = "Superclan"
description = "Awesome backups and family stuff"
};
};
}
How to add machines
Machines can be added via inventory.machines OR via buildClan directly.
Note
It doesn't matter where the machine gets introduced to buildClan - All delarations are valid, duplications are merged.
However the clan-app (UI) will create machines in the inventory, because it cannot create arbitrary nix code or nixos configs.
In the following example backup_server is one machine - it may specify parts of its configuration in different places.
buildClan {
machines = {
"backup_server" = {
# Any valid nixos config
};
"jon" = {
# Any valid nixos config
};
};
inventory = {
machines = {
"backup_server" = {
# Don't include any nixos config here
# The following fields are avilable
# description: null | string
# icon: null | string
# name: string
# system: null | string
# tags: [...string]
};
"jon" = {
# Same as above
};
};
};
}
Services
Available clanModules
Currently the inventory interface is implemented by the following clanModules
See the respective module documentation for available roles.
Adding services to machines
A module can be added to one or multiple machines via Roles. clan's Role interface provide sane defaults for a module this allows the module author to reduce the configuration overhead to a minimum.
Each service can still be customized and configured according to the modules options.
- Per instance configuration via
services.<serviceName>.<instanceName>.config - Per role configuration via
services.<serviceName>.<instanceName>.roles.<roleName>.config - Per machine configuration via
services.<serviceName>.<instanceName>.machines.<machineName>.config
Setting up the Backup Service
Borgbackup Example
To configure a service it needs to be added to the machine.
It is required to assign the service (borgbackup) an arbitrary instance name. (instance_1)
See also: Multiple Service Instances
buildClan {
inventory = {
machines = {
"backup_server" = {
# Don't include any nixos config here
# See inventory.Machines for available options
};
"jon" = {
# Don't include any nixos config here
# See inventory.Machines for available options
};
};
services = {
borgbackup.instance_1 = {
roles.client.machines = [ "jon" ];
roles.server.machines = [ "backup_server" ];
};
};
};
}
Scalabling the Backup
The inventory allows machines to set Tags
It is possible to add services to multiple machines via tags. The service instance gets added in the specified role. In this case role = "client"
Tags Example
buildClan {
inventory = {
machines = {
"backup_server" = {
# Don't include any nixos config here
# See inventory.Machines for available options
};
"jon" = {
tags = [ "backup" ];
};
"sara" = {
tags = [ "backup" ];
};
};
services = {
borgbackup.instance_1 = {
roles.client.tags = [ "backup" ];
roles.server.machines = [ "backup_server" ];
};
};
};
}
Multiple Service Instances
Important
Not all modules implement support for multiple instances yet. Multiple instance usage could create complexity, refer to each modules documentation, for intended usage.
Example
In this example backup_server has role client and server in different instances.
buildClan {
inventory = {
machines = {
"jon" = {};
"backup_server" = {};
"backup_backup_server" = {}
};
services = {
borgbackup.instance_1 = {
roles.client.machines = [ "jon" ];
roles.server.machines = [ "backup_server" ];
};
borgbackup.instance_1 = {
roles.client.machines = [ "backup_server" ];
roles.server.machines = [ "backup_backup_server" ];
};
};
};
}
API specification
The complete schema specification is available here
Or it can build anytime via: