From 87eee8ab082ec5cc34e7afbd1b5166f2ed503a34 Mon Sep 17 00:00:00 2001
From: Doug Goldstein <doug.goldstein@rackspace.com>
Date: Tue, 10 Dec 2024 08:39:29 -0600
Subject: [PATCH] docs: start to break up and define the deployment

Start to break up the docs from the quick start into each component step
so that it's more clear how things are intended to be deployed.
---
 docs/deploy-guide/deploy-repo.md     | 39 ++++++++++++++++++++++++++++
 docs/deploy-guide/getting-started.md | 21 +++++++++++++++
 mkdocs.yml                           |  2 ++
 3 files changed, 62 insertions(+)
 create mode 100644 docs/deploy-guide/deploy-repo.md
 create mode 100644 docs/deploy-guide/getting-started.md

diff --git a/docs/deploy-guide/deploy-repo.md b/docs/deploy-guide/deploy-repo.md
new file mode 100644
index 000000000..a5baec34a
--- /dev/null
+++ b/docs/deploy-guide/deploy-repo.md
@@ -0,0 +1,39 @@
+# Deploy Repository
+
+The deployment repository will contain configuration related to your deployment.
+Some of these items may be Kubernetes manifests or custom resources which will
+be consumed by different tools. It is recommended that one Deploy Repository
+is used per Management environment (NEED BETTER WORD HERE??), see [Introduction](./index.md) for information
+on what this is.
+
+The layout of this repo will be something like:
+
+```shell
+.
+├── management # (1)
+│   ├── helm-configs # (2)
+│   └── manifests # (3)
+├── iad3-prod # (4)
+│   ├── flavors -> ../flavors/prod # (5)
+│   ├── helm-configs
+│   └── manifests
+├── iad3-staging # (6)
+│   ├── flavors -> ../flavors/nonprod # (7)
+│   ├── helm-configs
+│   └── manifests
+├── global-prod # (8)
+│   ├── helm-configs
+│   └── manifests
+└── flavors
+    ├── nonprod
+    └── prod
+```
+
+1. This contains data which the cluster labeled as `management` will consume.
+2. helm `values.yaml` files per application/component will be here for `management`.
+3. Any kubernetes manifests per application/component will be here for `management`.
+4. This contains data which the cluster labeled as `iad3-prod` will consume.
+5. The definitions of the hardware flavors that this cluster, which later you will see maps to a region will use.
+6. This contains data which the cluster labeled as `iad3-staging` will consume.
+7. The definitions of the hardware flavors that this cluster, which later you will see maps to a region will use. Notice it is different than staging.
+8. The cluster labeled as `global-prod` will have resources consumed here.
diff --git a/docs/deploy-guide/getting-started.md b/docs/deploy-guide/getting-started.md
new file mode 100644
index 000000000..4f1ab2fdb
--- /dev/null
+++ b/docs/deploy-guide/getting-started.md
@@ -0,0 +1,21 @@
+# Getting Started
+
+You will need to have available a number of local utilities,
+a clone of this repo and another Git repo which will be referred to
+as the deploy repo. You will also need at least once Kubernetes
+cluster available to you, while multiple clusters are the advisable
+approach for any production or deployment at scale as the [Introduction](./index.md)
+mentions.
+
+Embracing [GitOps][gitops] and declarative configuration, we will need to have
+some items available before we begin.
+
+1. A Git repo that you'll be able to commit to and that you'll be able to provide
+read-only credentials to the tooling to fetch data from. Something like
+[GitHub Deploy Keys][gh-deploy-keys] will work.
+2. A DNS zone under which you can create multiple DNS entries. You can use a service
+like [sslip.io](https://sslip.io) for test purposes.
+3. The ability to get SSL certificates for these domains via cert-manager.
+
+[gitops]: <https://about.gitlab.com/topics/gitops/>
+[gh-deploy-keys]: <https://docs.github.com/en/authentication/connecting-to-github-with-ssh/managing-deploy-keys#set-up-deploy-keys>
diff --git a/mkdocs.yml b/mkdocs.yml
index 62793f5b6..d4e73f76a 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -113,6 +113,8 @@ nav:
   - 'Deployment Guide':
     - deploy-guide/index.md
     - Quick Start: deploy-guide/gitops-install.md
+    - deploy-guide/getting-started.md
+    - deploy-guide/deploy-repo.md
     - deploy-guide/auth.md
     - deploy-guide/extra-regions.md
     - deploy-guide/external-argocd.md