[doc] Add placeholders in new deployment documentation (#1068)

This PR initiates the migration of the legacy deployment documentation from build/deploy/ to /deploy.
It introduces placeholders to offer an opportunity for discussion about the future structure and allow a future step by step migration of the documentation.

deploy/README.md

@@ -2,49 +2,53 @@
 
 > This folder contains the increments toward the new deployment approach as described in #874.
 
-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.
+## Introduction
 
-The deployment tools are conceptually broken down in three phases:
+An operational DSS deployment requires a specific architecture to be compliant with [standards requirements](../README.md#standards-and-regulations) and meet performance expectations as described in [architecture](./architecture.md).
 
-- [Infrastructure](#infrastructure)
-- [Services](#services)
-- [Operations](#operations)
+## Deployment options
 
-## [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.
-
+This repository provides three layers of abstraction to deploy a DSS instance via Kubernetes.
+As described below, InterUSS provides tooling for Kubernetes deployments on Amazon Web Services (EKS) and Google Cloud (GKE).
+However, you can do this on any supported [cloud provider](https://kubernetes.io/docs/concepts/cluster-administration/cloud-providers/) or even on your own infrastructure.
+Review [InterUSS pooling requirements](./architecture.md#objective) and consult the Kubernetes documentation for your chosen provider.
+
+The three layers are the following:
+
+1. [Infrastructure](#infrastructure) provides instructions and tooling to easily provision a Kubernetes cluster and cloud resources (load balancers, storage...) to a cloud provider. The resulting infrastructure meets the [Pooling requirements](./architecture.md#objective).
 Terraform modules are provided for:
-- [Amazon Web Services (EKS)](infrastructure/modules/terraform-aws-dss)
-- [Google (GKE)](infrastructure/modules/terraform-google-dss)
+ - [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. 
+1. [Services](#services) provides the tooling to deploy a DSS instance to a Kubernetes cluster.
+ - [Helm Charts](services/helm-charts/dss)
+ - [Tanka](../build/deploy)
 
-Services can be deployed using those approaches:
- - [Helm Charts](services/helm-charts/dss)
- - [Tanka](../build/deploy)
+1. [Operations](#operations) provides instructions to operate a deployed DSS instance.
+  - [Pooling procedure](./operations/README.md#pooling-procedure)
+  - [Troubleshooting](./operations/README.md#troubleshooting) 
 
-## [Operations](./operations)
-It is responsible to provide diagnostic capabilities and utilities to **operate** the Services, such as certificates management. Currently, the operations scripts are located inside [build](../build) and helpers are generated in the workspace directory by terraform after deployment. It also contains the Infrastructure and Services configurations [used by the CI](../.github/workflows/dss-deploy.yml).
+Depending on your level of expertise and your internal organizational practices, you should be able to use each layer independently or complementary.
 
-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)
+For local deployment approaches, see the documentation located in the [build folder](../build/README.md#deployment-options)
 
 ## 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:
+You can find below two guides to deploy a DSS instance from scratch:
 - [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)
+For a complete use case, you can look into the configurations of the [CI job](../.github/workflows/dss-deploy.yml) in operations: [ci](operations/ci)
 
 ## Migrations and upgrades
 
 Information related to migrations and upgrades can be found in [MIGRATION.md](MIGRATION.md).
 
 ## Development
 
+The following diagram represents the resources in this repository per layer.
+![Deploy Overview](../assets/generated/deploy_overview.png)
+
 ### Formatting
 
 Terraform files must be formatted using `terraform fmt -recursive` command to pass the CI linter check.

deploy/architecture.md

@@ -0,0 +1,31 @@
+# Kubernetes deployment
+
+## Introduction
+
+See [introduction](../build/pooling.md#introduction)
+
+## Architecture
+
+See [architecture](../build/deploy/README.md#architecture)
+
+### Terminology notes
+
+See [teminology notes](../build/pooling.md#terminology-notes).
+
+## Pooling
+
+### Objective
+
+See [Pooling Objective](../build/pooling.md#objective) and subsections.
+
+### Additional requirements
+
+See [Additional requirements](../build/pooling.md#additional-requirements).
+
+### Survivability
+
+See [survivability](../build/deploy/README.md#survivability).
+
+### Sizing
+
+See [sizing](../build/deploy/README.md#sizing).

deploy/operations/README.md

@@ -0,0 +1,29 @@
+# Operations
+
+This folder contains the instructions and related material used to operate a DSS. It is responsible to provide diagnostic capabilities and utilities to operate the DSS instance, such as certificates management. 
+
+Currently, the operations scripts are located inside [build](../../build) and if using the [infrastructure layer](../infrastructure), helpers are generated in the workspace directory by terraform after deployment.
+
+As a complete example, the configuration files [used by the CI job](../../.github/workflows/dss-deploy.yml) of the [infrastructure](../infrastructure) and [servics](../services) layers are located in [ci](./ci).
+
+## Pooling procedure
+
+### Creating a new pool
+
+See [Creating a new pool](../../build/pooling.md#creating-a-new-pool)
+
+### Establishing a pool with first instance 
+
+See [Establishing a pool with first instance](../../build/pooling.md#establishing-a-pool-with-first-instance)
+
+### Joining an existing pool with new instance
+
+See [Joining an existing pool with new instance](../../build/pooling.md#joining-an-existing-pool-with-new-instance)
+
+### Leaving a pool
+
+See [Leaving a pool](../../build/pooling.md#leaving-a-pool)
+
+## Troubleshooting
+
+See [Troubleshooting](../../build/README.md#troubleshooting)

deploy/services/helm-charts/dss/README.md

@@ -12,7 +12,7 @@ Requirements and instructions to create a new Kubernetes cluster can be found [h
 2. Validate the configuration: `helm lint -f values.dev.yaml .`
 3. Set a RELEASE_NAME to `dss`: `export RELEASE_NAME=dss`
 It is temporarily the only release name possible.
-4. Set the kube client context of your , example: `export KUBE_CONTEXT=gke_interuss-deploy-example_europe-west6-a_dss-dev-w6`
+4. Set the kube client context of your system, example: `export KUBE_CONTEXT=gke_interuss-deploy-example_europe-west6-a_dss-dev-w6`
 5. Run `helm dep update --kube-context=$KUBE_CONTEXT`
 6. Install the chart: `helm install --kube-context=$KUBE_CONTEXT -f values.dev.yaml $RELEASE_NAME .`
 

deploy/services/tanka/README.md

@@ -0,0 +1,6 @@
+# Tanka
+
+See [Tanka](../../../build/deploy/README.md#kubernetes-deployment-via-tanka)
+and the [legacy deployment procedure](../../../build/README.md#deploying-a-dss-instance-via-kubernetes) 
+
+