A Guide to Setting Up TimeScaleDB on Kubernetes

As with most of my devops experience, setting up TimeScaleDB on my Kubernetes cluster has been a painful process of trying different solutions and digging through Github issues until I succeed.

Initially, I tried using TimeScaleDB outside Kubernetes using DigitalOcean's managed postgres database, which comes with support for TSDB, with one caveat – the apache license version of TSDB doesn't support data retention among other features. The full list of lacking features can be found at https://docs.timescale.com/about/latest/timescaledb-editions/#feature-comparison.

As data retention was a requirement for my project and is only available on the community license, I decided to install TSDB in my existing Kubernetes cluster, and here's how I did it.

Failures

The TSDB docs show a list of recommended Kubernetes operators on their docs including:

• StackGres
• Postgres Operator (Patroni)
• PGO
• CloudNativePG

I tried all of these, having success with only one: CloudNativePG.

StackGres and Postgres Operator both come with the apache license of TSDB. I did find a promising comment on a Github issue for using the Community license of TSDB, however even after following the instructions, postgres still didn't let me apply a retention policy to my hypertable, due to tsdb still using the apache license.

CloudNativePG with TSDB (Community License)

Setting up CloudNativePG with TimeScaleDB Community License was a lot less painful than the other options.

Installing CloudNativePG can be done with a one liner:

kubectl apply --server-side -f https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/release-1.23/releases/cnpg-1.23.2.yaml

Make sure to use the latest release.

Next, create a yaml file for your database cluster as timescaledb.yaml, using the timescaledb-postgis image:

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: timescaledb
spec:
  instances: 1
  imageName: ghcr.io/imusmanmalik/timescaledb-postgis:latest
  bootstrap:
    initdb:
      postInitTemplateSQL:
        - CREATE EXTENSION timescaledb;
        - CREATE EXTENSION postgis;
        - CREATE EXTENSION postgis_topology;
        - CREATE EXTENSION fuzzystrmatch;
        - CREATE EXTENSION postgis_tiger_geocoder;
  postgresql:
    shared_preload_libraries:
      - timescaledb
  storage:
    size: 5Gi
    # storageClass: do-block-storage # In my case, I need a custom storage class with DigitalOcean

And finally apply this file to your cluster:

kubectl apply -f ./timescaledb.yaml

And that's it!

Connecting to the Database

You can find the password for your database with:

kubectl get secret timescaledb-app -o jsonpath='{.data.password}' | base64 --decode

And connecting to it can be done by first port forwarding your database locally:

kubectl port-forward timescaledb-0 6432:5432

Replace timescaledb-0 with the pod name of your cluster.

Finally connect using psql:

psql -U app -h localhost -p 6432 app

Best of luck!