Install TimescaleDB on Kubernetes

You can install a TimescaleDB instance on any Kubernetes deployment. Use the timescaledb-single Helm chart to deploy a highly available TimescaleDB database, and timescaledb-multinode to deploy a multi-node distributed TimescaleDB database. For more information about the components that are deployed with these charts, see TimescaleDB on Kubernetes.

Before you begin installing TimescaleDB on a Kubernetes deployment, make sure you have installed:

If you want to, you can create your own .yaml file to use parameters other than those specified in the default values.yaml. You can name this file <MY_VALUES.yaml>. For details about the parameters you can set, see the Administrator Guide.

Install TimescaleDB using a Helm chart

Install TimescaleDB on Kubernetes using a Helm chart with the default values.yaml file. When you use the values.yaml file, the user credentials are randomly generated during installation. Therefore, the helm upgrade command does not rotate the credentials, because changing the database credentials would break the database. Instead, it continues to use the credentials generated during helm install.

This section provides instructions to deploy TimescaleDB using the timescaledb-single Helm chart.

Installing TimescaleDB using a Helm chart

  1. Add the TimescaleDB Helm chart repository:

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

  2. Verify that the repository is up to date:

    1. helm repo update

  3. Install the TimescaleDB Helm chart, by replacing <MY_NAME> with a name of your choice:

    1. helm install <MY_NAME> timescale/timescaledb-single

    If you created a <MY_VALUES.yaml> file, use this command instead:

    1. helm install <MY_NAME> -f <MY_VALUES.yaml> charts/timescaledb-single

Connect to TimescaleDB

You can connect to TimescaleDB from an external IP address, or from within the cluster.

Connecting to TimescaleDB using an external IP

note

If you configured the user credentials in the my_values.yaml file, you don’t need to decode the passwords. In the following section replace MY_NAME with the name that you provided during the installation.

  1. Get the name of the host to connect to:

    1. kubectl get service/<MY_NAME>

  2. Decode the admin user password PGPASSWORD_ADMIN that was generated during the Helm installation:

    1. PGPASSWORD_ADMIN=$(kubectl get secret --namespace default
    1. <MY_NAME>-credentials -o jsonpath="{.data.PATRONI_admin_PASSWORD}" | base64 --decode)

  3. OptionalDecode the super user password `PGPOSTGRESPASSWORD` that was generated during the Helm installation:

    1. PGPASSWORD_POSTGRES=$(kubectl get secret --namespace default
    1. <MY_NAME>-credentials -o jsonpath="{.data.PATRONI_SUPERUSER_PASSWORD}" | base64 --decode)

  4. Connect to psql as admin user:

    1. kubectl run -i --tty --rm psql --image=postgres \
    3.   --env "PGPASSWORD=$PGPASSWORD_ADMIN" \
    5.   --command -- psql -U admin \
    7.   -h <MY_NAME>.default.svc.cluster.local postgres

Connecting to TimescaleDB from inside the cluster

  1. Get the Pod on which TimescaleDB is installed:

    1. MASTERPOD="$(kubectl get pod -o name --namespace default -l release=test,role=master)"

  2. Run psql inside the Pod containing the primary:

    1. kubectl exec -i --tty --namespace default ${MASTERPOD} -- psql -U postgres

Create a database

After installing and connecting to TimescaleDB you can create a database, connect to the database, and also verify that the TimescaleDB extension is installed.

Creating a database

  1. At the prompt, create an empty database. For example, to create a database called tsdb:

    1. CREATE database tsdb;

  2. Connect to the database you created:

    1. \c tsdb

  3. Verify that the TimescaleDB extension is installed by using the \dx command at the command prompt. The output looks like this:

    1. List of installed extensions
    3. Name     | Version |   Schema   |                            Description
    1. -------------+---------+------------+-------------------------------------------------------------------
    3. plpgsql     | 1.0     | pg_catalog | PL/pgSQL procedural language
    5. timescaledb | 2.1.1   | public     | Enables scalable inserts and complex queries for time-series data
    7. (2 rows)
    9. (END)

Clean up

You can use Helm to uninstall TimescaleDB on the Kubernetes cluster and clean up the Pods, persistent volume claim (PVC), S3 backups, and more.

Cleaning up

To remove the spawned Pods:

  2. helm delete <MY_NAME>

Some items, such as PVCs and S3 backups, are not removed immediately. For more information about purging these items, see the Administrator Guide.

Where to next

Now that you have your first TimescaleDB database up and running, see the TimescaleDB section to learn what you can do with it.

To work through some tutorials that help you get started with TimescaleDB and time-series data, check out the tutorials section.

To get help or chat with the Timescale team, get in contact.