From b6fe22b09d9453e56ac26fb4bcfb83c26a79e9d2 Mon Sep 17 00:00:00 2001
From: Bryton Hall <email@bryton.io>
Date: Sat, 8 Jul 2023 02:07:58 -0400
Subject: [PATCH] docs: add gitops and more secret managing schemes

---
 docs/content/examples/secrets/_index.md       | 16 ------
 .../{k3s/_index.md => deploy.md}              | 21 +++++++
 docs/content/tips-n-tricks/secrets/_index.md  | 56 +++++++++++++++++++
 .../secrets/default.nix                       |  0
 4 files changed, 77 insertions(+), 16 deletions(-)
 delete mode 100644 docs/content/examples/secrets/_index.md
 rename docs/content/tips-n-tricks/{k3s/_index.md => deploy.md} (64%)
 create mode 100644 docs/content/tips-n-tricks/secrets/_index.md
 rename docs/content/{examples => tips-n-tricks}/secrets/default.nix (100%)

diff --git a/docs/content/examples/secrets/_index.md b/docs/content/examples/secrets/_index.md
deleted file mode 100644
index c132e06..0000000
--- a/docs/content/examples/secrets/_index.md
+++ /dev/null
@@ -1,16 +0,0 @@
-A good runtime secret option (thus avoiding exposing them in the nix store) is loading values with [vals](https://github.com/variantdev/vals).
-A minimal example, using the file provider, might look like
-
-{{< source "default.nix" >}}
-
-{{< hint info >}}
-**NOTE**: The creation of `/path/to/secret` is out of scope but we recommend checking out one of the [secret managing schemes](https://nixos.wiki/wiki/Comparison_of_secret_managing_schemes).
-{{< /hint >}}
-
-Then it's up to you when and where to apply from with something along the lines of:
-
-```nix
-pkgs.writeShellScript "apply" ''
-  cat /path/to/manifests | ${pkgs.vals}/bin/vals eval | ${pkgs.kubectl}/bin/kubectl -f -
-''
-```
diff --git a/docs/content/tips-n-tricks/k3s/_index.md b/docs/content/tips-n-tricks/deploy.md
similarity index 64%
rename from docs/content/tips-n-tricks/k3s/_index.md
rename to docs/content/tips-n-tricks/deploy.md
index 831331c..448e311 100644
--- a/docs/content/tips-n-tricks/k3s/_index.md
+++ b/docs/content/tips-n-tricks/deploy.md
@@ -1,3 +1,24 @@
+Kubenix is compatible with any tooling that can ingest standard Kubernetes manifests.
+
+## gitops
+
+Instead of push-based deploys with `kubectl`, tools like [ArgoCD](https://argo-cd.readthedocs.io/en/stable/) or [Flux](https://fluxcd.io/) can be used to pull manifests from a git repo.
+
+Some advantages here are
+
+- git as the source of record
+- easy rollbacks
+- resource pruning
+
+While some tradeoffs include
+
+- additional complexity (in exchange for flexibility)
+- out-of-band deployments can be more difficult to debug and hook into
+
+Once setup, deployments are as simple as writing manifests to a git repo.
+
+## k3s
+
 The k3s project supports [automatic resource deployment](https://docs.k3s.io/installation/packaged-components#auto-deploying-manifests-addons) of files in the `/var/lib/rancher/k3s/server/manifests` directory.
 
 As such, on a server node, we can write kubenix's output there.
diff --git a/docs/content/tips-n-tricks/secrets/_index.md b/docs/content/tips-n-tricks/secrets/_index.md
new file mode 100644
index 0000000..8950bbe
--- /dev/null
+++ b/docs/content/tips-n-tricks/secrets/_index.md
@@ -0,0 +1,56 @@
+As the nix store is world-readable, we want to avoid writing secrets during evaluation.
+
+We can roughly break the entire process, from nix to kube, down to
+
+    eval -> deploy -> run
+
+## eval time
+
+This is the process of taking nix configuration and generating a JSON manifest.
+
+The generated manifest is written to the nix store;
+so inlining (unencrypted) secrets is entirely possible but not ideal.
+
+## deploy time
+
+The simplest option is to inject secrets during deploy; that is, after manifests have been generated but prior to running `kubectl apply` (or equivalent).
+
+### example
+
+We can pipe manifests through [vals](https://github.com/variantdev/vals) prior to apply.
+Such that using the file provider might look like
+
+{{< source "default.nix" >}}
+
+{{< hint info >}}
+**NOTE**: the creation of `/path/to/secret` is out of scope but we recommend checking out one of the [secret managing schemes](https://nixos.wiki/wiki/Comparison_of_secret_managing_schemes)
+{{< /hint >}}
+
+Then the apply might look something like
+
+```nix
+pkgs.writeShellScript "apply" ''
+  cat manifest.json | ${pkgs.vals}/bin/vals eval | ${pkgs.kubectl}/bin/kubectl -f -
+''
+```
+
+{{< hint info >}}
+**NOTE**: the builtin `kubenix` CLI uses this approach so it's not _necessary_ to implement yourself
+{{< /hint >}}
+
+
+## runtime
+
+A more robust option is to resolve secrets from _within_ the cluster itself.
+
+This can be done with tools that either
+
+- reference external sources 
+
+    similar to the deploy time example; instead, resolving secrets with a controller running inside the cluster (e.g., [external-secrets](https://github.com/external-secrets/external-secrets))
+
+- decrypt inline secrets
+
+    values can be decrypted by a controller within the cluster itself (e.g., [sealed-secrets](https://github.com/bitnami-labs/sealed-secrets)) or using external keys (e.g., [sops](https://github.com/getsops/sops))
+
+    
\ No newline at end of file
diff --git a/docs/content/examples/secrets/default.nix b/docs/content/tips-n-tricks/secrets/default.nix
similarity index 100%
rename from docs/content/examples/secrets/default.nix
rename to docs/content/tips-n-tricks/secrets/default.nix