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

docs: Rename guides to manual, Rename reference to options, add secure boot chapter to manual. Add secrets chapter to manual.

Browse Source
This commit is contained in:
Qubasa
2024-09-20 16:52:52 +02:00
parent 2f50ccc77f
commit 036cd710e1
13 changed files with 351 additions and 319 deletions
Download Patch File Download Diff File Expand all files Collapse all files

50
docs/site/guides/add-machines.md
View File

@@ -1,50 +0,0 @@
# How to add machines
Clan has two general methods of adding machines
- **Automatic**: Detects every folder in the `machines` folder.
- **Declarative**: Explicit declarations in nix.
## Automatic register
Every machine of the form `machines/{machineName}` will be registered automatically.
Automatically imported:
- [x] ``machines/{machineName}/configuration.nix`
- [x] ``machines/{machineName}/hardware-configuration.nix`
- [x] ``machines/{machineName}/facter.json` Automatically configured, for further information see [nixos-facter](../blog/posts/nixos-facter.md)
## Manual declaration
Machines can also be added manually under `buildClan`, `clan.*` in flake-parts or via [`inventory`](../guides/inventory.md).
!!! Note
It is possible to use `inventory` and `buildClan` together at the same time.
=== "**Individual Machine Configuration**"
```{.nix}
buildClan {
machines = {
"jon" = {
# Any valid nixos config
};
};
}
```
=== "**Inventory Configuration**"
```{.nix}
buildClan {
inventory = {
machines = {
"jon" = {
# Inventory machines can set tags
tags = [ "zone1" ];
};
};
};
}
```

7
docs/site/guides/index.md
View File

@@ -1,7 +0,0 @@
# Guides
Detailed guides into the following subtopics:
- [Getting Started](../index.md): Getting started with clan.
- [Adding Machines](./add-machines.md): How to add machines.
- [Inventory](./inventory.md): Configuring Services across machine boundaries

135
docs/site/guides/inventory.md
View File

@@ -1,135 +0,0 @@
# Inventory
`Inventory` is an abstract service layer for consistently configuring distributed services across machine boundaries.
See [Inventory API Documentation](../reference/nix-api/inventory.md)
This guide will walk you through setting up a backup service, where the inventory becomes useful.
!!! example "Experimental status"
The inventory implementation is not considered stable yet.
We are actively soliciting feedback from users.
Stabilizing the API is a priority.
## Prerequisites
- [x] [Add machines](./add-machines.md) to your clan.
## Services
The inventory defines `services`. Membership of `machines` is defined via roles exclusively.
See the each [module documentation](../reference/clanModules/index.md) for available roles.
!!! Note
It is possible to use any [clanModule](../reference/clanModules/index.md) in the inventory and add machines via
`roles.default.*`
### Adding services to machines
A module can be added to one or multiple machines via `Roles`. clan's `Role` interface provide sane defaults for a module this allows the module author to reduce the configuration overhead to a minimum.
Each service can still be customized and configured according to the modules options.
- Per instance configuration via `services.<serviceName>.<instanceName>.config`
- Per role configuration via `services.<serviceName>.<instanceName>.roles.<roleName>.config`
- Per machine configuration via `services.<serviceName>.<instanceName>.machines.<machineName>.config`
### Setting up the Backup Service
!!! Example "Borgbackup Example"
To configure a service it needs to be added to the machine.
It is required to assign the service (`borgbackup`) an arbitrary instance name. (`instance_1`)
See also: [Multiple Service Instances](#multiple-service-instances)
```{.nix hl_lines="6-7"}
buildClan {
inventory = {
services = {
borgbackup.instance_1 = {
# Machines can be added here.
roles.client.machines = [ "jon" ];
roles.server.machines = [ "backup_server" ];
};
};
};
}
```
### Scaling the Backup
The inventory allows machines to set Tags
It is possible to add services to multiple machines via tags as shown
!!! Example "Tags Example"
```{.nix hl_lines="5 8 14"}
buildClan {
inventory = {
machines = {
"jon" = {
tags = [ "backup" ];
};
"sara" = {
tags = [ "backup" ];
};
# ...
};
services = {
borgbackup.instance_1 = {
roles.client.tags = [ "backup" ];
roles.server.machines = [ "backup_server" ];
};
};
};
}
```
### Multiple Service Instances
!!! danger "Important"
Not all modules implement support for multiple instances yet.
Multiple instance usage could create complexity, refer to each modules documentation, for intended usage.
!!! Example
In this example `backup_server` has role `client` and `server` in different instances.
```{.nix hl_lines="11 14"}
buildClan {
inventory = {
machines = {
"jon" = {};
"backup_server" = {};
"backup_backup_server" = {}
};
services = {
borgbackup.instance_1 = {
roles.client.machines = [ "jon" ];
roles.server.machines = [ "backup_server" ];
};
borgbackup.instance_2 = {
roles.client.machines = [ "backup_server" ];
roles.server.machines = [ "backup_backup_server" ];
};
};
};
}
```
### API specification
**The complete schema specification is available [here](../reference/nix-api/inventory.md)**
Or it can build anytime via:
```sh
nix build git+https://git.clan.lol/clan/clan-core#inventory-schema
> result
> ├── schema.cue
> └── schema.json
```