Skip to content
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
217 lines (141 sloc) 10.8 KB


This document records manual migrations that are necessary to apply when upgrading to certain Sourcegraph versions. All manual migrations between the version you are upgrading from and the version you are upgrading to should be applied (unless otherwise noted).


(optional) Keep LSIF data through manual migration

If you have previously uploaded LSIF precise code intelligence data and wish to retain it after upgrading, you will need to perform this migration.

Skipping the migration

If you choose not to migrate the data, Sourcegraph will use basic code intelligence until you upload LSIF data again.

You may run the following commands to remove the now unused resources:

kubectl delete svc lsif-server
kubectl delete deployment lsif-server
kubectl delete pvc lsif-server


The lsif-server service has been replaced by a trio of services defined in precise-code-intel, and the persistent volume claim in which lsif-server stored converted LSIF uploads has been replaced by bundle storage.

Upgrading to 3.15 will create a new empty volume for LSIF data. Without any action, the LSIF data previously uploaded to the instance will be lost. To retain old LSIF data, perform the following migration steps. This will cause some temporary downtime for precise code intelligence.


  1. Deploy 3.15. This will create a bundle-manager persistent volume claim.
  2. Release the claims to old and new persistent volumes by taking down lsif-server and precise-code-intel-bundle-manager.
kubectl delete svc lsif-server
kubectl delete deployment lsif-server
kubectl delete deployment precise-code-intel-bundle-manager
  1. Deploy the lsif-server-migrator deployment to transfer the data from the old volume to the new volume.
kubectl apply -f configure/lsif-server-migrator/lsif-server-migrator.Deployment.yaml
  1. Watch the output of the lsif-server-migrator until the copy completes ('Copy complete!').
kubectl logs lsif-server-migrator
  1. Tear down the deployment and re-create the bundle manager deployment.
kubectl delete deployment lsif-server-migrator
  1. Remove the old persistent volume claim.
kubectl delete pvc lsif-server


The command now uses kustomize and requires kubectl client version >= 1.14.

If your kubectl client version is older and doesn't support apply -k you need to install the standalone kustomize binary, generate the YAML files with kustomize build and then use the built YAML with kubectl apply -f. For example use:

kustomize build base | kubectl apply -f -
kustomize build base/rbac-roles | kubectl apply -f -

in your version of if you cannot upgrade kubectl to a client version >= 1.14.

Existing installations: Migrating the container user from root to non-root

Version 3.14 changes the security context of the installation by switching to a non-root user for all containers. This allows running Sourcegraph in clusters with restrictive security policies.

Existing installations that have been run as root before need to migrate their persistent volumes to work in 3.14. We are providing a kustomization that needs to be run once to execute the migration:

NOTE: This needs kubectl client version >= 1.14. If you don't have that you can still install the kustomize binary and generate the yaml file with it and then apply it with -f.

cd overlays/migrate-to-nonroot
kubectl apply -k .

NOTE: This needs kubectl client version >= 1.14. If you don't have that you can still install the kustomize binary and generate the yaml file with it and then apply it with -f like so:

cd overlays/migrate-to-nonroot
kustomize build -o nonroot-migration.yaml
kubectl apply -f nonroot-migration.yaml

This will inject initContainers that do the chown command for containers that have persistent volumes and then restart the necessary containers.

NOTE: The migration still needs the elevated permissions because it needs to run as user root.

New installations do not need this kustomization and existing installations can operate from base again after the migration.

New installations: accommodate clusters with restrictive security policies

New installations on clusters with restrictive security policies can now use a kustomization to accomodate those restrictions:

cd overlays/non-privileged
kubectl -n ns-sourcegraph apply -l deploy=sourcegraph,rbac-admin!=escalated -k .

The only requirement for the installer is admin cluster role in a given namespace.

IMPORTANT NOTE: If you change the namespace please change all three occurences in this directory tree to the new value.


In 3.11 we removed the management console. If you make use of CRITICAL_CONFIG_FILE or SITE_CONFIG_FILE, please refer to the migration notes for Sourcegraph 3.11+.


