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

Run formatter

Browse Source
This commit is contained in:
pinpox
2025-08-25 18:40:51 +02:00
parent a9c53b8b1e
commit 41c52197ea
71 changed files with 2118 additions and 1379 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
docs/site/guides/migrations/disk-id.md
View File

@@ -1,6 +1,8 @@
# Migrate disko config from `clanModules.disk-id`
If you previously bootstrapped a machine's disk using `clanModules.disk-id`, you should now migrate to a standalone, self-contained disko configuration. This ensures long-term stability and avoids reliance on dynamic values from Clan.
If you previously bootstrapped a machine's disk using `clanModules.disk-id`, you
should now migrate to a standalone, self-contained disko configuration. This
ensures long-term stability and avoids reliance on dynamic values from Clan.
If your `disko.nix` currently looks something like this:
@@ -49,8 +51,8 @@ Run the following command to retrieve the generated disk ID for your machine:
clan vars list <machineName>
```
Which should print the generated `disk-id/diskId` value in clear text
You should see output like:
Which should print the generated `disk-id/diskId` value in clear text You should
see output like:
```shellSession
disk-id/diskId: fcef30a749f8451d8f60c46e1ead726f
@@ -68,7 +70,8 @@ We are going to make three changes:
- Remove `let in, imports, {lib,clan-core,config, ...}:` to isolate the file.
- Replace `suffix` with the actual disk-id
- Move `disko.devices.disk.main.device` from `flake.nix` or `configuration.nix` into this file.
- Move `disko.devices.disk.main.device` from `flake.nix` or `configuration.nix`
into this file.
```{.nix title="disko.nix" hl_lines="7-9 11-14"}
{
@@ -93,6 +96,8 @@ We are going to make three changes:
}
```
These steps are only needed for existing configurations that depend on the `diskId` module.
These steps are only needed for existing configurations that depend on the
`diskId` module.
For newer machines clan offers simple *disk templates* via its [templates cli](../../reference/cli/templates.md)
For newer machines clan offers simple *disk templates* via its
[templates cli](../../reference/cli/templates.md)

169
docs/site/guides/migrations/migrate-inventory-services.md
View File

