[deploy] Consolidate deployment documentation (#984)

* [deploy] Consolidate documentation

* Update deploy/infrastructure/README.md

Co-authored-by: Benjamin Pelletier <[email protected]>

* Update deploy/infrastructure/README.md

Co-authored-by: Benjamin Pelletier <[email protected]>

* Address PR comments

---------

Co-authored-by: Benjamin Pelletier <[email protected]>

assets/deploy_infrastructure_modules.puml

@@ -0,0 +1,23 @@
+@startuml
+
+frame "Infrastructure" #lightblue {
+  package "terraform-*-dss" as TD #lightblue {
+    [terraform-*-kubernetes] as TK #lightblue
+    [terraform-common-dss] as TCD #lightblue
+  }
+}
+
+cloud "Cloud Provider" as C {
+  package "Kubernetes Cluster" as K #lightblue {
+    component "Kubernetes Node" as KN #lightblue {
+    }
+    component "Kubernetes Node" as KN2 #lightblue {
+    }
+  }
+}
+
+TD -down-> K #blue: 1. Prepare the Infrastructure
+TK -> TCD: harmonized\noutputs
+TCD -right-> ( ): 2. Generate Services configuration
+
+@enduml

assets/deploy_overview.puml

@@ -0,0 +1,37 @@
+@startuml
+
+frame "Infrastructure" #lightblue {
+  package "terraform-*-dss" as TD #lightblue {
+    [terraform-*-kubernetes] as TK #lightblue
+    [terraform-common-dss] as TCD #lightblue
+  }
+}
+
+frame "Services" #lightgreen {
+  [Helm Charts] as H #lightgreen
+}
+
+frame "Operations" as O #lightyellow {
+  [Scripts] as S #lightyellow
+}
+
+cloud "Cloud Provider" as C {
+  package "Kubernetes Cluster" as K #lightblue {
+    component "Kubernetes Node" as KN #lightblue {
+      () pods as P #lightgreen
+    }
+    component "Kubernetes Node" as KN2 #lightblue {
+      () pods as P2 #lightgreen
+    }
+  }
+}
+
+TD -> K #blue: 1. Prepare the Infrastructure
+TK -> TCD: harmonized\noutputs
+TCD -right-> H: 2. Generate Services configuration
+H -down-> P #green: 3. Deploy the Services
+H -down-> P2 #green
+S -up-> P #orange
+S -> P2 #orange: 4. Operate the Services
+
+@enduml

deploy/README.md

@@ -1,13 +1,40 @@
 # DSS Deployment
 
-This folder contains the increments toward the new deployment approach as described in [#874](https://github.com/interuss/dss/issues/874).
+> This folder contains the increments toward the new deployment approach as described in #874.
 
-The infrastructure folder contains the terraform modules to deploy the DSS to kubernetes clusters of various cloud providers:
+An operational DSS requires two different services: the DSS core-service API and the Cockroach database. 
+This folder contains the tools to prepare the infrastructure in multiple cloud providers, deploy the services and operate it.
 
-- Amazon Web Services: [terraform-aws-dss](./infrastructure/modules/terraform-aws-dss/README.md)
-- Google Cloud Engine: [terraform-google-dss](./infrastructure/modules/terraform-google-dss/README.md)
+The deployment tools are conceptually broken down in three phases:
 
-The service folder contains the scripts required to deploy the DSS to a Kubernetes cluster:
+- [Infrastructure](#infrastructure)
+- [Services](#services)
+- [Operations](#operations)
 
-- Helm Charts: [services/helm-charts](./services/helm-charts)
-- Tanka: [../build/deploy/](../build/deploy)
+## [Infrastructure](./infrastructure)
+It is responsible to prepare infrastructure on various cloud providers to accept deployment of Services below. It includes the Kubernetes cluster creation, cluster nodes, load balancer and associated fixed IPs, etc. This stage is cloud provider specific.
+
+Terraform modules are provided for:
+- [Amazon Web Services (EKS)](infrastructure/modules/terraform-aws-dss)
+- [Google (GKE)](infrastructure/modules/terraform-google-dss)
+
+## [Services](./services)
+It is responsible for managing Kubernetes resources and **deploying** the Services required by an operational DSS. The ambition is to be cloud provider agnostic for the Services part. 
+
+Services can be deployed using those approaches:
+  - [Helm Charts](services/helm-charts/dss)
+  - [Tanka](../build/deploy)
+
+## [Operations](./operations)
+It is responsible to provide diagnostic capabilities and utilities to **operate** the Services, such as certificates management may be simplified using the deployment manager CLI tools. It also contains the Infrastructure and Services configurations [used by the CI](../.github/workflows/dss-deploy.yml).
+
+The following diagram represents the modules provided in this repository per phase and their impact on the various resources.
+![Deploy Overview](../assets/generated/deploy_overview.png)
+
+## Getting started
+
+If you wish to deploy a DSS from scratch, "Getting Started" instructions can be found in the terraform modules and covers all steps to get a running DSS:
+- [Amazon Web Services (EKS)](infrastructure/modules/terraform-aws-dss/README.md#Getting-started)
+- [Google (GKE)](infrastructure/modules/terraform-google-dss/README.md#Getting-started)
+
+For a real use case, you can look into the configurations of the [CI job](../.github/workflows/dss-deploy.yml) in operations: [ci](operations/ci)

deploy/infrastructure/README.md

@@ -1,6 +1,21 @@
-# DSS Deployment
+# Infrastructure
 
-The `modules` directory contains the terraform modules required to deploy the DSS using cloud providers.
+As a phase in [DSS deployment](..), this folder contains the terraform modules required to prepare the infrastructure to host a DSS deployment.
+See [Services](../README.md#services) to deploy the DSS once the infrastructure is ready.
+
+## Modules
+The [modules](modules) directory contains the terraform public modules required to prepare the infrastructure on various cloud providers.
 
 - [terraform-aws-dss](./modules/terraform-aws-dss/README.md): Amazon Web Services deployment
 - [terraform-google-dss](./modules/terraform-google-dss/README.md): Google Cloud Engine deployment
+
+## Dependencies
+The [dependencies](dependencies) directory contains submodules used by the public modules described above. They are not expected to be 
+used directly by users. Those submodules are the combination of the cloud specific dependencies `terraform-*-kubernetes`
+and `terraform-common-dss`. `terraform-common-dss` module aggregates and outputs the infrastructure configuration 
+which can be used as input to the `Services` deployment as shown in the diagram below.
+
+![Infrastructure Modules](../../assets/generated/deploy_infrastructure_modules.png)
+
+## Utils
+This [utils folder](utils) contains scripts to help manage the terraform modules and dependencies. See the README in that folder for details.