Sourcegraph on Kubernetes with Helm

Best for large enterprises that require a multi-node, self-hosted solution. Helm offers a simple deployment process on Kubernetes using well known and standard tooling.

Our Helm chart has a lot of sensible defaults baked into the values.yaml so that when an override file is used to make the changes, you never have to deal with merge conflicts during upgrades (see more about customizations in the configuration section).

High-level overview of how to use Helm with Sourcegraph

Prepare any required customizations

Most environments will likely require some customizations to the default Helm chart values. See Configuration for more information.
Additionally, resource allocations for individual services may need to be adjusted. See our Resource Estimator for more information.

Review the customized Helm chart

There are three mechanisms that can be used to review any customizations made, this is an optional step, but may be useful the first time you deploy Sourcegraph, for peace of mind.

Follow the relevant platform-specific guide below to deploy Sourcegraph to your environment:

Google GKE
AWS EKS
Azure AKS
Other cloud providers or on-prem

Quickstart

This quickstart guide is useful to those already familiar with Helm who have a good understanding of how to use Helm in the environment they want to deploy into, and who just want to quickly deploy Sourcegraph with Helm with the default configuration. If this doesn't cover what you need to know, see the links above for platform-specific guides.

To use the Helm chart, add the Sourcegraph helm repository (on the machine used to interact with your cluster):

SH
$ helm repo add sourcegraph https://helm.sourcegraph.com/release

Install the Sourcegraph chart using default values:

SH
$ helm install --version {CURRENT_VERSION_NO_V} sourcegraph sourcegraph/sourcegraph

Sourcegraph should now be available via the address set. Browsing to the url should now provide access to the Sourcegraph UI to create the initial administrator account.

More information on configuring the Sourcegraph application can be found here: Configuring Sourcegraph

Configuration

The Sourcegraph Helm chart is highly customizable to support a wide range of environments. We highly recommend that customizations be applied using an override file, which allows customizations to persist through upgrades without needing to manage merge conflicts.

The default configuration values can be viewed in the values.yaml file along with all supported options.

To customize configuration settings with an override file, begin by creating an empty yaml file (e.g. override.yaml).

(The configuration override file can be created in advance of deployment, and the configuration override settings can be populated in preparation.)

It's recommended that the override file be maintained in a version control system such as GitHub, but for testing, this can be created on the machine from which the Helm deployment commands will be run.

DO NOT copy the default values file as a boilerplate for your override file. You risk having outdated values during future upgrades. Instead, only include the configuration that you need to change and override.

Example overrides can be found in the examples folder. Please take a look at our examples – feel free to copy and adapt them for your own override file.

Providing the override file to Helm is done with the inclusion of the values flag and the name of the file:

SH
$ helm upgrade --install --values ./override.yaml --version {CURRENT_VERSION_NO_V} sourcegraph sourcegraph/sourcegraph

When making configuration changes, it's recommended to review the changes that will be applied—see Reviewing Changes.

Specific Configuration Scenarios

Using external PostgreSQL databases

To use external PostgreSQL databases, first review our general recommendations and required postgres permissions.

We recommend storing the credentials in Secrets created outside the helm chart and managed in a secure manner. Each database requires its own Secret and should follow the following format. The Secret name can be customized as desired:

YAML
apiVersion: v1
kind: Secret
metadata:
  name: pgsql-credentials
data:
  # notes: secrets data has to be base64-encoded
  database: ""
  host: "" # example: pgsql.database.example.com
  password: ""
  port: ""
  user: ""
---
apiVersion: v1
kind: Secret
metadata:
  name: codeintel-db-credentials
data:
  # notes: secrets data has to be base64-encoded
  database: ""
  host: ""
  password: ""
  port: ""
  user: ""
---
apiVersion: v1
kind: Secret
metadata:
  name: codeinsights-db-credentials
data:
  # notes: secrets data has to be base64-encoded
  database: ""
  host: ""
  password: ""
  port: ""
  user: ""

The above Secrets should be deployed to the same namespace as the existing Sourcegraph deployment.

You can reference the Secrets in your override.yaml by configuring the existingSecret key:

YAML
codeIntelDB:
  enabled: false # disables deployment of the database
  auth:
    existingSecret: codeintel-db-credentials
 
codeInsightsDB:
  enabled: false
  auth:
    existingSecret: codeinsights-db-credentials
 
pgsql:
  enabled: false
  auth:
    existingSecret: pgsql-credentials

The using external databases example demonstrates this approach.

Although not recommended, credentials can also be configured directly in the helm chart. For example, add the following to your override.yaml to customize pgsql credentials:

