API

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

exports

Attribute: exports

This services exports. Gets merged with all other services exports.

Exports are used to share and expose information between instances.

Define exports in the perInstance or perMachine scope.

Accessing the exports:

{ exports, ... }: {
  _class = "clan.service";

  # ...
  roles.peer.perInstance = { exports, ...}: { ...};

  # ...
  perMachine = { exports, ...}: { ...};
}

Type: submodule

Default:

{ }

Declared in: lib/modules/inventory/distributed-service/service-module.nix

instances

Attribute: exports.instances

export modules defined in 'perInstance' mapped to their instance name

Example

with instances:

instances.A = { ... };
instances.B= { ... };

roles.peer.perInstance = { instanceName, machine, ... }:
{
  exports.foo = 1;
}

This yields all other services can access these exports
=>
exports.instances.A.foo = 1;
exports.instances.B.foo = 1;

Type: attribute set of module

Declared in: lib/modules/inventory/distributed-service/service-module.nix

machines

Attribute: exports.machines

export modules defined in 'perMachine' mapped to their machine name

Example

with machines:

instances.A = { roles.peer.machines.jon = ... };
instances.B = { roles.peer.machines.jon = ... };

perMachine = { machine, ... }:
{
  exports.foo = 1;
}

This yields all other services can access these exports
=>
exports.machines.jon.foo = 1;
exports.machines.sara.foo = 1;

Type: attribute set of module

Declared in: lib/modules/inventory/distributed-service/service-module.nix

manifest

Attribute: manifest

Meta information about this module itself

Type: submodule

Declared in: lib/modules/inventory/distributed-service/service-module.nix

description

Attribute: manifest.description

A Short description of the module.

Type: string

Default:

"No description"

Declared in: lib/modules/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/modules/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/modules/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/modules/inventory/distributed-service/manifest/default.nix

readme

Attribute: manifest.readme

Extended usage description

Type: string

Default:

""

Declared in: lib/modules/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/modules/inventory/distributed-service/service-module.nix

exports

Attribute: perMachine.exports

export modules defined in 'perMachine' mapped to their machine name

Example

with machines:

instances.A = { roles.peer.machines.jon = ... };
instances.B = { roles.peer.machines.jon = ... };

perMachine = { machine, ... }:
{
  exports.foo = 1;
}

This yields all other services can access these exports
=>
exports.machines.jon.foo = 1;
exports.machines.sara.foo = 1;

Type: module

Default:

{ }

Declared in: lib/modules/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/modules/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/modules/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/modules/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 instances
```
{
  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/modules/inventory/distributed-service/service-module.nix

exports

Attribute: roles.<roleName>.perInstance.exports

export modules defined in 'perInstance' mapped to their instance name

Example

with instances:

instances.A = { ... };
instances.B= { ... };

roles.peer.perInstance = { instanceName, machine, ... }:
{
  exports.foo = 1;
}

This yields all other services can access these exports
=>
exports.instances.A.foo = 1;
exports.instances.B.foo = 1;

Type: module

Default:

{ }

Declared in: lib/modules/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/modules/inventory/distributed-service/service-module.nix

API

exports

instances

machines

manifest

categories

description

features

API

name

readme

perMachine

exports

nixosModule

roles

interface

perInstance

exports

nixosModule