Skip to content

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 to understand how they work. There is also a bare-bones template.

nixlet.nix

Example
{
  name = "attic";
  version = "0.0.1";
  description = "Multi-tenant Nix Binary Cache";
  defaultProject = "attic";
}

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.

Usage without nixlet.nix
mkNixlet {
  name = "";
  version = "";
  # etc.
}
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

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:

Simple string value
hello = mkOption {
  type = types.str;
  default = "World";
  description = "Hello world!";
}

The end-user using your Nixlet can then do this:

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.

# 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.

{nixlet, ...}:
with nixlet; {
  imports = [./some-resource.nix];
  # or directly
  kubernetes.resources.configMaps."${values.uniqueName}-config".data.hello = values.hello;
}