Merge pull request 2i2c-org#3940 from GeorgianaElena/runbook-deployments

[documentation] Create collection of runbooks for new hub turnup phases

docs/hub-deployment-guide/deploy-support/register-central-grafana.md

@@ -1,3 +1,4 @@
+(register-new-cluster-with-central-grafana)=
 # Register the cluster's Prometheus server with the central Grafana
 
 Once you have [deployed the support chart](deploy-support-chart), you must also register this cluster as a datasource for the [central Grafana dashboard](grafana-dashboards:central). This will allow you to visualize cluster statistics not only from the cluster-specific Grafana deployment but also from the central dashboard, that aggregates data from all the clusters.

docs/hub-deployment-guide/runbooks/index.md

@@ -0,0 +1,14 @@
+(hub-deployment-guide:runbooks)=
+# Runbooks on how to handle new hub turn-up requests
+
+The following sections contain step-by-step runbooks that must be followed in order to drive to completion each phase of a new hub deployment.
+
+```{warning}
+This is still a work in progress and this contents might change.
+```
+
+```{toctree}
+:maxdepth: 1
+phase1/index.md
+phase2/index.md
+```

docs/hub-deployment-guide/runbooks/phase1/index.md

@@ -0,0 +1,36 @@
+(hub-deployment-guide:runbooks:phase1)=
+# Phase 1: Account setup
+
+This phase is applicable for cases where a new cluster needs to be setup to accommodate the new hub. This allows us to exactly determine the spend on a cloud account, ensure the privacy of users on that cloud account from others, as well as making it easier to provide more cloud access to users when necessary.
+
+```{note}
+For the purposes of this documentation, an "account" represents a unit of billing. This concept has different names across the major cloud providers we support, and therefore it's difficult to generalise the term.
+For example, "project" on GCP, "account" on AWS, "subscription" on Azure, and so forth.
+```
+
+## Definition of ready
+
+The following table lists the information that needs to be available to the engineer before this phase can start.
+
+- Cloud Provider
+- Will 2i2c pay for cloud costs and recover them via invoice?
+- Target Start Date
+- Community Representatives
+- Technical Contacts added to Airtable?
+
+## Outputs
+
+At the end of Phase 1, all engineers should have access to the cloud account where the new cluster and hub will be deployed to.
+
+No file assets will be generated at the end of this phase.
+
+## Available runbooks
+
+Based on the information provided, choose one of the following runbooks to follow.
+
+```{toctree}
+:maxdepth: 1
+new-gcp-project
+new-aws-account
+aws-external-account
+```

docs/hub-deployment-guide/runbooks/phase2/index.md

@@ -0,0 +1,74 @@
+(hub-deployment-guide:runbooks:phase2)=
+# Phase 2: Cluster setup
+
+This assumes all engineers have access to this new account, and will be able to set up the cluster and support, without any new hubs being set up.
+
+## Definition of ready
+
+The following table lists the information that needs to be available to the engineer before this phase can start.
+
+- Region / Zone of the cluster
+- Name of cluster
+- Is GPU required?
+
+## Outputs
+
+At the end of Phase 1, there should be a new cluster setup, with fully configured and deployed support components.
+
+The file assets that should have been generated at the end of this phase and included in the PR should be:
+
+```bash
+➕ config/clusters/<new-cluster-name>
+  ├── cluster.yaml
+  ├── enc-deployer-credentials.secret.json
+  ├── enc-support.secret.values.yaml
+  ├── enc-grafana-token.secret.yaml
+  └── support.values.yaml
+```
+
+```bash
+➕ terraform/<cloud-provider>/projects
+  └── <new-cluster>.tfvars
+```
+
+If on AWS:
+
+```bash
+➕ eksctl
+  ├── <new-cluster>.jsonnet
+  ├── ssh-keys/
+    ├── <new-cluster>.key.pub
+    ├── secret
+    └   └── <new-cluster>.key
+```
+
+And the following existing file should be updated to accommodate the new cluster:
+
+```bash
+～ .github/workflows
+  └── deploy-grafana-dashboards.yaml
+```
+
+```{tip}
+When reviewing cluster setup PRs, make sure the files above are all present.
+```
+
+## Cluster setup runbook
+
+All of the following steps must be followed in order to consider phase 2 complete. Steps contain references to other smaller, topic-specifc runbooks that are gathered together and listed in the order they should be carried on by an engineer.
+
+1. **Create the new cluster**
+
+   Follow the provider-specific steps in [](new-cluster:new-cluster) to create the cluster.
+
+2. **Configure and deploy the support chart**
+
+   Follow the steps in [](deploy-support-chart) to configure and deploy the support chart.
+
+3. **Setup Grafana dashboards**
+
+   Follow the steps in [](setup-grafana) to setup Grafana dashboards for the newly created cluster.
+
+4. **Register the new cluster with the central 2i2c Grafana**
+
+   Follow the steps in [](register-new-cluster-with-central-grafana) so that the cluster you just added will be findable from the 2i2c central Grafana.

docs/index.md

@@ -49,7 +49,7 @@ These sections walk an engineer step-by-step through the workflow of setting up
 ```{toctree}
 :maxdepth: 1
 :caption: Hub deployment guide
-hub-deployment-guide/cloud-accounts/index.md
+hub-deployment-guide/runbooks/index.md
 hub-deployment-guide/new-cluster/index.md
 hub-deployment-guide/deploy-support/index.md
 hub-deployment-guide/hubs/new-hub.md