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/docs/deploy-guide/getting-started.md b/docs/deploy-guide/getting-started.md index 17762154e..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.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 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 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..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/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':