Sourcegraph Machine Images

We aim to improve the overall deployment experience for our users through customized machine images.

All Sourcegraph image instances are deployed into a single K3s server cluster, running on a single node with an embedded SQLite Database. It allows us to package all the Sourcegraph services with necessary components into one single launcher image so that you can spin up a Sourcegraph instance with just a few clicks in less than 10 minutes.

This deployment method is highly recommended for customers who do not wish to spend too much time on looking for the right configurations and maintenance, while still having full control over their instances. The Sourcegraph image instances also provide high-availability and flexibility in resource usage, with the capability for scaling and making additional customizations easy whenever your needs have changed, by simply adjusting the worker/agent nodes, while still being on a single node environment. See the official K3s docs to learn more about the architecture of a K3s server.

Most importantly, everything we use to build and publish the images can be found in our public deployment repository so that you can oversee our image creation and development process. You are also welcome to check out and follow our progress and updates there.

Our deployment and release process is also documented in the deployment docs.

All Sourcegraph machine images are free to download, and we strongly encourage you to spin up a Sourcegraph AMI instance to experiment with. They are currently available in the following formats:

AWS AMIs Azure Images Google Compute Images

Sourcegraph Machine Image Instance Overview

  • Self-hosted
  • Single node
  • Preconfigured according to your business size
  • Deployed with our Helm Charts to a K3s, a highly available lightweight Kubernetes distribution cluster, using the containerd run time with built-in ingress, load balancer provider, and local storage provisioner (Click here for the full K3s dependency list)
  • Easy to maintain and configure
  • Supports all Sourcegraph features
  • Ability to perform upgrades easily with or without SSH access

Sourcegraph AWS AMI Instances

All AMI instances are currently pinned with a Sourcegraph version that the instance is launched with to ensure restarting the instance will not cause upgrades accidentally. The version number is saved into a text file on both the root (file path: /home/ec2-user/.sourcegraph-version) and data volumes (file path: /mnt/data/.sourcegraph-version) where it will be read by the reboot script on each reboot. Upgrades will only happen on reboot if the version numbers from both volumes are different.

Detailed deployment and upgrade instructions can be found in our AWS AMIs docs.

Unique AMI IDs can be found in our release page.

What is a Sourcegraph AMI Instance?

  • Self-hosted
  • Single node
  • Preconfigured according to your business size
  • Deployed with our Helm Charts to a K3s, a highly available lightweight Kubernetes distribution cluster, using the containerd run time with built-in ingress, load balancer provider, and local storage provisioner (Click here for the full K3s dependency list)
  • Easy to maintain and configure
  • Supports all Sourcegraph features
  • Ability to perform upgrades easily with or without SSH access

Creation procress

Our AWS AMIs are all based on the HVM method, which provides us with the ability to create a Sourcegraph instance directly on the virtual machine using the verified Amazon Linux 2 Kernel 5.10 x86_64 HVM as the base image. The following steps are performed during the AMI creation process through our install script:

  1. De-escalate to ec2-user to make sure tasks are performed by non-root user
  2. Install Git
  3. Clone the deployment repository
  4. Data volumes are formatted and labeled for the AMI instance to mount later
  5. Add configurations to the kernel that would otherwise limit Sourcegraph search performance
  6. Adjust the local firewall settings to ensure K3s cluster networking/DNS can pass through
  7. Link the ephemeral kubelet/pod storage to our data disk
  8. Link the persistent volume pod storage to our data disk
  9. Link the K3s's embedded database to our data disk
  10. Install K3s on root volume
  11. Correct permission of the K3s kube config file located in /etc/rancher/k3s/k3s.yaml
  12. Install Helm on root volume
  13. Download Sourcegraph Helm Charts on root volume
  14. Deploy Sourcegraph using the local Helm Charts
  15. Save the version number to both root and data volumes
  16. Add a cronjob to run the reboot script on each reboot
  17. K3s is stopped and disabled
  18. The instance will then be stopped to create an AMI using the attached volumes

Data volumes

Each AWS AMI comes with two Amazon EBS volumes, one is for root, and the other one is for data:

  • The root volume contains all the files inside the sourcegraph/deploy repository that are used to build that image and deploy the Sourcegraph instance that lives inside that specific image
    • File path to the deployment repo sourcegraph/deploy: /home/ec2-user/deploy/
    • A local copy of the helm charts that were used to create the AMI: /home/ec2-user/deploy/install/sourcegraph-charts.tar
    • Version number of the AMI Instance: /mnt/data/.sourcegraph-version
    • Create a copy of the kube config file from /etc/rancher/k3s/k3s.yaml allows you to manage the k3s cluster from outside the cluster
  • The data volume is where all your Sourcegraph data will be stored after the instance has been launched. The K3s embedded SQLite database is also mounted onto that volume to make back-up, upgrade, and recovery of the volumes easier.
    • Data of your cluster are stored in the mounted path: /mnt/data
    • Version number of the deployment on disk: /mnt/data/.sourcegraph-version

Sourcegraph does not have access to your cluster and data.

Network and Security

ami-diagram
  • K3s exposes the kubelet API to the Kubernetes control plane node through a websocket tunnel in order to eliminate the need to expose extra ports on the worker nodes.
  • No ingress requirements which allow cluster owners to restrict inbound traffic to only traffic within their network
  • Built-in certificate rotation with the expiration date of 12 months docs
  • Enable custom certificates through etcdctl as recommended by K3s.
  • Ability to launch an AMI instance on EC2 with custom encryption docs.

Please refer to the official CIS hardening guide by K3s for more details and general tips on how to improve security of your cluster.

Additional resources