Integrate Kubernetes with Tiger Cloud

Kubernetes is an open-source container orchestration system that automates the deployment, scaling, and management of containerized applications. You can connect Kubernetes to Tiger Cloud, and deploy TimescaleDB within your Kubernetes clusters.

This guide explains how to connect a Kubernetes cluster to Tiger Cloud, configure persistent storage, and deploy TimescaleDB in your kubernetes cluster.

Prerequisites

To follow the steps on this page:

• Self-managed Kubernetes or a Kubernetes Turnkey Cloud Solution.
• kubectl for command-line interaction with your cluster.

Integrate TimescaleDB in a Kubernetes cluster

Tiger Cloud

To connect your Kubernetes cluster to your Tiger Cloud service:

1. Create a default namespace for your Tiger Cloud components

   1. Create a 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. Create a Kubernetes secret that stores your Tiger Cloud service credentials

   Update the following command with your connection details, then run it:

   kubectl create secret generic timescale-secret \
    --from-literal=PGHOST=<host> \
    --from-literal=PGPORT=<port> \
    --from-literal=PGDATABASE=<dbname> \
    --from-literal=PGUSER=<user> \
    --from-literal=PGPASSWORD=<password>

3. Configure network access to Tiger Cloud

   • Managed Kubernetes: outbound connections to external databases like Tiger Cloud work by default. Make sure your cluster’s security group or firewall rules allow outbound traffic to Tiger Cloud IP.

   • Self-hosted Kubernetes: If your cluster is behind a firewall or running on-premise, you may need to allow egress traffic to Tiger Cloud. Test connectivity using your connection details:

     nc -zv <host> <port>

     If the connection fails, check your firewall rules.

4. Create a Kubernetes deployment that can access your Tiger Cloud

   Run the following command to apply the deployment:

   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

5. Test the connection

   1. Create and run a pod that uses the connection details you added to timescale-secret in the timescale namespace:

      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 a psql shell in the test-pod you just created:

      kubectl exec -it test-pod -- bash -c "psql -h \$PGHOST -U \$PGUSER -d \$PGDATABASE"

   You start a psql session connected to your Tiger Cloud service.

Self-hosted TimescaleDB

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 Tiger Data components

   1. Create the Tiger Data namespace:

      kubectl create namespace tigerdata

   2. Set this namespace as the default for your session:

      kubectl config set-context --current --namespace=tigerdata

   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: tigerdata-pvc
   spec:
     accessModes:
       - ReadWriteOnce
     resources:
       requests:
         storage: 10Gi
   EOF

3. Deploy TimescaleDB as a StatefulSet

   By default, the TimescaleDB HA Docker image you are installing on Kubernetes uses the default PostgreSQL database, user and password. This image includes TimescaleDB and TimescaleDB Toolkit. 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-ha:pg18'
             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: tigerdata-storage
         volumes:
           - name: tigerdata-storage
             persistentVolumeClaim:
               claimName: tigerdata-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 tigerdata-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: tigerdata-app
      spec:
        replicas: 1
        selector:
          matchLabels:
            app: tigerdata-app
        template:
          metadata:
            labels:
              app: tigerdata-app
          spec:
            containers:
            - name: tigerdata-container
              image: postgres:latest
              envFrom:
                - secretRef:
                    name: tigerdata-secret
      EOF

7. Test the database connection

   1. Create and run a pod to verify database connectivity using your connection details saved in tigerdata-secret:

      kubectl run test-pod --image=postgres --restart=Never \
      --env="PGHOST=$(kubectl get secret tigerdata-secret -o=jsonpath='{.data.PGHOST}' | base64 --decode)" \
      --env="PGPORT=$(kubectl get secret tigerdata-secret -o=jsonpath='{.data.PGPORT}' | base64 --decode)" \
      --env="PGDATABASE=$(kubectl get secret tigerdata-secret -o=jsonpath='{.data.PGDATABASE}' | base64 --decode)" \
      --env="PGUSER=$(kubectl get secret tigerdata-secret -o=jsonpath='{.data.PGUSER}' | base64 --decode)" \
      --env="PGPASSWORD=$(kubectl get secret tigerdata-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 have successfully integrated Kubernetes with Tiger Cloud.