@@ -1,21 +1,23 @@
# 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](../../guides/services/community.md)
**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](../../guides/services/community.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`).
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 |
| 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
@@ -66,7 +68,7 @@ services = {
};
```
---
______________________________________________________________________
## ✅ After: New `instances` Definition with `clanServices`
@@ -151,13 +153,14 @@ instances = {
};
```
---
______________________________________________________________________
## Steps to Migrate
### Move `services` entries to `instances`
Check if a service that you use has been migrated [In our reference](../../reference/clanServices/index.md)
Check if a service that you use has been migrated
[In our reference](../../reference/clanServices/index.md)
In your inventory, move it from:
@@ -171,9 +174,10 @@ to:
instances = { ... };
```
Each nested service-instance-pair becomes a flat key, like `borgbackup.simple → borgbackup-simple`.
Each nested service-instance-pair becomes a flat key, like
`borgbackup.simple → borgbackup-simple`.
---
______________________________________________________________________
### Add `module.name` and `module.input`
@@ -194,15 +198,15 @@ inputs.clan-core.url = "github:clan/clan-core";
Then refer to it as `input = "clan-core"`.
---
______________________________________________________________________
### 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.
- 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:
@@ -214,7 +218,8 @@ roles.default.machines."test-inventory-machine".settings = {
### Important Type Changes
The new `instances` format uses **attribute sets** instead of **lists** for tags and machines:
The new `instances` format uses **attribute sets** instead of **lists** for tags
and machines:
```nix
# ❌ Old format (lists)
@@ -239,73 +244,70 @@ roles.moon.machines.eva = { };
roles.moon.machines.eve = { };
```
---
______________________________________________________________________
## Migration Status of clanModules
The following table shows the migration status of each deprecated clanModule:
| clanModule | Migration Status | Notes |
| clanModule | Migration Status | Notes |
|--------------------------|-------------------------------------------------------------------|------------------------------------------------------------------|
| `admin` | ✅ [Migrated](../../reference/clanServices/admin.md) | |
| `auto-upgrade` | ❌ Removed | |
| `borgbackup-static` | ❌ Removed | |
| `borgbackup` | ✅ [Migrated](../../reference/clanServices/borgbackup.md) | |
| `data-mesher` | ✅ [Migrated](../../reference/clanServices/data-mesher.md) | |
| `deltachat` | ❌ Removed | |
| `disk-id` | ❌ Removed | |
| `dyndns` | [Being Migrated](https://git.clan.lol/clan/clan-core/pulls/4390) | |
| `ergochat` | ❌ Removed | |
| `garage` | ✅ [Migrated](../../reference/clanServices/garage.md) | |
| `golem-provider` | ❌ Removed | |
| `heisenbridge` | ❌ Removed | |
| `importer` | ✅ [Migrated](../../reference/clanServices/importer.md) | |
| `iwd` | ❌ Removed | Use [wifi service](../../reference/clanServices/wifi.md) instead |
| `localbackup` | ✅ [Migrated](../../reference/clanServices/localbackup.md) | |
| `localsend` | ❌ Removed | |
| `machine-id` | ❌ Removed | Now an [option](../../reference/clan.core/settings.md) |
| `matrix-synapse` | ✅ [Migrated](../../reference/clanServices/matrix-synapse.md) | |
| `moonlight` | ❌ Removed | |
| `mumble` | ❌ Removed | |
| `mycelium` | ✅ [Migrated](../../reference/clanServices/mycelium.md) | |
| `nginx` | ❌ Removed | |
| `packages` | ✅ [Migrated](../../reference/clanServices/packages.md) | |
| `postgresql` | ❌ Removed | Now an [option](../../reference/clan.core/settings.md) |
| `root-password` | ✅ [Migrated](../../reference/clanServices/users.md) | See [migration guide](../../reference/clanServices/users.md#migration-from-root-password-module) |
| `single-disk` | ❌ Removed | |
| `sshd` | ✅ [Migrated](../../reference/clanServices/sshd.md) | |
| `state-version` | ✅ [Migrated](../../reference/clanServices/state-version.md) | |
| `static-hosts` | ❌ Removed | |
| `sunshine` | ❌ Removed | |
| `syncthing-static-peers` | ❌ Removed | |
| `syncthing` | ✅ [Migrated](../../reference/clanServices/syncthing.md) | |
| `thelounge` | ❌ Removed | |
| `trusted-nix-caches` | ✅ [Migrated](../../reference/clanServices/trusted-nix-caches.md) | |
| `user-password` | ✅ [Migrated](../../reference/clanServices/users.md) | |
| `vaultwarden` | ❌ Removed | |
| `xfce` | ❌ Removed | |
| `zerotier-static-peers` | ❌ Removed | |
| `zerotier` | ✅ [Migrated](../../reference/clanServices/zerotier.md) | |
| `zt-tcp-relay` | ❌ Removed | |
| `admin` | ✅ [Migrated](../../reference/clanServices/admin.md) | | |
`auto-upgrade` | ❌ Removed | | | `borgbackup-static` | ❌ Removed | | |
`borgbackup` | ✅ [Migrated](../../reference/clanServices/borgbackup.md) | | |
`data-mesher` | ✅ [Migrated](../../reference/clanServices/data-mesher.md) | | |
`deltachat` | ❌ Removed | | | `disk-id` | ❌ Removed | | | `dyndns` |
[Being Migrated](https://git.clan.lol/clan/clan-core/pulls/4390) | | |
`ergochat` | ❌ Removed | | | `garage` | ✅
[Migrated](../../reference/clanServices/garage.md) | | | `golem-provider` | ❌
Removed | | | `heisenbridge` | ❌ Removed | | | `importer` | ✅
[Migrated](../../reference/clanServices/importer.md) | | | `iwd` | ❌ Removed |
Use [wifi service](../../reference/clanServices/wifi.md) instead | |
`localbackup` | ✅ [Migrated](../../reference/clanServices/localbackup.md) | | |
`localsend` | ❌ Removed | | | `machine-id` | ❌ Removed | Now an
[option](../../reference/clan.core/settings.md) | | `matrix-synapse` | ✅
[Migrated](../../reference/clanServices/matrix-synapse.md) | | | `moonlight` | ❌
Removed | | | `mumble` | ❌ Removed | | | `mycelium` | ✅
[Migrated](../../reference/clanServices/mycelium.md) | | | `nginx` | ❌ Removed |
| | `packages` | ✅ [Migrated](../../reference/clanServices/packages.md) | | |
`postgresql` | ❌ Removed | Now an
[option](../../reference/clan.core/settings.md) | | `root-password` | ✅
[Migrated](../../reference/clanServices/users.md) | See
[migration guide](../../reference/clanServices/users.md#migration-from-root-password-module)
| | `single-disk` | ❌ Removed | | | `sshd` | ✅
[Migrated](../../reference/clanServices/sshd.md) | | | `state-version` | ✅
[Migrated](../../reference/clanServices/state-version.md) | | | `static-hosts` |
❌ Removed | | | `sunshine` | ❌ Removed | | | `syncthing-static-peers` | ❌
Removed | | | `syncthing` | ✅
[Migrated](../../reference/clanServices/syncthing.md) | | | `thelounge` | ❌
Removed | | | `trusted-nix-caches` | ✅
[Migrated](../../reference/clanServices/trusted-nix-caches.md) | | |
`user-password` | ✅ [Migrated](../../reference/clanServices/users.md) | | |
`vaultwarden` | ❌ Removed | | | `xfce` | ❌ Removed | | | `zerotier-static-peers`
| ❌ Removed | | | `zerotier` | ✅
[Migrated](../../reference/clanServices/zerotier.md) | | | `zt-tcp-relay` | ❌
Removed | |
---
______________________________________________________________________
!!! 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.
!!! 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.
## Troubleshooting Common Migration Errors
### Error: "not of type `attribute set of (submodule)`"
This error occurs when using lists instead of attribute sets for tags or machines:
This error occurs when using lists instead of attribute sets for tags or
machines:
```
error: A definition for option `flake.clan.inventory.instances.borgbackup-blob64.roles.client.tags' is not of type `attribute set of (submodule)'.
```
**Solution**: Convert lists to attribute sets as shown in the "Important Type Changes" section above.
**Solution**: Convert lists to attribute sets as shown in the "Important Type
Changes" section above.
### Error: "unsupported attribute `module`"
@@ -315,7 +317,8 @@ This error indicates the module structure is incorrect:
error: Module ':anon-4:anon-1' has an unsupported attribute `module'.
```
**Solution**: Ensure the `module` attribute has exactly two fields: `name` and `input`.
**Solution**: Ensure the `module` attribute has exactly two fields: `name` and
`input`.
### Error: "attribute 'pkgs' missing"
@@ -325,25 +328,30 @@ This suggests the instance configuration is trying to use imports incorrectly:
error: attribute 'pkgs' missing
```
**Solution**: Use the `module = { name = "..."; input = "..."; }` format instead of `imports`.
**Solution**: Use the `module = { name = "..."; input = "..."; }` format instead
of `imports`.
### Removed Features
The following features from the old `services` format are no longer supported in `instances`:
The following features from the old `services` format are no longer supported in
`instances`:
- Top-level `config` attribute (use `roles.<role>.settings` instead)
- Direct module imports (use the `module` declaration instead)
### extraModules Support
The `extraModules` attribute is still supported in the new instances format! The key change is how modules are specified:
The `extraModules` attribute is still supported in the new instances format! The
key change is how modules are specified:
**Old format (string paths relative to clan root):**
```nix
roles.client.extraModules = [ "nixosModules/borgbackup.nix" ];
```
**New format (NixOS modules):**
```nix
# Direct module reference
roles.client.extraModules = [ ../nixosModules/borgbackup.nix ];
@@ -359,11 +367,14 @@ roles.client.extraModules = [
];
```
The `extraModules` now expects actual **NixOS modules** rather than string paths. This provides better type checking and more flexibility in how modules are specified.
The `extraModules` now expects actual **NixOS modules** rather than string
paths. This provides better type checking and more flexibility in how modules
are specified.
**Alternative: Using @clan/importer**
For scenarios where you need to import modules with specific tag-based targeting, you can also use the dedicated `@clan/importer` service:
For scenarios where you need to import modules with specific tag-based
targeting, you can also use the dedicated `@clan/importer` service:
```nix
instances = {
@@ -378,6 +389,6 @@ instances = {
## Further reference
* [Inventory Concept](../../concepts/inventory.md)
* [Authoring a 'clan.service' module](../../guides/services/community.md)
* [ClanServices](../clanServices.md)
- [Inventory Concept](../../concepts/inventory.md)
- [Authoring a 'clan.service' module](../../guides/services/community.md)
- [ClanServices](../clanServices.md)

58
docs/site/guides/migrations/migration-facts-vars.md
View File

@@ -1,16 +1,20 @@
# Migrate modules from `facts` to `vars`.
For a high level overview about `vars` see our [blog post](https://clan.lol/blog/vars/).
For a high level overview about `vars` see our
[blog post](https://clan.lol/blog/vars/).
This guide will help you migrate your modules that still use our [`facts`](../../guides/secrets.md) backend
to the [`vars`](../../concepts/generators.md) backend.
This guide will help you migrate your modules that still use our
[`facts`](../../guides/secrets.md) backend to the
[`vars`](../../concepts/generators.md) backend.
The `vars` [module](../../reference/clan.core/vars.md) and the clan [command](../../reference/cli/vars.md) work in tandem, they should ideally be kept in sync.
The `vars` [module](../../reference/clan.core/vars.md) and the clan
[command](../../reference/cli/vars.md) work in tandem, they should ideally be
kept in sync.
## Keep Existing Values
In order to keep existing values and move them from `facts` to `vars`
we will need to set the corresponding option in the vars module:
In order to keep existing values and move them from `facts` to `vars` we will
need to set the corresponding option in the vars module:
```
migrateFact = "fact-name"
@@ -19,10 +23,10 @@ migrateFact = "fact-name"
This will now check on `vars` generation if there is an existing `fact` with the
name already present and if that is the case will migrate it to `vars`.
Let us look at the mapping a little closer.
Suppose we have the following fact: `facts.services.vaultwarden.secret.admin`.
This would read as follows: The `vaultwarden` `fact` service has the `admin` secret.
In order to migrate this fact we would need to have the following `vars` configuration:
Let us look at the mapping a little closer. Suppose we have the following fact:
`facts.services.vaultwarden.secret.admin`. This would read as follows: The
`vaultwarden` `fact` service has the `admin` secret. In order to migrate this
fact we would need to have the following `vars` configuration:
```nix
vars.generators.vaultwarden = {
@@ -31,13 +35,14 @@ vars.generators.vaultwarden = {
};
```
And this would read as follows: The vaultwarden `vars` module generates the admin file.
And this would read as follows: The vaultwarden `vars` module generates the
admin file.
## Prompts
Because prompts can be a necessity for certain systems `vars` have a shorthand for defining them.
A prompt is a request for user input. Let us look how user input used to be handled in facts:
Because prompts can be a necessity for certain systems `vars` have a shorthand
for defining them. A prompt is a request for user input. Let us look how user
input used to be handled in facts:
```nix
facts.services.forgejo-api = {
@@ -46,7 +51,9 @@ facts.services.forgejo-api = {
generator.script = "cp $prompt_value > $secret/token";
};
```
To have analogous functionality in `vars`:
```nix
vars.generators.forgejo-api = {
prompts.token = {
@@ -55,8 +62,11 @@ vars.generators.forgejo-api = {
};
};
```
This does not only simplify prompting, it also now allows us to define multiple prompts in one generator.
A more analogous way to the `fact` method is available, in case the module author needs more flexibility with the prompt input:
This does not only simplify prompting, it also now allows us to define multiple
prompts in one generator. A more analogous way to the `fact` method is
available, in case the module author needs more flexibility with the prompt
input:
```nix
vars.generators.forgejo-api = {
@@ -92,8 +102,9 @@ facts.services.syncthing = {
};
```
This would be the corresponding `vars` module, which also will migrate existing
facts.
This would be the corresponding `vars` module, which also will migrate existing facts.
```nix
vars.generators.syncthing = {
migrateFact = "syncthing";
@@ -116,12 +127,15 @@ vars.generators.syncthing = {
'';
};
```
Most of the usage patterns stay the same, but `vars` have a more ergonomic interface.
There are not two different ways to define files anymore (public/secret).
Now files are defined under the `files` attribute and are secret by default.
Most of the usage patterns stay the same, but `vars` have a more ergonomic
interface. There are not two different ways to define files anymore
(public/secret). Now files are defined under the `files` attribute and are
secret by default.
## Happy Migration
We hope this gives you a clear path to start and finish your migration from `facts` to `vars`.
Please do not hesitate reaching out if something is still unclear - either through [matrix](https://matrix.to/#/#clan:clan.lol) or through our git [forge](https://git.clan.lol/clan/clan-core).
We hope this gives you a clear path to start and finish your migration from
`facts` to `vars`. Please do not hesitate reaching out if something is still
unclear - either through [matrix](https://matrix.to/#/#clan:clan.lol) or through
our git [forge](https://git.clan.lol/clan/clan-core).