mirror of
https://gitlab.com/TECHNOFAB/nixlets.git
synced 2025-12-12 01:50:05 +01:00
116 lines
2.7 KiB
Markdown
116 lines
2.7 KiB
Markdown
# Creating Nixlets
|
|
|
|
Nixlets need a `default.nix` and a `values.nix` (a `nixlet.nix` containing the metadata is also recommended).
|
|
|
|
Check out the existing [nixlets](https://gitlab.com/technofab/nixlets/-/tree/main/nixlets) to understand how they work.
|
|
There is also a bare-bones [template](https://gitlab.com/technofab/nixlets/-/tree/main/template/).
|
|
|
|
## `nixlet.nix`
|
|
|
|
```nix title="Example"
|
|
{
|
|
name = "attic";
|
|
version = "0.0.1";
|
|
description = "Multi-tenant Nix Binary Cache";
|
|
defaultProject = "attic";
|
|
}
|
|
```
|
|
|
|
<!-- TODO: more description, also show how it works without this file -->
|
|
|
|
It's best to create a file `nixlet.nix` for your Nixlet. It's possible to create
|
|
Nixlets without this file, by passing the metadata directly to `mkNixlet`, but
|
|
when you intend to package the Nixlet this won't work, because when fetching
|
|
Nixlets it expects the metadata.
|
|
|
|
```nix title="Usage without nixlet.nix"
|
|
mkNixlet {
|
|
name = "";
|
|
version = "";
|
|
# etc.
|
|
}
|
|
```
|
|
|
|
```nix title="Usage with nixlet.nix"
|
|
mkNixlet ./path;
|
|
```
|
|
|
|
Metadata:
|
|
|
|
- `name`: Name of the Nixlet
|
|
- `version`: Version of the Nixlet itself (like Helm Chart version)
|
|
- `description`: Short description of the Nixlet
|
|
- `defaultProject`: Kubenix has the concept of projects.
|
|
This makes it possible to use the same Nixlet multiple times by specifying
|
|
different projects. This is typically included in the resources' names.
|
|
(see also `uniqueName` below)
|
|
|
|
## `values.nix`
|
|
|
|
```nix title="Template"
|
|
{
|
|
lib,
|
|
utils,
|
|
nixlet,
|
|
...
|
|
}:
|
|
with lib;
|
|
with utils;
|
|
with nixlet; {
|
|
# for some basic values see https://github.com/helm/examples/blob/4888ba8fb8180dd0c36d1e84c1fcafc6efd81532/charts/hello-world/values.yaml
|
|
options = {
|
|
# define values here
|
|
};
|
|
}
|
|
```
|
|
|
|
In `values.nix` you declare options the end-user can set.
|
|
This uses the NixOS/nixpkgs module system.
|
|
|
|
To create a simple string input you can add this in the `options = {}` above:
|
|
|
|
```nix title="Simple string value"
|
|
hello = mkOption {
|
|
type = types.str;
|
|
default = "World";
|
|
description = "Hello world!";
|
|
}
|
|
```
|
|
|
|
The end-user using your Nixlet can then do this:
|
|
|
|
```nix title="Usage"
|
|
nixlet.render {
|
|
# ...
|
|
values = {
|
|
hello = "Nixlets";
|
|
};
|
|
}
|
|
```
|
|
|
|
It is recommended to use an option like seen below to create a unique name for the Nixlet's resources.
|
|
|
|
```nix
|
|
# internal
|
|
uniqueName = mkOption {
|
|
internal = true;
|
|
type = types.str;
|
|
default = "${project}-atticd"; # example for atticd
|
|
};
|
|
```
|
|
|
|
Then use that in your resource names like seen below.
|
|
|
|
## `default.nix`
|
|
|
|
This file is the entrypoint to your Nixlet. You can define all the resources
|
|
in this file directly or import other files.
|
|
|
|
```nix
|
|
{nixlet, ...}:
|
|
with nixlet; {
|
|
imports = [./some-resource.nix];
|
|
# or directly
|
|
kubernetes.resources.configMaps."${values.uniqueName}-config".data.hello = values.hello;
|
|
}
|
|
```
|