Custom Resources

The kubernetes.customTypes option allows you to register Custom Resource Definitions (CRDs) with Kubenix. This enables type-safe definition of custom resources using Nix options.

Defining Custom Types #

To register a CRD, add an entry to the kubernetes.customTypes list. Each entry defines the Group, Version, Kind, and the Nix module that describes the schema of the resource.

Example #

    module.nix

{ kubenix, config, lib, ... }: {
  imports = [ kubenix.modules.k8s ];

  # 1. Define the Custom Resource Definition (CRD)
  # This tells Kubenix about the new resource type so it can generate options for it.
  kubernetes.customTypes = [{
    group = "stable.example.com";
    version = "v1";
    kind = "CronTab";
    # The attribute name to use under `kubernetes.resources`
    attrName = "crontabs";
    # Define the schema of the custom resource using Nix options
    module = {
      options = {
        cronSpec = lib.mkOption {
          description = "Cron schedule";
          type = lib.types.str;
        };
        image = lib.mkOption {
          description = "Image to run";
          type = lib.types.str;
        };
        replicas = lib.mkOption {
          description = "Number of replicas";
          type = lib.types.int;
          default = 1;
        };
      };
    };
  }];

  # 2. Instantiate the Custom Resource
  # Now we can use the `crontabs` attribute to define resources.
  kubernetes.resources.crontabs.my-new-cron-object = {
    metadata.name = "my-new-cron-object";
    spec.cronSpec = "* * * * */5";
    spec.image = "my-awesome-cron-image";
  };
}

Instantiation #

Once a custom type is defined, you can instantiate resources under kubernetes.resources.<attrName>. In the example above, we set attrName = "crontabs", so we can define resources under kubernetes.resources.crontabs.

The generated JSON output will look something like this:

{
  "apiVersion": "stable.example.com/v1",
  "kind": "CronTab",
  "metadata": {
    "name": "my-new-cron-object",
     ...
  },
  "spec": {
    "cronSpec": "* * * * */5",
    "image": "my-awesome-cron-image",
    "replicas": 1
  }
}