add docs about configuring gitserver's replica count before initally deploying to the cluster (sourcegraph#81)

Author: ggilmore

docs/configure.md

@@ -298,22 +298,38 @@ We also have the following experimental language servers (please [read about the
 
 ## Configure gitserver replica count
 
-Repository clones are consistently striped across all `gitserver` replicas. Other services need to be aware of how many `gitserver` replicas exist so they can resolve an individual repo.
+**Note:** If you're creating a new cluster and would like to change `gitserver`'s replica count, do
+so _before_ running `./kubectl-apply-all.sh` for the first time. Changing this after the cluster
+configuration has been applied will require manually resizing the `indexed-search` volume.
+
+Increasing the number of `gitserver` replicas can improve performance when your instance contains a large number of repositories. Repository clones are consistently striped across all `gitserver` replicas. Other services need to be aware of how many `gitserver` replicas exist so they can resolve an individual repo.
 
 To change the number of `gitserver` replicas:
 
 1. Update the `replicas` field in [gitserver.StatefulSet.yaml](../base/gitserver/gitserver.StatefulSet.yaml).
-2. Update the `SRC_GIT_SERVERS` environment variable in all services to reflect the number of replicas.
+1. Update the `SRC_GIT_SERVERS` environment variable in all services to reflect the number of replicas.
 
-   For example, if there are 2 gitservers then `SRC_GIT_SERVERS` should have the value `gitserver-0.gitserver:3178 gitserver-1.gitserver:3178`.
+   For example, if there are 2 gitservers then `SRC_GIT_SERVERS` should have the value `gitserver-0.gitserver:3178 gitserver-1.gitserver:3178`:
 
    ```yaml
    - env:
        - name: SRC_GIT_SERVERS
          value: gitserver-0.gitserver:3178 gitserver-1.gitserver:3178
    ```
 
-Here is a convenience script that performs both steps:
+1. Update the requested `storage` capacity in [base/indexed-search/indexed-search.PersistentVolumeClaim.yaml](../base/indexed-search/indexed-search.PersistentVolumeClaim.yaml) to be `200Gi` multiplied by the number of `gitserver` replicas.
+
+   For example, if there are 2 `gitserver` replicas then the `storage` requested in [base/indexed-search/indexed-search.PersistentVolumeClaim.yaml](../base/indexed-search/indexed-search.PersistentVolumeClaim.yaml) should have the value `400Gi`.
+
+   ```yaml
+   # base/indexed-search/indexed-search.PersistentVolumeClaim.yaml
+   spec:
+     resources:
+       requests:
+         storage: 400Gi
+   ```
+
+Here is a convenience script that performs all three steps:
 
 ```bash
 # This script requires https://github.com/sourcegraph/jy and https://github.com/sourcegraph/yj
@@ -331,6 +347,11 @@ GITSERVERS=$(for i in `seq 0 $(($REPLICA_COUNT-1))`; do echo -n "gitserver-$i.gi
 # Update SRC_GIT_SERVERS environment variable in other services
 find . -name "*yaml" -exec sed -i.sedibak -e "s/value: gitserver-0.gitserver:3178.*/value: $GITSERVERS/g" {} +
 
+IDX_SEARCH=base/indexed-search/indexed-search.PersistentVolumeClaim.yaml
+
+# Update the storage requested in indexed-search's persistent volume claim
+cat $IDX_SEARCH | yj | jq --arg REPLICA_COUNT "$REPLICA_COUNT" '.spec.resources.requests.storage = ((($REPLICA_COUNT |tonumber)  * 200) | tostring)+"Gi"' | jy -o $IDX_SEARCH
+
 # Delete sed's backup files
 find . -name "*.sedibak" -delete
 ```

docs/install.md

@@ -30,6 +30,8 @@
    git clone https://github.com/sourcegraph/deploy-sourcegraph && cd deploy-sourcegraph && git checkout ${VERSION}
    ```
 
+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:
 
    ```bash