From 2e5a3e0802f9d5f3b45007aec3971a3663e8b312 Mon Sep 17 00:00:00 2001
From: "ryan-distrust.co" <ryan@hashbang.sh>
Date: Mon, 15 May 2023 21:51:31 -0400
Subject: [PATCH] docs: add guide for using sops

---
 docs/managing-secrets-with-sops.md | 55 ++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)
 create mode 100644 docs/managing-secrets-with-sops.md

diff --git a/docs/managing-secrets-with-sops.md b/docs/managing-secrets-with-sops.md
new file mode 100644
index 0000000..d40f300
--- /dev/null
+++ b/docs/managing-secrets-with-sops.md
@@ -0,0 +1,55 @@
+# Encrypting
+
+To encrypt a Kubernetes `v1/Secret` with sops from the command line:
+
+```sh
+sops --encrypt --encrypted-regex '^(data|stringData)$' --input-type=json --output-type=yaml <file>
+```
+
+`sops` does not recognize `-` as standard input, so to use standard input on
+Linux systems you can use `/dev/stdin`. Input type is set to `json` assuming
+the file passed in will be generated by `terraform`, but if made by hand can
+be set to `yaml` or, if using a filepath, omitted entirely.
+
+When a secret is available in Terraform's output, the following pattern can be
+used to extract the secret from Terraform and encrypt it to a Kubernetes
+Secret:
+
+```sh
+sops exec-env secrets/production.env \
+  'terraform c-chdir=infra/main output -json' \
+  | jq '.database_users.value.keycloak' \
+  | sops --encrypt --encrypted-regex '^(data|stringData)' --input-type=json --output-type=yaml /dev/stdin \
+  > kustomizations/keycloak/postgres-auth.enc.yaml
+```
+
+# Decrypting
+
+To decrypt a Kubernetes `v1/Secret` encrypted with sops, using `ksops`:
+
+```yaml
+# secret.enc.yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: secret-stuff
+stringData:
+  hello: "ENC[AES256_GCM,data:9m+JbWLI=,tag:KTOvMahnDdOnmAEAqzfaMw==,type:str]"
+---
+# secret-generator.yaml
+apiVersion: viaduct.ai/v1
+kind: ksops
+metadata:
+  name: ksops
+files:
+- ./secret.enc.yaml
+# kustomization.yaml
+generators:
+- secret-generator.yaml
+```
+
+When running `kustomize`, be sure to pass the `--enable-alpha-plugins` flag.
+
+# Editing
+
+`sops <file>`