Merge pull request #895 from rackerlabs/more-deploy

docs: update more information about the deployment repo

Author: cardoe

docs/deploy-guide/deploy-repo.md

@@ -0,0 +1,67 @@
+# Creating the Deploy Repo
+
+A deployment of UnderStack includes many different services, some of
+which will require specific configuration about your environment such
+as details about the hardware you will use or details on how you will
+connect to the hardware.
+
+These details will be accumulated in your Deployment Repository with
+some data being shared while most being scoped to a
+[Global cluster](./welcome.md#system-division) or
+a [Site cluster](./welcome.md#system-division).
+
+## Initial Structure
+
+To begin we will create our directory structure inside our Deployment Repository.
+
+```bash title="From the Deployment Repo"
+# where 'my-global' is the environment name you've used for your global cluster
+mkdir -p my-global/{manifests,helm-configs,inventory}
+# where 'my-site' is the environment name you've used for your site cluster
+mkdir -p my-site/{manifests,helm-configs,inventory}
+
+cat <<- EOF > my-global/deploy.yaml
+---
+name: my-global
+understack_url: https://github.com/rackerlabs/understack.git
+understack_ref: v0.0.5  # replace with the tag or git reference you want to use
+deploy_url: git@github.com:my-org/my-deploy.git
+deploy_ref: HEAD
+EOF
+
+cat <<- EOF > my-site/deploy.yaml
+---
+name: my-site
+understack_url: https://github.com/rackerlabs/understack.git
+understack_ref: v0.0.5
+deploy_url: git@github.com:my-org/my-deploy.git
+deploy_ref: HEAD
+EOF
+```
+
+For `dev` focused deployments, you do not need to specify the refs directly
+as they can be set on the ArgoCD cluster secret to allow more flexibility
+during testing.
+
+### manifests directory
+
+Inside of the `manifests` directory you'll create child directories that will
+be named after each application that we will deploy. These directories are
+expected to hold a `kustomization.yaml` as `kustomize` will be used to apply
+these manifests to your cluster.
+
+### helm-configs directory
+
+The `helm-configs` directory holds YAML files which are Helm `values.yaml`
+files that are used as additional values files that will be merged together
+by Helm.
+
+### inventory directory
+
+This directory contains an Ansible inventory file along with Ansible
+group_vars that are used as data by Ansible executions within the cluster
+to configure different services
+
+This directory contains an Ansible inventory file along with Ansible
+group_vars that are used as data by Ansible executions within the cluster
+to configure different services.

docs/deploy-guide/getting-started.md

@@ -21,6 +21,8 @@ be consumed by different tools. It is recommended that one Deploy Repository
 is used per Management tier, see [Introduction](./welcome.md) for information
 on what this is.
 
+### Layout
+
 The layout of this repo will be something like:
 
 ```shell
@@ -53,13 +55,23 @@ The layout of this repo will be something like:
 7. The definitions of the hardware flavors that this cluster, which later you will see maps to a site. Notice it is different than staging.
 8. The cluster labeled as `global-prod` will have resources consumed here.
 
-### Deploy repository permissions
+### Creation and Access
 
-To get started, you'll need a Deploy Repository that you can commit to. This means you should have write access to this repository.
+To effectively utilize [GitOps][gitops] we will need a Deploy Repository.
 
-For the deployment tool, [ArgoCD](./argocd.md), you'll need to set up read-only credentials. This allows ArgoCD to fetch the necessary data without making any changes to your repository. One way to achieve this is by using [GitHub Deploy Keys][gh-deploy-keys] or similar solutions.
+```bash
+# create my-deploy locally
+git init my-deploy
+# or clone one down
+git clone https://url/to/my-deploy
+```
 
-[GitHub Deploy Keys][gh-deploy-keys] will work.
+This will need to be hosted somewhere that your ArgoCD instance in your
+Management Cluster will be able to access it. For ArgoCD, you will need
+to set up read-only credentials. This allows ArgoCD to fetch the
+necessary data being able to making any changes to your repository.
+One way to achieve this is by using [GitHub Deploy Keys][gh-deploy-keys]
+or check the [ArgoCD][argocd] documentation for other methods.
 
 ## UnderStack Repository
 

docs/deploy-guide/gitops-install.md

@@ -29,6 +29,8 @@ git init uc-deploy
 git clone https://path/to/my/uc-deploy
 ```
 
+See [Deployment Repository](./getting-started.md#creation-and-access)
+
 ## Pre-deployment
 
 Embracing GitOps and declarative configuration, we will define three

docs/deploy-guide/argocd.md renamed to docs/deploy-guide/management-cluster.md

@@ -1,8 +1,8 @@
-# ArgoCD
+# Management Cluster
 
 The deployment of all the services into your Kubernetes cluster is handled
 by [ArgoCD][argocd]. The [System Division](./welcome.md#system-division)
-defines the location where [ArgoCD][argocd] runs as the __Management__ cluster.
+defines the location where [ArgoCD][argocd] runs as the __Management__ role.
 While it is possible to run ArgoCD from the same cluster that your services
 will run in, it is not advisable outside of a development setup. The
 approach that UnderStack uses to deploy it's services with ArgoCD is the

docs/deploy-guide/welcome.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 tiers,
+A fully deployed UnderStack is divided into three distinct parts, or clusters,
 that are referred to in the documentation as:
 
 - Management
@@ -30,19 +30,19 @@ flowchart TD
   B[Global] --> E[Site N];
 ```
 
-A fully functioning system only needs one _Management_ tier, one _Global_
-tier and one or more _Site_ 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
+A fully functioning system only needs one _Management_ cluster, one _Global_
+cluster and one or more _Site_ cluster(s). In this configuration,
+the _Management_ cluster is responsible for utilizing our [GitOps][gitops]
+tool, [ArgoCD][argocd] to deploy the expected state to all other clusters.
+While the _Global_ cluster 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 _Site_
-tiers will run the tools and services that need to live close to the
+clusters will run the tools and services that need to live close to the
 actual hardware.
 
-In fact, one _Management_ tier can control multiple _Global_ tiers
-and their associated _Site_ tiers. We call the grouping of the _Global_
-tier and it's associated _Site_ tiers a _partition_. An example
+In fact, one _Management_ cluster can control multiple _Global_ clusters
+and their associated _Site_ clusters. We call the grouping of the _Global_
+cluster and it's associated _Site_ clusters a _partition_. An example
 would be a staging partition and a production partition.
 
 ```mermaid

mkdocs.yml

@@ -121,11 +121,15 @@ nav:
     - deploy-guide/welcome.md
     - deploy-guide/getting-started.md
     - Quick Start: deploy-guide/gitops-install.md
-    - deploy-guide/argocd.md
-    - deploy-guide/auth.md
-    - deploy-guide/extra-sites.md
-    - deploy-guide/add-remove-app.md
-    - deploy-guide/override-openstack-svc-config.md
+    - Preparing Our Deployment:
+      - deploy-guide/deploy-repo.md
+      - deploy-guide/auth.md
+    - Starting the Deployment:
+      - deploy-guide/management-cluster.md
+    - Further Actions:
+      - deploy-guide/extra-sites.md
+      - deploy-guide/add-remove-app.md
+      - deploy-guide/override-openstack-svc-config.md
   - 'Operator Guide':
     - operator-guide/index.md
     - 'OpenStack':