From 0d04ae9c22938dbd7eb4f0821800096960c54edd Mon Sep 17 00:00:00 2001
From: Doug Goldstein <doug.goldstein@rackspace.com>
Date: Tue, 5 Mar 2024 16:57:21 -0600
Subject: [PATCH] docs: craft a gitops focused installation

---
 docs/gitops-install.md | 91 ++++++++++++++++++++++++++++++++++++++++++
 mkdocs.yml             |  1 +
 2 files changed, 92 insertions(+)
 create mode 100644 docs/gitops-install.md

diff --git a/docs/gitops-install.md b/docs/gitops-install.md
new file mode 100644
index 000000000..0942aa96c
--- /dev/null
+++ b/docs/gitops-install.md
@@ -0,0 +1,91 @@
+# GitOps based Install
+
+This guide is not meant to be a definitive guide to [GitOps][gitops] and
+how it can be used with UnderStack or even a best practices example
+but instead focused on an example development oriented installation.
+It will make a few assumptions and some opinionated choices that may
+not align with a production best practices installation.
+Most notable assumptions are:
+
+- [GitOps][gitops] tooling runs on the same cluster as the deploy
+- AIO (All-in-One) configuration
+- Your cluster is a blank slate and can be entirely consumed
+
+You will have the source to your deployment and all the pre-deployment
+work will occur on your local machine and not on any of the target
+machines.
+
+## Getting the source
+
+You must fetch the source to this repo and since we will be using
+[GitOps][gitops], you must also have a deployment repo. These
+operations can all happen locally on your development machine.
+
+```bash
+git clone https://github.com/rackerlabs/understack
+# then either
+git init my-deploy
+# or
+git clone https://path/to/my/deploy
+```
+
+The remainder of this guide will assume you've set the following
+environment variables:
+
+```bash
+export US_REPO=$(pwd)/understack
+export US_DEPLOY=$(pwd)/uc-deploy
+```
+
+## Pre-deployment
+
+Embracing GitOps and declarative configuration, we will define three
+distinct pieces of information for your deployment.
+
+- Infrastructure: Where the software will live
+- Secrets: What are all the credentials, passwords, etc needed by the software
+- Cluster: The actual software that will be deployed
+
+To properly scope this you'll need an environment name. For the
+purposes of this document we'll call it `my-k3s`. To create the space to
+work from you can run the following:
+
+```bash
+mkdir -p ${US_DEPLOY}/infrastructure/my-k3s
+mkdir -p ${US_DEPLOY}/secrets/my-k3s
+mkdir -p ${US_DEPLOY}/clusters/my-k3s
+```
+
+### Populating the infrastructure
+
+TODO: some terraform template examples for building infra
+
+### Generating secrets
+
+Secrets in their very nature are sensitive pieces of data. The ultimate
+storage and injection of these in a production environment needs to be
+carefully considered. For the purposes of this document no specific
+choice has been made but tools like Vault, Sealed Secrets, SOPS, etc
+should be considered. This will only generate the necessary secrets
+using random data to sucessfully continue the installation.
+
+TODO: probably give at least one secure example
+
+```bash
+${US_REPO}/scripts/quick-secrets-gen.sh "${US_DEPLOY}/secrets/my-k3s"
+cd ${US_DEPLOY}
+git add secrets/my-k3s
+git commit -m "my-k3s: secrets generation"
+```
+
+### Defining the app deployment
+
+In this section we will use the [App of Apps][app-of-apps] pattern to define
+the deployment of all the components of UnderStack.
+
+TODO: Thinking maybe we make a helm chart and have people run
+`helm template --output-dir "${US_DEPLOY}/cluster/my-k3s"` in
+this step?
+
+[gitops]: <https://about.gitlab.com/topics/gitops/>
+[app-of-apps]: <https://argo-cd.readthedocs.io/en/stable/operator-manual/cluster-bootstrapping/>
diff --git a/mkdocs.yml b/mkdocs.yml
index ed0f68e10..3b70f9aa1 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -53,3 +53,4 @@ nav:
   - openstack-helm.md
   - secrets.md
   - install-understack-ubuntu-k3s.md
+  - gitops-install.md