YAML
pgsql:
  enabled: false # Disable internal pgsql database
  auth:
    database: "custom-db"
    host: pgsql.database.company.com # External pgsql host
    user: "new-user"
    password: "new-password"
    port: "5432"

Using external Redis instances

To use external Redis instances, first review our general recommendations.

If your external Redis instances do not require authentication, you can configure access in your override.yaml with the endpoint settings:

YAML
redisCache:
  enabled: false
  connection:
    endpoint: redis://redis-cache.example.com:6379 # use a dedicated Redis, recommended
 
redisStore:
  enabled: false
  connection:
    endpoint: redis://redis-shared.example.com:6379/2 # shared Redis, not recommended

If your endpoints do require authentication, we recommend storing the credentials in Secrets created outside the helm chart and managed in a secure manner.

YAML
apiVersion: v1
kind: Secret
metadata:
  name: redis-cache-connection
data:
  # notes: secrets data has to be base64-encoded
  endpoint: ""
---
apiVersion: v1
kind: Secret
metadata:
  name: redis-store-connection
data:
  # notes: secrets data has to be base64-encoded
  endpoint: ""

You can reference this secret in your override.yaml by configuring the existingSecret key:

YAML
redisCache:
  enabled: false
  connection:
    existingSecret: redis-cache-connection
 
redisStore:
  enabled: false
  connection:
    existingSecret: redis-store-connection

The using your own Redis example demonstrates this approach.

Using external Object Storage

To use an external Object Storage service (S3-compatible services, or GCS), first review our general recommendations. Then review the following example and adjust to your use case.

See override.yaml for an example override file. The example assumes the use of AWS S3. You may configure the environment variables accordingly for your own use case based on our general recommendations.

If you provide credentials with an access key / secret key, we recommend storing the credentials in Secrets created outside the helm chart and managed in a secure manner. An example Secret is shown here:

YAML
apiVersion: v1
kind: Secret
metadata:
  name: sourcegraph-s3-credentials
data:
  # notes: secrets data has to be base64-encoded
  PRECISE_CODE_INTEL_UPLOAD_AWS_ACCESS_KEY_ID: ""
  PRECISE_CODE_INTEL_UPLOAD_AWS_SECRET_ACCESS_KEY: ""

In your override.yaml, reference this Secret and the necessary environment variables:

YAML
blobstore:
  enabled: false # Disable deployment of the built-in object storage
 
# we use YAML anchors and alias to keep override file clean
objectStorageEnv: &objectStorageEnv
  PRECISE_CODE_INTEL_UPLOAD_BACKEND:
    value: S3 # external object storage type, one of "S3" or "GCS"
  PRECISE_CODE_INTEL_UPLOAD_BUCKET:
    value: lsif-uploads # external object storage bucket name
  PRECISE_CODE_INTEL_UPLOAD_AWS_ENDPOINT:
    value: https://s3.us-east-1.amazonaws.com
  PRECISE_CODE_INTEL_UPLOAD_AWS_REGION:
    value: us-east-1
  PRECISE_CODE_INTEL_UPLOAD_AWS_ACCESS_KEY_ID:
    secretKeyRef: # Pre-existing secret, not created by this chart
      name: sourcegraph-s3-credentials
      key: PRECISE_CODE_INTEL_UPLOAD_AWS_ACCESS_KEY_ID
  PRECISE_CODE_INTEL_UPLOAD_AWS_SECRET_ACCESS_KEY:
    secretKeyRef: # Pre-existing secret, not created by this chart
      name: sourcegraph-s3-credentials
      key: PRECISE_CODE_INTEL_UPLOAD_AWS_SECRET_ACCESS_KEY
 
frontend:
  env:
    <<: *objectStorageEnv
 
preciseCodeIntel:
  env:
    <<: *objectStorageEnv

Using SSH to clone repositories

