yadunut/clan-core
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

lib/modules: move modules out of lib

Browse Source
This commit is contained in:
Johannes Kirschbauer
2025-10-21 19:35:50 +02:00
parent 0d088cac7e
commit 346e3d816a
42 changed files with 5 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
modules/clan/computed-tags.nix Normal file
View File

@@ -0,0 +1,23 @@
{
lib,
...
}:
{
# Add the computed tags to machine tags for displaying them
inventory = {
tags = (
{ machines, ... }:
{
# Only compute the default value
# The option MUST be defined in inventoryClass/interface.nix
all = lib.mkDefault (builtins.attrNames machines);
nixos = lib.mkDefault (
builtins.attrNames (lib.filterAttrs (_n: m: m.machineClass == "nixos") machines)
);
darwin = lib.mkDefault (
builtins.attrNames (lib.filterAttrs (_n: m: m.machineClass == "darwin") machines)
);
}
);
};
}

12
modules/clan/default.nix Normal file
View File

@@ -0,0 +1,12 @@
{ clan-core }:
{
_class = "clan";
_module.args = {
inherit clan-core;
inherit (clan-core) clanLib;
};
imports = [
./module.nix
./interface.nix
];
}

4
modules/clan/flake-module.nix Normal file
View File

@@ -0,0 +1,4 @@
{ self, lib, ... }:
{
flake.modules.clan.default = lib.modules.importApply ./default.nix { clan-core = self; };
}

391
modules/clan/interface.nix Normal file
View File

