technofab/nixible
1
0
Fork 0
mirror of https://gitlab.com/TECHNOFAB/nixible.git synced 2025-12-11 01:30:10 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

feat: add more options and generate docs for all options

Browse source
This commit is contained in:
technofab 2025-08-09 20:49:11 +02:00
parent ba08a453ea
commit 8dccb9a9a8
No known key found for this signature in database
5 changed files with 213 additions and 166 deletions
Download patch file Download diff file Expand all files Collapse all files

3
docs/options.md Normal file
View file

@ -0,0 +1,3 @@
# Options
{% include 'options.md' %}

130
docs/reference.md
View file

@ -84,132 +84,6 @@ mkNixibleCli config
Creates a CLI executable for your Nixible configuration.
Basically `(mkNixible config).config.cli`.
## Configuration Options
______________________________________________________________________
### `ansiblePackage`
**Type:** `package`
**Default:** Custom ansible-core package
The Ansible package to use. The default package is optimized for size, by not
including the gazillion collections that `pkgs.ansible` and `pkgs.ansible-core` include.
```nix
ansiblePackage = pkgs.ansible;
```
### `collections`
**Type:** `attrsOf collectionType`
**Default:** `{}`
Ansible collections to fetch from Galaxy.
```nix
collections = {
"community-general" = {
version = "8.0.0";
hash = "sha256-...";
};
};
```
### `dependencies`
**Type:** `listOf package`
**Default:** `[]`
Additional packages available at runtime.
```nix
dependencies = [pkgs.git pkgs.rsync];
```
### `inventory`
**Type:** `attrs`
**Default:** `{}`
Ansible inventory as Nix data structure, converted to JSON.
```nix
inventory = {
webservers = {
hosts = {
web1 = { ansible_host = "192.168.1.10"; };
};
vars = {
http_port = 80;
};
};
};
```
### `playbook`
**Type:** `listOf playbookType`
List of plays that make up the playbook.
```nix
playbook = [
{
name = "Configure servers";
hosts = "webservers";
become = true;
tasks = [
{
name = "Install nginx";
package = {
name = "nginx";
state = "present";
};
}
];
}
];
```
## Collection Type
### `version`
**Type:** `str`
Version of the collection from Ansible Galaxy.
### `hash`
**Type:** `str`
SHA256 hash of the collection tarball for verification.
## Playbook Type
### `name`
**Type:** `str`
Name of the play.
### `hosts`
**Type:** `str`
Target hosts pattern (e.g., "all", "webservers", "localhost").
### `become`
**Type:** `bool`
**Default:** `false`
Whether to use privilege escalation.
### `tasks`
**Type:** `listOf attrs`
**Default:** `[]`
List of tasks to execute. Each task corresponds to Ansible task syntax.
Standard Ansible playbook options are supported: `gather_facts`, `serial`, `vars`, `vars_files`, `tags`, `handlers`, `pre_tasks`, `post_tasks`, etc.
See [options](./options.md) for more.

7
flake.lock generated
View file