In 3.9 we migrated indexed-search to a StatefulSet. However, we didn't migrate the indexed-search service to a headless service. You can't mutate a service, so you will need to replace the service before running

# Replace since we can't mutate services
kubectl replace --force -f base/indexed-search/indexed-search.Service.yaml

# Now apply all so frontend knows how to speak to the new service address
# for indexed-search


In 3.9 indexed-search is migrated from a Kubernetes Deployment to a StatefulSet. By default Kubernetes will assign a new volume to indexed-search, leading to it being unavailable while it reindexes. To avoid that we need to update the PersistentVolume's claim to the new indexed-search pod (from indexed-search to data-indexed-search-0. This can be achieved by running the commands in the script below before upgrading. Please read the script closely to understand what it does before following it.

# Set the reclaim policy to retain so when we delete the volume claim the volume is not deleted.
kubectl patch pv -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}' $(kubectl get pv -o json | jq -r '.items[] | select( == "indexed-search")') 

# Stop indexed search so we can migrate it. This means indexed search will be down!
kubectl scale deploy/indexed-search --replicas=0

# Remove the existing claim on the volume
kubectl delete pvc indexed-search

# Move the claim to data-indexed-search-0, which is the name created by stateful set.
kubectl patch pv -p '{"spec":{"claimRef":{"name":"data-indexed-search-0","uuid":null}}}' $(kubectl get pv -o json | jq -r '.items[] | select( == "indexed-search")') 

# Create the stateful set
kubectl apply -f base/indexed-search/indexed-search.StatefulSet.yaml


If you're deploying Sourcegraph into a non-default namespace, refer to "Use non-default namespace" in docs/ for further configuration instructions.


Before upgrading or downgrading 3.7, please consult the v3.7.2 migration guide to ensure you have enough free disk space.


🚨 If you have not migrated off of helm yet, please refer to docs/ before reading the following notes for migrating to Sourcegraph 3.0.

🚨 Please upgrade your Sourcegraph instance to 2.13.x before reading the following notes for migrating to Sourcegraph 3.0.


In Sourcegraph 3.0 all site configuration has been moved out of the config-file.ConfigMap.yaml and into the PostgreSQL database. We have an automatic migration if you use version 3.2 or before. Please do not upgrade directly from 2.x to 3.3 or higher.

After running 3.0, you should visit the configuration page (/site-admin/configuration) and the management console and ensure that your configuration is as expected. In some rare cases, automatic migration may not be able to properly carry over some settings and you may need to reconfigure them.

sourcegraph-frontend service type

The type of the sourcegraph-frontend service (base/frontend/sourcegraph-frontend.Service.yaml) has changed from NodePort to ClusterIP. Directly applying this change will fail. Instead, you must delete the old service and then create the new one (this will result in a few seconds of downtime):

kubectl delete svc sourcegraph-frontend
kubectl apply -f base/frontend/sourcegraph-frontend.Service.yaml

Language server deployment

Sourcegraph 3.0 removed lsp-proxy and automatic language server deployment in favor of Sourcegraph extensions. As a consequence, Sourcegraph 3.0 does not automatically run or manage language servers. If you had code intelligence enabled in 2.x, you will need to follow the instructions for each language extension and deploy them individually. Read the code intelligence documentation.


Sourcegraph 3.0 removed HTTPS / TLS features from Sourcegraph in favor of relying on Kubernetes Ingress Resources. As a consequence, Sourcegraph 3.0 does not expose TLS as the NodePort 30433. Instead you need to ensure you have setup and configured either an ingress controller (recommended) or an explicit NGINX service. See ingress controller documentation, NGINX service documentation, and configure TLS/SSL documentation.

If you previously configured TLS_KEY and TLS_CERT environment variables, you can remove them from base/frontend/sourcegraph-frontend.Deployment.yaml

Postgres 11.1

Sourcegraph 3.0 ships with Postgres 11.1. The upgrade procedure is mostly automatic. Please read this page for detailed information.


Beginning in version 2.12.0, Sourcegraph's Kubernetes deployment requires an Enterprise license key. Follow the steps in docs/

You can’t perform that action at this time.