Skip to content

Commit

Permalink
update docs (k8s, install, update, scale, troubleshoot)
Browse files Browse the repository at this point in the history
  • Loading branch information
@beyang
beyang committed May 18, 2018
1 parent 82bc1ba commit 3859ca3
Show file tree
Hide file tree
Showing 5 changed files with 380 additions and 190 deletions.
101 changes: 71 additions & 30 deletions docs/install.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,19 @@
* <a href="https://kubernetes.io/docs/tasks/tools/install-kubectl/" target="_blank">kubectl</a>, v1.8.6 or later
* <a href="https://docs.helm.sh/using_helm/#installing-helm" target="_blank">Helm</a>, v2.9.1 or later
* Access to server infrastructure on which you can create a Kubernetes cluster (see
[resource allocation guidelines](scaling.md))
[resource allocation guidelines](scale.md))

## Install

> **Note:** Sourcegraph sends performance and usage data to Sourcegraph to help us make our product
> better for you. The data sent does NOT include any source code or file data (including URLs that
> might implicitly contain this information). You can view traces and disable telemetry in the site
> admin area on the server.
Sourcegraph Data Center is deployed using Kubernetes. Before proceeding with these
instructions, [provision a Kubernetes](k8s.md) cluster on the infrastructure of your choice.
instructions, [provision a Kubernetes](k8s.md) cluster on the infrastructure of your choice. Make
sure you have [configured `kubectl` to access your cluster](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/).


1. Install Tiller with RBAC privileges (the server-side counterpart to Helm) on your cluster:

Expand All @@ -23,13 +30,13 @@ instructions, [provision a Kubernetes](k8s.md) cluster on the infrastructure of
helm init --service-account tiller
```

* If installing Tiller is not an option, consult the instructions below for installing without Tiller.
* If your Kubernetes environment does not permite RBAC, consult the instructions below for
installing without RBAC.
* If installing Tiller is not an option, consult the instructions below
for [installing without Tiller](#install-without-tiller).
* If your Kubernetes environment does not permit RBAC, consult the instructions below
for [installing without RBAC](#install-without-rbac).

1. Create a `values.yaml` file with the following contents:


```
cluster:
storageClass:
Expand Down Expand Up @@ -80,20 +87,65 @@ instructions, [provision a Kubernetes](k8s.md) cluster on the infrastructure of
You will now see the Sourcegraph setup page when you visit the address of your instance. If you made your instance
accessible on the public Internet, make sure you secure it before adding your private repositories.

### Common errors

* `kubectl get pv` shows no Persistent Volumes, and/or `kubectl get events` shows a `Failed to provision volume with
StorageClass "default"` error.
### Add language servers for code intelligence

