[docs] Restructure user documentation (#1336)

Author: barroco

build/README.md

@@ -1,3 +1,3 @@
 # Deploying a DSS instance
 
-This documentation has been moved to [interuss.github.io/dss](https://interuss.github.io/dss/dev/build).
+This documentation has been moved to [interuss.github.io/dss](https://interuss.github.io/dss/dev/infrastructure/google-manual).

build/deploy/README.md

@@ -1,6 +1,6 @@
 # Kubernetes deployment via Tanka
 
-The documentation and configuration have been moved to [interuss.github.io/dss](https://interuss.github.io/dss/dev/services/tanka/).
+The documentation and configuration have been moved to the [services directory](../../deploy/services/tanka/).
 Architecture, Survivability and Sizing sections have been moved to [interuss.github.io/dss](https://interuss.github.io/dss/dev/architecture/)
 
 ## Migrating configurations to new location

deploy/MIGRATION.md

@@ -1,3 +1,3 @@
 # CockroachDB and Kubernetes version migration
 
-This documentation has been moved to [interuss.github.io/dss](https://interuss.github.io/dss/dev/migration).
+This documentation has been moved to [interuss.github.io/dss](https://interuss.github.io/dss/dev/operations/migrations).

deploy/infrastructure/modules/terraform-aws-dss/DNS.md

@@ -1,3 +1,3 @@
 # Setup DNS
 
-This documentation has been moved to [interuss.github.io/dss](https://interuss.github.io/dss/dev/infrastructure/terraform-aws-dss/dns).
+This documentation has been moved to [interuss.github.io/dss](https://interuss.github.io/dss/dev/infrastructure/aws).

deploy/infrastructure/modules/terraform-aws-dss/README.md

@@ -1,3 +1,3 @@
 # terraform-aws-dss
 
-This documentation has been moved to [interuss.github.io/dss](https://interuss.github.io/dss/dev/infrastructure/terraform-aws-dss).
+This documentation has been moved to [interuss.github.io/dss](https://interuss.github.io/dss/dev/infrastructure/aws).

deploy/infrastructure/modules/terraform-google-dss/DNS.md

@@ -1,3 +1,3 @@
 # Setup DNS
 
-This documentation has been moved to [interuss.github.io/dss](https://interuss.github.io/dss/dev/infrastructure/terraform-google-dss/dns).
+This documentation has been moved to [interuss.github.io/dss](https://interuss.github.io/dss/dev/infrastructure/google).

deploy/infrastructure/modules/terraform-google-dss/README.md

@@ -1,3 +1,3 @@
 # terraform-google-dss
 
-This documentation has been moved to [interuss.github.io/dss](https://interuss.github.io/dss/dev/infrastructure/terraform-google-dss).
+This documentation has been moved to [interuss.github.io/dss](https://interuss.github.io/dss/dev/infrastructure/google).

deploy/operations/ci/aws-1/README.md

@@ -1,3 +1,40 @@
 # AWS-1 CI deployment
 
-This documentation has been moved to [interuss.github.io/dss](https://interuss.github.io/dss/dev/operations/ci/aws-1).
+This module deploys a DSS to a Kubernetes cluster in AWS. It is primarily by our [CI](https://github.com/interuss/dss/blob/master/.github/workflows/dss-deploy.yml).
+See [test.sh](https://github.com/interuss/dss/blob/master/deploy/operations/ci/aws-1/test.sh) for the complete list of actions.
+
+## Terraform state
+
+The terraform backend is configured to be shared using a S3 bucket. (see [`main.tf`](https://github.com/interuss/dss/blob/master/deploy/operations/ci/aws-1/main.tf)).
+
+## Debugging
+
+In case of issue, it is possible to connect to the cluster and retrieve the terraform state to manage it
+locally.
+
+### Connection to the cluster
+
+To connect to the cluster, authenticate yourself to the AWS account.
+Run the following command to load the kubernetes config:
+```
+aws eks --region us-east-1 update-kubeconfig --name dss-ci-aws-ue1
+```
+Call the kubernetes cluster using `kubectl`
+
+#### Add other roles
+
+Access to the cluster is managed using the config map `aws-auth`.
+Its definition is managed in [`kubernetes_admin_access.tf`](https://github.com/interuss/dss/blob/master/deploy/operations/ci/aws-1/kubernetes_admin_access.tf).
+Currently only the user who bootstrapped the cluster and the ones assuming
+the administrator role (see [`local_variables.tf`](https://github.com/interuss/dss/blob/master/deploy/operations/ci/aws-1/local_variables.tf)) have access.
+
+### Run terraform locally
+
+In case of failure, a user with administrator role can take over the deployment by cloning this
+repository and retrieving the current deployment state by running the following command:
+
+```
+terraform init
+```
+
+At this point, the user can replay or clean the deployment as if it was the CI runner.

docs/services/index.md deploy/services/README.mddocs/services/index.md renamed to deploy/services/README.md

@@ -2,5 +2,5 @@
 
 This section contains the instructions and related material used to deploy DSS services on a Kubernetes cluster. Two options are currently provided:
 
-* An [helm chart](helm-charts.md)
-* A [tanka library](tanka.md)
+* A [helm chart](helm-charts/dss)
+* A [tanka library](tanka)

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

@@ -1,3 +1,25 @@
-# DSS Helm Chart
+# Helm Chart
+An [Helm Chart](https://helm.sh/) is provided [there](https://github.com/interuss/dss/tree/master/deploy/services/helm-charts/dss) to deploy the DSS and datastore (CockroachDB or Yugabyte) kubernetes resources.
 
-This documentation has been moved to [interuss.github.io/dss](https://interuss.github.io/dss/dev/services/helm-charts).
+## Requirements
+1. A Kubernetes cluster should be running and you should be properly authenticated. Requirements and instructions to create a new Kubernetes cluster can be found here:
+    * [AWS](../../../../docs/infrastructure/aws.md)
+    * [Google](../../../../docs/infrastructure/google.md)
+    * [Minikube](../../../../docs/infrastructure/minikube.md)
+
+2. Create the certificates and apply them to the cluster using the instructions [here](../../../../docs/operations/certificates-management.md)
+3. Install [Helm](https://helm.sh/) version 3.11.3 or higher
+
+## Usage
+1. Copy `values.example.yaml` to `values.dev.yaml` and edit it. In particular, the key `dss.image` must be set manually. See `values.schema.json` for schema definition. The root key `cockroachdb` supports all values supported by the [`cockroachdb` Chart](https://github.com/cockroachdb/helm-charts/tree/master/cockroachdb#configuration)). Note that values.yaml contains the default values and are always passed to helm.
+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 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 .`
+
+### Update the chart
+When changing the values in values.dev.yaml, values.yaml, the templates or upgrading the helm chart dependencies, changes can be applied to the cluster using the following command:
+
+1. Run `helm upgrade --kube-context=$KUBE_CONTEXT -f values.dev.yaml $RELEASE_NAME .`