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

Merge pull request 'docs: fix multiple format errors, improve readability of vars' (#5142) from Qubasa/clan-core:improve_vars_docs into main

Browse Source 
Reviewed-on: https://git.clan.lol/clan/clan-core/pulls/5142
This commit is contained in:
Luis Hebendanz
2025-09-12 10:46:15 +00:00
parent fd162f6fc8 447b0bf8ac
commit 60195f9614
11 changed files with 64 additions and 154 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
docs/mkdocs.yml
View File

@@ -61,8 +61,6 @@ nav:
- Continuous Integration: guides/getting-started/flake-check.md
- Convert Existing NixOS Config: guides/getting-started/convert-flake.md
- ClanServices: guides/clanServices.md
- Backup & Restore: guides/backups.md
- Disk Encryption: guides/disk-encryption.md
- Vars:
- Overview: guides/vars-overview.md
- Getting Started: guides/vars-backend.md
@@ -70,6 +68,8 @@ nav:
- Advanced Examples: guides/vars-advanced-examples.md
- Troubleshooting: guides/vars-troubleshooting.md
- Age Plugins: guides/age-plugins.md
- Backup & Restore: guides/backups.md
- Disk Encryption: guides/disk-encryption.md
- Secrets management: guides/secrets.md
- Networking: guides/networking.md
- Zerotier VPN: guides/mesh-vpn.md
@@ -89,7 +89,6 @@ nav:
- Disk id: guides/migrations/disk-id.md
- Concepts:
- Inventory: concepts/inventory.md
- Generators: concepts/generators.md
- Autoincludes: concepts/autoincludes.md
- Templates: concepts/templates.md
- Reference:
@@ -224,4 +223,4 @@ plugins:
- redoc-tag
- redirects:
redirect_maps:
guides/getting-started/secrets.md: concepts/generators.md
guides/getting-started/secrets.md: guides/vars-overview.md

45
docs/site/concepts/generators.md
View File

@@ -1,45 +0,0 @@
# Generators
Generators are the core mechanism of the clan vars system for automating the creation and management of generated files, especially secrets, in your NixOS configurations.
## What are Generators?
Generators solve a common problem: instead of manually running commands like `mkpasswd` to create password hashes and copying them into your configuration, generators automate this process declaratively.
A generator defines:
- **Input prompts**: Values to request from users (passwords, names, etc.)
- **Generation script**: Logic to transform inputs into outputs
- **Output files**: Generated files that can be secrets or public data
- **Dependencies**: Other generators this one depends on
- **Runtime inputs**: Tools and packages needed by the script
## Key Benefits
- **Reproducible**: Same inputs produce same outputs across machines
- **Declarative**: Defined in your NixOS configuration alongside usage
- **Secure**: Automatic handling of secrets storage and deployment
- **Collaborative**: Shared generators work across team environments
- **Automated**: No manual copy-paste of generated values
## Common Use Cases
- **Password hashing**: Generate secure password hashes for user accounts
- **SSH keys**: Create and manage SSH host and user keys
- **Certificates**: Generate TLS certificates and certificate authorities
- **API tokens**: Create secure random tokens for services
- **Configuration files**: Generate config files that depend on secrets
## Learning Path
1. **Start here**: [Vars Getting Started Guide](../guides/vars-backend.md) - Hands-on tutorial with practical examples
2. **Understand the architecture**: [Vars Concepts Guide](../guides/vars-concepts.md) - Deep dive into design principles and patterns
3. **Explore complex scenarios**: [Advanced Examples](../guides/vars-advanced-examples.md) - Real-world patterns and best practices
4. **Troubleshoot issues**: [Troubleshooting Guide](../guides/vars-troubleshooting.md) - Common problems and solutions
## API Reference
For complete configuration options and technical details, see:
- [Vars NixOS Module Reference](../reference/clan.core/vars.md) - All configuration options
- [Vars CLI Reference](../reference/cli/vars.md) - Command-line interface

2
docs/site/guides/macos.md
View File

@@ -7,7 +7,7 @@ This guide explains how to manage macOS machines using Clan.
Currently, Clan supports the following features for macOS:
- `clan machines update` for existing [nix-darwin](https://github.com/nix-darwin/nix-darwin) installations
- Support for [vars](../concepts/generators.md)
- Support for [vars](../guides/vars-overview.md)
## Add Your Machine to Your Clan Flake

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

@@ -3,7 +3,7 @@
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.
to the [`vars`](../../guides/vars-overview.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.

52
docs/site/guides/secrets.md
View File

@@ -1,5 +1,5 @@
This article provides an overview over the underlying secrets system which is used by [Vars](../concepts/generators.md).
Under most circumstances you should use [Vars](../concepts/generators.md) directly instead.
This article provides an overview over the underlying secrets system which is used by [Vars](../guides/vars-overview.md).
Under most circumstances you should use [Vars](../guides/vars-overview.md) directly instead.
Consider using `clan secrets` only for managing admin users and groups, as well as a debugging tool.
@@ -292,15 +292,14 @@ The following diagrams illustrates how a user can provide a secret (i.e. a Passw
```plantuml
@startuml
!include C4_Container.puml
Person(user, "User", "Someone who manages secrets")
ContainerDb(secret, "Secret")
Container(machine, "Machine", "A Machine. i.e. Needs the Secret for a given Service." )
actor "User" as user
database "Secret" as secret
rectangle "Machine" as machine
Rel_R(user, secret, "Encrypt", "", "Pubkeys: User, Machine")
Rel_L(secret, user, "Decrypt", "", "user privkey")
Rel_R(secret, machine, "Decrypt", "", "machine privkey" )
user -right-> secret : Encrypt\n(Pubkeys: User, Machine)
secret -left-> user : Decrypt\n(user privkey)
secret -right-> machine : Decrypt\n(machine privkey)
@enduml
```
@@ -316,19 +315,18 @@ Common use cases:
```plantuml
@startuml
!include C4_Container.puml
System_Boundary(c1, "Group") {
Person(user1, "User A", "has access")
Person(user2, "User B", "has access")
rectangle "Group" {
actor "User A" as user1
actor "User B" as user2
}
ContainerDb(secret, "Secret")
Container(machine, "Machine", "A Machine. i.e. Needs the Secret for a given Service." )
Rel_R(c1, secret, "Encrypt", "", "Pubkeys: User A, User B, Machine")
Rel_R(secret, machine, "Decrypt", "", "machine privkey" )
database "Secret" as secret
rectangle "Machine" as machine
user1 -right-> secret : Encrypt
user2 -right-> secret : (Pubkeys: User A, User B, Machine)
secret -right-> machine : Decrypt\n(machine privkey)
@enduml
```
@@ -347,19 +345,17 @@ Common use cases:
```plantuml
@startuml
!include C4_Container.puml
!include C4_Deployment.puml
Person(user, "User", "Someone who manages secrets")
ContainerDb(secret, "Secret")
System_Boundary(c1, "Group") {
Container(machine1, "Machine A", "Both machines need the same secret" )
Container(machine2, "Machine B", "Both machines need the same secret" )
actor "User" as user
database "Secret" as secret
rectangle "Group" {
rectangle "Machine A" as machine1
rectangle "Machine B" as machine2
}
Rel_R(user, secret, "Encrypt", "", "Pubkeys: machine A, machine B, User")
Rel(secret, c1, "Decrypt", "", "Both machine A or B can decrypt using their private key" )
user -right-> secret : Encrypt\n(Pubkeys: machine A, machine B, User)
secret -down-> machine1 : Decrypt
secret -down-> machine2 : (Both machines can decrypt\nusing their private key)
@enduml
```

3
docs/site/guides/vars-advanced-examples.md
View File

@@ -1,6 +1,7 @@
# Advanced Vars Examples
This guide demonstrates complex, real-world patterns for the vars system. For basic usage, see the [Getting Started guide](vars-backend.md).
This guide demonstrates complex, real-world patterns for the vars system.
## Certificate Authority with Intermediate Certificates

39
docs/site/guides/vars-backend.md
View File

@@ -1,27 +1,19 @@
The `clan vars` subcommand is a powerful tool for managing machine-specific variables in a declarative and reproducible way. This guide will walk you through its usage, from setting up a generator to sharing and updating variables across machines.
!!! Note
This guide demonstrates the vars system for managing secrets and generated files
For a detailed API reference, see the [vars module documentation](../reference/clan.core/vars.md).
In this guide, you will learn how to:
Defining a linux user's password via the nixos configuration previously required running `mkpasswd ...` and then copying the hash back into the nix configuration.
1. Declare a `generator` in the machine's NixOS configuration.
2. Inspect the status of variables using the Clan CLI.
3. Generate variables interactively.
4. Observe the changes made to your repository.
5. Update the machine configuration.
6. Share the root password between multiple machines.
7. Change the root password when needed.
In this example, we will guide you through automating that interaction using clan `vars`.
By the end of this guide, you will have a clear understanding of how to use `clan vars` to manage sensitive data, such as passwords, in a secure and efficient manner.
For architectural concepts and design principles, see the [Concepts guide](vars-concepts.md). For the complete API reference, see the [vars module documentation](../reference/clan.core/vars.md).
This guide assumes
- Clan is set up already (see [Getting Started](../guides/getting-started/index.md))
- a machine has been added to the clan (see [Adding Machines](getting-started/add-machines.md))
This section will walk you through the following steps:
1. declare a `generator` in the machine's nixos configuration
2. inspect the status via the Clan CLI
3. generate the vars
4. observe the changes
5. update the machine
6. share the root password between machines
7. change the password
## Declare the generator
@@ -144,12 +136,3 @@ Updated var root-password/password-hash
new: $6$OyoQtDVzeemgh8EQ$zRK...
```
## Further Reading
- [Understanding Vars Concepts](vars-concepts.md) - Learn about the architecture and core concepts
- [Advanced Examples](vars-advanced-examples.md) - Complex real-world examples including certificates, SSH keys, and more
- [Troubleshooting Guide](vars-troubleshooting.md) - Common issues and solutions
- [Migration Guide](migrations/migration-facts-vars.md) - Migrate from legacy facts system
- [Reference Documentation for `clan.core.vars` NixOS options](../reference/clan.core/vars.md)
- [Reference Documentation for the `clan vars` CLI command](../reference/cli/vars.md)

8
docs/site/guides/vars-concepts.md
View File

@@ -1,6 +1,6 @@
# Understanding Clan Vars - Concepts & Architecture
This guide explains the architecture and design principles behind the vars system. For a hands-on tutorial, see the [Getting Started guide](vars-backend.md).
This guide explains the architecture and design principles behind the vars system.
## Architecture Overview
@@ -121,9 +121,3 @@ Compared to manual secret management, vars provides:
- **User prompts**: Gather input when needed
- **Easy regeneration**: Update secrets with a single command
## Next Steps
- [Practical Tutorial](vars-backend.md) - Step-by-step guide
- [Advanced Examples](vars-advanced-examples.md) - Real-world patterns
- [Troubleshooting](vars-troubleshooting.md) - Common issues
- [Reference](../reference/clan.core/vars.md) - Complete API

44
docs/site/guides/vars-overview.md
View File

@@ -16,9 +16,13 @@ users.users.root.hashedPasswordFile = "/tmp/root-password-hash";
```
This approach has several problems:
- **Not reproducible**: Manual steps vary between team members
- **Hard to maintain**: Updating secrets requires remembering manual commands
- **Deployment friction**: Secrets must be managed outside of your configuration
- **Team collaboration issues**: Sharing credentials securely is complex
### After Vars: Declarative Generation
@@ -85,46 +89,21 @@ The vars system has three main components:
### 1. **Generators**
Define how to create files from inputs:
- **Prompts**: Values requested from users
- **Scripts**: Generation logic
- **Dependencies**: Other generators this depends on
- **Outputs**: Files that get created
### 2. **Storage Backends**
Handle secret storage and deployment:
- **sops**: Encrypted files in git (recommended)
- **password-store**: GPG/age-based secret storage
- **vm**: For development/testing
### 3. **Integration**
Seamless NixOS integration:
- File paths available at build time
- Automatic deployment to machines
- Service restarts on changes
## Learning Path
Ready to get started? Follow this recommended path:
### 1. **🚀 Hands-On Tutorial**
[Vars Getting Started Guide](vars-backend.md)
Start here for a practical walkthrough with password generation.
### 2. **🏗️ Understand the Design**
[Vars Concepts & Architecture](vars-concepts.md)
Deep dive into design principles and advanced patterns.
### 3. **💡 Real-World Examples**
[Advanced Examples](vars-advanced-examples.md)
Complex scenarios including certificates, SSH keys, and databases.
### 4. **🔧 Troubleshooting**
[Troubleshooting Guide](vars-troubleshooting.md)
Solutions for common issues and debugging techniques.
### 5. **📚 Complete Reference**
- [NixOS Module Options](../reference/clan.core/vars.md)
- [CLI Commands](../reference/cli/vars.md)
## Quick Start Example
@@ -164,6 +143,3 @@ clan machines update my-machine
If you're currently using the legacy facts system, see our [Migration Guide](migrations/migration-facts-vars.md) for step-by-step instructions on upgrading to vars.
---
**Ready to start?** Head to the [Getting Started Guide](vars-backend.md) for your first hands-on experience with the vars system.

14
docs/site/guides/vars-troubleshooting.md
View File

@@ -1,6 +1,6 @@
# Troubleshooting Vars
Quick reference for diagnosing and fixing vars issues. For basic usage, see the [Getting Started guide](vars-backend.md).
Quick reference for diagnosing and fixing vars issues.
## Common Issues
@@ -240,8 +240,11 @@ clan vars list my-machine
**Solution**: Ensure your user/machine has the correct age keys configured. Clan manages encryption keys automatically based on the configured users and machines in your flake.
Check that:
1. Your machine is properly configured in the flake
2. Your user has access to the machine's secrets
3. The age key is available in the expected location
### Password Store Issues
@@ -261,6 +264,9 @@ If these solutions don't resolve your issue:
1. Check the [clan-core issue tracker](https://git.clan.lol/clan/clan-core/issues)
2. Ask in the Clan community channels
3. Provide:
- The generator configuration
- The exact error message
- Output of `clan --debug vars generate`
- The generator configuration
- The exact error message
- Output of `clan --debug vars generate`

2
docs/site/index.md
View File

@@ -55,7 +55,7 @@ Explore the underlying principles of Clan
<div class="grid cards" markdown>
- [Generators](./concepts/generators.md)
- [Vars](./guides/vars-overview.md)
---