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.