Create a Secret that contains the base64 encoded contents of your SSH private key (make sure it doesn't require a passphrase) and known_hosts file. The [Secret] will be mounted in the gitserver deployment to authenticate with your code host.

If you have access to the ssh keys locally, you can run the command below to create the secret:

SH
$ kubectl create secret generic gitserver-ssh \
    --from-file id_rsa=${HOME}/.ssh/id_rsa \
    --from-file known_hosts=${HOME}/.ssh/known_hosts

Alternatively, you may manually create the secret from a manifest file.

Do NOT commit the secret manifest into your Git repository unless you are okay with storing sensitive information in plaintext and your repository is private.

Create a file with the following and save it as gitserver-ssh.Secret.yaml

YAML
apiVersion: v1
kind: Secret
metadata:
  name: gitserver-ssh
data:
  # notes: secrets data has to be base64-encoded
  id_rsa: ""
  known_hosts: ""

Apply the created [Secret] with the command below:

SH
$ kubectl apply -f gitserver-ssh.Secret.yaml

You should add the following values to your override file to reference the [Secret] you created earlier.

YAML
gitserver:
  sshSecret: gitserver-ssh

Advanced Configuration Methods

The Helm chart is new and still under active development, and our values.yaml (and therefore the customization available to use via an override file) may not cover every need. Equally, some changes are environment or customer-specific, and so will never be part of the default Sourcegraph Helm chart.

The following guidance for using Kustomize with Helm and Helm Subcharts covers both of these scenarios.

While both of these approaches are available, deployment changes that are not covered by Sourcegraph documentation should be discussed with either your Customer Engineer or Support contact before proceeding, to ensure the changes proposed can be supported by Sourcegraph. This also allows Sourcegraph to consider adding the required customizations to the Helm chart.

Integrate Kustomize with Helm chart

For advanced users who are looking for a temporary workaround, we recommend applying Kustomize on the rendered manifests from our chart. Please do not maintain your own fork of our chart, this may impact our ability to support you if you run into issues.

You can learn more about how to integrate Kustomize with Helm from our example.

Helm subcharts

Helm subcharts can be used for permanent customizations to the official Sourcegraph helm chart. This is useful for changes such as adding a new resource unique to your deployment (PodSecurityPolicy, NetworkPolicy, additional services, etc.). These are long-lived customizations that shouldn't be contributed back to the Sourcegraph helm chart.

With a subchart, you create your own helm chart and specify the Sourcegraph chart as a dependency. Any resources you place in the templates folder of your chart will be deployed, as well as the Sourcegraph resources, allowing you to extend the Sourcegraph chart without maintaining a fork.

An example of a subchart is shown in the examples/subchart folder.

More details on how to create and configure a subchart can be found in the helm documentation.

Tracing

Sourcegraph supports HTTP tracing to help troubleshoot issues. See Tracing for details.

To enable tracing on your Helm instance, you'll need to either:

Deploy our bundled Jaeger backend, or
Configure an external tracing backend

Once a tracing backend has been deployed, see our Tracing page for next steps, including required changes to your Site Configuration to enable traces.

Enable the bundled Jaeger deployment

Sourcegraph bundles a Jaeger instance, but it is disabled by default. You can enable it by either adding this to your Helm values override file, or by appending the jaeger/override.yaml file to your Helm upgrade command.

YAML
jaeger:
  enabled: true

Configure OpenTelemetry Collector to use an external tracing backend

To configure the bundled otel-collector to export traces to an external OTel-compatible backend, you you can customize the otel-collector's config file directly in your Helm values override.yaml file.

For the specific configurations to set, see our OpenTelemetry page.

YAML
openTelemetry:
  gateway:
    config:
      traces:
        exporters:
          # Your exporter configuration here
        processors:
          # Your processor configuration here

To use an external Jaeger instance, copy and customize the configs from the opentelemetry-exporter/override.yaml file, and add them to your Helm values override file:

YAML
openTelemetry:
  gateway:
    env:
      JAEGER_HOST:
        value: "http://your.jaeger.endpoint"
    config:
      traces:
        exporters:
          jaeger:
            endpoint: "$JAEGER_HOST:14250"
            tls:
              insecure: true

Configure a tracing backend with TLS enabled

If you require a TLS connection to export trace data, you need to first add the certificate data to a secret. The following snippet demonstrates how you can achieve this:

Do NOT commit the secret manifest into your Git repository unless you are okay with storing sensitive information in plaintext and your repository is private.

YAML
apiVersion: v1
kind: Secret
metadata:
  name: otel-collector-exporters-tls
data:
  file.cert: "<.cert data>"
  file.key: "<.key data>"

After applying the secret to your cluster, you can use the opentelemetry-exporter/override-tls.yaml example, and configure the value openTelemetry.gateway.config.traces.exportersTlsSecretName in your Helm values override file to mount the certificate data in the otel-collector, and instruct the exporter to use TLS:

YAML
openTelemetry:
  gateway:
    env:
      JAEGER_HOST:
        value: "http://your.jaeger.endpoint"
    config:
      traces:
        exportersTlsSecretName: otel-collector-exporters-tls
        exporters:
          jaeger:
            endpoint: "$JAEGER_HOST:14250"
            tls:
              cert_file: /tls/file.cert
              key_file: /tls/file.key

Configure trace sampling

Review the trace sampling documentation, and the opentelemetry-exporter/override-processor.yaml example, then add the configs to your Helm values override file:

YAML
openTelemetry:
  gateway:
    config:
      traces:
        processors:
          probabilistic_sampler:
            hash_seed: 22 # An integer used to compute the hash algorithm. Note that all collectors for a given tier (e.g. behind the same load balancer) should have the same hash_seed.
            sampling_percentage: 10.0 # (default = 0): Percentage at which traces are sampled; >= 100 samples all traces

Cloud providers guides

This section is aimed at providing high-level guidance on deploying Sourcegraph via Helm on major Cloud providers. In general, you need the following to get started:

A working Kubernetes cluster, v1.19 or higher
The ability to provision persistent volumes, e.g. have Block Storage CSI storage driver installed
An Ingress Controller installed, e.g. platform native ingress controller, NGINX Ingress Controller.
The ability to create DNS records for Sourcegraph, e.g. sourcegraph.company.com

Configure Sourcegraph on Google Kubernetes Engine (GKE)

Prerequisites

You need to have a GKE cluster (>=1.19) with the HTTP Load Balancing addon enabled. Alternatively, you can use your own choice of Ingress Controller and disable the HTTP Load Balancing add-on, learn more.
Your account should have sufficient access rights, equivalent to the cluster-admin ClusterRole.
Connect to your cluster (via either the console or the command line using gcloud) and ensure the cluster is up and running by running: kubectl get nodes (several ready nodes should be listed)
Have the Helm CLI installed and run the following command to link to the Sourcegraph helm repository (on the machine used to interact with your cluster):

Please note that Autopilot clusters are not supported. Google managed clusters have security constraints that prevent the setup of the Sourcegraph services.

SH
$ helm repo add sourcegraph https://helm.sourcegraph.com/release

Steps

Step 1: – Create your override file and add in any configuration override settings you need—see configuration for more information on override files and the options for what can be configured.

Add into your override file the below values to configure both your ingress hostname and your storage class. We recommend configuring Ingress to use Container-native load balancing to expose Sourcegraph publicly on a domain of your choosing and setting the Storage Class to use Compute Engine persistent disk. (For an example file see override.yaml)

YAML
frontend:
  serviceType: ClusterIP
  ingress:
    enabled: true
    annotations:
      kubernetes.io/ingress.class: gce
# To enable HTTPS using a self-managed certificate
#    tlsSecret: example-secret
#    host: sourcegraph.example.com
  serviceAnnotations:
    cloud.google.com/neg: '{"ingress": true}'
    # Reference the `BackendConfig` CR created below
    beta.cloud.google.com/backend-config: '{"default": "sourcegraph-frontend"}'
 
storageClass:
  create: true
  type: pd-ssd # This configures SSDs (recommended).
  provisioner: pd.csi.storage.gke.io
  volumeBindingMode: WaitForFirstConsumer
  reclaimPolicy: Retain
 
extraResources:
  - apiVersion: cloud.google.com/v1
    kind: BackendConfig
    metadata:
      name: sourcegraph-frontend
    spec:
      healthCheck:
        checkIntervalSec: 5
        timeoutSec: 5
        requestPath: /ready
        port: 6060 # we use a custom port to perform healthcheck

The override file includes a BackendConfig CRD. This is necessary to instruct the GCP load balancer on how to perform health checks on our deployment.

Container-native load balancing is only available on VPC-native clusters. For legacy clusters, learn more.

Optionally, you can review the changes using one of three mechanisms that can be used to assess the customizations made. This is not required, but may be useful the first time you deploy Sourcegraph, for peace of mind.

Step 2: – Install the chart

SH
$ helm upgrade --install --values ./override.yaml --version {CURRENT_VERSION_NO_V} sourcegraph sourcegraph/sourcegraph

It will take around 10 minutes for the load balancer to be fully ready, you may check on the status and obtain the load balancer IP using the following command:

SH
$ kubectl describe ingress sourcegraph-frontend

Step 3: – Upon obtaining the allocated IP address of the load balancer, you should create a DNS A record for the sourcegraph.company.com domain. Finally, it is recommended to enable TLS and you may consider using Google-managed certificate in GKE or your own certificate.

If using a GKE manage certificate, add the following annotations to Ingress:

YAML
frontend:
  ingress:
    annotations:
      kubernetes.io/ingress.class: null
      networking.gke.io/managed-certificates: managed-cert # replace with actual Google-managed certificate name
      # if you reserve a static IP, uncomment below and update ADDRESS_NAME
      # also, make changes to your DNS record accordingly
      # kubernetes.io/ingress.global-static-ip-name: ADDRESS_NAME

If using your own certificate, you can do so with TLS Secrets.

Step 4: Create a file with the following and save it as sourcegraph-frontend-tls.Secret.yaml

YAML
apiVersion: v1
kind: Secret
metadata:
  name: sourcegraph-frontend-tls
type: kubernetes.io/tls
data:
  # the data is abbreviated in this example
  tls.crt: |
    MIIC2DCCAcCgAwIBAgIBATANBgkqh ...
  tls.key: |
    MIIEpgIBAAKCAQEA7yn3bRHQ5FHMQ ...

SH
$ kubectl apply -f ./sourcegraph-frontend-tls.Secret.yaml

Add the following values to your override file.

YAML
frontend:
  ingress:
    enabled: true
    annotations:
      kubernetes.io/ingress.class: gce
    tlsSecret: sourcegraph-frontend-tls # reference the created TLS Secret
    # replace with your actual domain
    host: sourcegraph.company.com

Step 5 – Validate the deployment Sourcegraph should now be available via the address set. Browsing to the url should now provide access to the Sourcegraph UI to create the initial administrator account.

Step 6 – Further configuration

Now the deployment is complete. More information on configuring the Sourcegraph application can be found here: Configuring Sourcegraph

Configure Sourcegraph on Elastic Kubernetes Service (EKS)

Prerequisites

You need to have a EKS cluster (>=1.19) with the following addons enabled:

You may consider deploying your own Ingress Controller instead of the ALB Ingress Controller, learn more

Your account should have sufficient access equivalent to the cluster-admin ClusterRole.
Connect to your cluster (via either the console or the command line using eksctl) and ensure the cluster is up and running using: kubectl get nodes (several ready nodes should be listed)
Have the Helm CLI installed and run the following command to link to the Sourcegraph helm repository (on the machine used to interact with your cluster):

SH
$ helm repo add sourcegraph https://helm.sourcegraph.com/release

Steps

Step 1: – Create your override file and add in any configuration override settings you need—see configuration for more information on override files and the options around what can be configured.

We recommend adding the following values into your override file to configure Ingress to use AWS Load Balancer Controller to expose Sourcegraph publicly on a domain of your choosing, and to configure the Storage Class to use AWS EBS CSI driver. For an example, see override.yaml.

Uncomment the provisioner that your Amazon EKS cluster implements.

YAML
frontend:
  ingress:
    enabled: true
    annotations:
      alb.ingress.kubernetes.io/target-type: ip # specifies targeting services with type ClusterIP
      # By default the AWS ALB will be internal to your VPC.
    #  alb.ingress.kubernetes.io/scheme: internet-facing  # use this annotation if you plan to provision a public Sourcegraph URL.
      kubernetes.io/ingress.class: alb # aws load balancer controller ingressClass name
      # additional aws alb ingress controller supported annotations
      # ...
    # replace with your actual domain
    host: sourcegraph.company.com
 
storageClass:
  create: true
  type: gp2 # This configures SSDs (recommended).
#  provisioner: ebs.csi.aws.com # use this provisioner if using the self-managed Amazon EBS Container Storage Interface driver
#  provisioner: kubernetes.io/aws-ebs # use this provisioner if using the Amazon EKS add-on
  volumeBindingMode: WaitForFirstConsumer
  reclaimPolicy: Retain

Step 2: – Install the chart

SH
$ helm upgrade --install --values ./override.yaml --version {CURRENT_VERSION_NO_V} sourcegraph sourcegraph/sourcegraph

It will take some time for the load balancer to be fully ready, use the following to check on the status and obtain the load balancer address (once available):

SH
$ kubectl describe ingress sourcegraph-frontend

Step 3: – Upon obtaining the allocated address of the load balancer, you should create a DNS record for the sourcegraph.company.com domain that resolves to the load balancer address.

It is recommended to enable TLS and configure a certificate properly on your load balancer. You may consider using an AWS-managed certificate and add the following annotations to Ingress.

YAML
frontend:
  ingress:
    annotations:
      kubernetes.io/ingress.class: alb
      # ARN of the AWS-managed TLS certificate
      alb.ingress.kubernetes.io/certificate-arn: arn:aws:acm:us-west-2:xxxxx:certificate/xxxxxxx

Step 4: – Validate the deployment Sourcegraph should now be available via the address set. Browsing to the url should now provide access to the Sourcegraph UI to create the initial administrator account.

Step 5: – Further configuration

Now the deployment is complete. More information on configuring the Sourcegraph application can be found here: Configuring Sourcegraph

References

Configure Sourcegraph on Azure Managed Kubernetes Service (AKS)

Prerequisites

You need to have an AKS cluster (>=1.19) with the following addons enabled:

You may consider using your custom Ingress Controller instead of Application Gateway, learn more.

Your account should have sufficient access equivalent to the cluster-admin ClusterRole.
Connect to your cluster (via either the console or the command line using the Azure CLI) and ensure the cluster is up and running using: kubectl get nodes (several ready nodes should be listed)
Have the Helm CLI installed and run the following command to link to the Sourcegraph helm repository (on the machine used to interact with your cluster):

SH
$ helm repo add sourcegraph https://helm.sourcegraph.com/release

Steps

Add into your override file the below values to configure both your ingress hostname and your storage class. We recommend configuring Ingress to use Application Gateway to expose Sourcegraph publicly on a domain of your choosing and Storage Class to use Azure Disk CSI driver. For an example see override.yaml.

YAML
frontend:
  ingress:
    enabled: true
    annotations:
      kubernetes.io/ingress.class: azure/application-gateway
      # additional azure application gateway supported annotations
      # ...
    # replace with your actual domain
    host: sourcegraph.company.com
 
storageClass:
  create: true
  type: null
  provisioner: disk.csi.azure.com
  volumeBindingMode: WaitForFirstConsumer
  reclaimPolicy: Retain
  parameters:
    storageaccounttype: Premium_LRS # This configures SSDs (recommended). A Premium VM is required.

Step 2: – Install the chart

SH
$ helm upgrade --install --values ./override.yaml --version {CURRENT_VERSION_NO_V} sourcegraph sourcegraph/sourcegraph

It will take some time for the load balancer to be fully ready, you can check on the status and obtain the load balancer address (when ready) using:

SH
$ kubectl describe ingress sourcegraph-frontend

Step 3: – Upon obtaining the allocated address of the load balancer, you should create a DNS record for the sourcegraph.company.com domain that resolves to the load balancer address.

It is recommended to enable TLS and configure the certificate properly on your load balancer. You may consider using an Azure-managed certificate and add the following annotations to Ingress.

YAML
frontend:
  ingress:
    annotations:
      kubernetes.io/ingress.class: azure/application-gateway
      # Name of the Azure-managed TLS certificate
      appgw.ingress.kubernetes.io/appgw-ssl-certificate: azure-key-vault-managed-ssl-cert

Step 5: – Further configuration

Now the deployment is complete. More information on configuring the Sourcegraph application can be found here: Configuring Sourcegraph

References

Configure Sourcegraph on other Cloud providers or on-prem

Prerequisites

You need to have a Kubernetes cluster (>=1.19) with the following components installed:

Ingress Controller, e.g. Cloud providers-native solution, NGINX Ingress Controller
Block Storage CSI driver

Your account should have sufficient access privileges, equivalent to the cluster-admin ClusterRole.
Connect to your cluster (via either the console or the command line using the relevant CLI tool) and ensure the cluster is up and running using: kubectl get nodes (several ready nodes should be listed)
Have the Helm CLI installed and run the following command to link to the Sourcegraph helm repository (on the machine used to interact with your cluster):

SH
$ helm repo add sourcegraph https://helm.sourcegraph.com/release

Steps

Read to configure the storageClass.provisioner and storageClass.parameters fields for your cloud provider or consult documentation of the storage solution in your on-prem environment.

The following will need to be included in your override.yaml, once adapted to your environment.

YAML
frontend:
  ingress:
    enabled: true
    annotations:
      kubernetes.io/ingress.class: ingress-class-name # replace with actual ingress class name
      # additional ingress controller supported annotations
      # ...
    # replace with your actual domain
    host: sourcegraph.company.com
 
storageClass:
  create: true
  provisioner: <REPLACE_ME>
  volumeBindingMode: WaitForFirstConsumer
  reclaimPolicy: Retain
  parameters:
    key1: value1

Step 2: – Install the chart

SH
$ helm upgrade --install --values ./override.yaml --version {CURRENT_VERSION_NO_V} sourcegraph sourcegraph/sourcegraph

It may take some time before your ingress is up and ready to proceed. Depending on how your Ingress Controller works, you may be able to check on its status and obtain the public address of your Ingress using:

SH
$ kubectl describe ingress sourcegraph-frontend

Step 3: – You should create a DNS record for the sourcegraph.company.com domain that resolves to the Ingress public address.

It is recommended to enable TLS and configure a certificate properly on your Ingress. You can utilize managed certificate solutions provided by Cloud providers, or your own method.

Alternatively, you may consider configuring cert-manager with Let's Encrypt in your cluster and add the following override to Ingress.

YAML
frontend:
  ingress:
    enabled: true
    annotations:
      kubernetes.io/ingress.class: ingress-class-name # replace with actual ingress class name
      # additional ingress controller supported annotations
      # ...
      # cert-managed annotations
      cert-manager.io/cluster-issuer: letsencrypt # replace with actual cluster-issuer name
    tlsSecret: sourcegraph-frontend-tls # cert-manager will store the created certificate in this secret.
    # replace with your actual domain
    host: sourcegraph.company.com

You also have the option to manually configure TLS certificate via TLS Secrets.

Create a file with the following and save it as sourcegraph-frontend-tls.Secret.yaml

YAML
apiVersion: v1
kind: Secret
metadata:
  name: sourcegraph-frontend-tls
type: kubernetes.io/tls
data:
  # the data is abbreviated in this example
  tls.crt: |
    MIIC2DCCAcCgAwIBAgIBATANBgkqh ...
  tls.key: |
    MIIEpgIBAAKCAQEA7yn3bRHQ5FHMQ ...

SH
$ kubectl apply -f ./sourcegraph-frontend-tls.Secret.yaml

Add the following values to your override file.

YAML
frontend:
  ingress:
    enabled: true
    annotations:
      kubernetes.io/ingress.class: ingress-class-name # replace with actual ingress class name
      # additional ingress controller supported annotations
      # ...
    tlsSecret: sourcegraph-frontend-tls # reference the created TLS Secret
    # replace with your actual domain
    host: sourcegraph.company.com

Step 5: – Further configuration

Now the deployment is complete. More information on configuring the Sourcegraph application can be found here: Configuring Sourcegraph

Upgrading Sourcegraph

The following procedures describe the process to update a Helm Sourcegraph instance. If you are unfamiliar with sourcegraph versioning or releases see our general concepts documentation.

Always consult the release notes for the versions your upgrade will pass over and end on.

Standard upgrades

A standard upgrade occurs between a Sourcegraph version and the minor or major version released immediately after it. If you would like to jump forward several versions, you must perform a multi-version upgrade instead.

Step 1: Review Helm Changelog and Sourcegraph Changelog and select the most recent version compatible with your current Sourcegraph version.

You can only upgrade one minor version of Sourcegraph at a time.

Step 2: Update your copy of the Sourcegraph Helm repo to ensure you have all the latest versions:

SH
$ helm repo update sourcegraph

Step 3: (Optional) Review the changes that will be applied—see Reviewing Changes for options.

Step 4: Install the new version:

SH
$ helm upgrade --install -f override.yaml --version {CURRENT_VERSION_NO_V} sourcegraph sourcegraph/sourcegraph

Step 5: Verify the installation has started:

SH
$ kubectl get pods --watch

When all pods have restarted and show as Running, you can browse to your Sourcegraph deployment and login to verify the instance is working as expected. For troubleshooting, refer to the Operations guide for common commands to gather more information about failures.

Multi-version upgrades

If you are upgrading to Sourcegraph 5.1 or later, we encourage you to perform an automatic multi-version upgrade. The following instructions are still applicable, just the manual version of what automatic multi-version upgrade do for you now (and therefore is valuable information during a bumpy upgrade).

Please see our cautionary note on upgrades, if you have any concerns about running a multi-version upgrade, please reach out to us at [email protected] for advisement.

Multi-version upgrade procedure

Step 1: Check Upgrade Readiness:

Check the upgrade notes for the version range you're passing through.
Check the Site Admin > Updates page to determine upgrade readiness.

Step 2: Scale down deployments and statefulSets that access the database, this step prevents services from accessing the database while schema migrations are in process. The following services must have their replicas scaled to 0:

Deployments (e.g., kubectl scale deployment <name> --replicas=0)
precise-code-intel-worker
repo-updater
searcher
sourcegraph-frontend
sourcegraph-frontend-internal
symbols
worker
Stateful sets (e.g., kubectl scale sts <name> --replicas=0):
gitserver
indexed-search

The following convenience commands provide an example of scaling down the necessary services in a single command:

Deployments:

SH
$ kubectl get -n sourcegraph deploy --no-headers | awk '{print $1}' | xargs -n 1 -P 8 -I % kubectl -n sourcegraph scale deployment % --replicas=0

StatefulSets:

SH
$ kubectl -n sourcegraph get sts --selector 'app.kubernetes.io/component!=codeinsights-db,app.kubernetes.io/component!=codeintel-db,app.kubernetes.io/component!=pgsql' --no-headers | awk '{print $1}' | xargs -n 1 -P 8 -I % kubectl -n sourcegraph scale sts % --replicas=0

The commands above use the sourcegraph namespace and are specific to the kubernetes-helm deployment.

Step 3: Run the migrator upgrade command

The following command is the general template for running an upgrade

SH
$ helm upgrade --install -n <your namespace> --set "migrator.args={upgrade,--from=<current version>,--to=<version to upgrade to>}" sourcegraph-migrator sourcegraph/sourcegraph-migrator --version <migrator image version>

The command above is general and you'll need to substitute in your own namespace, target sourcegraph version, and desired migrator image version. In general run the most recent version of migrator.

Example:

SH
$ helm upgrade --install -n sourcegraph --set "migrator.args={upgrade,--from=3.41.0,--to=4.5.1}" sourcegraph-migrator sourcegraph/sourcegraph-migrator --version {CURRENT_VERSION_NO_V}
Release "sourcegraph-migrator" has been upgraded. Happy Helming!
NAME: sourcegraph-migrator
LAST DEPLOYED: Tue Mar  7 18:23:56 2023
NAMESPACE: sourcegraph
STATUS: deployed
REVISION: 2
TEST SUITE: None
✅ Out of band migrations complete
👉 Migrating to v4.5 (step 3 of 3)
👉 Running schema migrations
✅ Schema migrations complete

You can learn more about running migrator operations in helm in the migrator operations doc.

Step 4: Upgrade your instance via helm upgrade

Now that the databases have been migrated to the latest versions, services can be scaled up and upgrade via the standard procedure. For example:

SH
$ helm upgrade -n <your namespace> --install -f override.yaml --version <sourcegraph version> sourcegraph sourcegraph/sourcegraph

Rollback

You can revert to a previous version with the following command:

SH
$ helm rollback sourcegraph

If you are rolling back more than a single version, then you must also roll back your database, as database migrations (which may have run at some point during the upgrade) are guaranteed to be compatible with one previous minor version.

Database Migrations

By default, database migrations will be performed during application startup by a migrator init container running prior to the frontend deployment. These migrations must succeed before Sourcegraph will become available. If the databases are large, these migrations may take a long time.

In some situations, administrators may wish to migrate their databases before upgrading the rest of the system to reduce downtime. Sourcegraph guarantees database backward compatibility to the most recent minor point release so the database can safely be upgraded before the application code.

To execute the database migrations independently, you can use the Sourcegraph Migrator helm chart.

Reviewing Changes

When configuring an override file or performing an upgrade, we recommend reviewing the changes before applying them.

Using helm template

The helm template command can be used to render manifests for review and comparison. This is particularly useful to confirm the effect of changes to your override file. This approach does not require access to the Kubernetes server.

For example:

Step 1: Render the initial manifests from your existing deployment setup to an output file:

SH
$ CHART_VERSION=0.7.0 # Currently deployed version
$ helm template sourcegraph -f override.yaml --version $CHART_VERSION sourcegraph sourcegraph/sourcegraph > original_manifests

Step 2: Make changes to your override file, and/or update the chart version, then render that output:

SH
$ CHART_VERSION=3.39.0 # Not yet deployed version
$ helm template sourcegraph -f override.yaml --version $CHART_VERSION sourcegraph sourcegraph/sourcegraph > new_manifests

Step 3: Compare the two outputs:

SH
$ diff original_manifests new_manifests

Using helm upgrade --dry-run

Similar to helm template, the helm upgrade --dry-run command can be used to render manifests for review and comparison. This requires access to the Kubernetes server but has the benefit of validating the Kubernetes manifests.

The following command will render and validate the manifests:

SH
$ helm upgrade --install --dry-run -f override.yaml sourcegraph sourcegraph/sourcegraph

Any validation errors will be displayed instead of the rendered manifests.

If you are having difficulty tracking down the cause of an issue, add the --debug flag to enable verbose logging:

SH
$ helm upgrade --install --dry-run --debug -f override.yaml sourcegraph sourcegraph/sourcegraph

The --debug flag will enable verbose logging and additional context, including the computed values used by the chart. This is useful when confirming your overrides have been interpreted correctly.

Using Helm Diff plugin

The Helm Diff plugin can provide a diff against a deployed chart. It is similar to the helm upgrade --dry-run option but can run against the live deployment. This requires access to the Kubernetes server.

To install the plugin, run:

SH
$ helm plugin install https://github.com/databus23/helm-diff

Then, display a diff between a live deployment and an upgrade, with 5 lines of context:

SH
$ helm diff upgrade -f override.yaml sourcegraph sourcegraph/sourcegraph -C 5

For more examples and configuration options, reference the Helm Diff plugin documentation.

Uninstalling Sourcegraph

Sourcegraph can be uninstalled by running the following command:

SH
$ helm uninstall sourcegraph

Some Persistent Volumes may be retained after the uninstall phase is complete. In your cloud provider, check for unattached disks and delete them as necessary.