# Sourcegraph on Kubernetes with Kustomize

<Callout type="warning">
	The Kustomize deployment type is planned for deprecation and will be sunset in a future release. We recommend using the [Helm deployment](/self-hosted/deploy/kubernetes) for all new Kubernetes installations.
</Callout>

Best for large enterprises that require a multi-node, self-hosted solution and prefer to use the Kustomize deployment type.

<QuickLinks>

    <QuickLink title="Installation" icon='lightbulb' href="#prerequisites" />
    <QuickLink title="Introduction" icon='theming' href="kustomize" />
    <QuickLink title="Configuration" icon='installation' href="configure" />
    <QuickLink title="Maintenance" icon='presets' href="operations" />

</QuickLinks>

## Getting Started

Below is an overview of installing Sourcegraph on Kubernetes using Kustomize.

### Prerequisites

-   [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) (v1.19 or later) with [Kustomize](https://kustomize.io/) (built into [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) in version >= 1.14)
-   A [Kubernetes](https://kubernetes.io/) cluster ([v1.19 or later](https://kubernetes.io/blog/2020/08/26/kubernetes-release-1.19-accentuate-the-paw-sitive/))

*   Support for Persistent Volumes with SSDs
*   You can optionally refer to our [terraform configurations](https://github.com/sourcegraph/tf-k8s-configs) for setting up clusters on:
*   [Amazon Web Services EKS](https://github.com/sourcegraph/tf-k8s-configs/tree/main/aws)
*   [Azure AKS](https://github.com/sourcegraph/tf-k8s-configs/tree/main/azure)
*   [Google Cloud Platform GKE](https://github.com/sourcegraph/tf-k8s-configs/tree/main/gcp)

<Callout type="warning">
	If your Sourcegraph version is older than `v4.5.0` or hasn't
	[migrated](/self-hosted/deploy/kubernetes/kustomize/migrate) to
	[`deploy-sourcegraph-k8s`](https://github.com/sourcegraph/deploy-sourcegraph-k8s),
	please refer to the [legacy deployment docs for
	Kubernetes](https://docs.sourcegraph.com/@v4.4.2/admin/deploy/kubernetes).
</Callout>

### **Step 1**: Set up a release branch

Create a release branch from the default branch (or [an available tag](https://github.com/sourcegraph/deploy-sourcegraph-k8s/tags)) in your local fork of the [deploy-sourcegraph-k8s](https://github.com/sourcegraph/deploy-sourcegraph-k8s) repository.

See the [docs on reference repository](/self-hosted/deploy/repositories) for detailed instructions on creating a local fork.

```bash
  # Recommended: replace the URL with your private fork
  $ git clone https://github.com/sourcegraph/deploy-sourcegraph-k8s.git
  $ cd deploy-sourcegraph-k8s
  $ git checkout {CURRENT_VERSION} && git checkout -b release
```

### **Step 2**: Set up a directory for your instance

Create a copy of the [instances/template](/self-hosted/deploy/kubernetes/kustomize/#template) directory and rename it to `instances/my-sourcegraph`:

```bash
  $ cp -R instances/template instances/my-sourcegraph
```

<Callout type="note">
	In Kustomize, this directory is referred to as an
	[overlay](https://kubectl.docs.kubernetes.io/references/kustomize/glossary/#overlay).
</Callout>

### **Step 3**: Set up the configuration files

**1.** Rename the [kustomization.template.yaml](/self-hosted/deploy/kubernetes/kustomize/#kustomization-yaml) file in `instances/my-sourcegraph` to `kustomization.yaml`.

-   The `kustomization.yaml` file is used to configure your Sourcegraph instance.

```bash
  $ mv instances/my-sourcegraph/kustomization.template.yaml instances/my-sourcegraph/kustomization.yaml
```

**2.** Rename the [buildConfig.template.yaml](/self-hosted/deploy/kubernetes/kustomize/#buildconfig-yaml) file in `instances/my-sourcegraph` to `buildConfig.yaml`.

-   The `buildConfig.yaml` file is used to configure components included in your `kustomization` file if required.

```bash
  $ mv instances/my-sourcegraph/buildConfig.template.yaml instances/my-sourcegraph/buildConfig.yaml
```

### **Step 4**: Set a namespace

By default, the provided `kustomization.yaml` template deploys Sourcegraph into the `ns-sourcegraph` namespace.

If you intend to deploy Sourcegraph into a different namespace, replace `ns-sourcegraph` with the name of the existing namespace in your cluster, or set it to `default` to deploy into the default namespace.

```yaml
# instances/my-sourcegraph/kustomization.yaml
namespace: sourcegraph
```

### **Step 5**: Set a storage class

A storage class must be created and configured before deploying Sourcegraph. SSD storage is not required but is strongly recommended for optimal performance.

#### Option 1: Create a new storage class

We recommend using a pre-configured storage class component for your cloud provider if you can create cluster-wide resources:

```yaml
# instances/my-sourcegraph/kustomization.yaml
components:
    # Select a component that corresponds to your cluster provider
    - ../../components/storage-class/aws/aws-ebs
    - ../../components/storage-class/aws/ebs-csi
    - ../../components/storage-class/azure
    - ../../components/storage-class/gke
```

See our [configurations guide](/self-hosted/deploy/kubernetes/configure) for the full list of available storage class components.

#### Option 2: Use an existing storage class

If you cannot create a new storage class and/or want to use an existing one with SSDs:

<details>
    <summary>Show instruction</summary>

    **1.** Include the `storage-class/name-update` component under the components list

    ```yaml
    # instances/my-sourcegraph/kustomization.yaml
    components:
    # This updates storageClassName to
    # the STORAGECLASS_NAME value from buildConfig.yaml
    - ../../components/storage-class/name-update
    ```

    **2.** Input the storage class name by setting the value of `STORAGECLASS_NAME` in `buildConfig.yaml`.

    For example, set `STORAGECLASS_NAME=sourcegraph` if `sourcegraph` is the name of an existing storage class:

    ```yaml
    # instances/my-sourcegraph/buildConfig.yaml
    kind: ConfigMap
    metadata:
    name: sourcegraph-kustomize-build-config
    data:
    STORAGECLASS_NAME: sourcegraph # -- [ACTION] Update storage class name here
    ```

</details>

#### Option 3: Use default storage class

Skip this step to use the default storage class without SSD support for non-production environments. However, you must recreate the cluster with SSDs configured for production environments later.

<Callout type="warning">
	Search performance will be severely impacted without SSDs provisioned.
</Callout>

### **Step 6**: Build manifests with Kustomize

Generate a new set of manifests locally using the configuration applied to the `my-sourcegraph` subdirectory without applying to the cluster.

```bash
$ kubectl kustomize instances/my-sourcegraph -o cluster.yaml
```

### **Step 7**: Review manifests

Review the generated manifests to ensure they match your intended configuration.

```bash
$ less cluster.yaml
```

### **Step 8**: Deploy the generated manifests

Apply the manifests from the output file `cluster.yaml` to your cluster:

```bash
$ kubectl apply --prune -l deploy=sourcegraph -f cluster.yaml
```

### **Step 9**: Monitor the deployment

Monitor the deployment status to ensure all components are running properly.

```bash
$ kubectl get pods -A -o wide --watch
```

### **Step 10**: Access Sourcegraph in Browser

To verify that the deployment was successful, port-forward the frontend pod with the following command:

```bash
$ kubectl port-forward svc/sourcegraph-frontend 3080:30080
```

Then access your new Sourcegraph instance at http://localhost:3080 to proceed to the site-admin setup step.

```bash
$ open http://localhost:3080
```

---

## Configure

After the initial deployment, additional configuration might be required for Sourcegraph to customize your deployment to suit your specific needs.

Common configurations that are strongly recommended for all Sourcegraph deployments:

-   [Enable the Sourcegraph monitoring stack](/self-hosted/deploy/kubernetes/configure#monitoring-stack)
-   [Enable tracing](/self-hosted/deploy/kubernetes/configure#tracing)
-   [Adjust resource allocations](/self-hosted/deploy/kubernetes/configure#instance-size-based-resources)
-   [Adjust storage sizes](/self-hosted/deploy/kubernetes/configure#adjust-storage-sizes)
-   [Configure ingress](/self-hosted/deploy/kubernetes/configure#ingress)
-   [Enable TLS](/self-hosted/deploy/kubernetes/configure#tls)

Other common configurations include:

-   [Set up an external PostgreSQL Database](/self-hosted/deploy/kubernetes/configure#external-postgres)
-   [Set up SSH connection for cloning repositories](/self-hosted/deploy/kubernetes/configure#ssh-for-cloning)

See the [configuration guide for Kustomize](/self-hosted/deploy/kubernetes/configure) for more configuration options.

## Learn more

-   [Scaling Sourcegraph on Kubernetes](/self-hosted/deploy/kubernetes/scale)
-   Examples of deploying Sourcegraph to the cloud provider listed below:
-   [Amazon EKS](/self-hosted/deploy/kubernetes/kustomize/eks)
-   [Google GKE](/self-hosted/deploy/kubernetes/kustomize/gke)
-   [Migration guide](/self-hosted/deploy/kubernetes/kustomize/migrate) on migrating from [deploy-sourcegraph](https://github.com/sourcegraph/deploy-sourcegraph) to [deploy-sourcegraph-k8s](https://github.com/sourcegraph/deploy-sourcegraph-k8s)
-   [Other deployment options](/self-hosted/deploy/)
-   [Troubleshooting](/self-hosted/deploy/kubernetes/troubleshoot)