docs: start to break up and define the deployment

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