Skip to content

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

See: clanService Authoring Guide

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:

[
  "Uncategorized"
]

Declared in: lib/inventory/distributed-service/manifest/default.nix

description

Attribute: manifest.description

A Short description of the module.

Type: string

Default:

"No description"

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:

true

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. 
    {
  instances = {
    <instanceName> = {
      roles = {
        <roleName> = {
          # Per-machine settings
          machines = { <machineName> = { settings = { ... }; }; }; };
          # Per-role settings
          settings = { ... };
      };
    };
  };
}

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:

"Throws: 'The service must define its roles' when not defined"

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: 
      {
    name = "machineName";
    roles = ["client" "server" ... ];
  }

  • roles: Attribute set of all roles of the instance, in the form: 

    roles = {
  client = {
    machines = {
      jon = {
        settings = {
          timeout = 60;
        };
      };
      # ...
    };
    settings = {
      timeout = 30;
    };
  };
  # ...
};

  • settings: The settings of the role, as defined in inventory 

    {
  timeout = 30;
}

  • extendSettings: A function that takes a module and returns a new module with extended settings. 
    extendSettings {
  timeout = mkForce 60;
};
->
{
  timeout = 60;
}

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