Integrate TimescaleDB with CloudNativePG on Kubernetes

Husn E Rabbi

GitHub · LinkedIn

Managing PostgreSQL on Kubernetes has come a long way. While deploying a database is relatively straightforward, operating it reliably in production is where the real challenge begins.

Backups, failover, upgrades, monitoring, and disaster recovery all require careful planning. Traditionally, this meant combining Helm charts with custom scripts or manually managing PostgreSQL images as requirements evolved.

CloudNativePG takes a different approach.

Rather than treating PostgreSQL as just another container, CloudNativePG manages it as a Kubernetes-native resource. You declare the desired state of your PostgreSQL cluster, and the operator continuously reconciles the cluster to match it. Tasks such as provisioning, failover, backups, rolling updates, and lifecycle management become automated.

With CloudNativePG's PostgreSQL extension containers, you can also deploy TimescaleDB without maintaining custom PostgreSQL images. PostgreSQL and its extensions are managed independently, making upgrades significantly easier.

This integration guide walks you through deploying TimescaleDB on CloudNativePG, enabling the extension, and creating your first hypertable.

Prerequisites for this integration guide

To follow these steps, you'll need:

• Kubernetes cluster (v1.31 or later recommended)
• kubectl configured
• A default StorageClass
• Cluster-admin permissions
• A running Kubernetes node with persistent storage

Architecture overview

The deployment architecture is intentionally simple.

+------------------------------------------------+
|                Kubernetes Cluster              |
+------------------------------------------------+
                    |
                    ▼
        CloudNativePG Operator
                    |
                    ▼
         PostgreSQL Cluster (CNPG)
                    |
                    ▼
    TimescaleDB OSS Extension Container
                    |
                    ▼
     Time-Series Applications & Services

CloudNativePG manages the PostgreSQL cluster lifecycle, while the TimescaleDB extension container provides the required extension binaries. This separation allows PostgreSQL and extensions to evolve independently.

Why extension containers?

Historically, installing PostgreSQL extensions in Kubernetes often required building and maintaining custom PostgreSQL images.

That approach introduces several operational challenges:

• Custom image maintenance
• Rebuilding images for PostgreSQL upgrades
• Managing extension compatibility
• Larger CI/CD pipelines
• More complex image security scanning

CloudNativePG extension containers eliminate these problems. Instead of embedding every extension into the PostgreSQL image, extensions are packaged separately. During cluster initialization, CloudNativePG mounts the extension container into PostgreSQL, making the extension available without modifying the base database image.

This keeps PostgreSQL images small, simplifies upgrades, and makes extension lifecycle management significantly cleaner.

Verify Kubernetes feature gates

CloudNativePG extension containers rely on the Kubernetes ImageVolume feature. Ensure your Kubernetes cluster supports this feature before continuing.

If you're using a managed Kubernetes service, consult your provider's documentation to verify support.

To confirm the API server has the feature gate enabled, run:

kubectl get pods -n kube-system \
  -l component=kube-apiserver \
  -o yaml | grep -A 20 "containers:" | grep -E "args:|feature-gates"

You should see output similar to:

--feature-gates=ImageVolume=true

If the feature gate is not enabled, extension containers will not function correctly.

Create a local Kubernetes cluster with Kind

If you don't already have a Kubernetes cluster available, Kind (Kubernetes in Docker) is one of the easiest ways to create a local development environment.

1. Create a configuration file

   Create a configuration file named kind-config.yaml.

   kind: Cluster
   apiVersion: kind.x-k8s.io/v1alpha4
   name: ops
   featureGates:
     ImageVolume: true

2. Create the cluster

   kind create cluster --config kind-config.yaml

3. Check the nodes

   kubectl get nodes

   You should see something similar to:

   NAME                 STATUS   ROLES           AGE   VERSION
   ops-control-plane    Ready    control-plane   1m    v1.34.x

Install CloudNativePG

At the time of writing, CloudNativePG 1.30 is the latest stable release in the 1.30 series.

1. Install the operator

   Install the operator:

   kubectl apply --server-side -f \
     https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/release-1.30/releases/cnpg-1.30.0.yaml

2. Verify that the operator is running

   Verify that the operator is running:

   kubectl rollout status deployment -n cnpg-system cnpg-controller-manager

   Once the deployment is successfully rolled out, your Kubernetes cluster is ready to manage PostgreSQL resources.

Deploy TimescaleDB

1. Create the PostgreSQL cluster

   1. Create a file named cluster-timescaledb.yaml:

      apiVersion: postgresql.cnpg.io/v1
      kind: Cluster
      metadata:
        name: cluster-timescaledb
      spec:
        imageName: ghcr.io/cloudnative-pg/postgresql:18-system-trixie
        instances: 1
        storage:
          size: 1Gi
        postgresql:
          shared_preload_libraries:
            - "timescaledb"
          parameters:
            timescaledb.telemetry_level: 'off'
            max_locks_per_transaction: '128'
          extensions:
            - name: timescaledb-oss
              image:
                reference: ghcr.io/cloudnative-pg/timescaledb-oss:2.27.2-18-trixie

      Key configuration details:

      • 2.27.2 is the TimescaleDB version.
      • 18 represents the PostgreSQL major version.
      • trixie indicates the Debian base image.

   2. Deploy the cluster:

      kubectl apply -f cluster-timescaledb.yaml

      CloudNativePG provisions the PostgreSQL instance and automatically mounts the TimescaleDB extension container.

