Sourcegraph on Kubernetes
Deploying on Kubernetes is for organizations that need highly scalable and available code search and code navigation.
Below is an overview of installing Sourcegraph on Kubernetes using Kustomize.
- kubectl (v1.19 or later) with Kustomize (built into kubectl in version >= 1.14)
- A Kubernetes cluster (v1.19 or later)
- Support for Persistent Volumes with SSDs
- You can optionally refer to our terraform configurations for setting up clusters on:
Step 1: Set up a release branch
Create a release branch from the default branch (or an available tag) in your local fork of the deploy-sourcegraph-k8s repository.
See the docs on reference repository for detailed instructions on creating a local fork.
# Recommended: replace the URL with your private fork $ git clone https://github.com/sourcegraph/deploy-sourcegraph-k8s.git $ cd deploy-sourcegraph-k8s $ git checkout v4.5.1 && git checkout -b release
Step 2: Set up a directory for your instance
Create a copy of the instances/template directory and rename it to
$ cp -R instances/template instances/my-sourcegraph
Step 3: Set up the configuration files
1. Rename the kustomization.template.yaml file in
kustomization.yamlfile is used to configure your Sourcegraph instance.
$ mv instances/my-sourcegraph/kustomization.template.yaml instances/my-sourcegraph/kustomization.yaml
2. Rename the buildConfig.template.yaml file in
buildConfig.yamlfile is used to configure components included in your
kustomizationfile if required.
$ mv instances/my-sourcegraph/buildConfig.template.yaml instances/my-sourcegraph/buildConfig.yaml
Step 4: Set namespace
By default, the provided
kustomization.yaml template deploys Sourcegraph into the
If you intend to deploy Sourcegraph into a different namespace, replace
ns-sourcegraph with the name of the existing namespace in your cluster, or set it to
default to deploy into the default namespace.
# instances/my-sourcegraph/kustomization.yaml namespace: sourcegraph
Step 5: Set storage class
A storage class must be created and configured before deploying Sourcegraph. SSD storage is not required but is strongly recommended for optimal performance.
Option 1: Create a new storage class
We recommend using a preconfigured storage class component for your cloud provider if you can create cluster-wide resources:
# instances/my-sourcegraph/kustomization.yaml components: # Select a component that corresponds to your cluster provider - ../../components/storage-class/aws/aws-ebs - ../../components/storage-class/aws/ebs-csi - ../../components/storage-class/azure - ../../components/storage-class/gke
See our configurations guide for the full list of available storage class components.
Option 2: Use an existing storage class
If you cannot create a new storage class and/or want to use an existing one with SSDs:
1. Include the
storage-class/name-update component under the components list
# instances/my-sourcegraph/kustomization.yaml components: # This updates storageClassName to # the STORAGECLASS_NAME value from buildConfig.yaml - ../../components/storage-class/name-update
2. Input the storage class name by setting the value of
For example, set
sourcegraph is the name of an existing storage class:
# instances/my-sourcegraph/buildConfig.yaml kind: ConfigMap metadata: name: sourcegraph-kustomize-build-config data: STORAGECLASS_NAME: sourcegraph # -- [ACTION] Update storage class name here
Option 3: Use default storage class
Skip this step to use the default storage class without SSD support for non-production environments. However, you must recreate the cluster with SSDs configured for production environments later.
Step 6: Build manifests with Kustomize
Generate a new set of manifests locally using the configuration applied to the
my-sourcegraph subdirectory without applying to the cluster.
$ kubectl kustomize instances/my-sourcegraph -o cluster.yaml
Step 7: Review manifests
Review the generated manifests to ensure they match your intended configuration.
$ less cluster.yaml
Step 8: Deploy the generated manifests
Apply the manifests from the ouput file
cluster.yaml to your cluster:
$ kubectl apply --prune -l deploy=sourcegraph -f cluster.yaml
Step 9: Monitor the deployment
Monitor the deployment status to ensure all components are running properly.
$ kubectl get pods -A -o wide --watch
Step 10: Access Sourcegraph in Browser
To verify that the deployment was successful, port-forward the frontend pod with the following command:
$ kubectl port-forward svc/sourcegraph-frontend 3080:30080
Then access your new Sourcegraph instance at http://localhost:3080 to proceed to the site-admin setup step.
$ open http://localhost:3080
After the initial deployment, additional configuration might be required for Sourcegraph to customize your deployment to suit your specific needs.
Common configurations that are strongly recommended for all Sourcegraph deployments:
- Enable the Sourcegraph monitoring stack
- Enable tracing
- Adjust resource allocations
- Adjust storage sizes
- Configure ingress
- Enable TLS
Other common configurations include:
See the configuration guide for Kustomize for more configuration options.
We recommend deploying Sourcegraph on Kubernetes with Kustomize due to the flexibility it provides. If your organization uses Helm to deploy on Kubernetes, please refer to the documentation for the Sourcegraph Helm Charts instead.
- Examples of deploying Sourcegraph to the cloud provider listed below:
- Migration guide on migrating from deploy-sourcegraph to deploy-sourcegraph-k8s
- Other deployment options