Interface for making Services
This document describes the structure and configurable attributes of a clan.service
module.
Typically needed by module authors to define roles, behavior and metadata for distributed services.
Note
This is not a user-facing documentation, but rather meant as a reference for module authors
manifest
Attribute: manifest
Meta information about this module itself
Type: submodule
Declared in: lib/inventory/distributed-service/service-module.nix
categories
Attribute: manifest.categories
Categories are used for Grouping and searching.
While initial oriented on freedesktop the following categories are allowed
Type: list of (one of "AudioVideo", "Audio", "Video", "Development", "Education", "Game", "Graphics", "Social", "Network", "Office", "Science", "System", "Settings", "Utility", "Uncategorized")
Default:
Declared in: lib/inventory/distributed-service/manifest/default.nix
description
Attribute: manifest.description
A Short description of the module.
Type: string
Default:
Declared in: lib/inventory/distributed-service/manifest/default.nix
features
Attribute: manifest.features
Enable built-in features for the module
See the documentation for each feature: - API
Type: submodule
Default:
Declared in: lib/inventory/distributed-service/manifest/default.nix
API
Attribute: manifest.features.API
Readonly
Enables automatic API schema conversion for the interface of this module.
Type: boolean
Default:
Declared in: lib/inventory/distributed-service/manifest/default.nix
name
Attribute: manifest.name
The name of the module
Mainly used to create an error context while evaluating. This helps backtracking which module was included; And where an error came from originally.
Type: string
Declared in: lib/inventory/distributed-service/manifest/default.nix
readme
Attribute: manifest.readme
Extended usage description
Type: string
Default:
Declared in: lib/inventory/distributed-service/manifest/default.nix
perMachine
Attribute: perMachine
Per-machine configuration of the service.
This option is used to define machine-specific settings for the service once, if any service-instance is used.
Although the type is a deferredModule
, it helps to think of it as a function.
The 'function' takes the machine-name
and some other 'arguments'
Arguments:
machine
:{ name :: string; roles :: listOf String }
instances
: The scope of the machine, containing all instances and roles that the machine is part of.
Returns an attribute set
containing:
nixosModule
: The NixOS module for the machine.
Type: module
Default:
Declared in: lib/inventory/distributed-service/service-module.nix
nixosModule
Attribute: perMachine.nixosModule
A single NixOS module for the machine.
This module is later imported to configure the machine with the config derived from service's settings.
Example:
# ↓ machine.roles ...
perMachine = { machine, ... }:
{ # ↓ nixos-config
nixosModule = { config ,... }: {
systemd.services.foo = {
enable = true;
};
}
}
Type: module
Default:
Declared in: lib/inventory/distributed-service/service-module.nix
roles
Attribute: roles
Roles of the service.
A role is a specific behavior or configuration of the service. It defines how the service should behave in the context of the clan.
The <roleName>
s of the service are defined here. Later usage of the roles must match one of the roleNames
.
For example:
- 'roles.client = ...' for a client role that connects to the service
- 'roles.server = ...' for a server role that provides the service
Throws an error if empty, since this would mean that the service has no way of adding members.
Type: attribute set of (submodule)
Default:
Declared in: lib/inventory/distributed-service/service-module.nix
interface
Attribute: roles.<roleName>.interface
Abstract interface of the role.
This is an abstract module which should define 'options' for the role's settings.
Example:
{
options.timeout = mkOption {
type = types.int;
default = 30;
description = "Timeout in seconds";
};
}
Note:
machine.config
is not available here, since the role is definition is abstract.- defaults that depend on the machine or instance should be added to settings later in 'perInstance' or 'perMachine'
Type: module
Default:
Declared in: lib/inventory/distributed-service/service-module.nix
perInstance
Attribute: roles.<roleName>.perInstance
Per-instance configuration of the role.
This option is used to define instance-specific behavior for the service-role. (Example below)
Although the type is a deferredModule
, it helps to think of it as a function.
The 'function' takes the instance-name
and some other arguments
.
Arguments:
instanceName
(string
): The name of the instance.machine
: Machine information, containing:-
roles
: Attribute set of all roles of the instance, in the form: -
settings
: The settings of the role, as defined ininventory
extendSettings
: A function that takes a module and returns a new module with extended settings.
Returns an attribute set
containing:
nixosModule
: The NixOS module for the instance.
Type: module
Default:
Declared in: lib/inventory/distributed-service/service-module.nix
nixosModule
Attribute: roles.<roleName>.perInstance.nixosModule
This module is later imported to configure the machine with the config derived from service's settings.
Example:
roles.client.perInstance = { instanceName, ... }:
{
# Keep in mind that this module is produced once per-instance
# Meaning you might end up with multiple of these modules.
# Make sure they can be imported all together without conflicts
#
# ↓ nixos-config
nixosModule = { config ,... }: {
# create one systemd service per instance
# It is a common practice to concatenate the *service-name* and *instance-name*
# To ensure globally unique systemd-units for the target machine
systemd.services."webly-${instanceName}" = {
...
};
};
}
Type: module
Default:
Declared in: lib/inventory/distributed-service/service-module.nix