# How to setup HTTPS/TLS for your Kubernetes Sourcegraph instance

This document explains how to configure HTTPS/TLS for your Sourcegraph instance deployed with [deploy-sourcegraph-k8s](https://github.com/sourcegraph/deploy-sourcegraph-k8s) using Kustomize.

## Prerequisites

-   Sourcegraph deployed using [deploy-sourcegraph-k8s](https://github.com/sourcegraph/deploy-sourcegraph-k8s)
-   An ingress controller installed in your cluster
-   A domain name pointing to your ingress controller's external IP

## Option 1: TLS with existing certificates

If you already have TLS certificates, you can use the built-in TLS component.

### Step 1: Create a TLS secret

Create a Kubernetes secret containing your TLS certificate and private key:

```bash
kubectl create secret tls sourcegraph-frontend-tls \
  --cert=path/to/your/certificate.crt \
  --key=path/to/your/private.key \
  --namespace=YOUR_NAMESPACE
```

### Step 2: Configure your Kustomization

In your `instances/YOUR_INSTANCE/kustomization.yaml` file, uncomment the TLS component:

```yaml
components:
    # Enable TLS with existing certificates
    - ../../components/network/tls
```

### Step 3: Set environment variables

Add the required configuration to your `instances/YOUR_INSTANCE/.env` file:

```bash
TLS_HOST=sourcegraph.example.com
TLS_INGRESS_CLASS_NAME=nginx
TLS_CLUSTER_ISSUER=your-cluster-issuer  # if using cert-manager
```

### Step 4: Apply the configuration

```bash
# Generate updated manifests
kubectl kustomize instances/YOUR_INSTANCE -o cluster.yaml

# Apply the changes
kubectl apply --prune -l deploy=sourcegraph -f cluster.yaml
```

## Option 2: Cloud provider managed certificates

### AWS with Application Load Balancer (ALB)

For AWS deployments, you can use AWS Certificate Manager (ACM) certificates:

```yaml
components:
    # Use AWS managed certificates
    - ../../components/clusters/aws/managed-cert
    - ../../components/ingress/alb
```

Set the required environment variables:

```bash
AWS_CERTIFICATE_ARN=arn:aws:acm:region:account:certificate/certificate-id
HOST_DOMAIN=sourcegraph.example.com
```

### Google Kubernetes Engine (GKE)

For GKE deployments, you can use Google-managed SSL certificates:

```yaml
components:
    # Use GKE managed certificates
    - ../../components/clusters/gke/managed-cert
    - ../../components/ingress/gke
```

Set the required environment variables:

```bash
HOST_DOMAIN=sourcegraph.example.com
```

## Option 3: cert-manager integration

If you have [cert-manager](https://cert-manager.io/) installed in your cluster, you can automatically provision certificates:

### Step 1: Install cert-manager (if not already installed)

```bash
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.0/cert-manager.yaml
```

### Step 2: Create a ClusterIssuer

Create a ClusterIssuer for Let's Encrypt:

```yaml
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
    name: letsencrypt-prod
spec:
    acme:
        server: https://acme-v02.api.letsencrypt.org/directory
        email: your-email@example.com
        privateKeySecretRef:
            name: letsencrypt-prod
        solvers:
            - http01:
                  ingress:
                      class: nginx
```

### Step 3: Configure Sourcegraph with cert-manager

In your `instances/YOUR_INSTANCE/kustomization.yaml`:

```yaml
components:
    - ../../components/network/tls
```

Set the environment variables:

```bash
TLS_HOST=sourcegraph.example.com
TLS_INGRESS_CLASS_NAME=nginx
TLS_CLUSTER_ISSUER=letsencrypt-prod
```

## Step 4: Update Site Configuration

After configuring TLS, update your Sourcegraph site configuration to use HTTPS:

1. Navigate to **Site admin > Configuration**
2. Update the `externalURL` setting:

```json
{
	"externalURL": "https://sourcegraph.example.com"
}
```

## Verification

### Check ingress configuration

```bash
kubectl get ingress sourcegraph-frontend -o yaml
```

You should see TLS configuration in the output:

```yaml
spec:
    tls:
        - hosts:
              - sourcegraph.example.com
          secretName: sourcegraph-frontend-tls
```

### Test the HTTPS connection

```bash
curl -I https://sourcegraph.example.com
```

You should receive a response with `HTTP/2 200` or `HTTP/1.1 200` status.

### Check certificate details

```bash
echo | openssl s_client -servername sourcegraph.example.com -connect sourcegraph.example.com:443 2>/dev/null | openssl x509 -noout -dates
```

## Troubleshooting

### Certificate not loading

1. Verify the TLS secret exists and contains valid certificate data:

    ```bash
    kubectl get secret sourcegraph-frontend-tls -o yaml
    ```

2. Check ingress controller logs:
    ```bash
    kubectl logs -n ingress-nginx deployment/ingress-nginx-controller
    ```

### cert-manager certificate issues

1. Check certificate status:

    ```bash
    kubectl get certificate
    kubectl describe certificate sourcegraph-frontend-tls
    ```

2. Check cert-manager logs:
    ```bash
    kubectl logs -n cert-manager deployment/cert-manager
    ```

### DNS issues

Ensure your domain name points to your ingress controller's external IP:

```bash
kubectl get service -n ingress-nginx ingress-nginx-controller
nslookup sourcegraph.example.com
```

## Additional Resources

-   [Kubernetes Ingress TLS documentation](https://kubernetes.io/docs/concepts/services-networking/ingress/#tls)
-   [cert-manager documentation](https://cert-manager.io/docs/)
-   [deploy-sourcegraph-k8s TLS component](https://github.com/sourcegraph/deploy-sourcegraph-k8s/tree/main/components/network/tls)