Deploying Sourcegraph on Kubernetes is for organizations that need highly scalable and available code search and code intelligence.
Not sure if Kubernetes is the right choice for you? Learn more about the various Sourcegraph installation options.
Before you get started, we recommend learning about how Sourcegraph with Kubernetes works.
Additionally, we recommend reading the configuration guide, ensuring you have prepared the items below so that you're ready to start your installation:
- Customization
- Storage class
- Network Access
- PostgreSQL Database
- Scaling services
- Cluster role administrator access
WARNING: If you are deploying on Azure, you must ensure that your cluster is created with support for CSI storage drivers. This can not be enabled after the fact.
Once you are all set up, either install Sourcegraph directly or deploy Sourcegraph to a cloud of your choice.
-
After meeting all the requirements, make sure you can access your cluster with
kubectl
. -
cd
to the forked local copy of the deploy-sourcegraph repository previously set up during configuration. -
Deploy the desired version of Sourcegraph to your cluster by applying the Kubernetes manifests:
./kubectl-apply-all.sh
NOTE: Google Cloud Platform (GCP) users are required to give their user the ability to create roles in Kubernetes (Learn more):
kubectl create clusterrolebinding cluster-admin-binding --clusterrole cluster-admin --user $(gcloud config get-value account)
-
Monitor the status of the deployment:
kubectl get pods -o wide --watch
-
After deployment is completed, verify Sourcegraph is running by temporarily making the frontend port accessible:
kubectl port-forward svc/sourcegraph-frontend 3080:30080
-
Open http://localhost:3080 in your browser and you will see a setup page. Congratulations, you have Sourcegraph up and running! 🎉
NOTE: If you previously set up an
ingress-controller
, you can now also access your deployment via the ingress.
WARNING: If you intend to set this up as a production instance, we recommend you create the cluster in a VPC or other secure network that restricts unauthenticated access from the public Internet. You can later expose the necessary ports via an Internet Gateway or equivalent mechanism. Note that SG must expose port 443 for outbound traffic to codehosts and to enable telemetry with Sourcegraph.com. Additionally port 22 may be opened to enable git SSH cloning by Sourcegraph. Take care to secure your cluster in a manner that meets your organization's security requirements.
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.
Provider | Node type | Boot/ephemeral disk size |
---|---|---|
Amazon EKS (better than plain EC2) | m5.4xlarge | 100 GB (SSD preferred) |
AWS EC2 | m5.4xlarge | 100 GB (SSD preferred) |
Google Kubernetes Engine (GKE) | n1-standard-16 | 100 GB (default) |
Azure | D16 v3 | 100 GB (SSD preferred) |
Other | 16 vCPU, 60 GiB memory per node | 100 GB (SSD preferred) |
NOTE: Sourcegraph 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!
WARNING: If you are deploying on Azure, you must ensure that your cluster is created with support for CSI storage drivers. This can not be enabled after the fact.
Kubernetes is a portable, extensible, open-source platform for managing containerized workloads and services, that facilitates both declarative configuration and automation. Applications are deployed via a set of YAML files to configure the various components (storage, networking, containers). Learn more about Kubernetes here.
Our Kubernetes support has the following requirements:
- Sourcegraph Enterprise license. You can run through these instructions without one, but you must obtain a license for instances of more than 10 users.
- Minimum Kubernetes version: v1.19 and kubectl v1.19 or later (check kubectl docs for backward and forward compatibility with Kubernetes versions).
- Support for Persistent Volumes.
We also recommend familiarizing yourself with the following before proceeding with the install steps:
We support the use of Kustomize to modify and customize our Kubernetes manifests. Kustomize is a template free way to customize configuration, in a Kubernetes like way with a simple configuration file.
Some benefits of using Kustomize to generate manifests instead of modifying the base directly include:
- Reduce the odds of encountering a merge conflict when upgrading - they allow you to separate your unique changes from the upstream bases.
- Better enable us to support you if you run into issues, because how your deployment varies from our reference deployment is encapsulated in a small set of files.
For more information about how to use Kustomize with Sourcegraph, see our customization guide and introduction to overlays.
An overlay specifies customizations for a base directory of Kubernetes manifests, in this case the base/
directory in the reference repository. Overlays can:
- be used for example to change the number of replicas, change a namespace, add a label, etc
- refer to other overlays that eventually refer to the base (forming a directed acyclic graph with the base as the root)
Overlays can be used in one of two ways:
- With
kubectl
: Starting withkubectl
client version 1.14kubectl
can handlekustomization.yaml
files directly. When usingkubectl
there is no intermediate step that generates actual manifest files. Instead the combined resources from the overlays and the base are directly sent to the cluster. This is done with thekubectl apply -k
command. The argument to the command is a directory containing akustomization.yaml
file. - With
kustomize
: This generates manifest files that are then applied in the conventional way usingkubectl apply -f
.
The overlays provided in our overlays directory rely on the kustomize
tool and the overlay-generate-cluster.sh
script in the
root
directory to generate the manifests. There are two reasons why it was set up like this:
- It avoids having to put a
kustomization.yaml
file in thebase
directory and forcing users that don't use overlays to deal with it (unfortunatelykubectl apply -f
doesn't work if akustomization.yaml
file is in the directory). - It generates manifests instead of applying them directly. This provides opportunity to additionally validate the files
and also allows using
kubectl apply -f
with--prune
flag turned on (apply -k
with--prune
does not work correctly).
To learn about our available overlays and how to use them, please refer to our overlays guides.
Sourcegraph for Kubernetes is configured using our sourcegraph/deploy-sourcegraph
reference repository. This repository contains everything you need to spin up and configure a Sourcegraph deployment on Kubernetes.