@ -230,16 +230,17 @@
"nix-mkdocs": {
"locked": {
"dir": "lib",
"lastModified": 1745841841,
"narHash": "sha256-297zPQbUlc7ZAYDoaD6mCmQxCC3Tr4YOKekRF1ArZ7g=",
"lastModified": 1754753501,
"narHash": "sha256-k7KEGQ7qejmwrSXVSvZ9zVD1H+ZtNm0I5fmCVmZVi+4=",
"owner": "technofab",
"repo": "nixmkdocs",
"rev": "c7e3c3b13ded25818e9789938387bba6f2cde690",
"rev": "aba4f26f320b15043101824b65e72058ecab296f",
"type": "gitlab"
},
"original": {
"dir": "lib",
"owner": "technofab",
"ref": "v1.0.0",
"repo": "nixmkdocs",
"type": "gitlab"
}

38
flake.nix
View file

@ -17,6 +17,7 @@
perSystem = {
lib,
pkgs,
self',
config,
...
}: {
@ -42,6 +43,7 @@
path = ./docs;
deps = pp: [
pp.mkdocs-material
pp.mkdocs-macros
(pp.callPackage inputs.mkdocs-material-umami {})
];
config = {
@ -78,12 +80,21 @@
}
];
};
plugins = ["search" "material-umami"];
plugins = [
"search"
"material-umami"
{
macros = {
include_dir = self'.packages.optionsDocs;
};
}
];
nav = [
{"Introduction" = "index.md";}
{"Usage" = "usage.md";}
{"Examples" = "examples.md";}
{"Reference" = "reference.md";}
{"Options" = "options.md";}
];
markdown_extensions = [
"pymdownx.superfences"
@ -174,13 +185,34 @@
packages = let
nblib = import ./lib {inherit pkgs lib;};
ntlib = inputs.nixtest.lib {inherit pkgs lib;};
in {
doclib = inputs.nix-mkdocs.lib {inherit lib pkgs;};
in rec {
tests = ntlib.mkNixtest {
modules = ntlib.autodiscover {dir = ./tests;};
args = {
inherit pkgs nblib ntlib;
};
};
optionsDoc = doclib.mkOptionDocs {
module = {
imports = [
nblib.module
{
_module.args.pkgs = pkgs;
}
];
};
roots = [
{
url = "https://gitlab.com/TECHNOFAB/nixible/-/blob/main/lib";
path = toString ./lib;
}
];
};
optionsDocs = pkgs.runCommand "options-docs" {} ''
mkdir -p $out
ln -s ${optionsDoc} $out/options.md
'';
};
};
};
@ -195,7 +227,7 @@
treefmt-nix.url = "github:numtide/treefmt-nix";
nix-gitlab-ci.url = "gitlab:technofab/nix-gitlab-ci?dir=lib";
nixtest.url = "gitlab:technofab/nixtest?dir=lib";
nix-mkdocs.url = "gitlab:technofab/nixmkdocs?dir=lib";
nix-mkdocs.url = "gitlab:technofab/nixmkdocs/v1.0.0?dir=lib";
mkdocs-material-umami.url = "gitlab:technofab/mkdocs-material-umami";
};

201
lib/module.nix
View file