> Code intelligence is a [paid upgrade](https://about.sourcegraph.com/pricing/) on top of the Data
> Center deployment option. After following these instructions to confirm it
> works, [buy code intelligence](https://about.sourcegraph.com/contact/sales).
[Code intelligence](https://about.sourcegraph.com/docs/code-intelligence) provides advanced code
navigation and cross-references for your code on Sourcegraph.

To enable code intelligence, add a `site.langservers` property to your `values.yaml` file specifying which
language servers to run (omitting languages you don't want):

```yaml
# values.yaml

site: {
"langservers": [
{ "language": "go" },
{ "language": "javascript" },
{ "language": "typescript" },
{ "language": "python" },
{ "language": "java" },
{ "language": "php" }
]
}
```

After modifying `values.yaml`, update your cluster:

```bash
helm upgrade -f values.yaml sourcegraph https://github.com/sourcegraph/datacenter/archive/$VERSION.tar.gz
```

For more information,
* Refer to the [examples](../examples) directory for an example of a cluster config with code
intelligence enabled.
* See the [language-specific docs](https://about.sourcegraph.com/docs/code-intelligence) for
configuring specific languages.
* [Contact us](mailto:[email protected]) with questions or problems relating to code
intelligence.

### Additional configuration

Check that a storage class named "default" exists via `kubectl get storageclass`. If one does exist, run `kubectl get storageclass default -o=yaml` and verify that the zone indicated in the output matches the zone of your cluster.
You can set additional fields in `values.yaml` to configure your cluster to index your code host,
add custom search scopes, enable TLS, turn on SSO, and more. The default set of configuration values
is defined by the `values.yaml` file in *this* directory.

* `Error: release sourcegraph failed: namespaces "default" is forbidden: User "system:serviceaccount:kube-system:default" cannot get namespaces in the namespace "default": Unknown user "system:serviceaccount:kube-system:default"`. Ensure you have created the RBAC resources and helm is using them. A common reason for it to fail is you are already using Helm, so `helm init --service-account tiller` does not work correctly. To fix this for your existing Helm installation, run:
The structure of `values.yaml` is split into two top-level fields:
- `site` defines application-level settings like code host integrations and authentication settings. The full set of
options for `site` is described here: https://about.sourcegraph.com/docs/config/settings.
- `cluster` defines settings specific to the configuration of the Kubernetes cluster, like replica counts and CPU/memory
allocation. Refer to the `values.yaml` in this repository to see which `cluster` fields can be overridden.


### Troubleshooting

See the [Troubleshooting page](troubleshoot.md).

```bash
kubectl apply -f https://about.sourcegraph.com/k8s/rbac-config.yml
kubectl patch deploy --namespace kube-system tiller-deploy -p '{"spec":{"template":{"spec":{"serviceAccount":"tiller"}}}}'
helm init --service-account tiller --upgrade
```

### Install without RBAC

Expand All @@ -102,8 +154,9 @@ that clean up temporary cache data. To do that we need to create RBAC resources.
Helm's
[Role-based Access Control documentation](https://github.com/kubernetes/helm/blob/v2.8.2/docs/rbac.md).

If using RBAC is not an option, you can set `"site.rbac": "disabled"` in your `values.yaml` and run `helm init` instead of
`helm init --service-account tiller` to install Tiller.
If using RBAC is not an option, then
* Set `"site.rbac": "disabled"` in your `values.yaml`
* Run `helm init` instead of `helm init --service-account tiller` to install Tiller.


### Install without Tiller
Expand All @@ -130,18 +183,6 @@ If `cluster.storageClass.create` is set to `none`, then you will need to create
After installing the Sourcegraph Helm chart, you should see persistent volume claims (`kubectl get pvc`) bound to
volumes provisioned using this storage class.

## Configuration
You can set additional values in `values.yaml` to configure your cluster. The default set of configuration values is
defined by the `values.yaml` file in *this* directory.
The configuration structure is split into two top-level fields:
- `site` defines application-level settings like code host integrations and authentication settings. The full set of
options for `site` is described here: https://about.sourcegraph.com/docs/config/settings.
- `cluster` defines settings specific to the configuration of the Kubernetes cluster, like replica counts and CPU/memory
allocation. Refer to the `values.yaml` in this repository to see which `cluster` fields can be overridden.
### Secrets

In some cases, it is desirable to set config fields to the contents of external files. The Helm CLI
Expand Down
46 changes: 19 additions & 27 deletions docs/k8s.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Provisioning a Kubernetes cluster for Sourcegraph Data Center
# Provisioning a Kubernetes cluster

<div class="alert alert-info">

Expand All @@ -10,31 +10,23 @@ mechanism. Take care to secure your cluster in a manner that meets your organiza

</div>

1. Follow the instructions in the table below for provisioning a Kubernetes cluster on your infrastructure. Use the
listed node type for your cluster.
Follow the instructions linked in the table below to provision a Kubernetes cluster for the
infrastructure provider of your choice, using the recommended node and list types in the
table.

<div class="resources">
<table class="table">
<tr>
<th colspan="3">Compute nodes</th>
</tr>
<tr><th>Provider</th><th>Node type</th><th>Boot/ephemeral disk size</th></tr>
<tr><td><a href="https://kubernetes.io/docs/getting-started-guides/aws/">AWS EC2</a></td><td>m4.4xlarge</td><td>N/A</td></tr>
<tr><td><a href="https://cloud.google.com/container-engine/docs/quickstart">Google Compute Engine</a></td><td>n1-standard-16</td><td>100 GB (default)</td></tr>
<tr><td><a href="https://azure.microsoft.com/en-us/services/container-service/kubernetes/">Azure VM</a></td><td>D16 v3</td><td>100 GB (SSD preferred)</td></tr>
<tr><td><a href="https://kubernetes.io/docs/setup/pick-right-solution/">Other</a></td><td>16 vCPU, 60 GiB memory per node</td><td>100 GB (SSD preferred)</td></tr>
</table>
</div>
> Note: Sourcegraph Data Center can run on any Kubernetes cluster, so if your infrastructure
> provider is not listed, see the "Other" row. Pull requests to add rows for more infrastructure
> providers are welcome!
2. Set
up
[Dynamic Provisioning](http://blog.kubernetes.io/2017/03/dynamic-provisioning-and-storage-classes-kubernetes.html)
for persistent volumes.
* If you are using AWS or Google Cloud, you can skip this step as you will configure the Sourcegraph Helm chart later to
include a storage class.
* If you are using Azure, we recommend creating a storage class that uses a Premium Managed Disk (SSD) with Premium_LRS.
* If you are using another cloud provider, refer to
the [Kubernetes storage documentation](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#storageclasses)
for the appropriate configuration. For performance reasons, SSDs are recommended.
* You can also manually provision the persistent volumes required by Sourcegraph Data Center. If that is the case,
inspect all files ending in ".PersistentVolumeClaim.yaml" and ensure a volume is created that satisfies each claim.
<div class="resources">
<table class="table">
<tr>
<th colspan="3">Compute nodes</th>
</tr>
<tr><th>Provider</th><th>Node type</th><th>Boot/ephemeral disk size</th></tr>
<tr><td><a href="https://kubernetes.io/docs/getting-started-guides/aws/">AWS EC2</a></td><td>m4.4xlarge</td><td>N/A</td></tr>
<tr><td><a href="https://cloud.google.com/container-engine/docs/quickstart">Google Compute Engine</a></td><td>n1-standard-16</td><td>100 GB (default)</td></tr>
<tr><td><a href="https://azure.microsoft.com/en-us/services/container-service/kubernetes/">Azure VM</a></td><td>D16 v3</td><td>100 GB (SSD preferred)</td></tr>
<tr><td><a href="https://kubernetes.io/docs/setup/pick-right-solution/">Other</a></td><td>16 vCPU, 60 GiB memory per node</td><td>100 GB (SSD preferred)</td></tr>
</table>
</div>
Loading

0 comments on commit 3859ca3

Please sign in to comment.