Using Helm

Requirements

• Helm 3 CLI
• Kubernetes 1.19 or greater

High-level overview of how to use Helm with Sourcegraph

1. Prepare any required customizations
   • Most environments are likely to need changes from the defaults - use the guidance in Configuration.
2. Review the changes
   • 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.
3. Select your deployment method and follow the guidance:
   • 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):

helm repo add sourcegraph https://sourcegraph.github.io/deploy-sourcegraph-helm/

Install the Sourcegraph chart using default values:

helm install --version 0.7.0 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.

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:

helm upgrade --install --values ./override.yaml --version 0.7.0 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 of 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:

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:

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:

pgsql:
  enabled: false # disable internal pgsql database
  auth:
    database: "customdb"
    host: pgsql.database.company.com # external pgsql host
    user: "newuser"
    password: "newpassword"
    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:

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 of the helm chart and managed in a secure manner.

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:

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 of the helm chart and managed in a secure manner. An example Secret is shown here:

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:

minio:
  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 stoage 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:

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.

Create a file with the following and save it as gitserver-ssh.Secret.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:

kubectl apply -f gitserver-ssh.Secret.yaml

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

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.

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

1. 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.
2. Your account should have sufficient access rights, equivalent to the cluster-admin ClusterRole.
3. 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)
4. 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):

helm repo add sourcegraph https://sourcegraph.github.io/deploy-sourcegraph-helm/

Steps

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)

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.

2 – Install the chart

helm upgrade --install --values ./override.yaml --version 0.7.0 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:

kubectl describe ingress sourcegraph-frontend

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:

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.

Create a file with the following and save it as sourcegraph-frontend-tls.Secret.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 ...

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

Add the following values to your override file.

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

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.

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

1. You need to have a EKS cluster (>=1.19) with the following addons enabled:
   • AWS Load Balancer Controller
   • AWS EBS CSI driver

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

1. Your account should have sufficient access equivalent to the cluster-admin ClusterRole.
2. 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)
3. 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):

helm repo add sourcegraph https://sourcegraph.github.io/deploy-sourcegraph-helm/

Steps

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.

frontend:
  ingress:
    enabled: true
    annotations:
      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
  volumeBindingMode: WaitForFirstConsumer
  reclaimPolicy: Retain

ℹ️ 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.

2 – Install the chart

helm upgrade --install --values ./override.yaml --version 0.7.0 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):

kubectl describe ingress sourcegraph-frontend

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.

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

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.

5 – Further configuration

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

References

• Enable TLS with AWS-managed certificate
• Supported AWS load balancer annotations

Configure Sourcegraph on Azure Managed Kubernetes Service (AKS)

Prerequisites

1. You need to have a AKS cluster (>=1.19) with the following addons enabled:
   • Azure Application Gateway Ingress Controller
   • Azure Disk CSI driver

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

1. Your account should have sufficient access equivalent to the cluster-admin ClusterRole.
2. 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)
3. 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):

helm repo add sourcegraph https://sourcegraph.github.io/deploy-sourcegraph-helm/

Steps

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.

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.

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.

ℹ️ 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.

2 – Install the chart

helm upgrade --install --values ./override.yaml --version 0.7.0 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:

kubectl describe ingress sourcegraph-frontend

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.

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

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.

5 – Further configuration

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

References

• Expose an AKS service over HTTP or HTTPS using Application Gateway
• Supported Azure Application Gateway Ingress Controller annotations
• What is Application Gateway Ingress Controller?

Configure Sourcegraph on other Cloud providers or on-prem

Prerequisites

1. 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
2. Your account should have sufficient access privileges, equivalent to the cluster-admin ClusterRole.
3. 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)
4. 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):

helm repo add sourcegraph https://sourcegraph.github.io/deploy-sourcegraph-helm/

Steps

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.

Read https://kubernetes.io/docs/concepts/storage/storage-classes/ 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.

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

ℹ️ 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.

2 – Install the chart

helm upgrade --install --values ./override.yaml --version 0.7.0 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:

kubectl describe ingress sourcegraph-frontend

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.

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

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 ...

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

Add the following values to your override file.

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

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.

5 – Further configuration

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

Upgrading Sourcegraph

A new version of Sourcegraph is released every month (with patch releases in between, released as needed). Check the Sourcegraph blog for release announcements.

Upgrading

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.

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

      helm repo update sourcegraph
   

2. (Optional) Review the changes that will be applied - see Reviewing Changes for options.

3. Install the new version:

   helm upgrade --install -f override.yaml --version 0.7.0 sourcegraph sourcegraph/sourcegraph

1. Verify the installation has started:

   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.

Rollback

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

   helm rollback sourcegraph

Sourcegraph only supports rolling back one minor version, due to database compatibility guarantees.

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:

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

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

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

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

3. Compare the two outputs:

      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:

   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:

   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:

   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:

   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:

helm uninstall sourcegraph

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