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.
RequirementsOur 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 SourcegraphTo use the Helm chart, add the Sourcegraph helm repository (on the machine used to interact with your cluster):
$ helm repo add sourcegraph https://helm.sourcegraph.com/releaseInstall the Sourcegraph chart using default values:
$ helm install --version 6.6.2517 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
ConfigurationThe 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 6.6.2517 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 databasesTo 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:
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: ""
sslmode: "require" # optional, enable if using SSL
---
apiVersion: v1
kind: Secret
metadata:
name: codeintel-db-credentials
data:
# notes: secrets data has to be base64-encoded
database: ""
host: ""
password: ""
port: ""
user: ""
sslmode: "require" # optional, enable if using SSL
---
apiVersion: v1
kind: Secret
metadata:
name: codeinsights-db-credentials
data:
# notes: secrets data has to be base64-encoded
database: ""
host: ""
password: ""
port: ""
user: ""
sslmode: "require" # optional, enable if using SSLThe 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-credentialsThe 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: "custom-db"
host: pgsql.database.company.com # External pgsql host
user: "new-user"
password: "new-password"
port: "5432"
sslmode: "require" # optional, enable if using SSLTo 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 recommendedIf your endpoints do require authentication, we recommend storing the credentials in Secrets created outside 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-connectionThe using your own Redis example demonstrates this approach.
Using external Object StorageTo 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.
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:
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:
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:
<<: *objectStorageEnvCreate 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_hostsAlternatively, 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.yamlYou should add the following values to your override file to reference the [Secret] you created earlier.
gitserver:
sshSecret: gitserver-sshThe 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.
Integrate Kustomize with Helm chartFor 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 subchartsHelm 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.
TracingSourcegraph supports HTTP tracing to help troubleshoot issues. See Tracing for details.
To enable tracing on your Helm instance, you'll need to either:
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 deploymentSourcegraph 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.
Configure OpenTelemetry Collector to use an external tracing backendTo 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.
openTelemetry:
gateway:
config:
traces:
exporters:
# Your exporter configuration here
processors:
# Your processor configuration hereTo 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:
openTelemetry:
gateway:
env:
JAEGER_HOST:
value: "http://your.jaeger.endpoint"
config:
traces:
exporters:
jaeger:
endpoint: "$JAEGER_HOST:14250"
tls:
insecure: trueIf 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.
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:
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.keyReview the trace sampling documentation, and the opentelemetry-exporter/override-processor.yaml example, then add the configs to your Helm values override file:
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 tracesThis 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:
sourcegraph.company.comHTTP Load Balancing addon enabled. Alternatively, you can use your own choice of Ingress Controller and disable the HTTP Load Balancing add-on, learn more.cluster-admin ClusterRole.gcloud) and ensure the cluster is up and running by running: kubectl get nodes (several ready nodes should be listed)Please note that Autopilot clusters are not supported. Google managed clusters have security constraints that prevent the setup of the Sourcegraph services.
$ helm repo add sourcegraph https://helm.sourcegraph.com/releaseStep 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 healthcheckThe override file includes a BackendConfig CRD. This is necessary to instruct the GCP load balancer on how to perform health checks on our deployment.
Step 2: – Install the chart
$ helm upgrade --install --values ./override.yaml --version 6.6.2517 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-frontendStep 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_NAMEIf 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
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.yamlAdd 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.comStep 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) Prerequisitescluster-admin ClusterRole.eksctl) and ensure the cluster is up and running using: kubectl get nodes (several ready nodes should be listed)$ helm repo add sourcegraph https://helm.sourcegraph.com/releaseStep 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.
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: RetainStep 2: – Install the chart
$ helm upgrade --install --values ./override.yaml --version 6.6.2517 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-frontendStep 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/xxxxxxxStep 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) Prerequisitescluster-admin ClusterRole.kubectl get nodes (several ready nodes should be listed)$ helm repo add sourcegraph https://helm.sourcegraph.com/releaseStep 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.Step 2: – Install the chart
$ helm upgrade --install --values ./override.yaml --version 6.6.2517 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-frontendStep 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-certStep 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
Referencescluster-admin ClusterRole.kubectl get nodes (several ready nodes should be listed)$ helm repo add sourcegraph https://helm.sourcegraph.com/releaseStep 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 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: value1Step 2: – Install the chart
$ helm upgrade --install --values ./override.yaml --version 6.6.2517 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-frontendStep 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.comYou 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.yamlAdd 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.comStep 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
Upgrading SourcegraphThe 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.
Standard upgradesA 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.
Step 2: Update your copy of the Sourcegraph Helm repo to ensure you have all the latest versions:
$ helm repo update sourcegraphStep 3: (Optional) Review the changes that will be applied—see Reviewing Changes for options.
Step 4: Install the new version:
$ helm upgrade --install -f override.yaml --version 6.6.2517 sourcegraph sourcegraph/sourcegraph
Step 5: Verify the installation has started:
$ kubectl get pods --watchWhen 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 Multi-version upgrade procedureStep 1: Check Upgrade Readiness:
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:
kubectl scale deployment <name> --replicas=0)kubectl scale sts <name> --replicas=0):The following convenience commands provide an example of scaling down the necessary services in a single command:
Deployments:
$ kubectl get -n sourcegraph deploy --no-headers | awk '{print $1}' | xargs -n 1 -P 8 -I % kubectl -n sourcegraph scale deployment % --replicas=0StatefulSets:
$ 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=0Step 3: Run the migrator upgrade command
The following command is the general template for running an upgrade
$ 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>Example:
$ helm upgrade --install -n sourcegraph --set "migrator.args={upgrade,--from=3.41.0,--to=4.5.1}" sourcegraph-migrator sourcegraph/sourcegraph-migrator --version 6.6.2517
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:
$ helm upgrade -n <your namespace> --install -f override.yaml --version <sourcegraph version> sourcegraph sourcegraph/sourcegraphYou can revert to a previous version with the following command:
$ helm rollback sourcegraphIf 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 MigrationsBy 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 ChangesWhen configuring an override file or performing an upgrade, we recommend reviewing the changes before applying them.
Using helm templateThe 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:
$ CHART_VERSION=0.7.0 # Currently deployed version
$ helm template sourcegraph -f override.yaml --version $CHART_VERSION sourcegraph sourcegraph/sourcegraph > original_manifestsStep 2: Make changes to your override file, and/or update the chart version, then render that output:
$ CHART_VERSION=3.39.0 # Not yet deployed version
$ helm template sourcegraph -f override.yaml --version $CHART_VERSION sourcegraph sourcegraph/sourcegraph > new_manifestsStep 3: Compare the two outputs:
$ diff original_manifests new_manifestsSimilar 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/sourcegraphAny 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/sourcegraphThe --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.
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-diffThen, 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 5For more examples and configuration options, reference the Helm Diff plugin documentation.
Uninstalling SourcegraphSourcegraph can be uninstalled by running the following command:
$ helm uninstall sourcegraphSome Persistent Volumes may be retained after the uninstall phase is complete. In your cloud provider, check for unattached disks and delete them as necessary.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4