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

@@ -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 tier, 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.

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>

docs/deploy-guide/index.md

@@ -14,7 +14,7 @@ with a production best practices installation. Improvements are always welcome.
 
 ## System Division
 
-A fully deployed UnderStack is divided into three distinct parts, or environments,
+A fully deployed UnderStack is divided into three distinct parts, or tiers,
 that are referred to in the documentation as:
 
 - Management
@@ -30,19 +30,19 @@ flowchart TD
   B[Global] --> E[Region N];
 ```
 
-A fully functioning system only needs one _Management_ environment, one _Global_
-environment and one or more _Region_ environment(s). In this configuration,
-the _Management_ environment is responsible for utilizing our [GitOps][gitops]
-tool, [ArgoCD][argocd] to deploy the expected state to all other environments.
-While the _Global_ environment is
+A fully functioning system only needs one _Management_ tier, one _Global_
+tier and one or more _Region_ tier(s). In this configuration,
+the _Management_ tier is responsible for utilizing our [GitOps][gitops]
+tool, [ArgoCD][argocd] to deploy the expected state to all other tier.
+While the _Global_ tier is
 responsible for hosting any services that are expected to exist only once
 for a whole system deployment such as the DCIM/IPAM tool. While the _Region_
-environments will run the tools and services that need to live close to the
+tiers will run the tools and services that need to live close to the
 actual hardware.
 
-In fact, one _Management_ environment can control multiple _Global_ environments
-and their associated _Region_ environments. We call the grouping of the _Global_
-environment and it's associated _Region_ environments a _partition_. An example
+In fact, one _Management_ tier can control multiple _Global_ tiers
+and their associated _Region_ tiers. We call the grouping of the _Global_
+tier and it's associated _Region_ tiers a _partition_. An example
 would be a staging partition and a production partition.
 
 ```mermaid

mkdocs.yml

@@ -113,6 +113,9 @@ nav:
   - 'Deployment Guide':
     - deploy-guide/index.md
     - Quick Start: deploy-guide/gitops-install.md
+    - Full Deploy:
+      - deploy-guide/getting-started.md
+      - deploy-guide/deploy-repo.md
     - deploy-guide/auth.md
     - deploy-guide/extra-regions.md
     - deploy-guide/external-argocd.md