2. Create a database

   1. Create database-timescaledb.yaml:

      apiVersion: postgresql.cnpg.io/v1
      kind: Database
      metadata:
        name: cluster-timescaledb-app
      spec:
        name: app
        owner: app
        cluster:
          name: cluster-timescaledb
        extensions:
          - name: timescaledb
            version: "2.27.2"

   2. Apply it:

      kubectl apply -f database-timescaledb.yaml

      CloudNativePG creates the database and enables the TimescaleDB extension automatically.

3. Verify the installation

   After deploying the cluster and database resources, connect to PostgreSQL and verify that the TimescaleDB extension has been installed successfully.

   1. Open a shell inside the PostgreSQL pod:

      kubectl exec -it cluster-timescaledb-1 -- sh

   2. Launch the PostgreSQL client:

      psql

   3. Connect to the application database:

      \c app

   4. List installed extensions:

      \dx

      You should see output similar to:

                     List of installed extensions
          Name     | Version |   Schema   |         Description
      -------------+---------+------------+------------------------------
       plpgsql     | 1.0     | pg_catalog | PL/pgSQL procedural language
       timescaledb | 2.27.2  | public     | TimescaleDB OSS

      The TimescaleDB extension is now active and ready for use.

Create your first hypertable

1. Create a hypertable

   Create a hypertable for sensor readings:

   CREATE TABLE sensor_data (
     time TIMESTAMPTZ NOT NULL,
     sensor_id INTEGER,
     temperature DOUBLE PRECISION,
     humidity DOUBLE PRECISION
   ) WITH (tsdb.hypertable, tsdb.partition_column = 'time');

   Unlike regular PostgreSQL tables, hypertables automatically partition data by time while presenting a single logical table to applications.

2. Insert sample data

   Populate the table with some test data:

   INSERT INTO sensor_data
   SELECT
       NOW() - (g || ' minutes')::interval,
       (random()*10)::int,
       random()*30,
       random()*100
   FROM generate_series(1,10000) g;

3. Query time-series data

   Use one of TimescaleDB's most popular functions to calculate the average temperature per hour:

   SELECT
     time_bucket('1 hour', time) AS bucket,
     avg(temperature) AS avg_temperature
   FROM sensor_data
   GROUP BY bucket
   ORDER BY bucket;

   The time_bucket() function groups timestamps into fixed intervals, making time-series aggregations both intuitive and efficient. This is one of the key capabilities that distinguishes TimescaleDB from standard PostgreSQL.

Production considerations

This guide intentionally keeps the deployment simple. For production environments, you'll typically want to enable additional capabilities.

High availability

Deploy multiple PostgreSQL instances.

instances: 3

CloudNativePG automatically manages leader election and failover.

Automated backups

CloudNativePG supports several backup strategies:

• S3-compatible object storage
• Google Cloud Storage
• Azure Blob Storage
• CSI VolumeSnapshots

Choose the approach that aligns with your storage platform and recovery objectives.

Point-in-time recovery

CloudNativePG supports restoring your database to an exact point in time using archived WAL files.

This capability is essential for recovering from accidental deletes or application errors.

Monitor

Production databases should expose metrics to Prometheus and visualize them using Grafana dashboards.

Typical metrics include:

• Query latency
• Replication lag
• Storage usage
• WAL generation
• Connection count

Storage

Database performance depends heavily on storage.

Use SSD-backed persistent volumes with an appropriate StorageClass, and size volumes based on expected data growth and retention requirements.

Upgrade PostgreSQL and TimescaleDB

One advantage of CloudNativePG extension containers is that PostgreSQL and extension upgrades become independent operations.

Instead of rebuilding custom PostgreSQL images every time a new TimescaleDB release becomes available, you can update the extension container version while allowing CloudNativePG to manage PostgreSQL upgrades according to its lifecycle.

This significantly reduces operational overhead and helps keep both PostgreSQL and TimescaleDB current with minimal effort.

Conclusion

CloudNativePG and TimescaleDB complement each other exceptionally well.

CloudNativePG simplifies PostgreSQL operations through Kubernetes-native automation, while TimescaleDB extends PostgreSQL with powerful time-series capabilities such as hypertables and time-based analytics.

Together they provide a clean, declarative, and production-ready platform for building time-series applications on Kubernetes.

By leveraging CloudNativePG's extension container framework, you can avoid maintaining custom PostgreSQL images, simplify upgrades, and keep your deployment aligned with cloud-native best practices.

Whether you're collecting IoT telemetry, monitoring infrastructure, processing financial events, or analyzing application metrics, this architecture provides a scalable foundation with minimal operational complexity.