README.md

kubenix

Kubernetes management with Nix

WARN: this is a work in progress, expect breaking changes

Usage

A minimal example flake.nix (build with nix build):

{
  inputs.kubenix.url = "github:hall/kubenix";
  outputs = {self, kubenix, ... }@inputs: let
    system = "x86_64-linux";
  in {
    packages.${system}.default = (kubenix.evalModules.${system} {
      module = { kubenix, ... }: {
        imports = [ kubenix.modules.k8s ];
        kubernetes.resources.pods.example.spec.containers.nginx.image = "nginx";
      };
    }).config.kubernetes.result;
  };
}

Or, if you're not using flakes, a default.nix file (build with nix-build):

{ kubenix ? import (builtins.fetchGit {
  url = "https://github.com/hall/kubenix.git";
  ref = "main";
}) }:
(kubenix.evalModules.x86_64-linux {
  module = { kubenix, ... }: {
    imports = [ kubenix.modules.k8s ];
    kubernetes.resources.pods.example.spec.containers.nginx.image = "nginx";
  };
}).config.kubernetes.result

Either way the JSON manifests will be written to ./result.

See the examples for more.

CLI

While kubenix is compatible with just about any deployment system, there's a simple builtin CLI which can:

• show a diff, prompt for confirmation, then apply
• prune removed resources
• pipe manifests through vals for the ability to inject secrets without writing them to the nix store

To configure this, override the default package, passing the arguments of evalModules.

{
  kubenix = inputs.kubenix.packages.${pkgs.system}.default.override {
    module = import ./cluster;
    # optional; pass custom values to the kubenix module
    specialArgs = { flake = self; };
  };
}

Then apply the resources with

nix run '.#kubenix'

which will print a diff and prompt for confirmation:

diff -N -u -I ' kubenix/hash: ' -I ' generation: ' /tmp/LIVE-2503962153/apps.v1.Deployment.default.home-assistant /tmp/MERGED-231044561/apps.v1.Deployment.default.home-assistant
--- /tmp/LIVE-2503962153/apps.v1.Deployment.default.home-assistant      2023-07-06 23:33:29.841771295 -0400
+++ /tmp/MERGED-231044561/apps.v1.Deployment.default.home-assistant     2023-07-06 23:33:29.842771296 -0400
@@ -43,7 +43,7 @@
     spec:
       automountServiceAccountToken: true
       containers:
-      - image: homeassistant/home-assistant:2023.5
+      - image: homeassistant/home-assistant:2023.6
         imagePullPolicy: IfNotPresent
         livenessProbe:
           failureThreshold: 3
apply? [y/N]:

HINT: use --help for more commands

Optionally, write the resources to ./result/manifests.json:

nix build '.#kubenix'

Attribution

This project was forked from GTrunSec, which was forked from xtruder, with commits incorporated from blaggacao.

Logo is a mishmash of the Kubernetes wheel and the NixOs snowflake.