From 1f00b3f84d5be249aa792be2a0074c9a8e58f609 Mon Sep 17 00:00:00 2001 From: Doug Goldstein Date: Tue, 29 Apr 2025 19:39:53 -0500 Subject: [PATCH 1/3] docs: stop avoiding the word cluster Tried to avoid using the word cluster in the docs so many times but it really doesn't make sense. Just embrace it and use it while making a note that its possible to use one cluster in place of multiple clusters. --- docs/deploy-guide/getting-started.md | 2 +- .../{argocd.md => management-cluster.md} | 4 ++-- docs/deploy-guide/welcome.md | 20 +++++++++---------- mkdocs.yml | 2 +- 4 files changed, 14 insertions(+), 14 deletions(-) rename docs/deploy-guide/{argocd.md => management-cluster.md} (99%) diff --git a/docs/deploy-guide/getting-started.md b/docs/deploy-guide/getting-started.md index 17762154e..1fa606c09 100644 --- a/docs/deploy-guide/getting-started.md +++ b/docs/deploy-guide/getting-started.md @@ -57,7 +57,7 @@ The layout of this repo will be something like: To get started, you'll need a Deploy Repository that you can commit to. This means you should have write access to this 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. +For the deployment tool, [ArgoCD][argocd], 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. [GitHub Deploy Keys][gh-deploy-keys] will work. diff --git a/docs/deploy-guide/argocd.md b/docs/deploy-guide/management-cluster.md similarity index 99% rename from docs/deploy-guide/argocd.md rename to docs/deploy-guide/management-cluster.md index 2e338cda6..808043546 100644 --- a/docs/deploy-guide/argocd.md +++ b/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 diff --git a/docs/deploy-guide/welcome.md b/docs/deploy-guide/welcome.md index 23124bb1d..153574b46 100644 --- a/docs/deploy-guide/welcome.md +++ b/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 diff --git a/mkdocs.yml b/mkdocs.yml index 346d4e93c..d0e4827ea 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -121,7 +121,7 @@ nav: - deploy-guide/welcome.md - deploy-guide/getting-started.md - Quick Start: deploy-guide/gitops-install.md - - deploy-guide/argocd.md + - deploy-guide/management-cluster.md - deploy-guide/auth.md - deploy-guide/extra-sites.md - deploy-guide/add-remove-app.md From 638ec14d4ee5cbf6917b0af4bd8d9b0740d8b89d Mon Sep 17 00:00:00 2001 From: Doug Goldstein Date: Tue, 29 Apr 2025 21:21:43 -0500 Subject: [PATCH 2/3] docs: detail the creation of deploy repo Add details on the creation of the Deployment Repository. --- docs/deploy-guide/getting-started.md | 20 ++++++++++++++++---- docs/deploy-guide/gitops-install.md | 2 ++ 2 files changed, 18 insertions(+), 4 deletions(-) diff --git a/docs/deploy-guide/getting-started.md b/docs/deploy-guide/getting-started.md index 1fa606c09..bfa3470ee 100644 --- a/docs/deploy-guide/getting-started.md +++ b/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], 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 diff --git a/docs/deploy-guide/gitops-install.md b/docs/deploy-guide/gitops-install.md index c8b2b988c..ac1409537 100644 --- a/docs/deploy-guide/gitops-install.md +++ b/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 From 1408645c0aa11dce1b337e1e4d6b50738cd20cd8 Mon Sep 17 00:00:00 2001 From: Doug Goldstein Date: Tue, 29 Apr 2025 21:51:22 -0500 Subject: [PATCH 3/3] docs: start documenting what goes into the deploy repo Create some documentation around what goes into the deploy repo. --- docs/deploy-guide/deploy-repo.md | 67 ++++++++++++++++++++++++++++++++ mkdocs.yml | 14 ++++--- 2 files changed, 76 insertions(+), 5 deletions(-) create mode 100644 docs/deploy-guide/deploy-repo.md diff --git a/docs/deploy-guide/deploy-repo.md b/docs/deploy-guide/deploy-repo.md new file mode 100644 index 000000000..66fa05368 --- /dev/null +++ b/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. diff --git a/mkdocs.yml b/mkdocs.yml index d0e4827ea..86c99ae6a 100644 --- a/mkdocs.yml +++ b/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/management-cluster.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':