add examples to docs site

docs/content/examples/image/_index.md

@@ -0,0 +1,66 @@
+---
+weight: 30
+---
+
+Instead of deploying a 3rd party image, we can build our own.
+
+We rely on the upstream [`dockerTools`](https://github.com/NixOs/nixpkgs/tree/master/pkgs/built-support/docker) package here.
+Specifically, we can use the `buildImage` function to define our image:
+
+{{< source "image.nix" >}}
+
+Then we can import this package into our `docker` module:
+
+{{< source "default.nix" >}}
+
+Now build the image with
+
+```sh
+nix build -f . --json config.docker.export
+```
+
+Render the generated manifests again and see that it now refers to the newly built tag:
+
+```json
+{
+  "apiVersion": "v1",
+  "items": [
+    {
+      "apiVersion": "v1",
+      "kind": "Pod",
+      "metadata": {
+        "annotations": {
+          "kubenix/k8s-version": "1.24",
+          "kubenix/project-name": "kubenix"
+        },
+        "labels": {
+          "kubenix/hash": "ac7e4794c3d37f0884e4512a680a30d20e1d6454"
+        },
+        "name": "example"
+      },
+      "spec": {
+        "containers": [
+          {
+            "image": "docker.somewhere.io/nginx:w7c63alk7kynqh2mqnzxy9n1iqgdc93s",
+            "name": "custom"
+          }
+        ]
+      }
+    }
+  ],
+  "kind": "List",
+  "labels": {
+    "kubenix/hash": "ac7e4794c3d37f0884e4512a680a30d20e1d6454",
+    "kubenix/k8s-version": "1.24",
+    "kubenix/project-name": "kubenix"
+  }
+}
+```
+
+Of course, to actually deploy, we need to push the image to our registry. The script defined at {{< option "docker.copyScript" >}} does just that.
+
+```sh
+$(nix build -f . --json config.docker.copyScript | jq -r '.[].outputs.out')
+```
+
+ <!-- TODO: can we make that `nix run -f . config.docker.copyScript` ? -->

docs/content/examples/image/default.nix

@@ -0,0 +1,13 @@
+{ kubenix ? import ../../../.. }:
+kubenix.evalModules.${builtins.currentSystem} {
+  module = {kubenix, config, pkgs, ...}: {
+    imports = with kubenix.modules; [k8s docker];
+    docker = {
+      registry.url = "docker.somewhere.io";
+      images.example.image =  pkgs.callPackage ./image.nix {};
+    };
+    kubernetes.resources.pods.example.spec.containers = {
+      custom.image = config.docker.images.example.path;
+    };
+  };
+}

docs/content/examples/image/image.nix

@@ -0,0 +1,20 @@
+{
+  dockerTools,
+  nginx,
+}:
+dockerTools.buildLayeredImage {
+  name = "nginx";
+  contents = [nginx];
+  extraCommands = ''
+    mkdir -p etc
+    chmod u+w etc
+    echo "nginx:x:1000:1000::/:" > etc/passwd
+    echo "nginx:x:1000:nginx" > etc/group
+  '';
+  config = {
+    Cmd = ["nginx" "-c" "/etc/nginx/nginx.conf"];
+    ExposedPorts = {
+      "80/tcp" = {};
+    };
+  };
+}