Promscale has been discontinued. We strongly recommend that you do not use Promscale in a production environment. Learn more.

You can install Promscale on Kubernetes using Helm or using a manifest file.


Before installing Promscale, refer to:

  • Promscale Resource recommendation guide to understand the resource requirements.
  • Promscale Configuration recommendation guide to understand configuration requirements.

You can install Promscale using Helm charts.

Before you begin, you must have installed Helm. For more information, including packages and installation instructions, see the Helm documentation.

The Helm charts must be installed in this order:

  1. Install the TimescaleDB Helm chart
  2. Install the Promscale Helm chart

Before you install the TimescaleDB Helm chart, you need to configure these settings in the values.yaml configuration file:


If you do not configure the user credentials before you start, they are randomly generated. When this happens, the helm upgrade command does not rotate the credentials, to prevent breaking the database by changing the database credentials instead it uses the same credentials that are generated during the helm install.

By default, the timescaledb-single Helm chart deploys TimescaleDB in high availability mode. This creates three database replicas, which consumes three times the amount of disk space. Each database instance mounts to its own persistent volume claim (PVC).

You can turn off high availability mode by changing the value of replicaCount to 1 in values.yaml.

  1. Download the default values.yaml file for the timescaledb-single Helm chart.
  2. In values.yaml, change the default replicaCount from 3 to 1.
  3. Use this values.yaml file with the -f flag when installing the timescaledb-single Helm chart. For installation instructions, see the procedures for installing the Helm chart.
  1. Add the TimescaleDB Helm chart repository:

    helm repo add timescale ''
  2. Check that the repository is up to date:

    helm repo update
  3. Install the TimescaleDB Helm chart, using a release name of your choice:

    helm install <RELEASE_NAME> timescale/timescaledb-single

You can provide arguments to the helm install command using this format: --set key=value[,key=value]. For example, to install the chart with backups enabled, use this command:

helm install <RELEASE_NAME> timescale/timescaledb-single --set backup.enabled=true

Alternatively, you can provide a YAML file that includes parameters for installing the chart, like this:

helm install <RELEASE_NAME> -f myvalues.yaml timescale/timescaledb-single

When you have your TimescaleDB Helm chart installed, you can install the Promscale Helm chart. Promscale needs to access your TimescaleDB database. You can provide the database URI, or specify connection parameters.

  1. Add the TimescaleDB Helm chart repository:

    helm repo add timescale ''
  2. Check that the repository is up to date:

    helm repo update
  3. Create a database called tsdb for Promscale data:

    kubectl exec -i --tty $(kubectl get pod -o name --namespace <NAMESPACE> -l role=master,release=<RELEASE_NAME>) -- psql -U postgres
  4. Capture the postgres user password:

    echo $(kubectl get secret --namespace default <RELEASE_NAME>-credentials -o jsonpath="{.data.PATRONI_SUPERUSER_PASSWORD}" | base64 --decode)
  5. Download the Promscale values.yaml, and update the connection section with your TimescaleDB connection details. Add or edit this section with your TimescaleDB connection details:

  6. Install the Promscale Helm chart:

    helm install <RELEASE_NAME> timescale/promscale -f values.yaml

    Replace <RELEASE_NAME> with the name of your choice

When you have installed Promscale, you can ingest data in a few different ways:

  • Migrate existing Prometheus data with Prom-migrator.

  • Ingest incoming data. For more information, see the send data section.