Install Promscale on Kubernetes

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

note

Before installing Promscale, refer to:

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

Install Promscale with Helm

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

Install the TimescaleDB Helm chart

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

note

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.

Disabling TimescaleDB high availability mode

  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.

Installing the TimescaleDB Helm chart

  1. Add the TimescaleDB Helm chart repository:

    1. helm repo add timescale 'https://charts.timescale.com'

  2. Check that the repository is up to date:

    1. helm repo update

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

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

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

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

Install the Promscale Helm chart

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.

Installing the Promscale Helm chart

  1. Add the TimescaleDB Helm chart repository:

    1. helm repo add timescale 'https://charts.timescale.com'

  2. Check that the repository is up to date:

    1. helm repo update

  3. Create a database called tsdb for Promscale data:

    1. kubectl exec -i --tty $(kubectl get pod -o name --namespace <NAMESPACE> -l role=master,release=<RELEASE_NAME>) -- psql -U postgres
    3. CREATE DATABASE tsdb WITH OWNER postgres;
    5. \q

  4. Capture the postgres user password:

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

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

    Replace <RELEASE_NAME> with the name of your choice

Install Promscale with a manifest file

This section includes instructions to install the Promscale Connector using a manifest file. To deploy TimescaleDB on Kubernetes use helm charts instead. Alternatively, you can install TimescaleDB on a host.

Installing the Promscale Connector with a manifest

  1. Download the template manifest file:

    1. curl https://raw.githubusercontent.com/timescale/promscale/0.13.0/deploy/static/deploy.yaml --output promscale-connector.yaml

  2. Edit the manifest and configure the TimescaleDB database details using the parameters starting with <PROMSCALE_DB>.

  3. Deploy the manifest:

    1. kubectl apply -f promscale-connector.yaml

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.