add docs about the default storage class (#87)

base/gitserver/gitserver.StatefulSet.yaml

@@ -76,6 +76,7 @@ spec:
     spec:
       accessModes:
       - ReadWriteOnce
+      storageClassName: sourcegraph
       resources:
         requests:
           # The size of disk used to mirror your git repositories.

base/indexed-search/indexed-search.PersistentVolumeClaim.yaml

@@ -7,6 +7,7 @@ metadata:
 spec:
   accessModes:
   - ReadWriteOnce
+  storageClassName: sourcegraph
   resources:
     requests:
       # The size of disk to used for search indexes.

base/pgsql/pgsql.PersistentVolumeClaim.yaml

@@ -7,6 +7,7 @@ metadata:
 spec:
   accessModes:
   - ReadWriteOnce
+  storageClassName: sourcegraph
   resources:
     requests:
       storage: 200Gi

base/redis/redis-cache.PersistentVolumeClaim.yaml

@@ -7,6 +7,7 @@ metadata:
 spec:
   accessModes:
   - ReadWriteOnce
+  storageClassName: sourcegraph
   resources:
     requests:
       storage: 100Gi

base/redis/redis-store.PersistentVolumeClaim.yaml

@@ -7,6 +7,7 @@ metadata:
 spec:
   accessModes:
   - ReadWriteOnce
+  storageClassName: sourcegraph
   resources:
     requests:
       storage: 100Gi

configure/jaeger/jaeger.PersistentVolumeClaim.yaml

@@ -9,6 +9,7 @@ metadata:
 spec:
   accessModes:
   - ReadWriteOnce
+  storageClassName: sourcegraph
   resources:
     requests:
       storage: 100Gi

configure/prometheus/prometheus.PersistentVolumeClaim.yaml

@@ -7,6 +7,7 @@ metadata:
 spec:
   accessModes:
   - ReadWriteOnce
+  storageClassName: sourcegraph
   resources:
     requests:
       storage: 200Gi

configure/ssd/README.md

@@ -1,6 +1,6 @@
 # SSDs
 
-Using local SSDs dramatically speeds up many of Sourcegraph's services. Read your cloud provider's documentation for mouting local SSDs.
+Using local SSDs dramatically speeds up many of Sourcegraph's services. Even if the cluster's default storage class uses SSDs, it's likely network-mounted rather than local. Read your cloud provider's documentation for mouting local SSDs.
 
 - [GCP](https://cloud.google.com/compute/docs/disks/local-ssd)
 - [AWS](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ssd-instance-store.html)

configure/xlang/typescript/npm-proxy.PersistentVolumeClaim.yaml

@@ -10,6 +10,7 @@ metadata:
 spec:
   accessModes:
   - ReadWriteOnce
+  storageClassName: sourcegraph
   resources:
     requests:
       storage: 100Gi

docs/configure.md

@@ -39,6 +39,7 @@ Configuration steps in this file depend on [jq](https://stedolan.github.io/jq/),
 
 ### Common configuration
 
+- [Configure a storage class](#configure-a-storage-class)
 - [Configure network access](#configure-network-access)
 - [Update site configuration](#update-site-configuration)
 - [Configure TLS/SSL](#configure-tlsssl)
@@ -51,7 +52,6 @@ Configuration steps in this file depend on [jq](https://stedolan.github.io/jq/),
 
 - [Configure gitserver replica count](#configure-gitserver-replica-count)
 - [Assign resource-hungry pods to larger nodes](#assign-resource-hungry-pods-to-larger-nodes)
-- [Configure a storage class](#configure-a-storage-class)
 - [Configure Prometheus](../configure/prometheus/README.md)
   - [Configure Alertmanager](../configure/prometheus/alertmanager/README.md)
 - [Configure Jaeger tracing](../configure/jaeger/README.md)
@@ -377,12 +377,78 @@ See [the official documentation](https://kubernetes.io/docs/concepts/configurati
 
 ## Configure a storage class
 
-Sourcegraph relies on the default storage class of your cluster. If your cluster does not have a default storage class or if you wish to use a different storage class for Sourcegraph, then you need to update all PersistentVolumeClaims with the name of the desired storage class.
+Sourcegraph expects there to be storage class named `sourcegraph` that it uses for all its persistent volume claims. This storage class must be configured before applying the base configuration to your cluster. The configuration details differ depending on your hosting provider, so you should:
+
+1. Create a stub `base/sourcegraph.StorageClass.yaml`.
+
+   ```yaml
+   # base/sourcegraph.StorageClass.yaml
+   kind: StorageClass
+   apiVersion: storage.k8s.io/v1
+   metadata:
+     name: sourcegraph
+     labels:
+       deploy: sourcegraph
+   #
+   # The values of the "provisioner" and "parameters" fields will differ depending on the cloud provider that you are using. Please read through https://kubernetes.io/docs/concepts/storage/storage-classes/ in order to know what values to add. 🚨 We recommend specifying SSDs as the disk type if possible. 🚨
+   #
+   # For example, if you are using GKE with a cluster whose nodes are all in the "us-central1-a" zone, you could use the following values:
+   #
+   # provisioner: kubernetes.io/gce-pd
+   # parameters:
+   #  type: pd-ssd
+   #  zones: us-central1-a
+   ```
+
+1. Read through the [Kubernetes storage class documentation](https://kubernetes.io/docs/concepts/storage/storage-classes/), and fill in the `provisioner` and `parameters` fields in `base/sourcegraph.StorageClass.yaml` with the correct values for your hosting provider (e.x.: [GCP](https://kubernetes.io/docs/concepts/storage/storage-classes/#gce), [AWS](https://kubernetes.io/docs/concepts/storage/storage-classes/#aws), [Azure](https://kubernetes.io/docs/concepts/storage/storage-classes/#azure-disk)).
+
+   **We highly recommend that the storage class use SSDs as the underlying disk type.**
+
+   Using the snippets below will create a storage class backed by SSDs:
+
+   - [GCP](https://kubernetes.io/docs/concepts/storage/storage-classes/#gce):
+
+     ```yaml
+     # base/sourcegraph.StorageClass.yaml
+     parameters:
+       type: pd-ssd
+     ```
+
+   - [AWS](https://kubernetes.io/docs/concepts/storage/storage-classes/#aws):
+
+     ```yaml
+     # base/sourcegraph.StorageClass.yaml
+     parameters:
+       type: gp2
+     ```
+
+   - [Azure](https://kubernetes.io/docs/concepts/storage/storage-classes/#azure-disk):
+
+     ```yaml
+     # base/sourcegraph.StorageClass.yaml
+     parameters:
+       storageaccounttype: Premium_LRS
+     ```
+
+
+1. Commit `base/sourcegraph.StorageClass.yaml` to your fork.
+
+### Using a storage class with an alternate name
+
+If you wish to use a different storage class for Sourcegraph, then you need to update all persistent volume claims with the name of the desired storage class. Convenience script:
 
 ```bash
+#!/bin/bash
+
 # This script requires https://github.com/sourcegraph/jy and https://github.com/sourcegraph/yj
+STORAGE_CLASS_NAME=
+
 find . -name "*PersistentVolumeClaim.yaml" -exec sh -c "cat {} | yj | jq '.spec.storageClassName = \"$STORAGE_CLASS_NAME\"' | jy -o {}" \;
-```
+
+GS=base/gitserver/gitserver.StatefulSet.yaml
+
+cat $GS | yj | jq  --arg STORAGE_CLASS_NAME $STORAGE_CLASS_NAME '.spec.volumeClaimTemplates = (.spec.volumeClaimTemplates | map( . * {spec:{storageClassName: $STORAGE_CLASS_NAME }}))' | jy -o $GS
+````
 
 ## Configure Lightstep tracing
 

docs/install.md

@@ -30,6 +30,8 @@
    git clone https://github.com/sourcegraph/deploy-sourcegraph && cd deploy-sourcegraph && git checkout ${VERSION}
    ```
 
+1. Configure the `sourcegraph` storage class for the cluster by reading through ["Configure a storage class"](../configure.md#configure-a-storage-class).
+
 1. If you want to add a large number of repositories to your instance, you should [configure the number of gitserver replicas](configure.md#configure-gitserver-replica-count) _before_ you continue with the next step.
 
 1. Deploy the desired version of Sourcegraph to your cluster:

docs/migrate.md

@@ -53,7 +53,11 @@ These steps will uninstall Sourcegraph from your cluster while preserving your d
    kubectl get pv -o json | jq --raw-output ".items | map(select(.spec.claimRef.name | contains(\"gitserver-\"))) | .[] | \"kubectl patch pv -p '{\\\"spec\\\":{\\\"claimRef\\\":{\\\"name\\\":\\\"repos-gitserver-\\(.spec.claimRef.name | ltrimstr(\"gitserver-\") | tonumber - 1)\\\"}}}' \\(.metadata.name)\""  | bash
    ```
 
-6. Proceed with the normal [installation steps](install.md).
+6. Proceed with the normal [installation steps](install.md). 🚨 When following the instructions for [configuring a storage class](configure.md#configure-a-storage-class), you need to make sure that the newly configured storage class has the same configuration as the one that you were using in the legacy helm deployment. Steps:
+
+   1. When creating the new storage class, use the same `cluster.storageClass.name` and `cluster.storageClass.zone` fields that were in your old [values.yaml](https://github.com/sourcegraph/deploy-sourcegraph/blob/helm-legacy/values.yaml).
+
+   1. Use the convenience script in ["Using a storage class with an alternate name"](configure.md#using-a-storage-class-with-an-alternate-name) to update all the `storageClassName` references in the PVCs to refer to the old `cluster.storageClass.name` field.
 
 7. The previous step produces a fresh base state, so you will need to reconfigure your cluster by following the relevant steps in [configure.md](configure.md) (e.g. exposing ports, applying your site config, enabling other services like language servers, Prometheus, Alertmanager, Jaeger, etc.).