From 25f4a7714cef926aba739e810ed58dafef249a88 Mon Sep 17 00:00:00 2001 From: Doug Goldstein 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 +++++++++++++++ docs/deploy-guide/index.md | 20 +++++++------- mkdocs.yml | 3 +++ 4 files changed, 73 insertions(+), 10 deletions(-) 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..a5ebd8f43 --- /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 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. 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]: +[gh-deploy-keys]: diff --git a/docs/deploy-guide/index.md b/docs/deploy-guide/index.md index b6202384c..66a8e1815 100644 --- a/docs/deploy-guide/index.md +++ b/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 diff --git a/mkdocs.yml b/mkdocs.yml index 7af1c1ed9..713c754dc 100644 --- a/mkdocs.yml +++ b/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