Deploy Tor Onion Services on Kubernetes

The sidecar pattern runs a Tor container alongside your application container in the same pod. Both containers share the localhost network, so Tor forwards .onion traffic directly to your app:

# tor-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: onion-service
spec:
  replicas: 1
  selector:
    matchLabels:
      app: onion-service
  template:
    metadata:
      labels:
        app: onion-service
    spec:
      containers:
      - name: web
        image: nginx:alpine
        ports:
        - containerPort: 80
        volumeMounts:
        - name: site-content
          mountPath: /usr/share/nginx/html
      - name: tor
        image: custom-tor:latest
        volumeMounts:
        - name: tor-keys
          mountPath: /var/lib/tor/hidden_service
      volumes:
      - name: tor-keys
        persistentVolumeClaim:
          claimName: tor-keys-pvc
      - name: site-content
        configMap:
          name: site-content

The Tor container uses a PersistentVolumeClaim to store onion keys, ensuring your .onion address persists across pod restarts and rescheduling. The web container is only accessible via localhost within the pod - no Kubernetes Service or Ingress is needed.

For high-traffic .onion sites, use OnionBalance to distribute requests across multiple backend pods. OnionBalance acts as a frontend that publishes a single .onion address while routing traffic to multiple backend instances, each with their own onion key:

# onionbalance-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: onionbalance
spec:
  replicas: 1
  template:
    spec:
      containers:
      - name: onionbalance
        image: custom-onionbalance:latest
        volumeMounts:
        - name: ob-config
          mountPath: /etc/onionbalance
        - name: ob-keys
          mountPath: /var/lib/tor/onionbalance
      volumes:
      - name: ob-config
        secret:
          secretName: onionbalance-config
      - name: ob-keys
        persistentVolumeClaim:
          claimName: ob-keys-pvc

Each backend pod runs its own Tor instance as a sidecar, generating a unique .onion backend address. OnionBalance combines these under a single frontend address, providing horizontal scaling and automatic failover if any backend pod goes down.

Kubernetes Secrets provide a way to store onion private keys securely within the cluster. However, standard Kubernetes Secrets are only base64-encoded, not encrypted. For production deployments, use a secrets management solution like Sealed Secrets or Vault:

# Store onion keys as a Kubernetes Secret
kubectl create secret generic tor-onion-keys \
  --from-file=hs_ed25519_secret_key=./keys/hs_ed25519_secret_key \
  --from-file=hs_ed25519_public_key=./keys/hs_ed25519_public_key \
  --from-file=hostname=./keys/hostname

# Reference in pod spec
volumeMounts:
- name: tor-keys
  mountPath: /var/lib/tor/hidden_service
  readOnly: true
volumes:
- name: tor-keys
  secret:
    secretName: tor-onion-keys
    defaultMode: 0600

Set defaultMode: 0600 to restrict file permissions on the mounted keys. The Tor daemon requires strict permissions on its hidden service directory, and Kubernetes volume mounts allow you to control this precisely.

AnubizHost provides dedicated servers powerful enough to run Kubernetes clusters for .onion service deployments. Our offshore infrastructure in Iceland, Romania, and Finland gives you privacy-respecting jurisdictions with high-performance hardware including NVMe storage and multi-core processors.

Whether you are running a single-node K3s cluster or a multi-node Kubernetes setup, AnubizHost offers the root access and network flexibility you need. Sign up anonymously with cryptocurrency - Bitcoin, Monero, Litecoin accepted. No KYC, no identity documents. Pre-configured Tor is available on every server, with our team ready to assist with Kubernetes-specific Tor deployments.