Install TimescaleDB on Kubernetes

Timescale Cloud: Performance, Scale, Enterprise

Self-hosted products

MST

You can run TimescaleDB inside Kubernetes using the TimescaleDB Docker container images.

Development and production environments

The following instructions are for development and testing installations. For a production environment, we strongly recommend that you implement the following, many of which you can achieve using PostgreSQL tooling.

Incremental backup and database snapshots, with efficient point-in-time recovery.
High availability replication, ideally with nodes across multiple availability zones.
Automatic failure detection with fast restarts, for both non-replicated and replicated deployments.
Asynchronous replicas for scaling reads when needed.
Connection poolers for scaling client connections.
Zero-down-time minor version and extension upgrades.
Forking workflows for major version upgrades and other feature testing.
Monitoring and observability.

Deploying for production? With a Timescale Cloud service we tune your database for performance and handle scalability, high availability, backups and management so you can relax.

Try for free

Prerequisites

To follow the steps on this page:

Install self-managed Kubernetes or sign up for a Kubernetes Turnkey Cloud Solution.
Install kubectl for command-line interaction with your cluster.

Integrate Timescale in a Kubernetes cluster

Running TimescaleDB on Kubernetes is similar to running PostgreSQL. This procedure outlines the steps for a non-distributed system.

To connect your Kubernetes cluster to self-hosted TimescaleDB running in the cluster:

Create a default namespace for Timescale components
1. Create the Timescale namespace:
```
kubectl create namespace timescale
```
2. Set this namespace as the default for your session:
```
kubectl config set-context --current --namespace=timescale
```
For more information, see Kubernetes Namespaces.

Set up a persistent volume claim (PVC) storage

To manually set up a persistent volume and claim for self-hosted Kubernetes, run the following command:


kubectl apply -f - <<EOF
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: timescale-pvc
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi
EOF

Deploy TimescaleDB as a StatefulSet

By default, the Timescale Docker image you are installing on Kubernetes uses the default PostgreSQL database, user and password. To deploy TimescaleDB on Kubernetes, run the following command:


kubectl apply -f - <<EOF
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: timescaledb
spec:
  serviceName: timescaledb
  replicas: 1
  selector:
    matchLabels:
      app: timescaledb
  template:
    metadata:
      labels:
        app: timescaledb
    spec:
      containers:
        - name: timescaledb
          image: 'timescale/timescaledb:latest-pg17'
          env:
            - name: POSTGRES_USER
              value: postgres
            - name: POSTGRES_PASSWORD
              value: postgres
            - name: POSTGRES_DB
              value: postgres
            - name: PGDATA
              value: /var/lib/postgresql/data/pgdata
          ports:
            - containerPort: 5432
          volumeMounts:
            - mountPath: /var/lib/postgresql/data
              name: timescale-storage
      volumes:
        - name: timescale-storage
          persistentVolumeClaim:
            claimName: timescale-pvc
EOF

Allow applications to connect by exposing TimescaleDB within Kubernetes


kubectl apply -f - <<EOF
apiVersion: v1
kind: Service
metadata:
  name: timescaledb
spec:
  selector:
    app: timescaledb
  ports:
    - protocol: TCP
      port: 5432
      targetPort: 5432
  type: ClusterIP
EOF

Create a Kubernetes secret to store the database credentials


kubectl create secret generic timescale-secret \
--from-literal=PGHOST=timescaledb \
--from-literal=PGPORT=5432 \
--from-literal=PGDATABASE=postgres \
--from-literal=PGUSER=postgres \
--from-literal=PGPASSWORD=postgres

Deploy an application that connects to TimescaleDB


kubectl apply -f - <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  name: timescale-app
spec:
  replicas: 1
  selector:
    matchLabels:
      app: timescale-app
  template:
    metadata:
      labels:
        app: timescale-app
    spec:
      containers:
      - name: timescale-container
        image: postgres:latest
        envFrom:
          - secretRef:
              name: timescale-secret
EOF

Test the database connection

Create and run a pod to verify database connectivity using your connection details saved in timescale-secret:


kubectl run test-pod --image=postgres --restart=Never \
--env="PGHOST=$(kubectl get secret timescale-secret -o=jsonpath='{.data.PGHOST}' | base64 --decode)" \
--env="PGPORT=$(kubectl get secret timescale-secret -o=jsonpath='{.data.PGPORT}' | base64 --decode)" \
--env="PGDATABASE=$(kubectl get secret timescale-secret -o=jsonpath='{.data.PGDATABASE}' | base64 --decode)" \
--env="PGUSER=$(kubectl get secret timescale-secret -o=jsonpath='{.data.PGUSER}' | base64 --decode)" \
--env="PGPASSWORD=$(kubectl get secret timescale-secret -o=jsonpath='{.data.PGPASSWORD}' | base64 --decode)" \
-- sleep infinity

Launch the PostgreSQL interactive shell within the created test-pod:


kubectl exec -it test-pod -- bash -c "psql -h \$PGHOST -U \$PGUSER -d \$PGDATABASE"

You see the PostgreSQL interactive terminal.

Install with PostgreSQL Kubernetes operators

You can also use PostgreSQL Kubernetes operators to simplify installation, configuration, and life cycle. The operators which our community members have told us work well are:

Install TimescaleDB on Kubernetes

Development and production environments

Prerequisites

Integrate Timescale in a Kubernetes cluster

Install with PostgreSQL Kubernetes operators

Related Content