Install Sourcegraph with Kubernetes

Deploying Sourcegraph into a Kubernetes cluster is for organizations that need highly scalable and available code search and code intelligence.

The Kubernetes manifests for a Sourcegraph on Kubernetes installation are in the repository deploy-sourcegraph.

Requirements

• Kubernetes v1.15 or later with an SSD storage class
  • Cluster role administrator access
• kubectl v1.15 or later
• Access to server infrastructure on which you can create a Kubernetes cluster (see resource allocation guidelines).
• Sourcegraph Enterprise license. You can run through these instructions without one, but you must obtain a license for instances of more than 10 users.
• A valid domain name for your Sourcegraph instance (to enable SSL/TLS)
• A valid TLS certificate (whether from a trusted certificate authority such as Comodo, RapidSSL, or others, a self-signed certificate that can be distributed and installed across all users’ machines, or the ability to use an existing reverse proxy that provides SSL termination for the connection)
• Access tokens or other credentials to connect to your code hosts of choice
• Administrative access to your single sign-on (SSO) provider of choice

Steps

• Provision a Kubernetes cluster on the infrastructure of your choice.

• Make sure you have configured kubectl to access your cluster.

  • If you are using GCP, you’ll need to give your user the ability to create roles in Kubernetes (see GCP’s documentation):

     kubectl create clusterrolebinding cluster-admin-binding --clusterrole cluster-admin --user $(gcloud config get-value account)
  

  • Clone the deploy-sourcegraph repository and check out the version tag you wish to deploy.

    # Go to https://github.com/sourcegraph/deploy-sourcegraph/tags and select the latest version tag
    git clone https://github.com/sourcegraph/deploy-sourcegraph && cd deploy-sourcegraph && git checkout ${VERSION}
    

• Configure the sourcegraph storage class for the cluster by reading through “Configure a storage class”.

• If you want to add a large number of repositories to your instance, you should configure the number of gitserver replicas and the number of indexed-search replicas before you continue with the next step. (See “Tuning replica counts for horizontal scalability” for guidelines.)

• Deploy the desired version of Sourcegraph to your cluster:

   ./kubectl-apply-all.sh

• Monitor the status of the deployment.

   watch kubectl get pods -o wide

• Once the deployment completes, verify Sourcegraph is running by temporarily making the frontend port accessible:

kubectl 1.9.x:

   kubectl port-forward $(kubectl get pod -l app=sourcegraph-frontend -o template --template="{{(index .items 0).metadata.name}}") 3080

kubectl 1.10.0 or later:

   kubectl port-forward svc/sourcegraph-frontend 3080:30080

Open http://localhost:3080 in your browser and you will see a setup page. Congrats, you have Sourcegraph up and running!

• Now configure your deployment.

Configuration

See the configuration docs.

Troubleshooting

See the Troubleshooting docs.

Updating

See the Upgrading Howto on how to upgrade. See the Upgrading docs for details on what changed in a version and if manual migration steps are necessary.

Cluster-admin privileges

Note: Not all organizations have this split in admin privileges. If your organization does not then you don’t need to change anything and can ignore this section.

The default installation has a few manifests that require cluster-admin privileges to apply. We have labelled all resources with a label indicating if they require cluster-admin privileges or not. This allows cluster admins to install the manifests that cannot be installed otherwise.

• Manifests deployed by cluster-admin

   ./kubectl-apply-all.sh -l sourcegraph-resource-requires=cluster-admin

• Manifests deployed by non-cluster-admin

   ./kubectl-apply-all.sh -l sourcegraph-resource-requires=no-cluster-admin

We also provide an overlay that generates a version of the manifests that does not require cluster-admin privileges.