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

Merge pull request 'Docs: refactor general structure' (#2168) from hsjobeki/clan-core:hsjobeki-docs/inventory into main

Browse Source
This commit is contained in:
clan-bot
2024-09-25 11:52:34 +00:00
parent 728cb60295 96b972d91d
commit 381d5f9f70
18 changed files with 597 additions and 89 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
docs/.gitignore vendored
View File

@@ -1,6 +1,3 @@
/site/reference/clan-core
/site/reference/clanModules
/site/reference/nix-api/inventory.md
/site/reference/cli
/site/reference
/site/static/Roboto-Regular.ttf
/site/static/FiraCode-VF.ttf

10
docs/mkdocs.yml
View File

@@ -40,15 +40,14 @@ exclude_docs: |
nav:
- index.md
- Manual:
- Overview: manual/index.md
- Tutorials:
- Getting Started:
- getting-started/index.md
- Installer: getting-started/installer.md
- Configure: getting-started/configure.md
- Secrets & Facts: getting-started/secrets.md
- Deploy Machine: getting-started/deploy.md
- Guides:
- Overview: manual/index.md
- Disk Encryption: getting-started/disk-encryption.md
- Mesh VPN: getting-started/mesh-vpn.md
- Backup & Restore: getting-started/backups.md
@@ -57,7 +56,11 @@ nav:
- Secrets: manual/secrets.md
- Secure Boot: manual/secure-boot.md
- Flake-parts: manual/flake-parts.md
- Authoring ClanModules:
- clanmodules/index.md
- Contribute: manual/contribute.md
- Concepts:
- Overview: concepts/index.md
- Reference:
- Overview: reference/index.md
- Clan Modules:
@@ -119,7 +122,6 @@ nav:
- reference/clan-core/deployment.md
- reference/clan-core/networking.md
- Nix API:
- reference/nix-api/index.md
- buildClan: reference/nix-api/buildclan.md
- Inventory: reference/nix-api/inventory.md
- Blog:

2
docs/nix/default.nix
View File

@@ -2,7 +2,6 @@
pkgs,
module-docs,
clan-cli-docs,
inventory-api-docs,
asciinema-player-js,
asciinema-player-css,
roboto,
@@ -33,7 +32,6 @@ pkgs.stdenv.mkDerivation {
mkdir -p ./site/reference/cli
cp -af ${module-docs}/* ./site/reference/
cp -af ${clan-cli-docs}/* ./site/reference/cli/
cp -af ${inventory-api-docs} ./site/reference/nix-api/inventory.md
mkdir -p ./site/static/asciinema-player
ln -snf ${asciinema-player-js} ./site/static/asciinema-player/asciinema-player.min.js

4
docs/nix/flake-module.nix
View File

@@ -8,6 +8,7 @@
...
}:
let
buildClanOptions = self'.legacyPackages.clan-internals-docs;
# Simply evaluated options (JSON)
# { clanCore = «derivation JSON»; clanModules = { ${name} = «derivation JSON» }; }
jsonDocs = import ./get-module-docs.nix {
@@ -67,6 +68,9 @@
# A file that contains the links to all clanModule docs
export CLAN_MODULES=${clanModulesFileInfo}
# buildClan options
export BUILD_CLAN_PATH=${buildClanOptions}/share/doc/nixos/options.json
mkdir $out
# The python script will place mkDocs files in the output directory

125
docs/nix/render_options/__init__.py
View File

@@ -35,6 +35,7 @@ from clan_cli.errors import ClanError
CLAN_CORE_PATH = Path(os.environ["CLAN_CORE_PATH"])
CLAN_CORE_DOCS = Path(os.environ["CLAN_CORE_DOCS"])
CLAN_MODULES = os.environ.get("CLAN_MODULES")
BUILD_CLAN_PATH = os.environ.get("BUILD_CLAN_PATH")
OUT = os.environ.get("out")
@@ -74,11 +75,15 @@ def join_lines_with_indentation(lines: list[str], indent: int = 4) -> str:
return "\n".join(indent_str + line for line in lines)
def render_option(name: str, option: dict[str, Any], level: int = 3) -> str:
def render_option(
name: str, option: dict[str, Any], level: int = 3, short_head: str | None = None
) -> str:
read_only = option.get("readOnly")
res = f"""
{"#" * level} {sanitize(name)}
{"#" * level} {sanitize(name) if short_head is None else sanitize(short_head)}
{f"**Attribute: `{name}`**" if short_head is not None else ""}
{"**Readonly**" if read_only else ""}
@@ -116,7 +121,6 @@ def render_option(name: str, option: dict[str, Any], level: int = 3) -> str:
decls = option.get("declarations", [])
if decls:
source_path, name = replace_store_path(decls[0])
print(source_path, name)
res += f"""
:simple-git: [{name}]({source_path})
"""
@@ -211,7 +215,7 @@ For more information, see the [inventory guide](../../manual/inventory.md).
clan_modules_descr = """Clan modules are [NixOS modules](https://wiki.nixos.org/wiki/NixOS_modules) which have been enhanced with additional features provided by Clan, with certain option types restricted to enable configuration through a graphical interface.
!!! note "🔹 = [inventory](../../manual/inventory.md) supported
!!! note "🔹"
Modules with this indicator support the [inventory](../../manual/inventory.md) feature.
"""
@@ -331,6 +335,117 @@ def build_option_card(module_name: str, frontmatter: Frontmatter) -> str:
return f"{to_md_li(module_name, frontmatter)}\n\n"
if __name__ == "__main__":
def produce_build_clan_docs() -> None:
if not BUILD_CLAN_PATH:
msg = f"Environment variables are not set correctly: BUILD_CLAN_PATH={BUILD_CLAN_PATH}. Expected a path to the optionsJSON"
raise ClanError(msg)
if not OUT:
msg = f"Environment variables are not set correctly: $out={OUT}"
raise ClanError(msg)
output = """# BuildClan
This provides an overview of the available arguments of the `buildClan` function.
!!! Note "Flake-parts"
Each attribute is also available via `clan.<option>`
For example `clan.inventory = ...;` is equivalent to `buildClan { inventory = ...; }`.
"""
with Path(BUILD_CLAN_PATH).open() as f:
options: dict[str, dict[str, Any]] = json.load(f)
# print(options)
for option_name, info in options.items():
# Skip underscore options
if option_name.startswith("_"):
continue
# Skip inventory sub options
# Inventory model has its own chapter
if option_name.startswith("inventory."):
continue
print(f"Rendering option of {option_name}...")
output += render_option(option_name, info)
outfile = Path(OUT) / "nix-api/buildclan.md"
outfile.parent.mkdir(parents=True, exist_ok=True)
with Path.open(outfile, "w") as of:
of.write(output)
def produce_inventory_docs() -> None:
if not BUILD_CLAN_PATH:
msg = f"Environment variables are not set correctly: BUILD_CLAN_PATH={BUILD_CLAN_PATH}. Expected a path to the optionsJSON"
raise ClanError(msg)
if not OUT:
msg = f"Environment variables are not set correctly: $out={OUT}"
raise ClanError(msg)
output = """# Inventory
This provides an overview of the available attributes of the `inventory` model.
It can be set via the `inventory` attribute of the [`buildClan`](./buildclan.md#inventory) function, or via the [`clan.inventory`](./buildclan.md#inventory) attribute of flake-parts.
"""
# Inventory options are already included under the buildClan attribute
# We just omited them in the buildClan docs, because we want a seperate output for the inventory model
with Path(BUILD_CLAN_PATH).open() as f:
options: dict[str, dict[str, Any]] = json.load(f)
def by_cat(item: tuple[str, dict[str, Any]]) -> Any:
name, _info = item
parts = name.split(".") if "." in name else ["root", "sub"]
# Make everything fixed lenght.
remain = 10 - len(parts)
parts.extend(["A"] * remain)
category = parts[1]
# Sort by category,
# then by length of the option,
# then by the rest of the options
comparator = (category, -remain, parts[2:9])
return comparator
seen_categories = set()
for option_name, info in sorted(options.items(), key=by_cat):
# Skip underscore options
if option_name.startswith("_"):
continue
# Skip non inventory sub options
if not option_name.startswith("inventory."):
continue
category = option_name.split(".")[1]
heading_level = 3
if category not in seen_categories:
heading_level = 2
seen_categories.add(category)
parts = option_name.split(".")
short_name = ""
for part in parts[1:]:
if "<" in part:
continue
short_name += ("." + part) if short_name else part
output += render_option(
option_name, info, level=heading_level, short_head=short_name
)
outfile = Path(OUT) / "nix-api/inventory.md"
outfile.parent.mkdir(parents=True, exist_ok=True)
with Path.open(outfile, "w") as of:
of.write(output)
if __name__ == "__main__": #
produce_build_clan_docs()
produce_inventory_docs()
produce_clan_core_docs()
produce_clan_modules_docs()

4
docs/nix/shell.nix
View File

@@ -3,7 +3,6 @@
pkgs,
module-docs,
clan-cli-docs,
inventory-api-docs,
asciinema-player-js,
asciinema-player-css,
roboto,
@@ -20,9 +19,8 @@ pkgs.mkShell {
mkdir -p ./site/reference/cli
cp -af ${module-docs}/* ./site/reference/
cp -af ${clan-cli-docs}/* ./site/reference/cli/
cp -af ${inventory-api-docs} ./site/reference/nix-api/inventory.md
chmod +w ./site/reference/*
chmod -R +w ./site/reference/*
echo "Generated API documentation in './site/reference/' "

7
docs/site/clanmodules/index.md Normal file
View File

@@ -0,0 +1,7 @@
# Authoring a clanModule
This site will guide you through authoring your first module. Explaining which conventions must be followed, such that others will have an enjoyable experience and the module can be used with minimal effort.
:fontawesome-solid-road-barrier: :fontawesome-solid-road-barrier: :fontawesome-solid-road-barrier:
Under construction
:fontawesome-solid-road-barrier: :fontawesome-solid-road-barrier: :fontawesome-solid-road-barrier:

3
docs/site/concepts/index.md Normal file
View File

@@ -0,0 +1,3 @@
# Core Concepts
TODO

3
docs/site/getting-started/secrets.md
View File

@@ -60,5 +60,4 @@ If you followed the quickstart tutorial all necessary secrets are initialized at
## Whats next?
- [Deployment](deploy.md): How to remotely deploy your machine
- [Advanced Secrets](../manual/secrets.md) If you want to know more about how to save and share passwords in your clan
- Full [Secrets](../manual/secrets.md) guide If you want to know more about how to save and share passwords in your clan

20
docs/site/index.md
View File

@@ -1,8 +1,14 @@
---
hide:
- navigation
- toc
---
# Home
## Welcome to **Clan**'s documentation
[Quickstart Guide](./getting-started/index.md){ .md-button }
[Getting Started](./getting-started/index.md){ .md-button }
## What's inside
@@ -19,13 +25,21 @@ This documentation is structured into the following sections
[:octicons-arrow-right-24: Getting started](./getting-started/index.md)
- :material-sign-direction:{ .lg .middle } __Manual__
- :simple-abstract:{ .lg .middle } __Concepts__
---
Important Core Concepts that should be inderstood to get the best experience.
[:octicons-arrow-right-24: Core Concepts](./concepts/index.md)
- :material-sign-direction:{ .lg .middle } __Guides__
---
Instructions and explanations for practical Implementations ordered by Topic.
[:octicons-arrow-right-24: Manual](./manual/index.md)
[:octicons-arrow-right-24: Guides](./manual/index.md)
- :material-api:{ .lg .middle } __Reference__

42
docs/site/manual/index.md
View File

@@ -17,18 +17,50 @@ Instructions and explanations for practical Implementations ordered by Topics.
[:octicons-arrow-right-24: Getting started](../getting-started/index.md)
- :fontawesome-solid-user-group:{ .lg .middle } __Authoring Modules__
---
Create clanModules that can be reused by the community.
[:octicons-arrow-right-24: Authoring clanModules](../clanmodules/index.md)
</div>
## Guides
**How-to Guides for achieving a certain goal or solving a specific issue.**
- [Adding Machines](./adding-machines.md): Learn how Clan automatically includes machines and Nix files.
<div class="grid cards" markdown>
- [Secrets](./secrets.md): Learn how to manage secrets.
- [Machines](./adding-machines.md)
- [Inventory](./inventory.md): Clan's declaration format for running **services** on one or multiple **machines**.
---
- [Flake-parts guide](./flake-parts.md): Use clan with [flake-parts](https://flake.parts/).
Learn how Clan automatically includes machines and Nix files.
- [Contribute](./contribute.md): Discover how to set up a development environment to contribute to Clan!
- [Secrets](./secrets.md)
---
Learn how to manage secrets.
- [Inventory](./inventory.md)
---
Clan's declaration format for running **services** on one or multiple **machines**.
- [Flake-parts](./flake-parts.md)
---
Use clan with [https://flake-parts.dev]()
- [Contribute](./contribute.md)
---
Discover how to set up a development environment to contribute to Clan!
</div>

2
docs/site/reference/index.md
View File

@@ -7,7 +7,7 @@ This section of the site provides an **automatically extracted** overview of the
- Learn how to use the [Clan CLI](./cli/index.md)
- Explore available services and application [modules](./clanModules/index.md)
- Discover [configuration options](./clan-core/index.md) that manage essential features
- Find descriptions of the [Nix interfaces](./nix-api/index.md) for defining a Clan
- Find descriptions of the [Nix interfaces](./nix-api/buildclan.md) for defining a Clan
---

179
docs/site/reference/nix-api/buildclan.md
View File

@@ -1,29 +1,170 @@
# buildClan
# BuildClan
The core [function](https://git.clan.lol/clan/clan-core/src/branch/main/lib/build-clan/default.nix) that produces a Clan. It returns a set of consistent configurations for all machines with ready-to-use secrets, backups and other services.
This provides an overview of the available arguments of the `buildClan` function.
## Inputs
!!! Note "Flake-parts"
Each attribute is also available via `clan.<option>`
`directory`
: The directory containing the machines subdirectory
For example `clan.inventory = ...;` is equivalent to `buildClan { inventory = ...; }`.
`machines`
: Allows to include machine-specific modules i.e. machines.${name} = { ... }
`meta`
: An optional set
### directory
: `{ name :: string, icon :: string, description :: string }`
`inventory`
: Service set for easily configuring distributed services, such as backups
: For more details see [Inventory](./inventory.md)
`specialArgs`
: Extra arguments to pass to nixosSystem i.e. useful to make self available
`pkgsForSystem`
: A function that maps from architecture to pkgs, if specified this nixpkgs will be only imported once for each system.
This improves performance, but all nipxkgs.* options will be ignored.
`(string -> pkgs )`
The directory containing the clan.
A typical directory structure could look like this:
```
.
├── flake.nix
├── assets
├── machines
├── modules
└── sops
```
buildClan argument: `directory`
**Type**: `path`
**Default**:
```nix
"Root directory of the flake"
```
:simple-git: [interface.nix](https://git.clan.lol/clan/clan-core/src/branch/main/lib/build-clan/interface.nix)
### inventory
The `Inventory` submodule.
For details see the [Inventory](./inventory.md) documentation.
**Type**: `submodule`
:simple-git: [interface.nix](https://git.clan.lol/clan/clan-core/src/branch/main/lib/build-clan/interface.nix)
### machines
A mapping of machine names to their nixos configuration.
???+ example
```nix
machines = {
my-machine = {
# Your nixos configuration
};
};
```
**Type**: `module`
**Default**:
```nix
{ }
```
:simple-git: [interface.nix](https://git.clan.lol/clan/clan-core/src/branch/main/lib/build-clan/interface.nix)
### meta
Global information about the clan.
**Type**: `null or (submodule)`
**Default**:
```nix
null
```
:simple-git: [interface.nix](https://git.clan.lol/clan/clan-core/src/branch/main/lib/build-clan/interface.nix)
### meta.name
Needs to be (globally) unique, as this determines the folder name where the flake gets downloaded to.
**Type**: `null or string`
:simple-git: [interface.nix](https://git.clan.lol/clan/clan-core/src/branch/main/lib/build-clan/interface.nix)
### pkgsForSystem
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 nipxkgs.* options will be ignored.
**Type**: `function that evaluates to a(n) (null or (attribute set))`
**Default**:
```nix
"Lambda :: String -> { ... } | null"
```
:simple-git: [interface.nix](https://git.clan.lol/clan/clan-core/src/branch/main/lib/build-clan/interface.nix)
### specialArgs
Extra arguments to pass to nixosSystem i.e. useful to make self available
**Type**: `attribute set of raw value`
**Default**:
```nix
{ }
```
:simple-git: [interface.nix](https://git.clan.lol/clan/clan-core/src/branch/main/lib/build-clan/interface.nix)

6
docs/site/reference/nix-api/index.md
View File

@@ -1,6 +0,0 @@
# Nix API Overview
There are two top-level components of the Nix API, which together allow for the declarative definition of a Clan:
- the [Inventory](./inventory.md), a structure representing the machines, services, custom configurations, and other data that constitute a Clan, and
- the [`buildClan`](./buildclan.md) function, which constructs a Clan from an Inventory definition.

16
lib/build-clan/eval-docs.nix Normal file
View File

@@ -0,0 +1,16 @@
{ pkgs, lib }:
let
eval = lib.evalModules {
modules = [
./interface.nix
];
};
evalDocs = pkgs.nixosOptionsDoc {
options = eval.options;
warningsAreErrors = false;
};
in
{
inherit (evalDocs) optionsJSON optionsNix;
inherit eval;
}

15
lib/build-clan/flake-module.nix
View File

@@ -1,11 +1,14 @@
{ self, inputs, ... }:
{
self,
inputs,
...
}:
let
inputOverrides = builtins.concatStringsSep " " (
builtins.map (input: " --override-input ${input} ${inputs.${input}}") (builtins.attrNames inputs)
);
in
{
perSystem =
{
pkgs,
@@ -13,10 +16,14 @@ in
system,
...
}:
# let
let
jsonDocs = import ./eval-docs.nix {
inherit pkgs lib;
};
# in
in
{
legacyPackages.clan-internals-docs = jsonDocs.optionsJSON;
# Run: nix-unit --extra-experimental-features flakes --flake .#legacyPackages.x86_64-linux.evalTests
legacyPackages.evalTests-build-clan = import ./tests.nix {

34
lib/build-clan/interface.nix
View File

@@ -35,13 +35,34 @@ in
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
};
};
```
'';
};
inventory = lib.mkOption {
type = types.submodule { imports = [ ../inventory/build-inventory/interface.nix ]; };
description = ''
The `Inventory` submodule.
For details see the [Inventory](./inventory.md) documentation.
'';
};
# Meta
meta = lib.mkOption {
description = ''
Global information about the clan.
'';
type = types.nullOr (
types.submodule {
options = {
@@ -58,15 +79,28 @@ in
pkgsForSystem = lib.mkOption {
type = types.functionTo (types.nullOr types.attrs);
default = _: null;
defaultText = "Lambda :: String -> { ... } | 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 nipxkgs.* options will be ignored.
'';
};
# Outputs
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 = { };
};
# flake.clanInternals
clanInternals = lib.mkOption {
# Hide from documentation. Exposes internals to the cli.
visible = false;
# type = types.raw;
# ClanInternals
type = types.submodule {

165
lib/inventory/build-inventory/interface.nix
View File

@@ -7,43 +7,73 @@ let
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
'';
};
};
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
'';
};
};
moduleConfig = lib.mkOption {
default = { };
type = types.attrsOf types.anything;
description = ''
Configuration of the specific clanModule.
!!! Note
Configuration is passed to the nixos configuration scoped to the module.
```nix
clan.<serviceName> = { ... # Config }
```
'';
};
extraModulesOption = lib.mkOption {
description = ''
List of imported '.nix' expressions.
List of addtionally imported `.nix` expressions.
Strings are interpreted relative to the 'directory' passed to buildClan.
The import only happens if the machine is part of the service or role.
Supported types:
- **Strings**: Interpreted relative to the 'directory' passed to buildClan.
- **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
???+ Example
To import the `special.nix` file
```
@@ -60,7 +90,6 @@ let
extraModules = [ "modules/special.nix" ];
}
```
'';
apply = value: if lib.isString value then value else builtins.seq (builtins.toJSON value) value;
default = [ ];
@@ -84,6 +113,11 @@ in
meta = metaOptions;
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.attrsOf (
types.submodule (
@@ -93,7 +127,25 @@ in
inherit (metaOptionsWith name) name description icon;
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;
@@ -114,6 +166,25 @@ in
};
services = lib.mkOption {
description = ''
Services of the inventory.
- The first `<name>` is the moduleName. It must be a valid clanModule name.
- The second `<name>` is an arbitrary instance name.
???+ Example
```nix
# ClanModule name. See the module documentation for the available modules.
# ↓ ↓ Instance name, can be anything, some services might use it as a unique identifier.
services.borgbackup."instance_1" = {
roles.client.machines = ["machineA"];
};
```
!!! Note
Services MUST be added to machines via `roles` exclusively.
See [`roles.<rolename>.machines`](#servicesrolesmachines) or [`roles.<rolename>.tags`](#servicesrolesmachines) for more information.
'';
default = { };
type = types.attrsOf (
types.attrsOf (
@@ -122,13 +193,67 @@ in
{
options.meta = metaOptionsWith name;
options.extraModules = extraModulesOption;
options.config = moduleConfig;
options.config = moduleConfig // {
description = ''
Configuration of the specific clanModule.
!!! Note
Configuration is passed to the nixos configuration scoped to the module.
```nix
clan.<serviceName> = { ... # Config }
```
???+ Example
For `services.borgbackup` the config is the passed to the machine with the prefix of `clan.borgbackup`.
This means all config values are mapped to the `borgbackup` clanModule exclusively (`config.clan.borgbackup`).
```nix
{
services.borgbackup."instance_1".config = {
destinations = [ ... ];
# See the 'borgbackup' module docs for all options
};
}
```
!!! Note
The module author is responsible for supporting multiple instance configurations in different roles.
See each clanModule's documentation for more information.
'';
};
options.machines = lib.mkOption {
description = ''
Attribute set of machines specific config for the service.
Will be merged with other service configs, such as the role config and the global config.
For machine specific overrides use `mkForce` or other higher priority methods.
???+ Example
```{.nix hl_lines="4-7"}
services.borgbackup."instance_1" = {
roles.client.machines = ["machineA"];
machineA.config = {
# Additional specific config for the machine
# This is merged with all other config places
};
};
```
'';
default = { };
type = types.attrsOf (
types.submodule {
options.extraModules = extraModulesOption;
options.config = moduleConfig;
options.config = moduleConfig // {
description = ''
Additional configuration of the specific machine.
See how [`service.<name>.<name>.config`](#servicesconfig) works in general for further information.
'';
};
}
);
};
@@ -139,13 +264,35 @@ in
options.machines = lib.mkOption {
default = [ ];
type = types.listOf types.str;
example = [ "machineA" ];
description = ''
List of machines which are part of the role.
The machines are referenced by their `attributeName` in the `inventory.machines` attribute set.
Memberships are decaled here to determine which machines are part of the service.
Alternatively, `tags` can be used to determine the membership, more dynamically.
'';
};
options.tags = lib.mkOption {
default = [ ];
apply = lib.unique;
type = types.listOf types.str;
description = ''
List of tags which are used to determine the membership of the role.
The tags are matched against the `inventory.machines.<machineName>.tags` attribute set.
If a machine has at least one tag of the role, it is part of the role.
'';
};
options.config = moduleConfig // {
description = ''
Additional configuration of the specific role.
See how [`service.<name>.<name>.config`](#servicesconfig) works in general for further information.
'';
};
options.config = moduleConfig;
options.extraModules = extraModulesOption;
}
);