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

To follow the steps on this page:

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:

  1. 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.

  2. 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
  3. 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
  4. 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
  5. 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
  6. 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
  7. Test the database connection

    1. 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
    2. 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.

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:

Keywords

Found an issue on this page?Report an issue or Edit this page in GitHub.