@ -4,7 +4,7 @@
config,
...
}: let
inherit (lib) mkOptionType isType filterAttrs types mkOption;
inherit (lib) mkOptionType isType filterAttrs types mkOption literalExpression;
unsetType = mkOptionType {
name = "unset";
@ -16,7 +16,11 @@
_type = "unset";
};
isUnset = isType "unset";
unsetOr = types.either unsetType;
unsetOr = typ:
(types.either unsetType typ)
// {
description = typ.description;
};
filterUnset = value:
if builtins.isAttrs value && !builtins.hasAttr "_type" value
@ -28,93 +32,226 @@
then builtins.filter (elem: !isUnset elem) (map filterUnset value)
else value;
mkUnsetOption = args:
mkOption args
// {
type = unsetOr args.type;
default = unset;
defaultText = literalExpression "unset";
};
collectionType = types.submodule {
options = {
version = mkOption {
type = types.str;
description = "Version of collection";
description = ''
Version of the collection.
'';
example = "1.0.0";
};
hash = mkOption {
type = types.str;
description = "Hash of the collection tarball";
description = ''
SHA256 hash of the collection tarball for verification.
'';
example = "sha256-...";
};
};
};
tasksType = types.submodule {
freeformType = types.attrsOf (types.attrsOf types.anything);
options = {
name = mkOption {
type = unsetOr types.str;
default = unset;
name = mkUnsetOption {
type = types.str;
description = ''
Name of the task.
'';
};
register = mkOption {
type = unsetOr types.str;
default = unset;
register = mkUnsetOption {
type = types.str;
description = ''
Register the task's output to a variable.
'';
};
block = mkOption {
type = unsetOr (types.listOf tasksType);
default = unset;
block = mkUnsetOption {
type = types.listOf tasksType;
description = ''
A block of tasks to execute.
'';
};
always = mkOption {
type = unsetOr (types.listOf types.attrs);
default = unset;
rescue = mkUnsetOption {
type = types.listOf tasksType;
description = ''
A list of tasks to execute on failure of block tasks.
'';
};
always = mkUnsetOption {
type = types.listOf types.attrs;
description = ''
Tasks that always run, regardless of task status.
'';
};
delegate_to = mkUnsetOption {
type = types.str;
description = ''
Delegate task execution to another host.
'';
};
ignore_errors = mkUnsetOption {
type = types.bool;
description = ''
Ignore errors and continue with the playbook.
'';
};
loop = mkUnsetOption {
type = types.anything;
description = ''
Define a loop for the task.
'';
};
when = mkUnsetOption {
type = types.str;
description = ''
Condition under which the task runs.
'';
};
};
};
playbookType = types.listOf (types.submodule {
playType = types.submodule {
freeformType = types.attrsOf (types.attrsOf types.anything);
options = {
name = mkOption {
type = types.str;
description = "Name of the play";
description = ''
Name of the play.
'';
};
hosts = mkOption {
type = types.str;
description = "The target hosts for this play (e.g., 'all', 'webservers')";
description = ''
The target hosts for this play (e.g., 'all', 'webservers').
'';
example = "all";
};
become = mkOption {
type = unsetOr types.bool;
default = unset;
description = "Whether to use privilege escalation (become: yes)";
remote_user = mkUnsetOption {
type = types.str;
description = ''
The user to execute tasks as on the remote server.
'';
};
gather_facts = mkOption {
type = unsetOr types.bool;
default = unset;
description = "";
tags = mkUnsetOption {
type = types.listOf types.str;
description = ''
Tags to filter tasks to run.
'';
};
become = mkUnsetOption {
type = types.bool;
description = ''
Whether to use privilege escalation (become: yes).
'';
};
become_method = mkUnsetOption {
type = types.str;
description = ''
Privilege escalation method.
'';
};
vars = mkUnsetOption {
type = types.attrs;
description = ''
Variables for the play.
'';
};
gather_facts = mkUnsetOption {
type = types.either types.bool types.str;
description = ''
Whether to run the setup module to gather facts before executing tasks.
'';
};
when = mkUnsetOption {
type = types.str;
description = ''
Condition under which the play runs.
'';
};
tasks = mkOption {
type = types.listOf tasksType;
default = [];
description = "List of tasks to execute in this play";
description = ''
List of tasks to execute in this play
'';
};
};
});
};
playbookType = types.listOf playType;
in {
options = {
ansiblePackage = mkOption {
type = types.package;
default = pkgs.python3Packages.callPackage ./ansible-core.nix {};
description = "Ansible package to use (default doesn't have any collections installed for size)";
description = ''
The Ansible package to use. The default package is optimized for size, by not including the gazillion collections that pkgs.ansible and pkgs.ansible-core include.
'';
example = literalExpression "pkgs.ansible";
};
collections = mkOption {
type = types.attrsOf collectionType;
default = {};
description = "Collections to fetch and install";
description = ''
Ansible collections to fetch and install from Galaxy.
'';
example = {
"community-general" = {
version = "8.0.0";
hash = "sha256-...";
};
};
};
dependencies = mkOption {
type = types.listOf types.package;
default = [];
description = "List of packages to include at runtime";
example = literalExpression "[pkgs.git pkgs.rsync]";
};
playbook = mkOption {
type = playbookType;
apply = res: filterUnset res;
description = "The actual playbook, defined as a Nix data structure";
example = [
{
name = "Configure servers";
hosts = "webservers";
become = true;
tasks = [
{
name = "Install nginx";
package = {
name = "nginx";
state = "present";
};
}
];
}
];
};
inventory = mkOption {
type = types.attrs;
default = {};
description = "Ansible inventory, will be converted to json and passed to ansible";
description = ''
Ansible inventory, will be converted to JSON and passed to Ansible.
'';
example = {
webservers = {
hosts = {
web1 = {ansible_host = "192.168.1.10";};
};
vars = {
http_port = 80;
};
};
};
};
inventoryFile = mkOption {