@@ -0,0 +1,391 @@
{
lib,
clanLib,
self,
config,
# TODO: Use dependency injection to allow for testing
# inventoryInterface,
...
}:
let
types = lib.types;
checkType = types.attrsOf (
types.submodule {
# Skip entire evaluation of this check
options.ignore = lib.mkOption {
type = types.bool;
default = false;
description = "Ignores this check entirely";
};
# Can only be defined once
options.assertion = lib.mkOption {
type = types.bool;
readOnly = true;
description = ''
The assertion that must hold true.
If false, the message is shown.
'';
};
# Message shown when the assertion is false
options.message = lib.mkOption {
type = types.str;
description = "Message shown when the assertion is false";
};
# TODO: add severity levels?
# Fail, Warn, Log
}
);
in
{
options = {
_prefix = lib.mkOption {
type = types.listOf types.str;
internal = true;
visible = false;
default = [ ];
};
# id :: { assertion, message }
checks = lib.mkOption {
type = checkType;
default = { };
description = ''
Assertions that must hold true when evaluating the clan.
When the assertion fails, the message is shown and the evaluation is aborted.
'';
};
self = lib.mkOption {
type = types.raw;
default = self;
defaultText = "Reference to the current flake";
description = ''
This is used to import external clan modules.
'';
# Workaround for lib.clan
apply =
s:
if lib.isAttrs s then
s
// {
inputs = (s.inputs or { }) // {
self.clan = config;
};
}
else
s;
};
directory = lib.mkOption {
type = types.coercedTo lib.types.raw (
v:
if lib.isAttrs v then
lib.warn "It appears you set 'clan.directory = self'. Instead set 'clan.self = self'. 'clan.directory' expects a path" v
else if v == null then
throw "Please set either clan.self or clan.directory"
else
v
) lib.types.path;
default = builtins.toString self;
defaultText = "Root directory of the flake";
description = ''
The directory containing the clan.
A typical directory structure could look like this:
```
.
├── flake.nix
├── assets
├── machines
├── modules
└── sops
```
'';
};
# TODO: make this writable by moving the options from inventoryClass into clan.
exports = lib.mkOption {
readOnly = true;
visible = false;
internal = true;
};
exportsModule = lib.mkOption {
internal = true;
visible = false;
type = types.deferredModule;
default = {
options.networking = lib.mkOption {
default = null;
type = lib.types.nullOr (
lib.types.submodule {
options = {
priority = lib.mkOption {
type = lib.types.int;
default = 1000;
description = ''
priority with which this network should be tried.
higher priority means it gets used earlier in the chain
'';
};
module = lib.mkOption {
# type = lib.types.enum [
# "clan_lib.network.direct"
# "clan_lib.network.tor"
# ];
type = lib.types.str;
default = "clan_lib.network.direct";
description = ''
the technology this network uses to connect to the target
This is used for userspace networking with socks proxies.
'';
};
# should we call this machines? hosts?
peers = lib.mkOption {
# <name>
type = lib.types.attrsOf (
lib.types.submodule (
{ name, ... }:
{
options = {
name = lib.mkOption {
type = lib.types.str;
default = name;
};
SSHOptions = lib.mkOption {
type = lib.types.listOf lib.types.str;
default = [ ];
};
host = lib.mkOption {
description = '''';
type = lib.types.attrTag {
plain = lib.mkOption {
type = lib.types.str;
description = ''
a plain value, which can be read directly from the config
'';
};
var = lib.mkOption {
type = lib.types.submodule {
options = {
machine = lib.mkOption {
type = lib.types.str;
example = "jon";
};
generator = lib.mkOption {
type = lib.types.str;
example = "tor-ssh";
};
file = lib.mkOption {
type = lib.types.str;
example = "hostname";
};
};
};
};
};
};
};
}
)
);
};
};
}
);
};
};
description = ''
A module that is used to define the module of flake level exports -
such as 'exports.machines.<name>' and 'exports.instances.<name>'
Example:
```nix
{
options.vars.generators = lib.mkOption {
type = lib.types.attrsOf (
lib.types.submoduleWith {
modules = [
{
options.script = lib.mkOption { type = lib.types.str; };
}
];
}
);
default = { };
};
}
```
'';
};
specialArgs = lib.mkOption {
type = types.attrsOf types.raw;
default = { };
description = "Extra arguments to pass to nixosSystem i.e. useful to make self available";
};
# Optional
machines = lib.mkOption {
type = types.attrsOf types.deferredModule;
default = { };
description = ''
A mapping of machine names to their nixos configuration.
???+ example
```nix
machines = {
my-machine = {
# Your nixos configuration
};
};
```
'';
};
modules = lib.mkOption {
# Correct type would be `types.attrsOf types.deferredModule` but that allows for
# Merging and transforms the value, which add eval overhead.
type = types.attrsOf types.raw;
default = { };
description = ''
An attribute set of exported modules.
'';
};
templates = lib.mkOption {
type = types.submodule { imports = [ ./templates.nix ]; };
default = { };
description = ''
Define Clan templates.
'';
};
inventory = lib.mkOption {
type = types.submoduleWith {
modules = [
clanLib.inventory.inventoryModule
];
};
description = ''
The `Inventory` submodule.
For details see the [Inventory](/reference/options/clan_inventory.md) documentation.
'';
};
# Meta
meta = lib.mkOption {
description = ''
Global information about the clan.
'';
type = types.deferredModuleWith {
staticModules = [ ../inventoryClass/meta-interface.nix ];
};
default = { };
};
secrets = lib.mkOption {
type = types.submodule { imports = [ ./secrets.nix ]; };
description = ''
Secrets related options such as AGE plugins required to encrypt/decrypt secrets using the CLI.
'';
default = { };
};
pkgsForSystem = lib.mkOption {
type = types.functionTo (types.nullOr types.attrs);
default = _system: null;
defaultText = "system: null";
description = ''
A function that maps from architecture to pkg. `( string -> pkgs )`
If specified this nixpkgs will be only imported once for each system.
This improves performance, but all `nixpkgs.*` options will be ignored.
Returning `null` for a system will fallback to the default behavior of respecting the `nixpkgs.*` options.
'';
};
# Outputs
darwinConfigurations = lib.mkOption {
# Hide from documentation.
# Exposed at the top-level of the flake, clan.darwinConfigurations should not used by the user.
# Instead, the user should use the `.#darwinConfigurations` attribute of the flake output.
visible = false;
type = types.lazyAttrsOf types.raw;
default = { };
};
nixosConfigurations = lib.mkOption {
# Hide from documentation.
# Exposed at the top-level of the flake, clan.nixosConfigurations should not used by the user.
# Instead, the user should use the `.#nixosConfigurations` attribute of the flake output.
visible = false;
type = types.lazyAttrsOf types.raw;
default = { };
};
nixosModules = lib.mkOption {
# Hide from documentation.
# Exposed at the top-level of the flake, clan.nixosModules should not used by the user.
# Instead, the user should use the `.#nixosModules` attribute of the flake output.
visible = false;
type = types.lazyAttrsOf types.raw;
default = { };
description = ''
NixOS modules that are generated by clan.
These are used to generate the `nixosConfigurations`.
'';
};
darwinModules = lib.mkOption {
# Hide from documentation.
# Exposed at the top-level of the flake, clan.darwinModules should not used by the user.
# Instead, the user should use the `.#darwinModules` attribute of the flake output.
visible = false;
type = types.lazyAttrsOf types.raw;
default = { };
description = ''
Darwin modules that are generated by clan.
These are used to generate the `darwinConfigurations`.
'';
};
# flake.clanInternals
clanInternals = lib.mkOption {
# Hide from documentation. Exposes internals to the cli.
visible = false;
# ClanInternals
type = types.submodule {
# Uncomment this if you want to add more stuff while debugging
# freeformType = types.attrsOf types.raw;
options = {
# Those options are interfaced by the CLI
# We don't specify the type here, for better performance.
# The machine 'imports' generated by the inventory per machine
inventoryClass = lib.mkOption {
type = types.submoduleWith {
modules = [ ];
};
};
secrets = lib.mkOption { type = lib.types.raw; };
templates = lib.mkOption { type = lib.types.raw; };
machines = lib.mkOption { type = lib.types.raw; };
};
};
};
};
}

271
modules/clan/module.nix Normal file
View File

@@ -0,0 +1,271 @@
{
config,
clan-core,
nixpkgs,
nix-darwin,
lib,
...
}:
let
inherit (lib)
mapAttrs'
;
inherit (config)
directory
inventory
pkgsForSystem
specialArgs
;
supportedSystems = [
"x86_64-linux"
"aarch64-linux"
"riscv64-linux"
"x86_64-darwin"
"aarch64-darwin"
];
/*
An attrset with nixpkgs instantiated for each platform.
This is important, as:
1. We don't want to call `pkgsForSystem system` multiple times
2. We need to fall back to `nixpkgs.legacyPackages.${system}` in case pkgsForSystem returns null
*/
pkgsFor = lib.genAttrs supportedSystems (
system:
let
pkgs = pkgsForSystem system;
in
if pkgs != null then pkgs else nixpkgs.legacyPackages.${system}
);
inherit (clan-core) clanLib;
moduleSystemConstructor = {
# TODO: remove default system once we have a hardware-config mechanism
nixos = nixpkgs.lib.nixosSystem;
darwin = nix-darwin.lib.darwinSystem;
};
allMachines = config.clanInternals.inventoryClass.machines; # <- inventory.machines <- clan.machines
machineClasses = lib.mapAttrs (name: _: inventory.machines.${name}.machineClass) allMachines;
configurations = lib.mapAttrs (
name: _:
moduleSystemConstructor.${machineClasses.${name}} {
# ATTENTION!: Dont add any modules here.
# Add them to 'outputs.moduleForMachine.${name}' instead.
modules = [ (config.outputs.moduleForMachine.${name} or { }) ];
specialArgs = {
inherit clan-core;
}
// specialArgs;
}
) allMachines;
# Expose reusable modules these can be imported or wrapped or instantiated
# - by the user
# - by some test frameworks
# IMPORTANT!: It is utterly important that we don't add any logic outside of these modules, as it would get tested.
nixosModules' = lib.filterAttrs (name: _: inventory.machines.${name}.machineClass == "nixos") (
config.outputs.moduleForMachine
);
darwinModules' = lib.filterAttrs (name: _: inventory.machines.${name}.machineClass == "darwin") (
config.outputs.moduleForMachine
);
nixosModules = mapAttrs' (name: machineModule: {
name = "clan-machine-${name}";
value = machineModule;
}) nixosModules';
darwinModules = mapAttrs' (name: machineModule: {
name = "clan-machine-${name}";
value = machineModule;
}) darwinModules';
nixosConfigurations = lib.filterAttrs (name: _: machineClasses.${name} == "nixos") configurations;
darwinConfigurations = lib.filterAttrs (name: _: machineClasses.${name} == "darwin") configurations;
# This instantiates NixOS for each system that we support:
# configPerSystem = <system>.<machine>.nixosConfiguration
# We need this to build nixos secret generators for each system
configsPerSystem = builtins.listToAttrs (
builtins.map (
system:
lib.nameValuePair system (
lib.mapAttrs (
_: machine:
machine.extendModules {
modules = [
(lib.modules.importApply ../machineModules/overridePkgs.nix {
pkgs = pkgsFor.${system};
})
];
}
) configurations
)
) supportedSystems
);
in
{
imports = [
(
{ ... }:
let
file = "${directory}/inventory.json";
inventoryLoaded =
if builtins.pathExists file then (builtins.fromJSON (builtins.readFile file)) else { };
in
{
imports = [
{
inventory._inventoryFile = file;
}
];
# Weirdly this works only if it is a function
# This seems to be a bug in nixpkgs
inventory = _: lib.setDefaultModuleLocation file inventoryLoaded;
}
)
{
# Note: we use clanLib.fs here, so that we can override it in tests
inventory = lib.optionalAttrs (clanLib.fs.pathExists "${directory}/machines") ({
imports = lib.mapAttrsToList (name: _t: {
_file = "${directory}/machines/${name}";
machines.${name} = { };
}) ((lib.filterAttrs (_: t: t == "directory") (clanLib.fs.readDir "${directory}/machines")));
});
}
{
inventory.machines = lib.mapAttrs (_n: _: { }) config.machines;
}
# config.inventory.meta <- config.meta
# Set default for computed tags
./computed-tags.nix
];
options.outputs.moduleForMachine = lib.mkOption {
type = lib.types.attrsOf lib.types.deferredModule;
};
config = {
inventory.meta = config.meta;
outputs.moduleForMachine = lib.mkMerge [
# Create some modules for each machine
# These can depend on the 'name' and
# everything that can be derived from the machine 'name'
# i.e. by looking up the corresponding information in the 'inventory' or 'clan' submodule
(lib.mapAttrs (
name: v:
(
{ ... }@args:
let
_class =
args._class or (throw ''
Your version of nixpkgs is incompatible with the latest clan.
Please update nixpkgs input to the latest nixos-unstable or nixpkgs-unstable.
Run:
nix flake update nixpkgs
'');
in
{
imports = [
(lib.modules.importApply ../machineModules/forName.nix {
inherit (config.inventory) meta;
inherit
name
directory
;
})
# Import the correct 'core' module
# We assume either:
# - nixosModules (_class = nixos)
# - darwinModules (_class = darwin)
(lib.optionalAttrs (clan-core ? "${_class}Modules") clan-core."${_class}Modules".clanCore)
]
++ lib.optionals (_class == "nixos") (v.machineImports or [ ]);
# default hostname
networking.hostName = lib.mkDefault name;
}
)
) config.clanInternals.inventoryClass.machines)
# The user can define some machine config here
# i.e. 'clan.machines.jon = ...'
config.machines
];
specialArgs = {
self = lib.mkDefault config.self;
};
# expose all machines as modules for re-use
inherit nixosModules;
inherit darwinModules;
# Ready to use configurations
# These are only shallow wrapping the 'nixosModules' or 'darwinModules' with
# lib.nixosSystem
inherit nixosConfigurations;
inherit darwinConfigurations;
exports = config.clanInternals.inventoryClass.distributedServices.servicesEval.config.exports;
clanInternals = {
inventoryClass =
let
flakeInputs = config.self.inputs;
in
{
_module.args = {
inherit clanLib;
};
imports = [
../inventoryClass/builder/default.nix
(lib.modules.importApply ../inventoryClass/service-list-from-inputs.nix {
inherit flakeInputs clanLib;
})
{
inherit inventory directory;
}
(
let
clanConfig = config;
in
{ config, ... }:
{
staticModules = clan-core.clan.modules;
distributedServices = clanLib.inventory.mapInstances {
inherit (clanConfig) inventory exportsModule;
inherit flakeInputs directory;
clanCoreModules = clan-core.clan.modules;
prefix = [ "distributedServices" ];
};
machines = config.distributedServices.allMachines;
}
)
../inventoryClass/inventory-introspection.nix
];
};
# TODO: unify this interface
# We should have only clan.modules. (consistent with clan.templates)
# Statically export the predefined clan modules
templates = clan-core.clan.templates;
secrets = config.secrets;
# machine specifics
machines = configsPerSystem;
};
};
}

18
modules/clan/secrets.nix Normal file
View File

@@ -0,0 +1,18 @@
{
lib,
...
}:
let
inherit (lib) types;
in
{
options = {
age.plugins = lib.mkOption {
type = types.listOf (types.strMatching "age-plugin-.*");
default = [ ];
description = ''
A list of age plugins which must be available in the shell when encrypting and decrypting secrets.
'';
};
};
}

57
modules/clan/templates.nix Normal file
View File

@@ -0,0 +1,57 @@
{
lib,
...
}:
let
inherit (lib) types;
templateType = types.submodule (
{ name, ... }:
{
options.description = lib.mkOption {
type = types.str;
default = name;
description = ''
The name of the template.
'';
};
options.path = lib.mkOption {
type = types.path;
description = ''
Holds the path to the clan template.
'';
};
}
);
in
{
options = {
# clan.templates.clan
clan = lib.mkOption {
type = types.attrsOf templateType;
default = { };
description = ''
Holds the different clan templates.
'';
};
# clan.templates.disko
disko = lib.mkOption {
type = types.attrsOf templateType;
default = { };
description = ''
Holds different disko templates.
'';
};
# clan.templates.machine
machine = lib.mkOption {
type = types.attrsOf templateType;
default = { };
description = ''
Holds the different machine templates.
'';
};
};
}

108
modules/dir_test.nix Normal file
View File

@@ -0,0 +1,108 @@
{
lib ? import <nixpkgs/lib>,
}:
let
clanLibOrig = (import ./.. { inherit lib; }).__unfix__;
clanLibWithFs =
{ virtual_fs }:
lib.fix (
lib.extends (
final: _:
let
clan-core = {
clanLib = final;
modules.clan.default = lib.modules.importApply ./clan { inherit clan-core; };
# Note: Can add other things to "clan-core"
# ... Not needed for this test
};
in
{
clan = import ../clan {
inherit lib clan-core;
};
# Override clanLib.fs for unit-testing against a virtual filesystem
fs = import ../clanTest/virtual-fs.nix { inherit lib; } {
inherit rootPath virtual_fs;
# Example of a passthru
# passthru = [
# ".*inventory\.json$"
# ];
};
}
) clanLibOrig
);
rootPath = ./.;
in
{
test_autoload_directories =
let
vclan =
(clanLibWithFs {
virtual_fs = {
"machines" = {
type = "directory";
};
"machines/foo-machine" = {
type = "directory";
};
"machines/bar-machine" = {
type = "directory";
};
};
}).clan
{ config.directory = rootPath; };
in
{
inherit vclan;
expr = {
machines = lib.attrNames vclan.config.inventory.machines;
definedInMachinesDir = map (
p: lib.hasInfix "/machines/" p
) vclan.options.inventory.valueMeta.configuration.options.machines.files;
};
expected = {
machines = [
"bar-machine"
"foo-machine"
];
definedInMachinesDir = [
true # /machines/foo-machine
true # /machines/bar-machine
false # <clan-core>/module.nix defines "machines" without members
];
};
};
# Could probably be unified with the previous test
# This is here for the sake to show that 'virtual_fs' is a test parameter
test_files_are_not_machines =
let
vclan =
(clanLibWithFs {
virtual_fs = {
"machines" = {
type = "directory";
};
"machines/foo.nix" = {
type = "file";
};
"machines/bar.nix" = {
type = "file";
};
};
}).clan
{ config.directory = rootPath; };
in
{
inherit vclan;
expr = {
machines = lib.attrNames vclan.config.inventory.machines;
};
expected = {
machines = [ ];
};
};
}

22
modules/eval-docs.nix Normal file
View File

@@ -0,0 +1,22 @@
{
pkgs,
lib,
clan-core,
}:
let
eval = lib.evalModules {
modules = [
clan-core.modules.clan.default
];
};
evalDocs = pkgs.nixosOptionsDoc {
options = eval.options;
warningsAreErrors = false;
transformOptions = clan-core.clanLib.docs.stripStorePathsFromDeclarations;
};
in
{
inherit (evalDocs) optionsJSON optionsNix;
inherit eval;
}

58
modules/flake-module.nix Normal file
View File

@@ -0,0 +1,58 @@
{
self,
inputs,
...
}:
let
inputOverrides = self.clanLib.flake-inputs.getOverrides inputs;
in
{
imports = [
./clan/flake-module.nix
];
perSystem =
{
pkgs,
lib,
system,
...
}:
let
jsonDocs = import ./eval-docs.nix {
inherit pkgs lib;
clan-core = self;
};
in
{
legacyPackages.clan-options = jsonDocs.optionsJSON;
# Run: nix-unit --extra-experimental-features flakes --flake .#legacyPackages.x86_64-linux.evalTests-build-clan
legacyPackages.evalTests-build-clan = import ./tests.nix {
inherit lib;
clan-core = self;
};
checks = {
eval-lib-build-clan = pkgs.runCommand "tests" { nativeBuildInputs = [ pkgs.nix-unit ]; } ''
export HOME="$(realpath .)"
nix-unit --eval-store "$HOME" \
--extra-experimental-features flakes \
--show-trace \
${inputOverrides} \
--flake ${
self.filter {
include = [
"flakeModules"
"inventory.json"
"lib"
"machines"
"nixosModules"
];
}
}#legacyPackages.${system}.evalTests-build-clan
touch $out
'';
};
};
}

5
modules/inventoryClass/builder/default.nix Normal file
View File

@@ -0,0 +1,5 @@
{
imports = [
./interface.nix
];
}

28
modules/inventoryClass/builder/interface.nix Normal file
View File

@@ -0,0 +1,28 @@
{ lib, ... }:
let
inherit (lib) types mkOption;
submodule = m: types.submoduleWith { modules = [ m ]; };
in
{
options = {
directory = mkOption {
type = types.path;
};
distributedServices = mkOption {
type = types.raw;
};
inventory = mkOption {
type = types.raw;
};
machines = mkOption {
type = types.attrsOf (submodule ({
options = {
machineImports = mkOption {
type = types.listOf types.raw;
};
};
}));
};
};
}

20
modules/inventoryClass/inventory-introspection.nix Normal file
View File

@@ -0,0 +1,20 @@
{
config,
lib,
clanLib,
...
}:
{
options.introspection = lib.mkOption {
readOnly = true;
# TODO: use options.inventory instead of the evaluate config attribute
default =
builtins.removeAttrs (clanLib.introspection.getPrios { options = config.inventory.options; })
# tags are freeformType which is not supported yet.
# services is removed and throws an error if accessed.
[
"tags"
"services"
];
};
}

376
modules/inventoryClass/inventory.nix Normal file
View File

@@ -0,0 +1,376 @@
# This module describes
# - clanInternals.inventoryClass.inventory
# - clan.inventory
# Which is the public interface for the inventory system
{
lib,
clanLib,
config,
options,
...
}:
let
types = lib.types;
metaOptionsWith = name: {
name = lib.mkOption {
type = types.str;
default = name;
description = ''
Name of the machine or service
'';
};
description = lib.mkOption {
default = null;
type = types.nullOr types.str;
description = ''
Optional freeform description
'';
};
icon = lib.mkOption {
default = null;
type = types.nullOr types.str;
description = ''
Under construction, will be used for the UI
'';
};
};
in
{
imports = [
(lib.mkRemovedOptionModule [ "services" ] ''
The `inventory.services` option has been removed. Use `inventory.instances` instead.
See: https://docs.clan.lol/concepts/inventory/#services
'')
];
options = {
# Internal things
_inventoryFile = lib.mkOption {
type = types.path;
readOnly = true;
internal = true;
visible = false;
};
noInstanceOptions = lib.mkOption {
type = types.bool;
internal = true;
visible = false;
default = false;
};
options = lib.mkOption {
internal = true;
visible = false;
type = types.raw;
default = options;
};
# ---------------------------
modules = lib.mkOption {
# Don't define the type yet
# We manually transform the value with types.deferredModule.merge later to keep them serializable
type = types.attrsOf types.raw;
default = { };
defaultText = "clanModules of clan-core";
description = ''
A mapping of module names to their path.
Each module can be referenced by its `attributeName` in the `inventory.services` attribute set.
!!! Important
Each module MUST fulfill the following requirements to be usable with the inventory:
- The module MUST have a `README.md` file with a `description`.
- The module MUST have at least `features = [ "inventory" ]` in the frontmatter section.
- The module MUST have a subfolder `roles` with at least one `{roleName}.nix` file.
For further information see: [Module Authoring Guide](../../guides/services/community.md).
???+ example
```nix
clan-core.lib.clan {
# 1. Add the module to the available inventory modules
inventory.modules = {
custom-module = ./modules/my_module;
};
# 2. Use the module in the inventory
inventory.services = {
custom-module.instance_1 = {
roles.default.machines = [ "machineA" ];
};
};
};
```
'';
apply = _: { };
};
assertions = lib.mkOption {
type = types.listOf types.unspecified;
internal = true;
visible = false;
default = [ ];
};
meta = lib.mkOption {
type = lib.types.submoduleWith {
modules = [
./meta-interface.nix
];
};
};
tags = lib.mkOption {
default = { };
description = ''
Tags of the inventory are used to group machines together.
It is recommended to use [`machine.tags`](#inventory.machines.tags) to define the tags of the machines.
This can be used to define custom tags that are either statically set or dynamically computed.
#### Static Tags
???+ example "Static Tag Example"
```nix
inventory.tags = {
foo = [ "machineA" "machineB" ];
};
```
The tag `foo` will always be added to `machineA` and `machineB`.
#### Dynamic Tags
It is possible to compute tags based on the machines properties or based on other tags.
!!! danger
This is a powerful feature and should be used with caution.
It is possible to cause infinite recursion by computing tags based on the machines properties or based on other tags.
???+ example "Dynamic Tag Example"
allButFoo is a computed tag. It will be added to all machines except 'foo'
`all` is a predefined tag. See the docs of [`tags.all`](#inventory.tags.all).
```nix
# inventory.tags ↓ ↓ inventory.machines
inventory.tags = {config, machines...}: {
# ↓↓↓ The "all" tag
allButFoo = builtins.filter (name: name != "foo") config.all;
};
```
!!! warning
Do NOT compute `tags` from `machine.tags` this will cause infinite recursion.
'';
type = types.submoduleWith {
specialArgs = {
inherit (config) machines;
};
modules = [
{
freeformType = with lib.types; lazyAttrsOf (listOf str);
# Reserved tags
# Defined as options here to show them in advance
options = {
# 'All machines' tag
all = lib.mkOption {
type = with lib.types; listOf str;
defaultText = "[ <All Machines> ]";
description = ''
!!! example "Predefined Tag"
Will be added to all machines
```nix
inventory.machines.machineA.tags = [ "all" ];
```
'';
};
nixos = lib.mkOption {
type = with lib.types; listOf str;
defaultText = "[ <All NixOS Machines> ]";
description = ''
!!! example "Predefined Tag"
Will be added to all machines that set `machineClass = "nixos"`
```nix
inventory.machines.machineA.tags = [ "nixos" ];
```
'';
};
darwin = lib.mkOption {
type = with lib.types; listOf str;
defaultText = "[ <All Darwin Machines> ]";
description = ''
!!! example "Predefined Tag"
Will be added to all machines that set `machineClass = "darwin"`
```nix
inventory.machines.machineA.tags = [ "darwin" ];
```
'';
};
};
}
];
};
};
machines = lib.mkOption {
description = ''
Machines in the inventory.
Each machine declared here can be referencd via its `attributeName` by the `inventory.service`s `roles`.
'';
default = { };
type = types.lazyAttrsOf (
types.submoduleWith ({
modules = [
(
{ name, ... }:
{
tags = builtins.attrNames (
# config.tags
lib.filterAttrs (_t: tagMembers: builtins.elem name tagMembers) config.tags
);
}
)
(
{ name, ... }:
{
options = {
inherit (metaOptionsWith name) name description icon;
machineClass = lib.mkOption {
default = "nixos";
type = types.enum [
"nixos"
"darwin"
];
description = ''
The module system that should be used to construct the machine
Set this to `darwin` for macOS machines
'';
};
installedAt = lib.mkOption {
type = types.nullOr types.int;
default = null;
description = ''
Indicates when the machine was first installed.
Timestamp is in unix time (seconds since epoch).
'';
};
tags = lib.mkOption {
description = ''
List of tags for the machine.
The machine can be referenced by its tags in `inventory.services`
???+ Example
```nix
inventory.machines.machineA.tags = [ "tag1" "tag2" ];
```
```nix
services.borgbackup."instance_1".roles.client.tags = [ "tag1" ];
```
!!! Note
Tags can be used to determine the membership of the machine in the services.
Without changing the service configuration, the machine can be added to a service by adding the correct tags to the machine.
'';
default = [ ];
apply = lib.unique;
type = types.listOf types.str;
};
deploy.targetHost = lib.mkOption {
description = "SSH address of the host to deploy the machine to";
default = null;
type = types.nullOr types.str;
};
deploy.buildHost = lib.mkOption {
description = "SSH address of the host to build the machine on";
default = null;
type = types.nullOr types.str;
};
};
}
)
];
})
);
};
instances =
if config.noInstanceOptions then
{ }
else
lib.mkOption {
description = "Multi host service module instances";
type = types.attrsOf (
types.submoduleWith {
modules = [
(
{ name, ... }:
{
options = {
# ModuleSpec
module = lib.mkOption {
default = { };
type = types.submodule {
options.input = lib.mkOption {
type = types.nullOr types.str;
default = null;
defaultText = "Name of the input. Default to 'null' which means the module is local";
description = ''
Name of the input. Default to 'null' which means the module is local
'';
};
options.name = lib.mkOption {
type = types.str;
default = name;
defaultText = "<Name of the Instance>";
description = ''
Attribute of the clan service module imported from the chosen input.
Defaults to the name of the instance.
'';
};
};
};
roles = lib.mkOption {
default = { };
type = types.attrsOf (
types.submodule {
imports = [
{
_file = "inventory/interface";
_module.args = {
inherit clanLib;
};
}
(import ./roles-interface.nix { })
];
}
);
};
};
}
)
];
}
);
default = { };
};
};
}

38
modules/inventoryClass/meta-interface.nix Normal file
View File

@@ -0,0 +1,38 @@
# This file is imported into:
# - clan.meta
# - clan.inventory.meta
{ lib, ... }:
let
types = lib.types;
metaOptions = {
name = lib.mkOption {
type = types.strMatching "[a-zA-Z0-9_-]*";
example = "my_clan";
description = ''
Name of the clan.
Needs to be (globally) unique, as this determines the folder name where the flake gets downloaded to.
Should only contain alphanumeric characters, `_` and `-`.
'';
};
description = lib.mkOption {
default = null;
type = types.nullOr types.str;
description = ''
Optional freeform description
'';
};
icon = lib.mkOption {
default = null;
type = types.nullOr types.str;
description = ''
Under construction, will be used for the UI
'';
};
};
in
{
options = metaOptions;
}

87
modules/inventoryClass/roles-interface.nix Normal file
View File

@@ -0,0 +1,87 @@
{
settingsOption ? null,
nestedSettingsOption ? null,
}:
{ lib, clanLib, ... }:
let
inherit (lib)
types
;
in
{
options = {
# TODO: deduplicate
machines = lib.mkOption {
type = types.attrsOf (
types.submodule {
options.settings =
if nestedSettingsOption != null then
nestedSettingsOption
else
lib.mkOption {
default = { };
type = clanLib.types.uniqueDeferredSerializableModule;
};
}
);
default = { };
};
tags = lib.mkOption {
type = types.coercedTo (types.listOf types.str) (t: lib.genAttrs t (_: { })) (
types.attrsOf (types.submodule { })
);
default = { };
};
settings =
if settingsOption != null then
settingsOption
else
lib.mkOption {
default = { };
type = clanLib.types.uniqueDeferredSerializableModule;
};
extraModules = lib.mkOption {
description = ''
List of additionally imported `.nix` expressions.
Supported types:
- **Strings**: Interpreted relative to the 'directory' passed to `lib.clan`.
- **Paths**: should be relative to the current file.
- **Any**: Nix expression must be serializable to JSON.
!!! Note
**The import only happens if the machine is part of the service or role.**
Other types are passed through to the nixos configuration.
???+ Example
To import the `special.nix` file
```
. Clan Directory
├── flake.nix
...
└── modules
├── special.nix
└── ...
```
```nix
{
extraModules = [ "modules/special.nix" ];
}
```
'';
apply = value: if lib.isString value then value else builtins.seq (builtins.toJSON value) value;
default = [ ];
type = types.listOf (
types.oneOf [
types.str
types.path
(types.attrsOf types.anything)
]
);
};
};
}

70
modules/inventoryClass/service-list-from-inputs.nix Normal file
View File

@@ -0,0 +1,70 @@
{
flakeInputs,
clanLib,
}:
{ lib, config, ... }:
let
inspectModule =
inputName: moduleName: module:
let
eval = clanLib.evalService {
modules = [ module ];
prefix = [
inputName
"clan"
"modules"
moduleName
];
};
in
{
manifest = eval.config.manifest;
roles = lib.mapAttrs (_n: v: { inherit (v) description; }) eval.config.roles;
};
in
{
options.staticModules = lib.mkOption {
readOnly = true;
type = lib.types.raw;
apply = moduleSet: lib.mapAttrs (inspectModule "<clan-core>") moduleSet;
};
options.modulesPerSource = lib.mkOption {
# { sourceName :: { moduleName :: {} }}
readOnly = true;
type = lib.types.raw;
default =
let
inputsWithModules = lib.filterAttrs (_inputName: v: v ? clan.modules) flakeInputs;
in
lib.mapAttrs (
inputName: v: lib.mapAttrs (inspectModule inputName) v.clan.modules
) inputsWithModules;
};
options.moduleSchemas = lib.mkOption {
# { sourceName :: { moduleName :: { roleName :: Schema }}}
readOnly = true;
type = lib.types.raw;
default = lib.mapAttrs (
_inputName: moduleSet:
lib.mapAttrs (
_moduleName: module:
(clanLib.evalService {
modules = [ module ];
prefix = [ ];
}).config.result.api.schema
) moduleSet
) config.modulesPerSource;
};
options.templatesPerSource = lib.mkOption {
# { sourceName :: { moduleName :: {} }}
readOnly = true;
type = lib.types.raw;
default =
let
inputsWithTemplates = lib.filterAttrs (_inputName: v: v ? clan.templates) flakeInputs;
in
lib.mapAttrs (_inputName: v: lib.mapAttrs (_n: t: t) v.clan.templates) inputsWithTemplates;
};
}

29
modules/machineModules/forName.nix Normal file
View File

@@ -0,0 +1,29 @@
{
name,
directory,
meta,
}:
{
_class,
lib,
...
}:
{
imports = builtins.filter builtins.pathExists (
[
"${directory}/machines/${name}/configuration.nix"
]
++ lib.optionals (_class == "nixos") [
"${directory}/machines/${name}/hardware-configuration.nix"
"${directory}/machines/${name}/disko.nix"
]
);
clan.core.settings = {
inherit (meta) name icon;
inherit directory;
machine = {
inherit name;
};
};
}

17
modules/machineModules/overridePkgs.nix Normal file
View File

@@ -0,0 +1,17 @@
{
pkgs,
}:
{
lib,
...
}:
{
imports = [
{
# For vars we need to ensure that the system so we run vars generate on
# is in sync with the pkgs of the system
nixpkgs.hostPlatform = lib.mkForce pkgs.system;
nixpkgs.pkgs = lib.mkForce pkgs;
}
];
}

232
modules/tests.nix Normal file
View File

@@ -0,0 +1,232 @@
{
lib,
clan-core,
}:
let
# Shallowly force all attribute values to be evaluated.
shallowForceAllAttributes = lib.foldlAttrs (
_acc: _name: value:
lib.seq value true
) true;
inherit (clan-core.clanLib) clan;
in
#######
{
autoloading = import ./dir_test.nix { inherit lib; };
test_missing_self =
let
eval = clan {
meta.name = "test";
directory = ./.;
};
in
{
expr = shallowForceAllAttributes eval.config;
expected = true;
};
test_only_required =
let
eval = clan {
self = {
inputs = { };
outPath = ./.;
};
meta.name = "test";
};
in
{
expr = shallowForceAllAttributes eval.config;
expected = true;
};
test_all_simple =
let
eval = clan {
self = {
inputs = { };
};
directory = ./.;
machines = { };
inventory = {
meta.name = "test";
};
};
in
{
expr = eval.config ? inventory;
expected = true;
};
test_outputs_clanInternals =
let
eval = clan {
self = {
inputs = { };
};
directory = ./.;
imports = [
# What the user needs to specify
{
directory = ./.;
inventory.meta.name = "test";
}
];
};
in
{
inherit eval;
expr = eval.config.clanInternals.inventoryClass.inventory.meta;
expected = {
description = null;
icon = null;
name = "test";
};
};
test_fn_simple =
let
eval = clan {
self = {
inputs = { };
};
directory = ./.;
meta.name = "test";
};
in
{
expr = lib.isAttrs eval.config.clanInternals;
expected = true;
};
test_fn_clan_core =
let
eval = clan {
self = {
inputs = { };
};
directory = ../../.;
meta.name = "test-clan-core";
};
in
{
expr = builtins.attrNames eval.config.nixosConfigurations;
expected = [
"test-backup"
"test-inventory-machine"
];
};
test_machines_are_modules =
let
eval = clan {
self = {
inputs = { };
};
directory = ../../.;
meta.name = "test-clan-core";
};
in
{
expr = builtins.attrNames eval.config.nixosModules;
expected = [
"clan-machine-test-backup"
"clan-machine-test-inventory-machine"
];
};
test_clan_all_machines =
let
eval = clan {
self = {
inputs = { };
};
directory = ./.;
meta.name = "test";
inventory.machines.machine1 = { };
machines.machine2 = { };
};
in
{
expr = builtins.attrNames eval.config.nixosConfigurations;
expected = [
"machine1"
"machine2"
];
};
test_clan_specialArgs =
let
eval = clan {
self = {
inputs = { };
};
directory = ./.;
meta.name = "test";
specialArgs.foo = "dream2nix";
machines.machine2 =
{ foo, ... }:
{
networking.hostName = foo;
nixpkgs.hostPlatform = "x86_64-linux";
};
};
in
{
expr = eval.config.nixosConfigurations.machine2.config.networking.hostName;
expected = "dream2nix";
};
test_clan_darwin_machines =
let
eval = clan {
self = {
inputs = { };
};
directory = ./.;
meta.name = "test";
machines.machine1 = { };
inventory.machines.machine2 = {
machineClass = "darwin";
};
inventory.machines.machine3 = {
machineClass = "nixos";
};
};
in
{
result = eval;
expr = {
nixos = builtins.attrNames eval.config.nixosConfigurations;
darwin = builtins.attrNames eval.config.darwinConfigurations;
};
expected = {
nixos = [
"machine1"
"machine3"
];
darwin = [ "machine2" ];
};
};
test_clan_all_machines_laziness =
let
eval = clan {
self = {
inputs = { };
};
directory = ./.;
meta.name = "test";
machines.machine1.non_existent_option = throw "eval error";
};
in
{
expr = builtins.attrNames eval.config.nixosConfigurations;
expected = [
"machine1"
];
};
}