Docs: init migration guide for clanServices
This commit is contained in:
Johannes Kirschbauer
@@ -4,6 +4,8 @@ Clan’s `clanServices` system is a composable way to define and deploy services
|
||||
|
||||
This guide shows how to **instantiate** a `clanService`, explains how service definitions are structured in your inventory, and how to pick or create services from modules exposed by flakes.
|
||||
|
||||
The term **Multi-host-modules** was introduced previously in the [nixus repository](https://github.com/infinisil/nixus) and represents a similar concept.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
@@ -17,6 +19,8 @@ inventory.instances.<instance_name>
|
||||
Each instance includes a reference to a **module specification** — this is how Clan knows which service module to use and where it came from.
|
||||
You can reference services from any flake input, allowing you to compose services from multiple flake sources.
|
||||
|
||||
These operate on a strict *role-based membership model*, meaning machines are added by assigning them specific *roles*.
|
||||
|
||||
---
|
||||
|
||||
## Basic Example
|
||||
@@ -32,6 +36,7 @@ inventory.instances = {
|
||||
input = "clan-core"; # <-- The flake input where the service is defined
|
||||
};
|
||||
# Participation of the machines is defined via roles
|
||||
# Right side needs to be an attribute set. Its purpose will become clear later
|
||||
roles.client.machines."machine-a" = {};
|
||||
roles.server.machines."backup-host" = {};
|
||||
};
|
||||
@@ -45,6 +50,54 @@ If you used `clan-core` as an input attribute for your flake:
|
||||
inputs.clan-core.url = "git+https://git.clan.lol/clan/clan-core"
|
||||
```
|
||||
|
||||
## Configuration Example
|
||||
|
||||
Each role might expose configurable options
|
||||
|
||||
See clan's [clanServices reference](../reference/clanServices/index.md) for available options
|
||||
|
||||
```nix
|
||||
inventory.instances = {
|
||||
borgbackup-example = {
|
||||
module = {
|
||||
name = "borgbackup";
|
||||
input = "clan-core";
|
||||
};
|
||||
roles.client.machines."machine-a" = {
|
||||
# 'client' -Settings of 'machine-a'
|
||||
settings = {
|
||||
backupFolders = [
|
||||
/home
|
||||
/var
|
||||
];
|
||||
};
|
||||
# ---------------------------
|
||||
};
|
||||
roles.server.machines."backup-host" = {};
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
## Tags
|
||||
|
||||
Multiple members can be defined using tags as follows
|
||||
|
||||
```nix
|
||||
inventory.instances = {
|
||||
borgbackup-example = {
|
||||
module = {
|
||||
name = "borgbackup";
|
||||
input = "clan-core";
|
||||
};
|
||||
#
|
||||
# The 'all' -tag targets all machines
|
||||
roles.client.tags."all" = {};
|
||||
# ---------------------------
|
||||
roles.server.machines."backup-host" = {};
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
## Picking a clanService
|
||||
|
||||
You can use services exposed by Clan’s core module library, `clan-core`.
|
||||
|
||||
@@ -1,7 +1,147 @@
|
||||
# How to migrate `Inventory.services`
|
||||
# Migrating from using `clanModules` to `clanServices`
|
||||
|
||||
**Audience**: This is a guide for **people using `clanModules`**.
|
||||
If you are a **module author** and need to migrate your modules please consult our **new** [clanServices authoring guide](../authoring/clanServices/index.md)
|
||||
|
||||
## What's Changing?
|
||||
|
||||
Clan is transitioning from the legacy `clanModules` system to the `clanServices` system. This guide will help you migrate your service definitions from the old format (`inventory.services`) to the new format (`inventory.instances`).
|
||||
|
||||
| Feature | `clanModules` (Old) | `clanServices` (New) |
|
||||
| ---------------- | -------------------------- | ----------------------- |
|
||||
| Module Class | `"nixos"` | `"clan.service"` |
|
||||
| Inventory Key | `services` | `instances` |
|
||||
| Module Source | Static | Composable via flakes |
|
||||
| Custom Settings | Loosely structured | Strongly typed per-role |
|
||||
| Migration Status | Deprecated (to be removed) | ✅ Preferred |
|
||||
|
||||
---
|
||||
|
||||
## Before: Old `services` Definition
|
||||
|
||||
```nix
|
||||
services = {
|
||||
admin = {
|
||||
simple = {
|
||||
roles.default.tags = [ "all" ];
|
||||
|
||||
roles.default.config = {
|
||||
allowedKeys = {
|
||||
"key-1" = "ssh-ed25519 AAAA...0J jon@jon-os";
|
||||
};
|
||||
};
|
||||
};
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✅ After: New `instances` Definition with `clanServices`
|
||||
|
||||
```nix
|
||||
instances = {
|
||||
# The instance_name is arbitrary but must be unique
|
||||
# We recommend to incorporate the module name in some kind to keep it clear
|
||||
admin-simple = {
|
||||
module = {
|
||||
name = "admin";
|
||||
input = "clan-core";
|
||||
};
|
||||
|
||||
roles.default.tags."all" = {};
|
||||
|
||||
# Move settings either into the desired role
|
||||
# In that case they effect all 'client-machines'
|
||||
roles.default.settings = {
|
||||
allowedKeys = {
|
||||
"key-1" = "ssh-ed25519 AAAA...0J jon@jon-os";
|
||||
};
|
||||
};
|
||||
# ----------------------------
|
||||
# OR move settings into the machine
|
||||
# then they affect only that single 'machine'
|
||||
roles.default.machines."jon".settings = {
|
||||
allowedKeys = {
|
||||
"key-1" = "ssh-ed25519 AAAA...0J jon@jon-os";
|
||||
};
|
||||
};
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Steps to Migrate
|
||||
|
||||
|
||||
|
||||
### 1. Move `services` entries to `instances`
|
||||
|
||||
Check if a service that you use has been migrated [In our reference](../reference/clanServices/index.md)
|
||||
|
||||
In your inventory, move it from:
|
||||
|
||||
```nix
|
||||
services = { ... };
|
||||
```
|
||||
|
||||
to:
|
||||
|
||||
```nix
|
||||
instances = { ... };
|
||||
```
|
||||
|
||||
Each nested service-instance-pair becomes a flat key, like `borgbackup.simple → borgbackup-simple`.
|
||||
|
||||
---
|
||||
|
||||
### 2. Add `module.name` and `module.input`
|
||||
|
||||
Each instance must declare the module name and flake input it comes from:
|
||||
|
||||
```nix
|
||||
module = {
|
||||
name = "borgbackup";
|
||||
input = "clan-core"; # The name of your flake input
|
||||
};
|
||||
```
|
||||
|
||||
If you used `clan-core` as an input:
|
||||
|
||||
```nix
|
||||
inputs.clan-core.url = "github:clan/clan-core";
|
||||
```
|
||||
|
||||
Then refer to it as `input = "clan-core"`.
|
||||
|
||||
---
|
||||
|
||||
### 3. Move role and machine config under `roles`
|
||||
|
||||
In the new system:
|
||||
|
||||
* Use `roles.<role>.machines.<hostname>.settings` for machine-specific config.
|
||||
* Use `roles.<role>.settings` for role-wide config.
|
||||
* Remove: `.config` as a top-level attribute is removed.
|
||||
|
||||
Example:
|
||||
|
||||
```nix
|
||||
roles.default.machines."test-inventory-machine".settings = {
|
||||
packages = [ "hello" ];
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
!!! Warning
|
||||
* Old `clanModules` (`class = "nixos"`) are deprecated and will be removed in the near future.
|
||||
* `inventory.services` is no longer recommended; use `inventory.instances` instead.
|
||||
* Module authors should begin exporting service modules under the `clan.modules` attribute of their flake.
|
||||
|
||||
## Further reference
|
||||
|
||||
- [Authoring a 'clan.service' module](../authoring/clanServices/index.md)
|
||||
- [Setting up `inventory.instances`](../manual/distributed-services.md)
|
||||
- [Inventory Reference](../reference/nix-api/inventory.md)
|
||||
* [Authoring a 'clan.service' module](../authoring/clanServices/index.md)
|
||||
* [ClanServices](../guides/clanServices.md)
|
||||
* [Inventory Reference](../reference/nix-api/inventory.md)
|
||||
Reference in New Issue
Block a user