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

Prerequisites

Sourcegraph deployed using 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 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:

Navigate to Site admin > Configuration
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

Verify the TLS secret exists and contains valid certificate data:
```
BASH
kubectl get secret sourcegraph-frontend-tls -o yaml
```

Check ingress controller logs:

BASH
kubectl logs -n ingress-nginx deployment/ingress-nginx-controller

cert-manager certificate issues

Check certificate status:

BASH
kubectl get certificate
kubectl describe certificate sourcegraph-frontend-tls

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