Kubenix

You can register Custom Resource Definitions (CRDs) in Kubenix to enable type-safe definitions of custom resources using Nix options. To do this, add an entry to the kubernetes.customTypes list. Each entry must specify the group, version, kind, and a Nix module that defines the schema for that resource.

# Conceptual structure for kubernetes.customTypes
kubernetes.customTypes = [
  {
    group = "stable.example.com";
    version = "v1";
    kind = "CronTab";
    module = ./path/to/your/schema.nix;
  }
];

For a more robust security model, resolve secrets from within the Kubernetes cluster itself. This can be achieved in two ways:

1. Reference external sources: Use a controller running inside the cluster (such as external-secrets) to fetch secrets from an external provider.
2. Decrypt inline secrets: Use a controller or tool within the cluster to decrypt secrets that were included in the manifest (such as sealed-secrets or using sops with external keys).

Kubenix uses a submodule system (built on top of the NixOS submodule system) to allow for the creation of resources across multiple Kubernetes namespaces. By defining a submodule, you can encapsulate resource definitions and then instantiate them multiple times with different namespace parameters.

To implement this pattern:

1. Define a submodule using Nix syntax to specify the required parameters (like namespace).
2. Use the submodule within a main module to instantiate resources for specific namespaces.

# Example pattern for a submodule definition
# (Referenced in the documentation via namespaced.nix)

# Example pattern for usage
# (Referenced in the documentation via module.nix)

After defining a custom type in kubernetes.customTypes, you can instantiate specific resources by adding them to the kubernetes.resources.<attrName> attribute set, where <attrName> matches the name used during definition.

For example, if you define a type with the name crontabs, you would define your resource instances under kubernetes.resources.crontabs. The resulting Kubernetes manifest will include the apiVersion, kind, metadata, and the spec defined by your Nix schema.

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

The simplest method is to inject secrets after manifests are generated but before they are applied to the cluster. You can pipe your generated manifests through vals to resolve secret values (e.g., using the file provider) before passing them to kubectl.

pkgs.writeShellScript "apply" ''
  cat manifest.json | ${pkgs.vals}/bin/vals eval | ${pkgs.kubectl}/bin/kubectl -f -
  ''

After building the image, you must push it to a registry before deployment. You can execute the script defined in config.docker.copyScript by building it and running the resulting path.

$(nix build -f . --print-out-paths config.docker.copyScript)

To build the image and generate the necessary configuration, use the nix build command targeting the config.docker.export path. This will produce the manifests that reference your newly built image tag.

nix build -f . --json config.docker.export

To define a Helm release in Kubenix, use the kubernetes.helm.releases option. This allows you to fetch and render Helm charts as part of your configuration evaluation, similar to how plain Kubernetes manifests are handled.

# Example of defining a Helm release
kubernetes.helm.releases = { ... };